@mmerterden/multi-agent-pipeline 20.28.0 → 20.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "20.28.0",
+  "version": "20.30.0",
   "description": "6-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",
@@ -86,6 +86,7 @@
     "CHANGELOG.md",
     "LICENSE",
     "SECURITY.md",
+    "!pipeline/office-src/**",
     "!pipeline/scripts/smoke-figma-config-schema.sh",
     "!pipeline/scripts/smoke-personal-data.sh",
     "!pipeline/scripts/validate-prefs.mjs",

package/pipeline/commands/multi-agent/analysis/SKILL.md

@@ -66,7 +66,9 @@ The template is platform-agnostic (Locked 22). It speaks in concepts (state hold
 
 ### Phase 0 - Intake
 
-Full picker chain: `$HOME/.claude/multi-agent-refs/analysis/intake.md`. Sequential `AskUserQuestion` steps filling `state.analysisSpec.*`: analysis name, analysis profile, account, platform multi-select, repos per platform, the six-question source batch (Figma / Swagger / Confluence / Jira / Standards / Firebase) and the two coverage opt-ins. Step narration is required - the chain length is known up front, so every step prints its breadcrumb.
+First, record the run so its hooks see an analysis run: `S="$HOME/.claude/logs/multi-agent/$TASK_ID"; mkdir -p "$S"; printf '{"taskId":"%s","mode":"analysis","status":"in_progress","currentPhase":0}' "$TASK_ID" | node $HOME/.claude/scripts/write-state.mjs "$S/agent-state.json"`.
+
+Full picker chain: `$HOME/.claude/multi-agent-refs/analysis/intake.md`. Sequential `AskUserQuestion` steps filling `state.analysisSpec.*`: analysis name, analysis profile, account, platform multi-select, repos per platform, the six-question source batch (Figma / Swagger / Confluence / Jira / Standards / Firebase) and the two coverage opt-ins. Every step prints its breadcrumb.
 
 ### Phases 1, 1b, 1b.1, 1c - Evidence gathering
 

package/pipeline/commands/multi-agent/autopilot-on/SKILL.md

@@ -206,25 +206,23 @@ installer puts it; the runner tries the captured path first, then that `PATH`.
 "Configure only" is a real answer and the safe default to offer first: the queue
 can be watched with `autopilot-status` for a while before anything runs.
 
-On **Start**:
+On **Start**, load the schedule and the awake agent with the same script the
+office panel's `POST /v1/autopilot/on` calls, naming every repo selected in step 3:
 
 ```bash
-launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.multi-agent.autopilot.plist" 2>/dev/null \
-  || launchctl load "$HOME/Library/LaunchAgents/com.multi-agent.autopilot.plist"
+node "$HOME/.claude/scripts/autopilot-control.mjs" on --repo <owner/name> [--repo <owner/name>...]
 ```
 
-Then the awake agent, rendered from
-`templates/multi-agent-autopilot-awake.plist.template` with the `awake.display`
-answer saved above:
-
-```bash
-. "$HOME/.claude/lib/autopilot-state.sh"
-node "$(ma_ap_asset scripts/autopilot-awake.mjs)" install
-```
-
-A non-zero exit means launchd refused the job: say so, with its path, and say
-the Mac may sleep between ticks until it is fixed. The schedule itself stays on.
-"Configure only" installs neither.
+It keeps exactly those repos in `config.json`, probes their credentials again
+(`autopilot-arming.mjs probeCredentials`), renders
+`templates/multi-agent-autopilot.plist.template` with its seven placeholders
+(NODE, TICK, LABEL, ROOT, INTERVAL, HOME, CLAUDE), loads it with `launchctl
+bootstrap` (falling back to `load`) and installs the awake agent with the
+`awake.display` answer saved above. `scheduled: false` with probe problems means
+nothing was loaded; say so with the problems. Exit 1 with `launchd refused`
+means launchd refused the job: say so, with its path, and say the Mac may sleep
+between ticks until it is fixed. "Configure only" is `--configure-only`, which
+saves the selection and installs neither.
 
 ### 9. Report what is now true
 

package/pipeline/commands/multi-agent/office-off/SKILL.md

@@ -0,0 +1,27 @@
+---
+description: "Close the office panel and stop its local server. Use when done with the panel."
+description-tr: "Ofis panelini hemen kapatır: office-on'un başlattığı yerel sözleşme sunucusunu durdurur. Arkada hiçbir şey kalmaz (relay yok, oturum yok, izleyici yok)."
+argument-hint: "(no arguments)"
+parameters: []
+gui: button
+destructive: false
+confirm: none
+allowed-tools: Bash
+---
+
+# multi-agent office-off  -  close the panel
+
+Stops the server `office-on` started, through the same script:
+
+```bash
+node "$HOME/.claude/scripts/office-control.mjs" off --json
+```
+
+Only the pid `office-on` recorded is signalled (SIGTERM), and only when its
+token file still names it, its command is `contract-server.mjs` and its start
+time matches; no other process is looked up or touched. The server removes its
+token file on the way out, so the old page stops working.
+
+Report in `outputLanguage`: whether a server was stopped (`stopped`), and the
+`remote` line as the script gives it. A panel that was already closed is not
+an error.

package/pipeline/commands/multi-agent/office-on/SKILL.md

@@ -0,0 +1,50 @@
+---
+description: "Open the office panel: a local browser page with agents at work, their chats, cost ledger and new runs. Use when you want to watch or drive runs from a browser."
+description-tr: "Ofis panelini açar: çalışan her ajanı (koşu başına bir masa, ekip faz sırasıyla oturur), sohbetlerini, maliyet defterini, autopilot'u, rutinleri, stack'leri, toolkit araçlarını ve yeni koşu başlatmayı gösteren yerel web sayfası. Yerel sözleşme sunucusunu gerektiğinde başlatır; panel kapanınca hiçbir şey çalışmaz."
+argument-hint: "(no arguments)"
+parameters: []
+gui: button
+destructive: false
+confirm: none
+allowed-tools: Bash
+---
+
+# multi-agent office-on  -  open the panel
+
+The panel is a page (`$HOME/.claude/office/index.html`) served by the
+pipeline's local contract server (`contract-server.mjs`, 127.0.0.1 only, a
+fresh bearer token per start). This command and `office-off` /
+`office-status` share one script, `office-control.mjs`.
+
+## Steps
+
+1. **Start or reuse the server and open the browser:**
+
+   ```bash
+   node "$HOME/.claude/scripts/office-control.mjs" on --json
+   ```
+
+   It starts `contract-server.mjs` in the background with the panel page, or
+   reuses the one it started earlier, then opens the browser at `/office` with
+   a one-time code in the URL fragment (valid 10 seconds, one use, handed over
+   through a 0600 launcher file, never on a command line), which the
+   page trades for the token. The token is never printed; do not read the
+   token file or pass `--print-token` yourself, since anything printed lands
+   in this transcript.
+
+2. **Report** (in `outputLanguage`): the page URL (`url`, without a code),
+   whether a server was started or reused, that it stops by itself after
+   `idleMinutes` without a request (and after 8 hours in any case), and that
+   `/multi-agent:office-off` stops it now. If `opened` is false, tell the user
+   to run the command again from a desktop session; a link works once, so a
+   reload of the page needs a new `office-on`.
+
+## What it does not do
+
+- No daemon, hook or file watcher: when the page is closed, the server exits
+  after its idle time and nothing else runs.
+- The panel's writes call the same scripts the terminal commands call; it adds
+  no behaviour of its own.
+- The server listens on 127.0.0.1 only. Remote access is not part of this
+  installation; `office-status` says whether a separate remote layer is
+  present.

