specrails-desktop 2.64.2 → 2.65.0

package/docs/internals/legacy-implementation-notes.md

@@ -6,6 +6,19 @@ reflect older implementations; current code, tests, AGENTS.md and the architectu
 decision take precedence. Search the relevant feature instead of loading the
 whole document. Relative links below were originally relative to the repo root.
 
+Known superseded entries (verified 2026-10-21; the current behaviour wins):
+
+- **Revision loop.** `factory:revision` is no longer a fourth factory loop; it is a
+  legacy id aliased to `factory:sdd-quick-openspec` (see [review packet](review-packet.md)).
+- **Setup wizard.** Retired; projects are added silently with background workspace
+  assembly (see [architecture](architecture.md#project-add-and-workspace-assembly)).
+- **Ultracode.** Renamed Freestyle; `ultracode` survives only as an input alias that
+  `normalizeRailMode` maps to `freestyle` for older Companion builds.
+- **`sr:why` / explanations, health-check, compat-check, refactor-recommender.**
+  Retired from Core; Core 6 ships only the `implement` and `retry` commands.
+- **Core pins.** Any `^4.x` / `^5.x` range quoted below is historical; the current
+  range is `CORE_PACKAGE_SPEC` in `server/core-package.ts`.
+
 ---
 
 # CLAUDE.md

package/docs/internals/local-testing-feedback-2026-10.md

@@ -0,0 +1,210 @@
+# Local testing: feedback-2026-10 program
+
+How to run this Desktop branch (`local/feedback-2026-10`, worktree
+`/Users/javi/repos/wt/desktop-local`) in dev against the local Core branch
+(`local/feedback-2026-10`, worktree `/Users/javi/repos/wt/core-local`), and a
+smoke checklist covering every feature of the program. Nothing here pushes or
+publishes anything.
+
+## 1. How Desktop finds Core in dev
+
+`npm run dev` starts `tsx watch server/index.ts` (API on `127.0.0.1:4200`) and
+Vite (`4201`, proxies `/api`). There is no bundled Core in dev.
+
+- **`SPECRAILS_CORE_BIN`** is the override for everything (`server/core-runtime.ts`
+  `resolveCoreRuntime`): framework install, `check-core-compat`, the update
+  card and the agent runtime (`<core>/dist/agent-runtime/{index,cli}.js`, found
+  next to the selected package). It may point at `bin/specrails-core.mjs` of a
+  checkout; Desktop walks up to its `package.json` and needs
+  `dist/installer/cli.js`. It is rejected when its version is older than
+  `~/.specrails/framework/current` (no downgrades) or its major is not 4–6.
+- **`SPECRAILS_CORE_RUNTIME_PATH`** (optional) pins the agent runtime entry
+  (`<core>/dist/agent-runtime/index.js`) explicitly.
+- **`SPECRAILS_FRAMEWORK_AUTOSWAP=false`** stops the boot-time framework swap.
+  Without it, a newer local Core is materialized into
+  `~/.specrails/framework/<version>` and `current` moves there, which your normal
+  Desktop then cannot resolve without the override.
+- `npm link` is not used.
+
+## 2. Build the local Core
+
+The Core branch exposes contract 5.7, role instructions 17, node kinds 8 and
+the `runtime api` capabilities `sessions`, `flowSessions`, `reviewBrief`,
+`deriveChange`, `architectClarifications`, `specTrace`, `baselineOnTouch` and
+`rulesInventory`. Build it before running Desktop or the paired tests.
+
+```sh
+git -C /Users/javi/repos/wt/core-local status --short     # expect no "UU" lines
+cd /Users/javi/repos/wt/core-local
+npm ci                       # only if dependencies changed (node_modules is shared with /Users/javi/repos/specrails-core)
+npm run build                # tsc → dist/
+node bin/specrails-core.mjs runtime api | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const c=JSON.parse(s).capabilities;console.log({architectClarifications:c.architectClarifications,specTrace:c.specTrace,baselineOnTouch:c.baselineOnTouch,rulesInventory:c.rulesInventory,reviewBrief:c.reviewBrief,deriveChange:c.deriveChange,flowSessions:c.flowSessions,sessions:c.sessions})})'
+```
+
+If `runtime api` does not print JSON in your build, check the capabilities
+from Desktop instead (step 4). The version in `core-local/package.json` equals
+the released 6.6.5, so the version number alone does not prove the local
+checkout is active.
+
+## 3. Run Desktop dev against it
+
+Run with your real `HOME`, after backing up the SQLite databases.
+
+**Why not an isolated `HOME`.** On macOS, changing `HOME` breaks the provider
+logins: the Claude CLI keeps its credentials in the login keychain keyed to
+the real home, so `claude`, `codex` and `gemini` look unauthenticated and every
+run fails. Running against your real data is safe because migrations 72–78 of
+this branch are additive (new tables and columns only): the released Desktop
+keeps working on the same databases after you go back to it.
+
+1. Close the released Desktop app, then back up every SQLite file
+   (`desktop.sqlite` and each project's `jobs.sqlite`, with their WAL/SHM
+   siblings), skipping the tool and runtime caches:
+
+   ```sh
+   BACKUP=~/specrails-db-backup-$(date +%Y%m%d)
+   mkdir -p "$BACKUP" && cd ~/.specrails && find . -name "*.sqlite*" -not -path "./tools/*" -not -path "./runtimes/*" | cpio -pdm "$BACKUP"
+   ```
+
+2. Start Desktop dev against the local Core:
+
+   ```sh
+   cd /Users/javi/repos/wt/desktop-local
+   SPECRAILS_CORE_BIN=/Users/javi/repos/wt/core-local/bin/specrails-core.mjs \
+   SPECRAILS_CORE_RUNTIME_PATH=/Users/javi/repos/wt/core-local/dist/agent-runtime/index.js \
+   SPECRAILS_FRAMEWORK_AUTOSWAP=false \
+   npm run dev
+   ```
+
+   Keep `SPECRAILS_FRAMEWORK_AUTOSWAP=false`: without it the newer local Core
+   is materialized into `~/.specrails/framework/<version>` and `current` moves
+   there, which the released Desktop then cannot resolve.
+
+3. Restore (only if needed): close both the dev server and the released app,
+   then copy the backup back over `~/.specrails`
+   (`cd "$BACKUP" && find . -name "*.sqlite*" | cpio -pdmu ~/.specrails`).
+
+- Use other ports if your normal Desktop is running:
+  `SPECRAILS_DEV_SERVER_PORT=4300 SPECRAILS_DEV_CLIENT_PORT=4301`.
+- After rebuilding Core, restart `npm run dev` (`tsx watch` only watches
+  Desktop files, and capabilities are read at startup).
+- Contract check against the same Core (optional):
+  `SPECRAILS_CORE_BIN=/Users/javi/repos/wt/core-local/bin/specrails-core.mjs npm run check-core-compat`.
+  A new Core checkpoint or verb makes it report incompatible; that is expected
+  until the Core branch is released and paired.
+
+Open `http://127.0.0.1:4201`.
+
+## 4. Verify which Core is active
+
+```sh
+TOKEN=$(cat ~/.specrails/desktop.token)
+curl -s -H "x-desktop-token: $TOKEN" http://127.0.0.1:4200/api/core-update/status   # runtimeSource: "override", runtimeVersion
+curl -s -H "x-desktop-token: $TOKEN" http://127.0.0.1:4200/api/meta                 # apiVersion and versions
+curl -si http://127.0.0.1:4200/api/health | grep -i x-specrails-api-version
+curl -s -H "x-desktop-token: $TOKEN" http://127.0.0.1:4200/api/projects/<projectId>/core/phase3-capabilities
+```
+
+The server log prints `[SetupManager] spawning core: …/core-local/bin/specrails-core.mjs`
+when a project is set up. `phase3-capabilities` must show `true` for every
+capability (all four are `true` with the local Core).
+
+## 5. Test project
+
+Use a throwaway repository with a test runner, at least one OpenSpec
+capability and a `CLAUDE.md`/`AGENTS.md` with a few rules:
+
+```sh
+mkdir -p /tmp/sr-smoke && cd /tmp/sr-smoke && git init -q && npm init -y >/dev/null
+npm i -D vitest >/dev/null && npm pkg set scripts.test="vitest run" scripts.lint="node -e 0"
+mkdir -p openspec/specs/search src && printf '### Requirement: Finds by title\nThe search SHALL match titles.\n\n### Requirement: Empty query\nAn empty query SHALL return nothing.\n' > openspec/specs/search/spec.md
+printf '# Rules\n- API calls use getApiBase()\n- Copy is reviewed by design\n' > AGENTS.md
+git add -A && git commit -qm init
+```
+
+Test projects need at least one commit: Flow and isolated rail launches
+create a worktree from the base branch, so a repository with an unborn HEAD is
+refused with "This repository has no commits yet" (`409
+repository_has_no_commits`). The `git commit` above covers it.
+
+Add it in Desktop (Add project), configure a provider, and set
+`.specrails/agent-runtime.json` verification to `npm test` (or accept the
+suggestion in Project settings ▸ Agent runtime).
+
+## 6. Smoke checklist
+
+Mark each line. "Core" means the capability must be announced by the local
+Core; without it the feature must be absent and nothing else may change.
+
+### Phase 0–1: review capacity
+- [ ] **Budget guard.** Project settings ▸ Budget: set a tiny daily cap, launch a rail → `409 daily_budget_exceeded` card; a running loop pauses between AI steps (`budget_paused`) and resumes after raising the cap.
+- [ ] **WIP limit.** Project settings ▸ Review limit = 1. With one delivery on review, the board badge reads "In review 1/1", Play is disabled with a tooltip, Launch all holds rails back; a Relaunch/revision of the existing delivery still works.
+- [ ] **Risk brief** (Core `reviewBrief`). After a run, the review packet opens with **What to look at** (risks high first); the draft PR body has the brief; mission/delivery cards show the top risk.
+- [ ] **Decision times.** Analytics shows time to decision / merge per loop; deciding a delivery updates it.
+- [ ] **Reviewer suggestion.** In a loop's agents editor, put reviewer and developer on the same model family → the "use another family" suggestion appears; Dismiss persists per project.
+
+### Phase 2: Flow (Core `sessions`, `flowSessions`, `deriveChange`)
+- [ ] **Triage chip.** A new spec gets a triage chip (size, recommended loop); the rail launch preselects the recommended loop; `POST /tickets/:id/triage` recomputes.
+- [ ] **Offer → entry.** In a mission, ask to explore an idea → a Flow offer card; accept → Flow bar, In Flow label on the board.
+- [ ] **Interrupt.** Send a message while the agent works → it is delivered mid-turn (no queue wait).
+- [ ] **"This is it".** Press it → launch card with **Flow → Spec** preselected; Launch.
+- [ ] **Flow → Spec loop.** The run derives the OpenSpec change; the packet shows **Derivation** (N/M files explained).
+- [ ] **Summary carries the conversation.** `.specrails/pipeline/<runId>/flow-summary.md` lists every message you typed in Flow (`transcriptTurns` > 0) with `↳ Agent:` first lines; the packet's Derivation shows the same turn count.
+- [ ] **Change name.** The derived change is `openspec/changes/<kebab spec title>` (no `ticket-N-addenda-…`).
+- [ ] **Repair round.** When the review rejects (or a check fails), the run log shows `fix` (fixer stance) then `derive` again, and the change is updated in place; an approval after the round archives normally.
+- [ ] **Requested changes.** With rounds exhausted, the mission card reads **The reviewer requested changes** with the issues and failing checks (no "Implementation failed · settlement_interrupted"); the rail strip shows **Changes requested** and no Discard.
+- [ ] **Back to Flow.** Press it → the Flow bar returns on the same worktree (files intact), the spec shows In Flow again, the delivery card reads **Back in Flow**, and your next message reaches the agent with the review.
+- [ ] **Relaunch.** From a requested-changes card, Relaunch → a new Flow → Spec run on the same rail and worktree re-derives the same change.
+- [ ] **Spec rewrite.** After settle, the placeholder spec is rewritten from the derived change (Contract Layer applied).
+- [ ] **Jira on review.** With Jira linked, the Flow spec gets its issue created and moved to review only after settle (never while In Flow).
+- [ ] **Companion «In Flow».** In the companion app (`/Users/javi/repos/wt/companion-in-flow`, commit `02c4b79`), the spec shows the In Flow label.
+
+### Phase 4: adoption
+- [ ] **Freestyle on Codex/Gemini.** Launch Freestyle on a rail with Codex, then Gemini → runs and verifies; no capability error.
+- [ ] **Minimal env.** Project settings ▸ Agent environment = minimal; `GET /api/projects/:id/agent-env/status` lists only allowlisted names; a run still authenticates its provider.
+- [ ] **Audit log.** After a run, `GET /api/projects/:id/jobs/:runId/audit?format=csv` lists reads/writes/execs; retention setting saves.
+- [ ] **API meta / update channels.** `X-Specrails-Api-Version: 1` on every `/api` response; `/api/meta` returns the version set; Settings ▸ Updates switches Latest/Stable without downgrading.
+- [ ] **Loop economics.** Analytics ▸ Loop economics lists loops with delivered/merged/discarded, cost split, rounds; unknown values show "no data", never 0.
+
+### Phase 3 + 4.4: this branch
+- [ ] **Out of scope (Quick).** Add spec (Quick) → the spec window shows **Out of scope** under the description, and the description has no Out of Scope section. Edit it (one item per line) and save; reopen → kept.
+- [ ] **Out of scope (Explore).** Explore a spec → the draft panel has an Out of scope list; Create Spec → the ticket has it. Continue editing a spec → its non-goals are kept after Update Spec.
+- [ ] **Agents see non-goals.** Launch Freestyle on that spec → the run log prompt contains `## Out of Scope`.
+- [ ] **Clarifications** (Core `architectClarifications`). Launch Implement on a deliberately ambiguous spec ("Add search; decide whether archived projects appear") → the run pauses with the question. With **Post architect clarifications to Jira** on and the spec linked to Jira, one comment appears on the issue. Reply in Jira; within a poll (≤ 60 s) the spec gets an open **clarification** addendum. A clear spec proceeds and, with the setting on, posts its assumptions instead. Setting off → no comment.
+- [ ] **Requirements demonstrated** (Core `specTrace`). Have the run tag one test `[spec:search/finds-by-title]` → the packet shows **Requirements demonstrated 1/2** with the touched requirement flagged; Analytics ▸ Loop economics shows `1/2 · 50%`.
+- [ ] **CI snippet.** In the test repo, `npx specrails-core pipeline trace --check --tests-passed` exits 1 naming the undemonstrated touched requirement (with an active change), 0 without `--check`.
+- [ ] **Drift sweep.** Loops library lists **Drift sweep** (read-only); running it changes no files and reports contradictions.
+- [ ] **Baseline on touch** (Core `baselineOnTouch`). Settings ▸ Existing-project anchoring ▸ Baseline on touch on. Spec a change to `src/` code no spec mentions → the packet shows **Spec created where the work passed** (module, requirements, tests) and the cost line adds "baseline $X of it". Break a characterization test on purpose → the run stops with "Baseline blocked: the characterization tests do not pass on the unchanged code…".
+- [ ] **Old Core.** Run Desktop without `SPECRAILS_CORE_BIN` (released Core) → anchoring switches disabled with an update note, no new packet sections, drift sweep absent, settle evidence unchanged.
+- [ ] **Rules inventory** (Core `rulesInventory`). Right after adding the project, Project settings ▸ Project rules shows the gates and the rules as **Unclassified** with an "inventoried offline" note (Core `init` runs it offline). **Re-run inventory** (provider configured in agent runtime settings) classifies them into automatable / human only / enforced. **Create spec** on an automatable rule adds a `todo` spec (source `rules`). The packet of the next delivery lists **Needs human eyes**. With no verification commands, Agent runtime ▸ verification shows the plain gates first; saving is explicit. The root `CLAUDE.md` of a Claude project has the `<!-- specrails-managed:start -->` block pointing at `.specrails/rules.json`.
+
+## 7. Automated checks
+
+```sh
+cd /Users/javi/repos/wt/desktop-local
+npm run typecheck
+npx vitest run                         # server
+npm run test --prefix client
+npm run test:scripts
+npm run audit:architecture
+npm run build
+for c in ticket-non-goals-and-jira-clarifications spec-trace-surfaces baseline-on-touch-settings project-rules-inventory; do openspec validate $c --strict; done
+```
+
+Paired engine suites against the local Core (what the CI `paired-core-engine`
+job runs; about 11 minutes):
+
+```sh
+cd /Users/javi/repos/wt/core-local && npm run build
+cd /Users/javi/repos/wt/desktop-local
+export SPECRAILS_CORE_SOURCE_DIR=/Users/javi/repos/wt/core-local
+export SPECRAILS_EFFICIENCY_CORE_ROOT=/Users/javi/repos/wt/core-local
+export SPECRAILS_CORE_BIN=/Users/javi/repos/wt/core-local/bin/specrails-core.mjs
+npm run check-core-compat                       # contract 5.7 (paired target 5.7) ✓ Compatible
+node scripts/paired-core-shards.mjs run 1/1 /tmp/paired.xml
+```
+
+The vendored `server/schemas/agent-runtime.schema.json`,
+`workflow-definition.schema.json` and `fixtures/` are byte-identical to
+`core-local/schemas/`; the schema parity tests compare them when
+`SPECRAILS_EFFICIENCY_CORE_ROOT` is set.

package/docs/internals/mcp-mission-audit.md

@@ -27,6 +27,10 @@ and no remote PRs were created. Source changes are retained on this branch.
 | Operational tools omitted useful review evidence and conversational launch defaults. | Add PR candidates/review packets, Git/worktree information, PR lookup and phase breakdowns. Preserve conversation provider/model/effort when launching compatible jobs/loops, and report when isolation is unavailable. |
 | Binary attachments were forwarded through a text response path. | Return attachment metadata and a download reference instead of decoding arbitrary bytes as text. |
 
+Follow-up (2026-10-21): mission agents now run with each provider's native
+read-only boundary while keeping MCP tools callable. See
+[read-only missions](mission-read-only-policy.md).
+
 ## New investigation workflow
 
 1. Identify the intended project from the conversation pin or durable catalog.

package/docs/internals/mission-rail-cards.md

@@ -28,8 +28,8 @@ Mission mode (Agent Mode) replaces the routed dashboard, so `RailsBoard`, `Specs
                                           + ONE automatic briefing turn
 ```
 
-- **Proposal** — an assistant message with one or more fenced `rail-launch` blocks. Each block is one `AgentRailLaunchCard`; undecided proposals are pinned in the dock above the composer.
-- **Launched** — Play succeeded (202). The proposal freezes into a "Launched → Rail N" stub (persisted on the message row), and the run card takes over.
+- **Proposal** — an assistant message with one or more fenced `rail-launch` blocks. Each block is one `AgentRailLaunchCard`; undecided proposals are live runs of the mission's run strip (above the composer; Launch performs the card's Play) and leave a one-line "Launch proposed" event in their history slot.
+- **Launched** — Play succeeded (202). The proposal freezes into a "Launched → Rail N" stub (persisted on the message row), and the run takes over the run strip (a launching skeleton until its first step shows).
 - **Running / settled / delivery** — the SAME envelope (`PrDecisionCardEnvelope`) carries `phase`, `runtime` and `hasDelivery`. With git, the delivery phase is the pre-existing PR-decision card. Without git, the card is run-only and ends at `completed` / `implementation_failed` / `discarded`.
 
 ## Protocol contract
@@ -107,10 +107,15 @@ WS messages: `agent_pr_decision` (existing, now carries the new fields), `agent_
 - `client/src/features/missions/components/AgentMessage.tsx` — extraction step after spec-draft (flag `FEATURE_MISSION_RAIL_CARDS`); renders `AgentRailLaunchCard` per proposal, `AgentRailLaunchPending`, `AgentRailLaunchUnreadable`.
 - `AgentRailLaunchCard.tsx` — live reconciliation (`/rails` availability, `/tickets`, `/profiles`, `useProviderDetection`, model/effort catalogs, loops), New rail, Play flow (`POST /rails` → `PUT /tickets` → `POST /launch` with `originConversationId` + `originSurface:'agent-chat'` → `notifyGitChanged` → intent PATCH), inline 400/409, launched/dismissed stubs, `FOCUS_PR_CARD_EVENT`.
 - Repository context (`/repositories`) is required before Play. The card shows launch targets and each spec's saved scope, including primary-only historical specs. **Edit → Save repositories** persists only `repositoryIds` through the pinned project's existing ticket PATCH; Cancel leaves it untouched. Saved scope and spec-list changes reconcile required targets while retaining extra launch targets and dropping workspace entries for removed repositories. Optional launch targets do not edit specs. Omitted required targets and missing/offline/context-only implementation targets block Play visibly. **Refresh** reloads assignments; failed loads expose **Retry loading**. The resolved launch scope and filtered workspace selection are frozen in the launched intent, and server admission remains authoritative.
-- `client/src/features/rails/lib/rail-launch-intents.ts` — session overlay (`recordLocalIntent`, `intentFor`); `useRailLaunchProposals.ts` — undecided proposals for the dock; `AgentPrPinnedDock.tsx` — proposals pinned above PR cards.
+- `client/src/features/rails/lib/rail-launch-intents.ts` — session overlay (`recordLocalIntent`, `intentFor`); `useRailLaunchProposals.ts` — undecided proposals for the run strip.
 - `AgentPrDecisionCard.tsx` — run phase header (`deriveMissionRunStatus`, live `useRuntimeRuns` first), run-only rendering for `hasDelivery === false`, `RunFailureBlock`, Resume / Approve / Recover / Relaunch, focus-bus scroll + flash.
-- `agent-pr-pinning.ts` `isPrEnvelopePinned`; `agent-run-failure.ts` (`parseRunFailureRow`, `systemBriefingRunId`, `FOCUS_PR_CARD_EVENT`, `MISSION_OPEN_RUN_EVENT`, `requestMissionOpenRun`); `AgentRunFailureMarker.tsx`.
+- `agent-pr-pinning.ts` `isPrEnvelopePinned` (a live delivery: the strip shows it); `agent-run-failure.ts` (`parseRunFailureRow`, `systemBriefingRunId`, `FOCUS_PR_CARD_EVENT`, `OPEN_RUN_STRIP_EVENT`, `MISSION_OPEN_RUN_EVENT`, `requestMissionOpenRun`); `AgentRunFailureMarker.tsx` (the failure as one history line in plain words).
+- **Run strip** (`AgentRunStrip.tsx`, model `mission-run-strip.ts`): the ONE live representation of a mission's runs, above the composer in the floating panel and the Agent-Mode inline view alike. It shows one run — the most urgent (waiting for you › failed › running › paused; ties: the newest) unless the person holds another — a switcher pick (session-only), the open panel, or focus inside the strip; a held strip is never swapped, a run that newly waits or fails gets a "needs you" dot and words in the switcher (or on "+N") and a polite "Rail N needs you"; only an idle strip follows urgency (`heldStripKey`); more than three runs ⇒ the shown one, the two most urgent and "+N" — as a status mark with a shape per state (spinner launching, pulsing dot running, bell waiting, triangle failed, pause, info circle for settled information — "Finished without changes" and "PR closed without merging" are `info`, not decisions: no bell, no sidebar attention dot, lowest urgency, no strip primary; their cards keep their actions) plus a screen-reader state word, the step in plain words (extension `describeRun`, else the humanized step id), progress (finished/total runs, only for several), elapsed time and billed cost (`—` until billed, `*` when some runs are unpriced). Red is only the failed mark and headline. A primary action shows only when the run needs the person and while its panel is closed. The card DECLARES it (`run-primary.tsx`: `RunPrimaryButton` / `useRunPrimary` register `{ id, label, kind, rank, disabled, run, focus }` in a registry the strip scopes per run; the lowest rank wins — Approve › paused Resume › Create PR / Publish / Reopen / retry › Resume › Recover › Relaunch). `local` actions (Resume, Back to Flow, Mark as done, Verify PR) run in one click without opening the panel or moving focus; `outward` ones (Create PR, Publish, Reopen, Approve, Recover and retry, Retry delivery, Launch / Play, and Recover and Relaunch, which spend money on a new run) never fire from the strip: it opens the panel and moves focus to the card's own control, which the person confirms. A run that needs the person without a declared action gets a specific way in ("See what failed", "See why it paused", "Open the decision"). Clicking the strip opens the run's full card as a panel anchored above the strip over the conversation (capped to the space above, so never clipped; not a modal: Esc or a click in the conversation closes it and focus returns to the strip). Every live card stays mounted (hidden) and reports its step and run vitals to the strip. Changes are announced politely ("Rail 1: Waiting for you: Ready for your review", "Rail 1 finished"). Motion only conveys state (strip morph and panel, 180–200 ms, none under reduced motion). Keyboard (`run-strip-keys.ts`, one app-wide `keydown` listener and a registry of mounted strips) is conversation-scoped: a shortcut acts on the strip of the mission containing the focused element, else the most recently focused mission (split views), else the most recently mounted. **⌥R** jumps to the strip (from the composer too; by physical key, so the Option character is not typed) and, pressed again inside it, shows or hides the details; **Esc** with nothing open returns focus to where ⌥R came from; **⌥[ / ⌥]** switch the shown run (announced "Showing Rail 1: …") only outside text fields, because Option+[ types a bracket on several layouts; **← / →** move along the switcher. A row control may claim one letter while the strip (not its panel) has focus with `data-strip-key` (Flow: P, H): never a global or destructive shortcut. ⌘/Ctrl combinations and keys inside other dialogs are left to the app; the floating mission panel counts as the mission's own surface. The toggle's tooltip and `aria-keyshortcuts` name ⌥R, switch tooltips name ⌥[ ⌥], and the app cheatsheet (`?`) lists them under Missions.
+- **History** never repeats the live run: a live delivery's slot is `AgentRunLaunchedLine` ("Launched on Rail 1 · #4 #7 · loop"), the failure row is "Rail 1 failed: <plain words>", an undecided proposal is "Launch proposed — waiting for you"; each opens the run. A settled Implement delivery keeps its full card in the history; a settled Flow → Spec run is `AgentSettledRunLine` ("Delivered: PR #812", "… went back to Flow") that expands its card in place (the Flow's closing summary is the full card of that story).
+- Focus bus: the history lines dispatch `FOCUS_PR_CARD_EVENT` scoped by `conversationId` (proposals use `OPEN_RUN_STRIP_EVENT`). The strip opens the matching live run's panel and re-dispatches once (`expanded: true`); a hidden card ignores the first dispatch; the visible card scrolls (`block: 'nearest'`, instant under reduced motion), takes focus as a labelled `region` (`tabIndex=-1`) and pulses (`motion-safe`). A settled Flow → Spec line expands its card the same way. An unknown run is a no-op.
+- Mission list: `AgentChatContext.attentionConversationIds` (from `agent_pr_decision` envelopes and the open conversation's rows, `deliveryNeedsPerson`) marks missions waiting for the person with a dot and its words: "Waiting for your decision" for a decision, "Needs attention: a run failed" (a destructive dot) for a failure (`attentionKinds`, `deliveryAttention`; a waiting decision outranks a failure; an extension's app-wide source reads as a decision). Extension runs feed the same dot with the strip's rule (`decision` or `failed` tone): an extension with an app-wide source (`MissionExtensions.useRunAttention`, Flow's per-project watch) reports every listed mission live, open or not, and the strip then leaves those runs to it; any other extension is reported by its mounted strip (`reportRunAttention`).
 - `client/src/features/missions/context/AgentChatContext.tsx` — appends the `run-failure` row live on `agent_run_failure`; `AgentWorkspaceContext.tsx` / `AgentModeJobsPane.tsx` — `specrails:mission-open-run` opens the Jobs pane + `JobDetailModal`; `hooks/useOsNotifications.ts` — stays in Mission mode.
+- Type scale on the strip, its panels and event lines (Flow's too): text and controls are **12px** at **≥ /75** foreground (labels, notes, errors, switcher entries, the single-run name, history event lines, Flow failure and run-card copy, the Preview menu URLs). Only compact chips and pills (`h-5`-class: the mode badge, status pills) may stay **11px**, and then at **≥ /70**. Never 10px.
 - Palette: `client/src/features/missions/lib/agent-context-palette.ts` (`rail` kind, `railsFromResponse`, `railChip`), `AgentComposer.tsx`, `AgentComposerEditor.tsx`, `AgentContextPalette.tsx`.
 
 ## Honesty rules
@@ -148,5 +153,5 @@ Migration 29 and the envelope fields are additive; persisted intents are inert w
 | Failure trigger / briefing / system turn | `server/modules/missions/runtime/mission-run-notify.test.ts`, `server/modules/missions/runtime/agent-failure-briefing.test.ts`, `server/agent-chat-mission-turn.test.ts`, `server/modules/delivery/runtime/rail-isolated-launch.test.ts` |
 | MCP runtime actions | `server/mcp/tools/jobs-runtime.test.ts` |
 | Launch card, proposals hook, stubs | `client/src/features/missions/components/__tests__/agent-rail-launch-card.test.tsx` |
-| Run card phases / failure block / pinning / marker | `mission-run-card.test.tsx`, `mission-run-pinning.test.ts`, `agent-run-failure.test.ts`, `agent-run-failure-marker.test.tsx` |
+| Run card phases / failure block / pinning / marker | `mission-run-card.test.tsx`, `mission-run-pinning.test.ts`, `agent-run-failure.test.ts`, `agent-run-failure-marker.test.tsx`, `agent-run-strip.test.tsx` (strip states, switcher, panel, primary action, history focus, inline surface), `mission-run-strip.test.ts` (tone/urgency/totals model) |
 | Palette rails, Mission-mode notifications | `client/src/lib/__tests__/agent-context-palette-rails.test.ts`, `client/src/hooks/__tests__/useOsNotifications.mission-mode.test.ts` |

package/docs/internals/mission-read-only-policy.md

@@ -0,0 +1,152 @@
+# Read-only missions
+
+Mission agents (the in-app agent chat) drive Specrails through the
+`specrails_*` MCP tools. They do not edit workspaces themselves. Until
+2026-10 that rule was held up by an app-owned working directory
+(`~/.specrails/agent-cwd`), the operator prompt and the MCP permission ladder:
+every provider still spawned in its write-capable mode. Since the
+`mission-read-only-policy` change, mission turns use each provider's native
+read-only boundary, so the rule holds even if a model ignores its prompt. Flow
+(see [Flow mode](flow-mode.md)) is the only write-capable mission mode, and it
+uses its own session; see [The Flow exception](#the-flow-exception).
+
+Source: [`mission-tool-policy.ts`](../../server/modules/missions/runtime/mission-tool-policy.ts).
+Kill switch: `SPECRAILS_MISSION_READ_ONLY=false` (see
+[configuration](configuration.md#mission-read-only-policy)).
+
+## Per-provider mapping
+
+The legacy transport covers one-shot turns and native live sessions (Claude
+stream-json, Codex app-server). The Core session column applies when the
+mission runs on Core agent sessions.
+
+| Provider | Legacy transport argv | Core session policy | MCP tools |
+| --- | --- | --- | --- |
+| Claude | `--dangerously-skip-permissions --tools Read,Grep,Glob,Agent,WebFetch,WebSearch` | `permissions: 'bypass'`, `tools: { mode: 'read-only' }` (Core's `--tools Read,Grep,Glob`) | ✅ |
+| Codex | `--sandbox read-only` (resume: `-c sandbox_mode="read-only"`; app-server `sandbox: 'read-only'`) | `permissions: 'read-only'` (read-only sandbox; the driver has no tool filtering) | ✅ |
+| Gemini | `--approval-mode plan --policy <cwd>/.gemini/specrails-plan-mcp-policy.toml` | no Core session driver | ✅ through the policy file |
+| Local engines | runner `--tools Read,Grep,Glob` | not applicable | ✅ (runner always adds `--mcp-config` tools) |
+| Kimi | unchanged (prompt mode auto-approves every tool) | not applicable | ✅ |
+
+### Why Claude does not use plan mode
+
+`toolPolicy: 'read-only'` alone maps Claude to `--permission-mode plan
+--safe-mode --tools Read,Grep,Glob`, which is correct for pure-output transforms
+but breaks missions. This was checked on claude 2.1.299 with a stub MCP server
+whose tool is described as state-changing:
+
+| Argv | MCP call | Write refused |
+| --- | --- | --- |
+| `--permission-mode plan --safe-mode --tools Read,Grep,Glob` | ❌ `--safe-mode` unloads `--mcp-config` servers | ✅ |
+| `--permission-mode plan --tools Read,Grep,Glob` | ❌ the model refuses state-changing calls in plan mode | ✅ |
+| same + `--allowedTools mcp__specrails` | ❌ still refused by the model | ✅ |
+| `--permission-mode dontAsk --tools Read,Grep,Glob --allowedTools mcp__specrails` | ✅ | ✅ (but connectors and external servers would need explicit allow rules) |
+| `--dangerously-skip-permissions --tools Read,Grep,Glob` | ✅ | ✅ |
+
+Missions use the last row, so MCP behaviour is unchanged. The boundary is the
+tool set: no built-in tool that writes files or runs commands exists in the
+session. `SpawnOptions.retainMcpTools` selects it. The added `Agent` tool is
+safe because native sub-agents inherit the restricted set. In the test, a
+sub-agent asked to create a file reported only read-only tools and could not.
+The Core claude driver maps `tools.mode: 'read-only'` to Core's fixed
+`Read,Grep,Glob`, and Core's plan-mode mapping for `permissions: 'read-only'`
+has the same MCP problem. The Core policy therefore keeps `bypass` and requests
+the read-only tool set.
+
+### Gemini plan mode and MCP
+
+Gemini's plan mode (gemini-cli 0.49.0) removes every MCP tool from the session.
+Its built-in `plan.toml` denies `toolName = "*"` at priority 40. When a mission
+turn is read-only, the MCP wiring writes a user-tier policy file with one rule
+per registered server (`specrails` plus injected external servers whose names
+match `[A-Za-z0-9_-]`):
+
+```toml
+[[rule]]
+toolName = "*"
+mcpName = "specrails"
+decision = "allow"
+priority = 100
+modes = ["plan"]
+```
+
+The rules apply only in plan mode, so they cannot widen a default or yolo turn.
+Built-in write and shell tools stay denied by plan mode. Plan mode still lets
+Gemini write plan Markdown files under its own `~/.gemini` plans directory,
+outside every workspace.
+
+## What stays outside the boundary
+
+- **MCP servers.** The boundary covers the provider's own built-in tools. MCP
+  servers keep their own semantics: Specrails' tools are governed by the mission
+  permission ladder (observe / edit / operate / autonomous). Claude.ai connectors
+  and user-configured external MCP servers run as before. Specrails does not
+  vet the tools those servers expose.
+- **Kimi.** Kimi Code prompt mode installs an approval handler that approves
+  every tool call and rejects `--plan`. Kimi has no native read-only mode, so
+  Kimi missions keep the previous behaviour. The adapter rejects `read-only`
+  explicitly, so Kimi never pretends to enforce it. The turn log records
+  `tools=default(unsupported)`.
+- **Codex shell reads.** Codex's read-only sandbox still runs shell commands
+  that do not write, such as `git status` or `ls`. Writes fail inside the
+  sandbox.
+- **Core sessions without tool filtering.** If a Core driver for an adapter that
+  needs `tools: 'read-only'` does not advertise `toolFiltering`, Desktop keeps
+  the legacy policy. Core would otherwise reject the session with
+  `policy_unenforceable`.
+- **Claude native sub-agents on Core sessions.** Core's read-only tool set has
+  no `Agent` tool, so a Claude mission on Core sessions cannot start native
+  sub-agents. Delegated sub-agents (`subagentRuntime.mode: 'delegated'`) are
+  launched by Core, so the missing `Agent` tool does not affect them. Keeping
+  `Agent` with read-only tools requires a Core change.
+
+## The Flow exception
+
+A conversation with an ACTIVE Flow runs its turns in a separate Core session
+(`flow:<flowId>`) whose cwd is the Flow worktree and whose policy is the rail
+write-role level: `permissions: 'bypass'`, default tools (Claude
+`--dangerously-skip-permissions`, Codex `--sandbox danger-full-access`). The
+agent can therefore write, run the typecheck and tests, and install
+dependencies in the worktree without interactive approvals. Long-lived apps
+run as Specrails background processes in the worktree, admitted below the
+Autonomous level after the user's explicit confirmation, and stopped with the
+Flow.
+
+The containment is honest but not a sandbox, exactly as for rails: the cwd,
+the persona rule never to touch anything outside the worktree, and the
+worktree's own branch (Flow delivers only that worktree). Details:
+[Flow mode › Permissions](flow-mode.md#permissions).
+
+Everything in this document still applies to every other mission turn: when
+the Flow is paused or ended, the conversation's next turn is a normal
+read-only mission turn again.
+
+## Operator features that need no native write tool
+
+Everything the operator manual asks for already goes through MCP on the server
+side. That includes code reads (`specrails_code`), git and gh diagnostics
+(`specrails_git`), background applications and their logs
+(`specrails_jobs background_*`), rails, specs, recovery patches
+(`specrails_recovery`) and support. The manual no longer promises a raw shell.
+It says that a shell, if one exists, is only for read-only git/gh diagnostics.
+
+## Verification
+
+- Unit and integration tests:
+  [`mission-tool-policy.test.ts`](../../server/modules/missions/runtime/mission-tool-policy.test.ts),
+  the read-only block of
+  [`agent-chat-manager.test.ts`](../../server/modules/missions/runtime/agent-chat-manager.test.ts),
+  the read-only block of
+  [`mission-core-sessions.test.ts`](../../server/modules/missions/runtime/mission-core-sessions.test.ts),
+  adapter argv tests, and the Gemini policy tests in
+  [`agent-mcp-config.test.ts`](../../server/agent-mcp-config.test.ts).
+- Live smokes (2026-10-21) used the adapter-built argv against a temporary
+  directory with a stub MCP server.
+  - **Claude 2.1.299 (haiku):** the MCP call ran, `secret.txt` was read, and no
+    file was created, including by a sub-agent.
+  - **Codex 0.160.1:** `exec --sandbox read-only` with the `-c mcp_servers.*`
+    overrides. The MCP call ran, the read succeeded, and the write was refused
+    by the sandbox.
+  - **Gemini 0.49.0:** plan mode with the generated policy. The MCP call ran,
+    the read succeeded, and `write_file` was denied by policy. Without the
+    policy, the MCP tool was absent.

package/docs/internals/modal-standard.md

@@ -0,0 +1,181 @@
+# Modal standard
+
+Every modal surface in the client follows one standard: one primitive, five
+sizes, one anatomy, one scrim, named layers and one entrance animation. The
+primitive lives in [`client/src/components/ui/dialog.tsx`](../../client/src/components/ui/dialog.tsx);
+the layer scale lives in [`client/src/lib/layers.ts`](../../client/src/lib/layers.ts).
+Tests for the contract: [`dialog-standard.test.tsx`](../../client/src/components/ui/__tests__/dialog-standard.test.tsx),
+[`dialog-movable.test.tsx`](../../client/src/components/ui/__tests__/dialog-movable.test.tsx)
+and the source guard [`modal-standard-guard.test.ts`](../../client/src/components/ui/__tests__/modal-standard-guard.test.ts).
+
+## When a modal is the right pattern
+
+Use a modal for a decision (confirm, launch) or a protected, focused task
+(Add Spec, Settings). Do not use one for something a user consults while
+working.
+
+| Surface | Pattern |
+|---|---|
+| Confirms, launch dialogs, Add Spec | Modal |
+| Settings | Modal (AGENTS.md: app settings are a modal; project settings are a route in board mode and `ProjectSettingsDialog` in Agent Mode, which has no routed dashboard) |
+| Spec detail, Job detail | Entity modal (`layer="entity"`), resizable, geometry persisted |
+| Loops, Plugins, Review packet | `fullscreen` modal with the standard header and a visible close. Candidates for routes. |
+| Docs, Analytics, agent activity log, background-process logs | `workspace` modal today. These are read while working, so they are candidates for a right-side sheet. |
+| Move to rail, Subscription usage, floating agent chat | Non-modal popovers and panels. Not dialogs. |
+
+The route and sheet conversions are deliberately not done yet. Each needs its
+own plan that keeps deep links working (`lib/global-route-mode-transition.ts`
+and the Mission-mode review entry).
+
+## Primitive
+
+Every modal is a Radix dialog, either through `DialogContent` or, for full-screen
+shells with custom key handling, through `DialogPrimitive.Content` wrapped in
+`DialogLayerProvider`. Radix provides the focus trap, initial focus, Escape
+stacking (only the top layer closes), `aria-labelledby`/`aria-describedby` and
+`hideOthers`, so the page behind is inert. Do not hand-roll
+`createPortal(<div role="dialog" aria-modal>)`. The source guard test rejects
+new hand-rolled `aria-modal` dialogs outside `components/ui`.
+
+Focus return is built in. On close, `DialogContent` refocuses the element that
+had focus at open. If that node was remounted while the modal was open (sidebar
+buttons are), it refocuses the live element with the same `id`, `data-testid`
+or `aria-label`. Give modal triggers one of these.
+
+## Sizes
+
+Pass `size` to `DialogContent`. Call sites do not set `max-w-*`, `w-*` or `h-*`.
+
+| Size | Geometry | Use |
+|---|---|---|
+| `confirm` | `max-w-md` (448px), auto height | All confirms |
+| `form` | `max-w-lg` (512px), auto height | Short forms and pickers |
+| `wide` (default) | `max-w-2xl` (672px), auto height up to 85dvh | Previews and multi-section forms |
+| `workspace` | `92vw × 82vh`, `max-w-5xl` | Settings, Project settings, Docs, Analytics, Add Spec, Agents catalog, background-process logs |
+| `fullscreen` | `96vw × 92vh` | Loops, Plugins, Review packet, Runtime graph |
+
+Below 640px every size fills the window minus a 16px gutter, and `workspace`
+and `fullscreen` fill it minus 8px. Heights are capped below the desktop title
+bar (`lib/modal-safe-area.ts`).
+
+## Anatomy
+
+```tsx
+<Dialog open={open} onOpenChange={setOpen}>
+  <DialogContent size="form">
+    <DialogHeader icon={<Rocket />} actions={/* optional */}>
+      <DialogTitle>Launch all specs?</DialogTitle>
+      <DialogDescription>Each spec starts on its own rail.</DialogDescription>
+    </DialogHeader>
+    <DialogBody>…</DialogBody>
+    <DialogFooter start={<CostEstimate />}>
+      <Button variant="ghost" onClick={cancel}>Cancel</Button>
+      <Button ref={primaryRef}>Launch 3 specs</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+- The panel is a flex column with no padding. The header and footer never
+  scroll. `DialogBody` is the only scrolling region.
+- **Header** (`px-5 py-4`, bottom border): optional 16px accent icon, then the
+  title (16px semibold) and an optional description (13px muted, at most two
+  lines), then right-aligned actions, then the close button.
+- **Close**: one 28×28 button with a 16px icon. It sits in the header row, or
+  top-right when a surface renders no header. Hide it
+  (`showCloseButton={false}`) only when the footer has an explicit Cancel or
+  Close.
+- **Footer** (`px-5 py-3`, top border): the `start` slot holds left-aligned
+  secondary info or a destructive action such as Delete. On the right, Cancel
+  (`variant="ghost"`) comes first, then the primary action (`default`, or
+  `destructive` when it destroys data). Footer buttons use the Button default
+  size. On narrow viewports the footer stacks with the primary on top.
+- **Initial focus**: the primary for confirms and launch dialogs
+  (`onOpenAutoFocus` → `primaryRef`), the first field for forms. `⌘↵` submits,
+  and the primary shows the kbd hint.
+- **Confirms** use `ConfirmDialog` (`components/ui/confirm-dialog.tsx`). It
+  takes `tone` (`destructive` by default, `default` for non-destructive
+  confirms such as merge or recover), `layer`, `busy`, `confirmDisabled`,
+  `secondaryAction` and test ids. Initial focus goes to the confirm button.
+
+## Copy
+
+The title names the object or the decision ("Discard local changes?"). The
+primary names the verb ("Discard changes"), never "OK" or "Confirm". The
+description states the consequence, not instructions about the UI. Every
+dialog has a `DialogDescription`, either visible or `sr-only`. A dialog that
+truly has none passes `aria-describedby={undefined}`.
+
+## Layers
+
+| Layer | z | Members |
+|---|---|---|
+| `base` | 50 | Ordinary dialogs (default) |
+| floating chat | 60 (grips 61) | Floating agent panel |
+| `entity` | 65 | Spec detail, Job detail, compare, agent activity log, loop and blueprint previews |
+| `stacked` | 70 | Anything opened from inside an entity modal or the floating panel: Flow prompts, SMASH, nested confirms |
+| dock | 75 | Minimized chats dock (stays clickable over modals) |
+| `capture` | 80 | Browser capture, web view, native browser pane, background-process logs, runtime graph |
+| `media` | 100 | Lightboxes |
+| toast | 110 | Toasts. Sonner portals to `<body>` (its own rule in `globals.css` pins it even higher) and switches to top-right while a modal is open, so a toast never covers a modal footer |
+
+Pass `layer` to `DialogContent` (or to `ConfirmDialog`). A dialog rendered
+inside another dialog inherits a layer automatically. Inside an `entity` modal
+it climbs to `stacked`. Inside any other layer it stays on that layer, and
+portal order puts the newer dialog on top. Do not write `z-[NN]` on overlay
+surfaces. Use `DIALOG_LAYER_CLASS` / `LAYER_CLASS` from `lib/layers.ts`.
+
+Two consequences of Radix modality to know about:
+
+- While any modal is open, Radix sets `pointer-events: none` on `<body>` and
+  hides everything outside the panel from assistive tech. The minimized chats
+  dock paints above modals (layer 75) but is not clickable until the modal
+  closes. Making it interactive would need an outside-interaction allowance in
+  `dialog.tsx`.
+- A raw-primitive surface (`DialogPrimitive.Content`) only gets automatic focus
+  return when it captures the opener itself. Spec detail, Job detail, the
+  lightbox (`MediaLightbox` in `features/chat/components/AttachmentPreviewLightbox.tsx`)
+  and the browser-capture shell (`CaptureDialogShell` in
+  `features/browser/components/browser-capture/NativeBrowserPane.tsx`) do.
+
+## Shared surfaces
+
+- `ConfirmDialog` (`components/ui/confirm-dialog.tsx`) for every confirm.
+- `MediaLightbox` for every image/PDF preview (media layer, media scrim).
+- `CaptureDialogShell` for the browser capture, web view and native browser
+  pane (capture layer). It forwards Tab/Space/arrow keys to the remote page
+  (`forwardsKey`) and only closes on a press on the scrim itself.
+
+## Scrim, surface, motion
+
+- Scrim: `bg-scrim backdrop-blur-sm`. `--color-scrim` is `rgb(0 0 0 / .6)` on
+  dark themes and `rgb(15 15 40 / .35)` on Aurora Light. Lightboxes use
+  `bg-scrim-media` (`rgb(0 0 0 / .85)`).
+- Surface: `bg-popover`, `border-border/30`, `rounded-xl`, `shadow-xl`.
+  `shadow-2xl` is reserved for the floating chat. Modals do not use
+  `glass-card`.
+- Motion: one entrance, fade plus 0.98 scale over 180ms with an exponential
+  ease-out, and a 120ms exit. Both are off under `prefers-reduced-motion`. The
+  `modal-panel` and `modal-scrim` classes in `globals.css` apply them through
+  the standalone `scale` property, so they compose with Tailwind v4's
+  `translate` centering. Non-Radix surfaces opt in with `modal-enter`.
+
+## Resizing
+
+Only the `workspace` size is resizable (`movableResizable`), plus Spec detail
+and Job detail, which own their geometry. The modal stays centered and resizes
+from corner and edge grips. There is no whole-panel drag. The grips render
+inside the panel (`ResizeGrips placement="inset"`), so they paint above the
+panel's own scrim and sit inside the focus trap, which keeps keyboard resize
+(arrows, Shift for large steps, Home/End, 0 to reset) reachable. Pass
+`persistKey="specrails.modal.<surface>"` so a workspace remembers its size.
+Confirms, forms and previews are never movable. Below 900px the grips are
+hidden.
+
+## Type floor
+
+The minimum for any text run inside a modal is 12px. 11px is allowed only on
+`h-5` chips and pills at ≥70% foreground, and those carry a `data-chip`
+attribute (see [mission rail cards](mission-rail-cards.md)). Chart axes are
+12px. The guard test rejects `text-[9px]`, `text-[10px]` and `text-[10.5px]`
+in modal files.