specrails-desktop 2.20.1 → 2.22.0

package/docs/internals/code-explorer-story.md

@@ -0,0 +1,135 @@
+# Code explorer: the construction story
+
+> Companion to the "Code explorer (read-only)" section of `CLAUDE.md`. This doc
+> covers the per-file **construction story** — the narrative layer that tells a
+> non-developer, for any file, HOW it was built: which specs intervened and what
+> each one contributed.
+
+## Problem
+
+`file_provenance` (migration 22) records *that* a job touched a file, and
+`file_provenance_diffs` (migration 23) stores the raw patch — but nothing told
+the *story*: no per-intervention line stats, no plain-language "what did spec
+#37 change in THIS file" narrative, and — critically — **loop runs recorded no
+provenance at all**. Both loop paths settle outside `QueueManager` (whose
+post-exit hook was the only provenance producer):
+
+- **Isolated worktree rails** (`rail-isolated-launch.ts`) — the run's writes
+  happen in a per-ticket worktree and settle in the launch's own promise chain.
+- **Shared-cwd rails** (`rails-router.ts` `launchLoopRun`) — the run settles in
+  the router's `.then`/`.catch`.
+
+So the entire loop-based implement path (the default rail mode) was invisible
+to the Code explorer.
+
+## Persistence (migration 37)
+
+`file_story_contributions` in the per-project `jobs.sqlite`:
+
+| column | meaning |
+| --- | --- |
+| `provenance_id` (PK) | 1:1 with `file_provenance.id` |
+| `job_id`, `file_path` | denormalised identity for path-scoped queries |
+| `added_lines`, `removed_lines` | unified-diff stats (`computeDiffStats`) |
+| `patch_excerpt` | ≤ 4 KB excerpt (`excerptPatch`; full patch stays in `file_provenance_diffs`) |
+| `summary` | nullable — the AI contribution paragraph |
+| `summary_model`, `summary_generated_at` | generation metadata |
+
+Stats rows are written **inside `recordProvenanceForJob`'s transaction**
+(`server/file-provenance.ts`), for every provenance row that has a collected
+patch. That means every producer — QueueManager jobs AND the loop seam — gets
+stats with zero extra calls. The prepare is guarded (like the migration-23
+`insertPatch`) so a pre-37 DB degrades cleanly.
+
+## The loop-run seam (`server/file-story.ts`)
+
+`recordLoopRunProvenance({ db, projectId, runId, ticketId, repoDir, snapshot,
+broadcast })` is the single chokepoint that mirrors QueueManager's
+`_recordProvenance`: gated by `isCodeExplorerEnabled()`, diff + patches +
+`recordProvenanceForJob` + per-row `file.provenance_updated` broadcast, and the
+`provenance.large_job` warn at >50 files. It never throws. `job_id` is the
+**loop run id**, so the existing `/code/diff?jobId=` endpoint and job-context
+filters key off it unchanged.
+
+Wiring:
+
+- `rail-isolated-launch.ts` — snapshots each fresh worktree at allocation
+  (after the overlay, so overlay files land in the snapshot's untracked set and
+  are never attributed to the run) and records at settle, on BOTH the success
+  and failure paths, before `commitWorktree`. Once-per-run guard (the `.catch`
+  also catches commit failures thrown after the `.then` recorded). Injectable
+  via `IsolatedLaunchIO.snapshot` / `.recordProvenance`.
+- `rails-router.ts` `launchLoopRun` — snapshots the **repo**
+  (`loopExec.repoDir` when relocated, else the cwd — never the workspace) and
+  records in `.then`/`.catch` with the same once-guard.
+- `queue-manager.ts` — **unchanged**. Its existing `recordProvenanceForJob`
+  call now also writes stats because the insert rides the same function.
+
+## Story assembly + generation
+
+- `getFileStory(db, path, getTicketSpec)` (`file-story.ts`) — provenance rows
+  (oldest-first: a construction story reads forward in time) LEFT JOINed with
+  contributions, enriched with the spec's live title/status via
+  `ProjectContext.getTicketSpec` (failure-tolerant, memoised per call).
+- `FileStoryManager.explain(...)` (`file-story-manager.ts`) — the on-demand,
+  budget-gated contribution generator. Prompt = spec title + change kind + the
+  stored patch (full patch preferred, excerpt fallback, honest "(not stored)"
+  note otherwise). Reuses `createFileSummaryGenerator`'s spawn/parse skeleton
+  via the new `systemPrompt` override — same haiku-class default model, same
+  timeout/kill/partial-usage semantics. **Deliberate decisions:** it shares the
+  file-summary monthly budget (`summary_monthly_budget_usd`) and records
+  `ai_invocations.surface = 'file-summary'` — one budget and one analytics
+  bucket cover the whole Code-section AI spend; no new Surface member. In-flight
+  dedupe per `provenanceId`; the synchronous gates (not-found/budget) run
+  BEFORE registering in-flight so a budget skip is never cached. Persists via
+  `setContributionSummary` (inserts a summary-only row for patchless historical
+  touches).
+
+## REST + WS
+
+- `GET  /api/projects/:id/code/file/story?path=` → `{ path, story: FileStoryEntry[] }`
+  (same traversal/deny-list/gitignore guards as `/summary`; works for deleted
+  files — their story is still told).
+- `POST /api/projects/:id/code/file/story/explain?path=` body
+  `{ provenanceId, overrideBudget? }` → `{ ok:true }` | 200 `{ skipped:'budget' }`
+  (client shows the inline override) | 404 | 500.
+- WS `file.story_updated` `{ projectId, path, provenanceId, ok, reason? }` —
+  open viewers of that file refetch; `spending.invalidated` fires alongside.
+
+The `FileStoryManager` is constructed per-`ProjectContext` at the code-router
+mount site (`project-router.ts`), memoised with the router.
+
+## Client
+
+`ConstructionStory.tsx` (in `client/src/components/code-explorer/`) renders the
+premium vertical timeline: glass cards on a dotted rail, each with kind
+icon/label, the spec chip (`#id · title`, click → `TicketDetailModal` via the
+`onOpenTicket` prop), status pill, `+N/−N` stats, date, and the contribution
+paragraph — or the honest fallback (kind + spec + date, spec-less variants for
+`ticket_id IS NULL`) with the **Explain this change** button (budget skip →
+inline "Generate anyway" override). The run-id footer filters the Code page by
+job. `FileViewer`'s bottom panel hosts it behind a **Story | Log** toggle
+(default `story`, persisted per project at
+`localStorage['specrails-desktop:code-history-mode:<projectId>']`); Log is the
+pre-existing `ProvenanceTimeline` with on-demand diffs, unchanged.
+
+**Agent-Mode parity is free**: the mission **Files** pane
+(`AgentModeCodePane.tsx`) embeds `CodePage` → `FileViewer`, so the story panel
+appears there with no extra code (the component only uses `getApiBase()`,
+props, and WS — nothing route-dependent).
+
+i18n: the `story.*` block in the `code` namespace, all 8 locales (parity test
+enforced).
+
+## Fallback ladder (locked design)
+
+Contribution text sources, in order: (a) the persisted AI `summary`; (b) the
+honest fallback — kind + spec + date only, never an invented claim. Diff stats
+render whenever migration-37 rows exist; historical (pre-37) touches show the
+bare provenance facts.
+
+## Out of scope / future
+
+Auto-generating contributions at provenance-record time (cost); a
+whole-file "biography" paragraph synthesised from all chapters; multi-ticket
+attribution (primary ticket only, unchanged from the base feature).