package/pipeline/commands/multi-agent/office-status/SKILL.md

@@ -0,0 +1,29 @@
+---
+description: "Whether the office panel is running, its URL (never the token) and its last actions. Use when unsure if the panel is open."
+description-tr: "Ofis panelinin durumunu raporlar: yerel sunucu çalışıyor mu, sayfa adresi (token asla), boşta kapanma süresi, uzak erişim, eşleşmiş telefonlar ve panelden yapılan son işlemler."
+argument-hint: "(no arguments)"
+parameters: []
+gui: button
+destructive: false
+confirm: none
+allowed-tools: Bash
+---
+
+# multi-agent office-status  -  what the panel is doing
+
+```bash
+node "$HOME/.claude/scripts/office-control.mjs" status --json
+```
+
+Report in `outputLanguage`:
+
+- `running`, and when it is, `url` and `idleMinutes`;
+- `remote`: "not available in this installation" unless a separate remote
+  layer is installed; report the line as given;
+- `pairedDevices`: the devices the phone registry lists; revoking one is
+  `phone-devices.mjs revoke`;
+- `recentActions`: the last writes taken through the server (route, step,
+  status, when, and whether from the panel page), from
+  `office-actions.jsonl`. They carry no request body.
+
+Never print the token or read the token file.

package/pipeline/commands/multi-agent/resume/SKILL.md

