chore: promote canary to main (79 commits, 17 install fixes from 2026-05-03)

.airc/ASSEMBLY-LINE.md

@@ -0,0 +1,121 @@
+# Assembly-line resilience (AIRC pilot — #1109)
+
+The kanban is an assembly line, not a Slack channel. If one agent
+drops offline or gets blocked, the work must be pickable by another
+peer without losing context. This document specifies how.
+
+## The problem this solves
+
+Two real failure modes from this repo's recent history:
+
+1. **Dupe PRs**: Peer A claims a task on AIRC, starts work, hits a long
+   build (cmake, prepush). Peer B sees no commits after N minutes,
+   assumes A stalled, opens a competing PR for the same task. A's
+   "please hold" arrives after B has pushed.
+
+2. **Silent stall**: Peer A claims a task, makes a commit or two, then
+   gets blocked (interrupt, environment issue, agent session ends).
+   No signal goes out. The task sits in a "claimed but not progressing"
+   state for hours. No one knows it's pickable.
+
+The assembly line requires that **claim + actual progress are
+distinguishable**, and that **pickup is safe and explicit**.
+
+## Heartbeat
+
+Every active owner of a queue item emits a heartbeat on AIRC at least
+every **30 minutes** while the task is in-flight. The heartbeat
+contains:
+
+- task id (PR # / issue #)
+- last-commit sha (or "no commits yet, still investigating")
+- current sub-step (e.g., "cmake build in progress, ETA 5min")
+- expected next signal time
+
+A heartbeat is NOT optional. If you genuinely cannot heartbeat (e.g.,
+you're about to close the session), emit a **handoff-pending**
+broadcast instead — see Pickup Protocol below.
+
+## Stall threshold
+
+An in-flight task is **stalled** when:
+
+- No heartbeat in the last 30 minutes **AND**
+- No new commits on the branch in the last 30 minutes **AND**
+- No reply to a direct AIRC ping addressed to the owner within 5
+  minutes.
+
+When all three are true, the task is **available for pickup**.
+Before that point, peers MUST NOT take over.
+
+## Pickup protocol
+
+To pick up a stalled task:
+
+1. Verify all three stall conditions on AIRC. Cite them in the
+   takeover broadcast: "Last heartbeat at T1, last commit at T2, ping
+   sent at T3 no reply."
+2. Broadcast intent: "Picking up #N from @owner. Will rebase their
+   branch onto current canary, continue from sha X, broadcast next
+   heartbeat at T+15m."
+3. Fetch the existing branch. Do NOT delete or rebase-overwrite their
+   commits — keep them as authorship attribution.
+4. Continue work on the SAME branch where possible. If the owner was
+   on a fork (e.g., RebelTechPro), push to a sibling branch on the
+   canonical repo and link it.
+5. Owner returns: they can either let the takeover continue (broadcast
+   "yielding, takeover confirmed") or reclaim (broadcast "back online,
+   resuming"). Reclaim requires the takeover peer to stop and
+   broadcast yield.
+
+## Handoff-pending (graceful exit)
+
+If you know you're going offline before the task is done, broadcast a
+handoff-pending **before** disappearing:
+
+```
+handoff-pending #N — going offline at T. Last commit sha X. Next
+step: <one sentence>. Anyone may pick up immediately; no stall wait
+required.
+```
+
+This bypasses the 30-min stall window. Peers can take over right
+away with explicit consent.
+
+## Why not just git lock files?
+
+Git has no built-in branch-level locking, and adding one creates a
+single point of failure (lock holder offline = branch frozen). AIRC
+broadcast + 30-min stall threshold is the lightweight assembly-line
+shape: no centralized lock, peer-observable state, automatic recovery
+on owner disappearance.
+
+## What NOT to do
+
+- **Don't take over a task without verifying all three stall
+  conditions.** The "I'm taking over unless someone posts a newer
+  branch in 5 seconds" pattern has a race condition.
+- **Don't rebase-overwrite an offline owner's commits to "tidy up."**
+  Their authorship trail is evidence + attribution.
+- **Don't pick up while the owner's prepush is still running.** Long
+  builds are common; absence of commits during a build is normal.
+- **Don't silently drop a task you can't finish.** Broadcast
+  handoff-pending so the line keeps moving.
+
+## Heartbeat example
+
+```
+heartbeat #1085 — owner @codex, last commit 7331be6b4 (4 min ago),
+current: cmake llama.cpp build in progress, ETA 8min, next signal
+expected by T+15min.
+```
+
+## Takeover example
+
+```
+picking up #1106 from @sibling-claude — stall verified: last
+heartbeat 18:01 (35min ago), last commit 17:55 (41min ago), ping at
+18:34 no reply. Branch: feat/adapter-dom-text on RebelTechPro fork.
+Continuing from sha f876dd440, will rebase onto current canary, next
+heartbeat at 18:50.
+```

.airc/ONBOARDING.md

@@ -0,0 +1,87 @@
+# Onboarding for new agents/humans (AIRC pilot — #1109)
+
+You arrived at the Continuum repo and want to contribute. Here's how
+to join the active collaboration.
+
+## TL;DR
+
+```bash
+# 1. Install airc (if not present)
+curl -fsSL https://raw.githubusercontent.com/CambrianTech/airc/main/install.sh | bash
+
+# 2. From the continuum repo root:
+airc knock "I'm <who you are>, want to help with <what>"
+
+# 3. Wait for approval from a current room member. They'll send back
+#    the join string for the private room.
+
+# 4. Join:
+airc join <invite-string>
+
+# 5. Read POLICY.md, QUEUE.md, ASSEMBLY-LINE.md before doing anything.
+```
+
+## What the `knock` does
+
+The `airc knock` command (see [CambrianTech/airc#559](https://github.com/CambrianTech/airc/issues/559))
+is a PUBLIC entrypoint. It posts your introduction to a designated
+public room. Current members of the private Continuum collaboration
+room see it and decide whether to approve. No information about the
+private room is exposed by knocking.
+
+If you're approved, you'll receive a join string via DM or a separate
+channel. That's the only thing that gets you into the private room.
+
+## Why a private room?
+
+The collaboration room contains:
+
+- in-flight PR coordination across multiple peers
+- internal discussion about repo direction
+- references to private dependencies, hardware setups, contributor
+  identities
+
+It is not a security boundary — anyone with the join string can join
+— but it is a courtesy + signal-to-noise filter. Public knocks let
+you express interest without polluting the working channel.
+
+## What approved members see when you knock
+
+Your knock message + the AIRC handle you'd use. That's it. They
+decide based on your stated intent (e.g., "I want to help with the
+LiveKit bridge", "I'm a maintainer of project X and want to mirror
+some patterns"). Approval is a low bar — we want contributors —
+but not zero.
+
+## Bad faith / abuse
+
+If a participant turns out to be acting in bad faith (spam, harassment,
+secret exfiltration, etc.) any approved member can trigger a **room
+rotation**: the private room gist rotates to a new id, the old gist is
+deleted, and only the remaining members receive the new join string.
+Bad-faith actors are dropped silently.
+
+See [SAFETY.md](SAFETY.md) for what to do/not do once joined.
+
+## Once you're in
+
+1. Read [POLICY.md](POLICY.md) — the rules.
+2. Read [QUEUE.md](QUEUE.md) — the current sprint queue + card format.
+3. Read [ASSEMBLY-LINE.md](ASSEMBLY-LINE.md) — heartbeat + pickup
+   protocol so peers can recover your work if you drop offline.
+4. Read [SAFETY.md](SAFETY.md) — what to do/not do as an outside agent.
+5. Ask on AIRC what's pickable from the queue OR propose a new card.
+   Don't unilaterally claim something without AIRC ack.
+
+## Status of the AIRC knock + approve primitives
+
+As of 2026-05-13:
+
+- **`airc knock <owner/repo> <message>`** — shipped in [airc#560](https://github.com/CambrianTech/airc/pull/560), merged to airc canary. Posts a labeled GitHub issue with a structured identity envelope (your ephemeral X25519 pubkey for the approver to encrypt the join string to).
+- **`airc approve <knock-issue-url>`** — shipped in [airc#561](https://github.com/CambrianTech/airc/pull/561), merged to airc canary. Approver picks the knock, generates per-approval ephemeral keypair, ECDH+HKDF derives a per-approval symmetric key, encrypts the private-room join string with ChaCha20-Poly1305, posts the ciphertext as a labeled comment on the knock issue. Forward-secret: ephemerals never persisted past one-shot use, so long-term key compromise years later cannot recover any prior approval.
+
+Knock at `CambrianTech/continuum` to express interest in helping
+this repo. Approved members of the private collaboration room will
+see your knock + decide.
+
+Queue tooling (claim/release/done/nudge) is in flight at [airc#562](https://github.com/CambrianTech/airc/issues/562) as the follow-up to #559.

.airc/POLICY.md

@@ -0,0 +1,81 @@
+# Continuum collaboration policy (AIRC pilot — #1109)
+
+This file is the canonical rulebook for any human or agent working in
+the Continuum repo. It is read on AIRC join (`/join` skill quotes the
+relevant lines) and enforced by pre-push hooks where possible.
+
+## Branch + PR rules
+
+- **All work targets the `canary` branch via PR.** Direct pushes to
+  `canary` or `main` are forbidden. Branch protection enforces this.
+- **`main` is the publish branch.** Only the canary→main promotion PR
+  modifies `main`, opened by Joel or a delegated agent once canary has
+  been dogfooded for at least one work session.
+- **Feature branches use one of three prefixes:** `feat/`, `fix/`,
+  `chore/`. Anything else (`codex/`, `experiment/`, ad-hoc names) is
+  reviewer-distracting drift; rename before opening the PR.
+- **PRs must rebase on canary before requesting review.** Stale PRs
+  fail the image-revision gate because pre-built canary images
+  invalidate when canary advances.
+
+## Push discipline
+
+- **`--no-verify` is forbidden.** No exceptions, even for "pre-existing
+  failures." If pre-push fails, fix the underlying issue OR
+  baseline-tolerate the gate (e.g., ESLint baseline). Bypassing the
+  hook means the next agent inherits the failure with no signal.
+- **`--no-gpg-sign`, `--no-edit` on rebase, force-push to canary/main:
+  also forbidden.** Force-pushes to your own feature branch are fine
+  if you announce on AIRC first.
+- **Every PR must show validation evidence in its description:** which
+  gates ran, what output they produced, what was skipped and why.
+  "Local gates green" without specifics is not evidence.
+
+## Error + fallback discipline
+
+- **Never swallow errors.** `2>/dev/null`, `|| true`, catch-and-continue
+  patterns must justify themselves in a comment ("expected-noise case
+  X because Y") or be removed. Errors are evidence for the next
+  debugger; suppressing them costs hours later.
+- **Fallbacks are illegal at the architectural layer.** Silent fallback
+  to a default model, to cloud when local fails, to an alternate code
+  path when the primary errors — all forbidden. Fail loud. The
+  caller decides recovery, not the callee.
+- **`try/catch` inside command `execute()` methods is forbidden by
+  default.** Let throws propagate; the outer `Commands.execute` shell
+  catches and surfaces. Inline justification required for any
+  exception that needs catching at this layer.
+
+## Pattern recognition + refactoring
+
+- **Always look for patterns before adding code.** If your change is
+  the Nth instance of a similar shape, find the primitive and refactor
+  existing instances into it in the same PR. Adding-without-improving
+  is the failure mode that grows the codebase entropy.
+- **Notice everywhere, act in scope.** Continuously catalog cleanup
+  opportunities while you read code. Don't roam to refactor areas
+  unrelated to your current task. Surface notes on AIRC or as
+  follow-up issues; don't dive in uninvited.
+
+## Methodology + evidence rules
+
+- **Common-sense sniff test before every test or claim.** Read your
+  proposed evidence as a skeptical outsider would. Filename leaks,
+  prompt-leaks, training-data memorization, generic outputs that any
+  model could hit by chance — all disqualify "PASS" claims.
+- **Use opaque manifest fixtures for sensory tests.** See
+  `test-data/images/manifest.json`. Never name a test input the
+  literal answer (no `cat.jpg`).
+- **Product-surface verification, not back-channel.** "I read logs and
+  saw a success line" is not the same as "the user-facing surface
+  reported success." If the product has a notification, wait for the
+  notification.
+
+## See also
+
+- [QUEUE.md](QUEUE.md) — current sprint queue + PR-card format
+- [ONBOARDING.md](ONBOARDING.md) — how to knock and join (depends on
+  airc#559)
+- [SAFETY.md](SAFETY.md) — outside-agent etiquette
+- [ASSEMBLY-LINE.md](ASSEMBLY-LINE.md) — heartbeat, stall threshold,
+  pickup protocol for blocked-or-offline-peer recovery

.airc/QUEUE.md

@@ -0,0 +1,84 @@
+# Sprint queue — PR card format (AIRC pilot — #1109)
+
+The queue is the active set of PRs and issues across one sprint.
+Every active card on the queue MUST have these fields filled in,
+either in the PR description or in an AIRC pinned message.
+
+## Card fields
+
+| Field | Required | Format | Example |
+|---|---|---|---|
+| **id** | yes | `#NNNN` (PR or issue) | `#1085` |
+| **branch** | yes (if PR) | `feat/...` / `fix/...` / `chore/...` | `fix/install-tier-name-divergence` |
+| **owner** | yes | AIRC peer/session identity from `airc whois` (sub-tab disambiguated). **Not** a GitHub username — one gh account commonly maps to many agents. | `claude-tab-#1` |
+| **status** | yes | `claimed` / `in-progress` / `blocked` / `review` / `merged` | `in-progress` |
+| **blockers** | if any | comma-separated `#NNNN` task ids | `#1085, airc#559` |
+| **env** | yes | `mac-m5` / `rtx5090-wsl2` / `linux-amd64-any` / `any` | `linux-amd64-any` |
+| **evidence** | yes-on-review | which gates ran + last sha they ran against | `prepush 61bdeb407: TS+ESLint+Rust 27/27 green` |
+| **next action** | yes | one sentence: what needs to happen next | `wait for image rebuild on linux/amd64 host` |
+| **last heartbeat** | yes-while-in-progress | ISO timestamp + commit sha | `2026-05-13T17:35Z @ 61bdeb407` |
+
+## Status transitions
+
+```
+(new) → claimed → in-progress → review → merged
+                ↘         ↘
+                 blocked ⇄ in-progress
+```
+
+- **`claimed`**: owner announced on AIRC, no commits yet.
+- **`in-progress`**: at least one commit on the branch.
+- **`blocked`**: explicit dependency on another card. Must name the
+  blocker.
+- **`review`**: PR open, hooks green, awaiting Codex review.
+- **`merged`**: landed on canary.
+
+## Where the card lives
+
+Single source of truth: **the PR itself** (description + airc broadcasts).
+The PR description carries the static fields; AIRC broadcasts carry
+heartbeats and status transitions.
+
+For pre-PR work (issue-only, exploration), the card lives in the
+issue body and AIRC.
+
+## Per-card AIRC broadcast hooks
+
+- **On claim**: `claiming #NNNN: <one-line scope>. branch=<X>. env=<Y>.`
+- **On first commit**: `in-progress #NNNN: first commit <sha>.`
+- **On heartbeat**: `heartbeat #NNNN — last commit <sha> at <T>, current: <substep>, next signal by T+30m.`
+- **On block**: `blocked #NNNN by <blocker-id>: <reason>. need: <unblock-spec>.`
+- **On review-ready**: `#NNNN ready for review at <sha>. validation: <gates>. requesting @codex.`
+- **On merged**: `#NNNN merged at <sha>. canary fast-forwarded.`
+
+## Queue rules
+
+1. **One PR per scope.** Don't open a competing PR for the same scope
+   if a card already exists. Coordinate on AIRC instead (see
+   [ASSEMBLY-LINE.md](ASSEMBLY-LINE.md) for pickup protocol).
+2. **Self-assign only after AIRC claim.** GitHub-assignment without
+   AIRC claim is invisible to peers and dupe-prone.
+3. **Cross-repo cards span both.** A task that needs continuum + airc
+   changes has a card in each, with `blockers` linking them. Don't
+   pretend they're independent.
+4. **Env tag must match reality.** If you can only run a step on a
+   specific host, tag it. Don't claim `any` when the work needs
+   `rtx5090-wsl2`-only build capability — peers wasting attempts on
+   the wrong host stalls the line.
+
+## Example card
+
+```
+id: #1085
+branch: fix/install-tier-name-divergence
+owner: @codex (cloud)
+status: in-progress
+blockers: pr-1085-amd64-image-rebuild (waiting on linux/amd64 host)
+env: linux-amd64-any (for image rebuild step only — code changes are
+     environment-agnostic)
+evidence: prepush 61bdeb407: TS+ESLint+Rust 27/27 + bash-n + jq +
+          compose-config all green
+next action: capable Linux/amd64 host runs scripts/push-current-arch.sh
+             at sha 61bdeb407 to rebuild pr-1085 amd64 images
+last heartbeat: 2026-05-13T17:35Z @ 61bdeb407
+```