package/docs/internals/gemini-mcp-registration.md

@@ -0,0 +1,53 @@
+# Gemini MCP registration (as-built facts + known gap)
+
+How MCP servers actually reach gemini-cli, what the app does about it today, and the surfaces
+where the historical `.mcp.json` assumption still silently fails. All claims verified
+empirically against **gemini-cli 0.49.0**.
+
+## The facts
+
+- **gemini-cli has NEVER read `.mcp.json`.** That file is a Claude convention. Gemini's only
+  MCP surface is the `mcpServers` object in **settings.json** — user scope (`~/.gemini/
+  settings.json`) or project scope (`<cwd>/.gemini/settings.json`).
+- **An untrusted cwd suppresses MCP entirely.** With the trusted-folders gate unresolved, a
+  headless (`gemini -p`) run exits **55** with `FatalUntrustedWorkspaceError`. The app-wide
+  antidote is `GEMINI_CLI_TRUST_WORKSPACE=true` injected per spawn — the pattern
+  `chat-manager` / `queue-manager` / `util/cli-prompt.ts` already use for every gemini spawn.
+- **Gemini exposes MCP tools under an FQN prefix**: `mcp_<server>_<tool>` — for the Specrails
+  server, `mcp_specrails_<canonical name>` (e.g. `mcp_specrails_specrails_specs`). The agent-chat
+  operator prompt (`server/agent-operator-prompt.ts`) notes this so the model calls the right
+  names on gemini.
+
+## What works today: agent chat
+
+`server/agent-mcp-config.ts` `prepareAgentMcp` (the desktop agent chat / Mission Control
+wiring) handles gemini correctly: it merges the `specrails` server entry into
+`<agent-cwd>/.gemini/settings.json` (merge-safe — read-if-exists, only the owned key touched)
+AND returns `env: { GEMINI_CLI_TRUST_WORKSPACE: 'true' }` for the spawn. The generic
+project-json `.mcp.json` write still happens alongside (harmless — gemini ignores it; it keeps
+the path uniform for any future project-json provider).
+
+## Known DEFERRED gap: every other 'project-json' gemini consumer
+
+The `mcpRegistration: 'project-json'` capability value really means **claude-style
+`.mcp.json`**. Every other consumer of that flag still writes/relies on `.mcp.json`, which
+gemini never loads — so on those surfaces an MCP server is registered but **silently never
+loads** for gemini:
+
+| Surface | What it does today | Effect on gemini |
+|---|---|---|
+| Plugins on rails (`server/plugin-manager.ts`, e.g. Serena) | surgical merge into `<project>/.mcp.json` for `project-json` providers | plugin installs "successfully", MCP server never loads in gemini rail spawns |
+| Workspace MCP (`server/agent-mcp-config.ts` `mergeSpecrailsIntoWorkspaceMcp`, via `workspace-manager.ts`) | writes `<workspace>/.mcp.json` | not read by gemini |
+| Explore `context_scope.mcp` (`server/chat-manager.ts`) | spawns from `<project.path>` so `.mcp.json` loads | loads nothing on gemini |
+
+Fixing these means writing into the repo's / workspace's `.gemini/settings.json`, which
+intersects the **pristine-repo / artifact-relocation policy** (the app must not mutate the
+user's repo, and `.gemini/` in the repo belongs to the user) — that is its own future change,
+deliberately not bundled with the agent-chat fix.
+
+## Doc corrections this note anchors
+
+- `docs/internals/adding-a-provider.md` no longer claims "`project-json` ⇒ nothing to add":
+  project-json is the claude `.mcp.json` mechanism; a provider with its own config surface
+  (gemini) needs explicit wiring + any trust env.
+- `docs/gemini.md` no longer claims Serena-style plugins "work" on gemini rails.

package/docs/internals/interactive-jobs.md

@@ -0,0 +1,212 @@
+# Interactive jobs (as-built)
+
+Every claude job — Job Detail (board) and the mission-mode job modal alike — renders a bottom
+agent-style composer while the job runs. This doc is the as-built record of the session model
+behind it: the transport, the two settle modes, the loop-step ownership design, the accounting
+reconciliation, and the failure interplay. User-facing behaviour: the in-app guide's
+[Job Detail view](../guide/en/pipeline/2-the-job-detail-view.md) page. Code:
+`server/interactive-job-session.ts`, `server/queue-manager.ts` (the interactive branch of
+`_startJob`), `server/loop-executors.ts` `planInteractiveAiStep`, `server/loop-run-manager.ts`
+`_runInteractiveAiStep`, `server/project-router-jobs.ts` (the two manager-agnostic routes),
+`client/src/components/InteractiveJobComposer.tsx`.
+
+## Session model
+
+A standard job spawns `claude -p <prompt>` once and settles when the child closes. An
+**interactive** job instead keeps ONE `claude -p --input-format stream-json` child resident
+across many user turns — the same persistent-stdin transport `ExploreStdinSessions` uses for
+Explore chat. Each user prompt is a newline-delimited stream-json message written to stdin; the
+agent works; the turn ends on a `result` event **without killing the child**. A prompt that
+arrives mid-stream queues behind the active turn and runs next (`job.turn_user` carries
+`queued: true`); the job still tends to continue its plan — messages are steering, not
+interruption.
+
+`InteractiveJobSession` owns the transport plus per-turn streaming/persistence/accounting. The
+owner (QueueManager or the loop engine) owns spawn-arg construction and the terminal settle
+(slot release, rail/ticket completion, `ai_invocations`) via the `onSettle(SettleInfo)`
+callback. Turn-id tagging (`_activeTurnId` / `_lastSettledTurnId`) guarantees a stray, late, or
+duplicate `result` frame can never be folded into the next turn's totals (BUG-INTJOB-03).
+
+### The spike that unlocked the flip
+
+The original interactive path was ultracode-only because ultracode sends prose, not a slash
+command. Spike-verified 2026-07-03 against **claude 2.1.198**: the claude CLI expands slash
+commands arriving as stream-json stdin user frames **exactly like the argv `-p "/cmd"` path**
+(evidence pointer: the dated comment block above the interactive gate in
+`server/queue-manager.ts` `_startJob`, and `loop-executors.ts` `planInteractiveAiStep`). That
+makes every job — `/specrails:implement`, `/specrails:batch-implement`, distilled loop commands,
+custom commands — transport-compatible, so the default flipped to interactive for every
+persistent-stdin-capable provider.
+
+## Gating
+
+Derived at **spawn time** (not enqueue) in `QueueManager._startJob`, so a queued job that
+survives a server restart (the in-memory selection map is lost) still spawns interactive:
+
+```
+spawnInteractive = isInteractiveJobsEnabled()            // SPECRAILS_INTERACTIVE_JOBS !== 'false'
+                && adapter.capabilities.persistentStdin  // claude only today
+                && (EnqueueOptions.interactive ?? true)  // tri-state per-job override
+```
+
+- `EnqueueOptions.interactive`: `false` = force the legacy one-shot spawn, `true` = force
+  interactive where capable, `undefined` = default ON.
+- codex/gemini (`persistentStdin: false`) always take the one-shot path — graceful, no
+  composer, byte-identical to before.
+- The rails launch body still accepts a legacy `interactive` param; it is **ignored** (wire
+  compat — the spawn-time gate decides).
+
+## `settleMode` semantics
+
+| | `'finalize'` | `'auto'` |
+|---|---|---|
+| Who gets it | ultracode/Freestyle QueueManager jobs (claude) | every other interactive job + ALL loop ai-steps |
+| End of session | explicit human **Finalize** only (SIGTERM → 2s → SIGKILL) | **quiescence**: a turn `result` arrived, nothing queued, no write in flight |
+| Idle between turns | by design (awaiting the human) | only transiently (microtask window) |
+| Wedge detector | never armed | the queue's zombie-timeout budget, reset on any raw child output; silence for the whole budget → fold in-flight turn, settle `crashed` |
+| Composer action | **Finalize Job** | **Wrap up now** (QueueManager) / **Settle this step** (loop step) |
+
+**Quiescence detail:** the auto-settle is deferred to a microtask after the `result` so anything
+in the same synchronous stdout batch is observed first, and re-checked — a user prompt that
+slipped in meanwhile queues/writes a new turn and **extends the session** instead. An explicit
+`finalize()` always settles immediately in either mode.
+
+## Loop-step ownership and routing
+
+All dashboard rail launches (factory `Implement`/`Batch`/`Freestyle` and custom loops) run
+through the `LoopRunManager`. When interactive jobs are enabled and the provider supports
+persistent stdin, each claude **ai-step** runs as its own `InteractiveJobSession`
+(`planInteractiveAiStep` builds the spawn plan; `_runInteractiveAiStep` owns the lifecycle):
+
+- **`runId` = the job row id.** The loop run's backing `jobs` row is created with `id = runId`,
+  so `/jobs/:id/*` routes address the run directly. `markJobInteractive` stamps the row when the
+  first interactive step goes live (idempotent), so `GET /jobs/:id` advertises the affordance.
+- **Turns go to the ACTIVE step's session** (`_interactiveSteps: Map<runId, session>`). Between
+  steps — decider, shell nodes, step boundaries — there is no session: `POST /messages` 409s,
+  and the composer shows a gentle waiting state instead (driven by the `job.interactive`
+  broadcast, `acceptingTurns: false` at step settle / `true` at step start). A between-steps
+  `GET /jobs/:id` still reports `interactiveSettleMode: 'auto'` via the `loop_runs` row so the
+  client can phrase the waiting state truthfully.
+- **Finalize settles the current STEP**, not the run: the session settles `'finalized'`, the
+  `SettleInfo` maps onto the same `AiStepResult` shape the one-shot executor returns, and the
+  loop advances with whatever the step produced (history, changeId capture, fail-fast all
+  untouched).
+- **Shared event seq:** the session draws event seq numbers from the engine's monotonic
+  allocator (`nextEventSeq`) because the loop engine persists its own step-boundary/log events
+  on the same job id — private counters would collide/replay out of order.
+- **Teardown matrix** (never leaks the child, never double-settles — `_settle` is idempotent):
+  quiescence / explicit finalize → `'finalized'` (step ok); step timeout → `session.abort()` →
+  fold in-flight turn → `'crashed'`; run cancel → `abort()` → `'crashed'` → engine settles the
+  run `'stopped'` at the next boundary; manager shutdown / project removal → `dispose()` (kill,
+  NO settle; the startup orphan sweeps reconcile rows on next boot). No zombie timer is armed on
+  loop steps — the loop's ai-step timeout bounds the whole step and is the sole watchdog
+  (byte-parity with the one-shot loop path, which has no zombie detector either).
+
+## Accounting reconciliation
+
+Two writers, one clean split — nothing double-records:
+
+- **The session feeds live job-row totals.** Every completed turn's REAL usage is summed onto
+  the `jobs` row as it lands (`accumulateInteractiveTurn`), so the live Job Detail totals are
+  honest (never an estimate) and the composer's `N turns · $X` line is real money. The
+  persistent transport reports `total_cost_usd`/`num_turns` **cumulatively** per turn, so the
+  session records deltas against a per-child baseline (clamped ≥ 0) — summing raw readings
+  would count turn 1 N times (COST-ACCOUNTING-AUDIT HIGH-2). Token fields are per-turn and sum
+  directly.
+- **The engine/owner is the sole `ai_invocations` authority.** QueueManager writes one row at
+  settle from the summed `SettleInfo` totals; the loop engine writes one `record()` row per
+  step the same way. The session itself never writes an invocation row.
+- **Mid-turn kill = fold, not drop.** A finalize/crash/timeout mid-turn folds the in-flight
+  turn's streamed per-assistant-event usage via `finaliseInvocationResult` and prices it from
+  the rate card (`estimated: true` → the row and job get the estimated badge; CRIT-4). Idempotent
+  (`_inflightFolded`) so a settle and a shutdown snapshot can't fold twice.
+- **Active duration ≠ wall clock.** `activeDurationMs` sums only write→result segments,
+  excluding idle time between turns, so a long-open `'finalize'` session doesn't inflate
+  per-ticket duration analytics (LOW-15).
+
+## Zero-work settles (failure semantics)
+
+Live evidence (run `01f41203`): a mistyped `/specrails:implement` made the claude CLI emit a
+**synthetic** terminal result frame — `{subtype:'success', is_error:false, num_turns:0,
+total_cost_usd:0, duration_api_ms:0, result:'Unknown command: /specrails:implement'}` — and exit
+cleanly. No model ever ran, yet the settle looked like a success (the job "completed" at $0; a
+factory loop then "succeeded" via verify/fix without implementing). Strictness rule: **if the
+command didn't actually run, the settle is FAILED.**
+
+- **The predicate is shared and whole-life.** `isZeroWorkSettle` (exported from
+  `server/interactive-job-session.ts`) judges the session/step's WHOLE accumulated life: it is
+  zero-work when `num_turns === 0` accumulated AND no assistant-derived event was ever observed
+  (`isModelWorkEvent`: text-delta / tool-use / assistant frames / usage-carrying events; `result`
+  frames do NOT count — the synthetic no-op IS a result frame) AND all four token counters are
+  zero. Belt-and-braces: a final result text matching `/^Unknown command:/` marks zero-work even
+  if the numeric accounting drifted — but only when no assistant event was seen, so a multi-turn
+  session that did real work earlier and merely **ended** on a synthetic frame (the user sent
+  `/help` late) is NOT zero-work and still completes.
+- **The session evaluates it at settle** and hands `SettleInfo.zeroWork` to the owner. It also
+  surfaces the reason as a visible stderr transcript line (`✖ Zero work performed — the command
+  never ran: Unknown command: …`) — necessary because `extractDisplayText` drops `result` frames,
+  so the synthetic text would otherwise never appear in the log.
+- **QueueManager** (`_settleInteractiveJob`): a zero-work `'finalized'` settle stamps the job
+  `'failed'` (exit code 1, failed `ai_invocations` row, dependents skipped) — **in both settle
+  modes**, so an ultracode Finalize after only the synthetic frame is also a failure. A canceled
+  job stays `'canceled'`.
+- **LoopRunManager** (ai-steps): a zero-work settle makes the step's `AiStepResult` `failed` and
+  its `loop_step_end` `status:'failed'`, and it **routes exactly like a crashed step** — the run
+  policy is unchanged (graph-dependent continue + the `AI_FAILFAST_THRESHOLD` consecutive-failure
+  abort); zero-work counts toward that streak like a no-output crash (its `Unknown command:` text
+  is a CLI synthetic, not model output), so a persistently-unresolvable command aborts the run the
+  same way a dead provider does. The one-shot loop path derives the same predicate at the engine
+  from the step result's accumulated signals (one-shot `text` accumulates only from assistant
+  text-deltas, so non-empty text ⇒ assistant events were seen).
+
+## Zombie / timeout interplay
+
+- **One-shot jobs**: unchanged — the queue's zombie timer kills a silent child.
+- **Interactive `'auto'`**: the same zombie budget is armed *inside* the session (reset on any
+  stdout/stderr `data`); firing folds the in-flight turn and settles `'crashed'`.
+- **Interactive `'finalize'`**: no timer at all — an idle session awaiting Finalize is the
+  feature. QueueManager's queue-level timer is never armed for interactive jobs.
+- **Loop ai-steps**: no zombie timer; the step timeout aborts the session (`'crashed'`,
+  `errorText: 'AI step timed out'`), partial work accounted.
+- **Finalize hard-deadline**: SIGTERM → 2s → SIGKILL, plus a forced settle if the child never
+  emits `close` (D-state / signal-swallowing) so the queue slot can never leak.
+- **Undeliverable turns**: a confirmed-failed stdin write (destroyed/EPIPE) is surfaced as a
+  delivery-failure note and settles `'crashed'` — a turn is only echoed to the transcript after
+  delivery is confirmed. Prompts still queued when the session ends are surfaced in the
+  transcript (`N queued prompt(s) were not sent`), never dropped silently.
+
+## Surface state on the wire
+
+- `GET /jobs/:id` → `interactiveSettleMode: 'finalize' | 'auto' | null` +
+  `interactiveAcceptingTurns: boolean` (S3 — lets the composer phrase Finalize vs wrap-up vs
+  waiting truthfully; `null`/`false` while queued, refetched on the queued→running flip).
+- `POST /:projectId/jobs/:id/messages` / `POST .../finalize` — **manager-agnostic**: QueueManager
+  is tried first, then LoopRunManager. `202` accepted/scheduled, `403` kill-switch off, `409` no
+  live session.
+- WS: `job.turn_user` (echo + `queued` flag), `job.turn_done` (running totals), `job.finalized`
+  (final totals + terminal status), `job.interactive` (`acceptingTurns` flip on loop-step
+  start/settle).
+- Provenance: interactive QueueManager jobs snapshot the repo working tree pre-spawn and diff at
+  settle, exactly like one-shots (Code Explorer attribution intact).
+
+## Kill-switch matrix
+
+| Setting | Effect |
+|---|---|
+| `SPECRAILS_INTERACTIVE_JOBS=false` (server) | Byte-identical legacy everywhere: every job spawns one-shot, `/messages` + `/finalize` return 403, loop ai-steps one-shot, no `job.*` interactive events. |
+| `VITE_FEATURE_INTERACTIVE_JOBS=false` (client build) | Hides the composer UI; the server behaviour is unchanged (pair it with the server flag for a full opt-out). |
+| `EnqueueOptions.interactive: false` (per job) | That one job spawns one-shot; everything else unaffected. |
+| Provider without `persistentStdin` (codex, gemini) | Automatic one-shot fallback, no error, no composer. |
+| Default (nothing set) | Interactive ON for every claude job and every claude loop ai-step. |
+
+## Bare-mode launches (same branch)
+
+Also part of this change: a `POST /rails/:i/launch` carrying a bare legacy `mode` and **no
+`loopId`** (MCP tools, mobile, direct REST) now derives the matching **factory loop** when Loops
+are enabled (`rails-router.ts`), so every launch door runs through the LoopRunManager like the
+dashboard — identical worktree isolation and ask-first PR flow. Without this, an agent-launched
+implement landed in the bare QueueManager branch: shared cwd, `SPECRAILS_GIT_AUTO=false`, no
+delivery row — stranded uncommitted work. Loops disabled ⇒ the legacy QueueManager path,
+unchanged. Relatedly, the agent-chat operator prompt gained the ask-confirmation-once
+turn-discipline rule (`server/agent-operator-prompt.ts`): a confirmation question is asked
+exactly once and ends the reply — the answer arrives as the next user message.