@@ -99,8 +99,9 @@ Read `state.waitingFor` FIRST: when it names a step, the run re-enters THAT step
 | `maturity` | Phase 0, the maturity step, with the item **re-fetched** and re-scored - an edit is a reason to look again, never proof the gap closed (`$HOME/.claude/multi-agent-refs/features/maturity-followup.md`); after a research pass that proceeded, re-scored through `research-gate.mjs --recheck` |
 | `user-channels-choice` | Phase 5, the channels multi-select, with the stored `channelsInput` |
 | `local-test` | Phase 3, the user-test gate, with the checkout the gate was waiting on |
+| `attended-reply` | `currentPhase`, at the step that asked for a typed reply: ask it again |
 | `question` | The step `state.pendingQuestion.stepId` names, after the answer is recorded (below) |
-| absent | `currentPhase + 1`, as before (same pipeline as the main multi-agent command) |
+| absent or `null` | `currentPhase + 1`, as before (same pipeline as the main multi-agent command) |
 
 **`--answer <optionId>`** answers `state.pendingQuestion` ({id, stepId, text, kind, options[]}) without a picker, which is how a client or a second terminal replies to a run parked on a question:
 

package/pipeline/commands/multi-agent/serve/SKILL.md

@@ -61,5 +61,7 @@ environment `launch.json` declares; the client starts the process.
 `POST /v1/runs/{id}/answer` accepts only an option the run's pending question
 offered. `POST /v1/runs/{id}/kill` and `POST /v1/gc` act only on a second
 request carrying the single-use confirm token the first one returned, and a
-kill never deletes the remote branch or the logs. Autopilot can be turned off
-over HTTP, never on.
+kill never deletes the remote branch or the logs. Autopilot on, a stack change
+and a routine removal take the same two steps, accept no browser origin but
+the server's own page, and are tagged `local-only` for any future remote
+carrier.

package/pipeline/commands/multi-agent/stack/SKILL.md

@@ -105,14 +105,21 @@ ON=$(MP="$MP" node -e 'import(process.env.HOME+"/.claude/scripts/_stack-routing.
 })' "$@") || exit 1
 ```
 
-After resolving `$ON`, edit `.claude/settings.json` (create `{ "enabledPlugins": {} }` if absent) so that:
-- every plugin in `$ON` is set to `true`,
-- every stack toolkit **not** in `$ON` is set to `false` (leave non-`@multi-agent-plugins` entries untouched),
-- `ai-common-toolkit@multi-agent-plugins` and `ai-analyst-toolkit@multi-agent-plugins` are always `true`,
-- every `ai-*-engineering-toolkit@multi-agent-plugins` key is **deleted** (retired names).
-- `xcode-integration@xcode-apple` follows `ios` (`true` with it, `false` without), only when `~/.claude/xcode-apple-marketplace` exists.
-
-Use the Read + Edit/Write tools (JSON must stay valid). Then print the resulting `enabledPlugins` block and run step 5 (Copilot/Codex refresh offer).
+Then write it with the one writer of these rules (the office panel's
+`POST /v1/stack` calls the same script):
+
+```bash
+node "$HOME/.claude/scripts/stack-toggle.mjs" set --repo "$PWD" "$@" --json
+```
+
+`stack-toggle.mjs` applies the write rules above (selection `true`, every other
+stack toolkit `false`, `ai-common-toolkit` and `ai-analyst-toolkit` always
+`true`, retired `ai-*-engineering-toolkit` keys deleted, `xcode-integration@xcode-apple`
+following `ios` when the Apple marketplace is linked, every other key kept),
+writes the file atomically and prints the resulting `enabledPlugins`. It refuses
+an empty selection and an unknown stack (exit 1) and never hand-edits the JSON.
+`stack-toggle.mjs status --repo "$PWD" --json` is the read for status mode.
+Then print the resulting `enabledPlugins` block and run step 5 (Copilot/Codex refresh offer).
 
 ## Notes
 

package/pipeline/commands/multi-agent/steer/SKILL.md

@@ -71,18 +71,19 @@ is being replaced.
    and `$INSTRUCTION` the text from step 3:
 
    ```bash
-   printf '{"pendingSteer":{"text":%s,"at":"%s","appliedAt":null,"appliedPhase":null}}' \
-     "$(node -e 'process.stdout.write(JSON.stringify(process.argv[1]))' "$INSTRUCTION")" \
-     "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-     | node $HOME/.claude/scripts/write-state.mjs "$STATE_FILE"
+   node "$HOME/.claude/scripts/steer-run.mjs" "$STATE_FILE" --text "$INSTRUCTION"
    ```
 
-   The instruction is JSON-encoded by `node -e`, not by hand: it is arbitrary
-   user text, and a quote or newline in it would otherwise produce invalid JSON
-   or, worse, a payload that merges into fields nobody meant to touch.
+   `steer-run.mjs` takes the same lock `write-state.mjs` owns and merges
+   `pendingSteer` (`text`, `at`, `appliedAt: null`, `appliedPhase: null`) into
+   the state; the instruction is passed as one argument and JSON-encoded by the
+   script, never by hand, so a quote or newline in it cannot produce invalid
+   JSON or a payload that merges into other fields. It refuses a finished run
+   (exit 1) and prints the unconsumed instruction it replaced, if any. The
+   office panel's `POST /v1/runs/{id}/steer` calls the same function.
 
-   Exit 2 (lock timeout) → the task is mid-write. Retry once, then report it
-   rather than forcing the write.
+   Exit 2 (usage) or a lock timeout → the task is mid-write. Retry once, then
+   report it rather than forcing the write.
 
 6. **Confirm**: `🧭 Steer queued for #N  -  applies at the entry to Phase {N+1}`
 

package/pipeline/commands/multi-agent/sync/SKILL.md