package/docs/internals/loop-step-log-explorer.md

@@ -0,0 +1,146 @@
+# Loop-step log explorer
+
+The premium log surface for **loop runs**. When a job's `command` starts with `loop:`, both job views — the board's Job Detail page (`client/src/pages/JobDetailPage.tsx`, `variant="page"`) and the mission-mode job modal (`client/src/components/JobDetailModal.tsx`, `variant="glass"`) — mount `LoopStepExplorer` (`client/src/components/loop-log/LoopStepExplorer.tsx`) instead of the flat `LogViewer`. Non-loop jobs keep the legacy `LogViewer` byte-identical.
+
+The explorer does **not** introduce a second log pipeline. It consumes the exact same `events` array (persisted rows + live WS frames) and the exact same line parser (`parseEvent → mergeAssistantLines → applyDiffDetection` from `LogViewer`), then *segments* the result by three structured events the loop engine already persists on the run's backing job row.
+
+## Event contract
+
+Emitted by `server/loop-run-manager.ts` (payload interfaces are exported there — `LoopStepEventPayload`, `LoopStepEndEventPayload`, `LoopGraphEventPayload`). All three ride the run's job row as ordinary persisted `events` rows plus `event` WS broadcasts (`event_type` below, `payload` = JSON of the interface). Purely additive to the existing stream — no DB migration.
+
+### `loop_graph` — once, at run start
+
+Emitted after the run-header log lines, before the first `loop_step`. It is the run's graph **snapshot**, verbatim, so historical replay stays faithful when the loop is later edited or deleted (`loop_runs` stores no graph).
+
+```ts
+interface LoopGraphEventPayload {
+  graph: LoopGraph
+  loopId: string
+  loopName: string       // display name; falls back to the loop id
+  provider: string
+  model: string
+  iterationLimit: number
+}
+```
+
+### `loop_step` — appended + broadcast BEFORE each step spawns
+
+```ts
+interface LoopStepEventPayload {
+  index: number          // 1-based ordinal within the WHOLE run (monotonic across iterations)
+  kind: 'ai-step' | 'shell' | 'decider'
+  title: string
+  nodeId: string         // resolves against loop_graph's snapshot
+  iteration: number      // 1-based pass at emission; increments when a Decider evaluates
+                         // (the Decider itself belongs to the pass it closes)
+  template?: string      // ai-step only — the AUTHORED prompt (raw {{cmd:X}} string),
+                         // present only when rendering changed it (a plain free-text
+                         // prompt would duplicate command). Capped at ~1000 chars + '…'.
+  command?: string       // ai-step only — the RENDERED prompt actually sent (magic
+                         // commands expanded, spec/run/const tokens resolved; excludes
+                         // the injected cross-iteration history). Capped at ~2000 chars + '…'.
+}
+```
+
+**Removed flat-log lines (log hygiene).** The engine used to open every ai-step with two log lines — `Template: …` and `Command: …`. Once the explorer landed those were pure noise (they duplicated what belongs to the step header), so they are **no longer emitted for any step**; the information rides the `loop_step` payload fields above instead, and the step body opens directly on real output. The per-kind *signal* lines are unchanged: the decider's `Goal: …` and the shell's `$ <command>` / `(exit N)` still stream in the flat log, as does the `🧑 <command>` echo of an interactive session (that is the real transcript — not deduped). Legacy runs recorded before this change simply lack the payload fields (client tolerates `undefined` → no disclosure) and keep their old `Template:`/`Command:` lines in the replayed body.
+
+The client surfaces `template`/`command` as a subtle **ⓘ disclosure** in the step-box header (`LoopStepSection`): collapsed by default, expands a compact monospace detail block with per-field copy controls, rendered independently of the body collapse state.
+
+### `loop_step_end` — appended + broadcast at each step's tail
+
+```ts
+interface LoopStepEndEventPayload {
+  index: number          // matches the opening loop_step's index
+  nodeId: string
+  status: 'ok' | 'failed'
+  exitCode: number | null   // shell steps: the real exit code; ai-step/decider: null
+  durationMs: number         // executor-reported, else the step's wall-clock
+  decision?: 'continue' | 'stop'  // decider steps only — the verdict the run routed by
+}
+```
+
+A step torn down by manager shutdown / project removal (disposed, never settles) gets **no** end event — that absence is meaningful (see the status model). A traversal exception, by contrast, *does* close the open step as `failed` on the settle path.
+
+**Zero-work steps end `failed`.** An ai-step whose settle consumed no model work — the claude CLI's synthetic `Unknown command:` result frame (`num_turns` 0, no assistant events, zero usage; run `01f41203`) — ends `status:'failed'`, never `'ok'`: the step's command never actually ran (`isZeroWorkSettle`, shared with QueueManager — see [interactive-jobs.md](interactive-jobs.md)). Because the `Template:`/`Command:` flat-log lines are gone and `result` frames carry no display text, the reason is surfaced as a stderr-style line **inside the step's segment** (before its `loop_step_end`): `✖ Zero work performed — the command never ran: Unknown command: …` — emitted by the interactive session at settle, or by the engine itself on the one-shot path. Run-level routing is unchanged: the step routes exactly like a crashed step (graph-dependent continue + the consecutive-failure fail-fast abort, which zero-work steps count toward).
+
+### Seq guarantees
+
+The run owns a single monotonic seq allocator (`takeSeq` in `runLoop`), **shared with an interactive step session** that persists its own provider events/logs on the same job id:
+
+- `loop_graph` precedes the first `loop_step`.
+- Each `loop_step_end` is appended **after its step's last persisted output line** — every emit site sits past the step's settle `await`, and the interactive session takes its seqs from the same allocator synchronously as it streams, so the end event's seq is always greater.
+- Live WS frames carry no reliable seq, so the client groups in **arrival order**; a refetch (which replays `getJobEvents ORDER BY seq`) reconciles naturally because the model is derived from whatever `events` currently holds.
+
+The engine also still emits the flat-log divider line per step (`━━━━━━ Step N · title ━━━━━━`) so the plain `LogViewer`/export view stays readable. Inside the explorer that divider duplicates the step-box header, so `groupByLoopStep` drops it (`STEP_DIVIDER_RE`).
+
+## Grouping model (`loop-log-model.ts`)
+
+`groupByLoopStep(events)` is a pure function returning a `LoopLogModel`:
+
+- **Setup bucket** — every line seen before the first `loop_step` (run banner, worktree notice…) lands in `setup`, rendered as a collapsible **Setup** section.
+- **Segments** — each `loop_step` opens a new bucket; ordinary events are bucketed to the last-seen step. A `loop_step_end` attaches to the **last** segment with a matching `index` (arrival-ordered). Malformed/unparseable payloads are tolerated and skipped.
+- **Live activity** — while a step streams, `deriveFrameActivity` keeps the segment's `lastActivity` (the "Reading file…"-style label shown on the running step's header).
+- **Legacy tolerance** — runs recorded before the enrichment may lack `nodeId`/`iteration` (both tolerated as `null`) and lack `loop_graph` entirely; iteration badges and the iteration counter simply hide, and the strip falls back (below).
+
+## Status model
+
+`segmentStatus(seg, { isLast, jobSettled })`:
+
+| Condition | Status |
+|---|---|
+| `end` present | `end.status` (`ok` / `failed`) |
+| No end, last segment, job running | `running` |
+| No end, last segment, job settled | **`interrupted`** |
+| No end, earlier segment | `unknown` (the loop advanced past it — no status glyph; overview chips render it as done) |
+
+**Interrupted rule.** The contract says an end event may only be missing when the step was torn down mid-flight (dispose/shutdown/project removal), so *missing end + settled run* renders the dashed amber **Interrupted** treatment on both the step box and its overview chip.
+
+**Legacy caveat (accepted v1).** Completed runs recorded **before** the enrichment have no `loop_step_end` rows at all, so their *final* step renders as Interrupted even though the run finished normally (mid-run steps are `unknown` → shown as done). Accepted for v1 — enriching historical rows was judged not worth a backfill.
+
+## Overview strip (`LoopOverviewStrip.tsx`)
+
+One chip per graph node, states `pending → running → ok / failed / interrupted`:
+
+- **With `loop_graph`**: chips follow `traversalOrder(graph)` — DFS from Start, continue-branch first — so the strip reads start → body… → decider → end (the loop-back edge is implied). The End chip derives from the job outcome (`pending` until settled, then ok/failed).
+- **Decider chips** carry the latest verdict as an icon (continue = loop-back, stop = exit).
+- **Iteration counter** (right-aligned): `Iteration {current}/{limit}` when a limit is known, else a compact `iter {count}` badge; hidden entirely on legacy runs with no iteration data.
+- **Legacy fallback (no `loop_graph`)**: a linear strip derived from the `loop_step`s actually seen, one chip per distinct node identity in first-seen order. Node identity is `nodeId` when present, else `kind::cleanedTitle` with the legacy `"(iteration N)"` suffix stripped (`nodeKeyForSegment`), so repeat passes over the same node collapse into one chip.
+- Clicking a chip focuses that node's **latest** step box (expands + smooth-scrolls to it).
+
+## Follow-mode interaction design
+
+- **Follow (default)**: exactly the latest section is open — the running step, the final step once settled, or Setup when no step has started — with autoscroll pinned to the bottom. A "Following live" pulse shows in the toolbar while the job runs.
+- **Any manual interaction pauses follow**: toggling/focusing a section, expand/collapse-all, or scrolling more than 80px up from the bottom (programmatic scrolls land *at* the bottom so they never trip this — same idiom as `LogViewer`'s autoscroll). The current expansion state is captured as the manual set.
+- **Resume follow**: while paused on a running job (and not filtering), a floating pill re-enters follow mode and scrolls back to live.
+- **Filtering** searches every section: while the filter is non-empty, all sections are treated as expanded; clearing it restores the previous mode.
+- **Copy**: each step header carries its own copy button (per-step lines only; the control lives outside the toggle so the header stays a valid button), and the toolbar copy grabs the whole log with `── Step N · title ──` separators.
+
+## Performance
+
+- **Collapsed sections render nothing** — the body subtree is not mounted, so a 10k-line settled step costs one header row.
+- `LoopStepSection` is memoized with a custom comparator over `(segment.key, lines.length, tail-line content, end fields, lastActivity, status, collapsed, filter)` — a WS flush that only grows the running step never re-renders settled boxes. The tail-content check matters because a streamed assistant continuation merges *into* the last line (no length change).
+- Both surfaces already batch incoming WS events via `requestAnimationFrame` before they reach the model; `groupByLoopStep` recomputes per flush, memoized on `events` (and UI language, since `parseEvent` localises the result summary line).
+
+## Ticket refs in log lines
+
+`#N` ticket refs in prose log lines (both the flat `LogViewer` and the step boxes here, which share `LogLine`) linkify into a quiet underline-dotted affordance opening the board's `TicketDetailModal` — ticket-only (`components/log-ticket-refs.tsx` feeds `splitAgentRefs` an empty job-uuid set, so job ids never linkify — no modal-in-modal), with diff-styled/stderr lines and markdown code excluded; project scope threads via one optional `projectId` prop (mission `JobDetailModal` passes its own; the board page defaults to the active project) through `useLogTicketActions`, which reuses the agent-chat verify-then-open flow and `agent:refs.*` copy.
+
+## The JobDetailModal stdout fix
+
+Shipped with this feature: the mission-mode modal's WS handler previously appended only `stderr` `log` frames as synthetic events. Loop-run engine lines (`▶ Loop … started`, shell output, step dividers) stream as **stdout** `log` frames, so a live loop in the modal never grew — the log looked frozen until reopen. The handler now appends both stdout and stderr, matching `JobDetailPage`'s behaviour.
+
+## i18n
+
+All explorer strings live under the `jobs` namespace, `loopExplorer.*` (16 keys — setup, iteration, iterationBadge, follow, resumeFollow, expandAll, collapseAll, copyStep, copied, stepDetail, stepDetailTemplate, stepDetailCommand, copyCommand, interrupted, waiting, stepMapAria), translated in all 8 locales. Chip fallback labels reuse `loops:builder.nodes.*`.
+
+## Files
+
+| File | Role |
+|---|---|
+| `server/loop-run-manager.ts` | Event emission (`emitStep` / `emitStepEnd` / `loop_graph`), exported payload types, seq allocator |
+| `client/src/components/loop-log/loop-log-model.ts` | Pure grouping/status/chip model |
+| `client/src/components/loop-log/LoopStepExplorer.tsx` | Container: follow mode, filter, copy, toolbar |
+| `client/src/components/loop-log/LoopOverviewStrip.tsx` | Live chip strip + iteration counter |
+| `client/src/components/loop-log/LoopStepSection.tsx` | Per-step / Setup collapsible sections (memoized) |
+| `client/src/components/loop-log/loop-node-visuals.ts` | Node-kind icon + accent mapping |
+| `client/src/components/loop-log/__tests__/` | Model + explorer tests |