@@ -73,7 +73,7 @@ Run every step automatically:
 ```
 Step 0: DOCTOR      doctor.mjs  -  exit 2 or 4 stops the sync
 Step 1.5: DETECT    Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 66 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 69 sub-command skills)
 Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + sub-command specs as refs + agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
@@ -241,14 +241,14 @@ same specs as reference files rather than as peer skills, via Step 2b -  see
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**66 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**69 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off, autopilot-on,
 autopilot-status, bug-bash, build-optimize, channels, complaint-analysis, create-jira,
 design-check, diff-explain, doctor, estimate, feedback, forget, garbage-collect, graph, help,
 ios-coding-standard, issue, jira, kill, language, log,
-manual-test, model, postmortem, prune-logs, prune-prompts, purge, refactor, research, resume, review, review-analysis, review-issue, review-jira, route-off, route-on, route-status,
+manual-test, model, office-off, office-on, office-status, postmortem, prune-logs, prune-prompts, purge, refactor, research, resume, review, review-analysis, review-issue, review-jira, route-off, route-on, route-status,
 routines, save, scaffold, scan, scenario-audit, search, security-review, serve, setup, stack, status, steer, store-ready, sync, test,
 test-accessibility, test-dark-mode, test-dynamic-type, test-gen, test-screenshots,
 testflight-validation, uninstall, update

package/pipeline/contract/CHANGELOG.md

@@ -3,6 +3,68 @@
 Versions of the client contract (`manifest.json` `contractVersion`), separate
 from the package version. See `README.md` for what counts as minor and major.
 
+## 1.4.0
+
+Added. Nothing existing changes shape; one narrowing for browser pages.
+
+- `remote` and `risk` on every surface in `manifest.json` and every route in
+  `ROUTES`: the scope a remote carrier would require (`read`, `answer`,
+  `launch`, `local-only`) and the confirmation tier (`read`, `low`, `high`).
+- `GET /v1/activity` and `GET /v1/activity/stream` (`activity.schema.json`):
+  a room per repository, a table (team) per run, a seat per agent; the stream is
+  `text/event-stream`, at most 4 at once (429 `too-many-streams`).
+- `GET /v1/agents/{sessionId}/{agentId}/chat` (`activity-chat.schema.json`):
+  one page of an agent's transcript, redacted; `before`, `limit`.
+- `POST /v1/autopilot/on` (two steps, `autopilot-on.schema.json`), `POST
+  /v1/runs/{id}/steer` (two steps, `launch`/`high`: the text and a preview
+  with a token bound to the run and the text, then the token alone;
+  `steer.schema.json`), `GET /v1/routines`, `DELETE /v1/routines/{name}` (two
+  steps), `GET /v1/stack`, `POST /v1/stack` (two steps).
+- `GET /v1/ledger` (`ledger.schema.json`): tokens and estimated USD today, this
+  week and this month, by run, repository, model and phase, each amount with
+  its source; an unmeasurable run is `not-measured`, never 0.
+- `GET /v1/runs/{id}/results` and `/evidence/{name}`: diff summary, review
+  findings, test outcome, screenshots and analysis documents from the run's
+  own files; a document is read only inside the run's roots (log directory,
+  artifacts, a worktree git lists) and only as Markdown or HTML.
+- `GET /v1/issues/{key}/maturity` (lib/issue-fetcher.sh), `GET /v1/prs`
+  (GitHub; Bitbucket reported as not implemented), `POST
+  /v1/runs/{id}/review-verdict` (two steps, lib/post-pr-review.sh; only for a
+  finished review with every finding triaged, 409 `review-incomplete`
+  otherwise; the token is bound to the decision and `findingsDigest`, 409
+  `confirm-mismatch` when they changed).
+- `GET /v1/tools`, `POST /v1/tools/{name}/call` (`local-only`): the
+  registered toolkit MCP server's tools, arguments checked against each
+  inputSchema, risk from each tool's annotations, and `allowed`/`reason`:
+  calls are denied by default (403 `tool-not-allowed`) except for read-only
+  tools that take no location and are outside the web and context families;
+  a `confirm` argument is refused; the toolkit child always runs with
+  `MULTI_AGENT_UNATTENDED=1` and `MCP_TOOLKIT_URL_POLICY=strict`.
+- `GET /v1/services/confluence`, `/crashlytics`, `/figma`: one page, issue or
+  frame through the pipeline's existing clients; a Confluence URL only on the
+  configured host (409 `host-not-allowed`); one request per service at a time
+  (429 `busy`).
+- `GET /v1/permissions`: the shape for pending host permission prompts;
+  `available: false` until the host records them readably.
+- `GET /office`: the optional panel page, 404 when none is installed;
+  `POST /office/code` and `POST /office/exchange` hand the page the token
+  through a one-time 10 second code instead of a URL; `GET
+  /office/assets/<name>.png` serves its sprites.
+- `--max-hours` (default 8): an absolute lifetime for the server.
+- `contract-error.schema.json`: `no-selection`, `repo-not-configured`,
+  `invalid-config`, `not-installed`, `repo-ambiguous`, `unreadable-settings`,
+  `not-removable`, `not-steerable`, `too-many-streams`, `no-review`,
+  `upstream-failed`, `tool-not-allowed`, `busy`, `review-incomplete`,
+  `host-not-allowed`.
+- Narrowed: a write (POST, DELETE) from a page on an `--allow-origin` origin is
+  now 403 `forbidden-origin`; only the server's own page may write. A native
+  client sends no Origin and is unaffected.
+- `?repo=` also takes a repository name from `GET /v1/repos` (on the stack
+  route and on `POST /v1/launch`), since a browser reads that list redacted,
+  without paths. The repository must still be a configured or registered one:
+  an unknown name is 403 `repo-not-allowed`, an ambiguous one 409
+  `repo-ambiguous`. A relative path is no longer 400 but resolved as a name.
+
 ## 1.3.0
 
 Added. Every new field is optional for a decoder: a run written before this

package/pipeline/contract/README.md

@@ -51,6 +51,31 @@ same bytes (`test/contract-parity.test.mjs`):
 | Garbage-collect (two steps) | `gc-plan.mjs preview [--scope S,...]`, then `gc-plan.mjs apply < items` | `POST /v1/gc` |
 | Autopilot status | `autopilot-control.mjs status` | `GET /v1/autopilot` |
 | Autopilot off | `autopilot-control.mjs off [--now]` | `POST /v1/autopilot/off` |
+| Autopilot on (two steps) | `autopilot-control.mjs on-preview --repo R...`, then `on --repo R... [--configure-only]` | `POST /v1/autopilot/on` |
+| Steer a run (two steps on the server) | `steer-run.mjs STATE --text T` | `POST /v1/runs/{id}/steer` |
+| Agent activity | `activity-snapshot.mjs --json` | `GET /v1/activity`, `GET /v1/activity/stream` (SSE) |
+| An agent's chat | `activity-snapshot.mjs chat SESSION [AGENT] [--before N] [--limit N]` | `GET /v1/agents/{sessionId}/{agentId}/chat` |
+| Cost ledger | `office-ledger.mjs --json` | `GET /v1/ledger` |
+| What a run produced | `run-results.mjs ID --json` | `GET /v1/runs/{id}/results` |
+| One screenshot | `run-results.mjs ID --evidence NAME` | `GET /v1/runs/{id}/evidence/{name}` |
+| Post a review verdict (two steps) | `work-items.mjs verdict ID [--post]` | `POST /v1/runs/{id}/review-verdict` |
+| An issue's maturity | `work-items.mjs maturity KEY` | `GET /v1/issues/{key}/maturity` |
+| Open pull requests | `work-items.mjs prs` | `GET /v1/prs` |
+| Toolkit MCP tools | `toolkit-tools.mjs list` | `GET /v1/tools` |
+| Call an allowed toolkit tool (read-only, no location argument) | `toolkit-tools.mjs call NAME JSON` | `POST /v1/tools/{name}/call` |
+| A Confluence page, a Crashlytics issue, a Figma frame | `service-read.mjs confluence\|crashlytics\|figma ...` | `GET /v1/services/{confluence,crashlytics,figma}` |
+| Pending host permission prompts | (none can be read yet) | `GET /v1/permissions` |
+| Routines | `routine-registry.mjs list --json` | `GET /v1/routines` |
+| Remove a routine (two steps) | `routine-registry.mjs remove --name N` | `DELETE /v1/routines/{name}` |
+| A repo's stacks | `stack-toggle.mjs status --repo P --json` | `GET /v1/stack?repo=R` |
+| Set a repo's stacks (two steps) | `stack-toggle.mjs set --repo P STACK... --json` | `POST /v1/stack` |
+
+Every surface in `manifest.json` carries `remote` (the scope a remote carrier
+would require: `read`, `answer`, `launch`, or `local-only` for anything that
+widens what runs on this machine: autopilot on, stack, routine removal, kill,
+gc) and `risk` (the confirmation tier: `read`, `low`, `high`). Locally the
+bearer token is the only credential; nothing enforces the tags yet. They are
+there so a later carrier reuses these routes without redefining them.
 
 Starting a run is always the client's act. `POST /v1/launch` validates the
 request, writes it (0600) and returns the argv, environment and working
@@ -90,7 +115,8 @@ Resuming is the client's act too: `POST /v1/runs/{id}/resume` returns the plan
 root, `409 not-resumable` for any other, a finished or a killed one, and `409
 run-active` while its session runs.
 
-Kill and gc remove things, so each takes two requests. The first (no
+Kill, gc, autopilot on and a stack change take two requests (a routine
+removal takes its token as `?confirm=`). The first (no
 `confirmToken`) returns the preview with `confirmToken` and `expiresAt`; the
 second sends the token back and acts on exactly what was previewed. A token is
 single use, lives 120 seconds in the server's memory only, and is bound to the
@@ -113,14 +139,34 @@ answer to the old one.
   that spawned the server can pass `--print-token` to get it on the ready line.
 - Every request sends `Authorization: Bearer <token>` and a `Host` of
   `127.0.0.1:<port>` or `localhost:<port>`.
-- A browser page is allowed only from an origin passed with `--allow-origin`;
-  CORS is off without one. A request carrying an `Origin` is always served
-  redacted.
+- A browser page is allowed only from the server's own origin (the optional
+  panel at `GET /office`) or an origin passed with `--allow-origin`; CORS is
+  off without one. A write (POST, DELETE) and the chat route accept no Origin
+  but the server's own, even an allowed one. A request carrying an `Origin` is
+  always served redacted.
+- The token is read from the `Authorization` header only, never from a cookie
+  or a query parameter.
+- `GET /office` serves the panel page (`MA_OFFICE_PAGE`, else
+  `prefs.global.office.page`, else the installed `office/index.html` beside the
+  package) without a token, with a per-response CSP nonce, and is 404 when no
+  page exists. The page never sees the token in a URL: `POST /office/code`
+  (bearer, no Origin) mints a code valid for 10 seconds and one use, the page
+  is opened with it in the fragment, and trades it at `POST /office/exchange`
+  (own Origin only, no bearer); a used, expired or unknown code is 401.
+  `GET /office/assets/<name>.png` serves the page's sprites, also without a
+  token: a plain file name, a PNG of at most 256 KiB directly in the assets
+  directory beside the page, and 404 for anything else.
+- Every write route appends one line (who, route, step, status; never a body
+  or token) to `~/.claude/logs/multi-agent/office-actions.jsonl`.
 - Bodies are JSON, at most 64 KiB, and must satisfy the route's schema.
 - Errors follow `contract-error.schema.json`; switch on `error`, never on
   `message`.
-- The server exits after 15 idle minutes (`--idle-minutes`) or on SIGTERM. It
-  is never a service; start it when you need it.
+- Service reads, the work list, the review verdict and autopilot control run
+  in child processes and never block other routes; a second request for the
+  same one while the first runs is 429 `busy`.
+- The server exits after 15 idle minutes (`--idle-minutes`), after 8 hours in
+  any case (`--max-hours`, an open event stream does not extend it) or on
+  SIGTERM. It is never a service; start it when you need it.
 
 A client that relays anything off this machine uses `redact=1` (or
 `--redact`) for every read.

package/pipeline/contract/fixtures/error-invalid-request.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.3.0",
+  "contractVersion": "1.4.0",
   "error": "invalid-request",
   "message": "the launch request was refused",
   "errors": [

package/pipeline/contract/fixtures/error-unauthorized.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.3.0",
+  "contractVersion": "1.4.0",
   "error": "unauthorized",
   "message": "a bearer token is required"
 }

package/pipeline/contract/fixtures/error-unsigned.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.3.0",
+  "contractVersion": "1.4.0",
   "error": "unsigned",
   "message": "a device signature is required"
 }