specrails-desktop 2.57.0 → 2.58.0

package/docs/internals/interactive-jobs.md

@@ -34,7 +34,7 @@ command. Spike-verified 2026-07-03 against **claude 2.1.198**: the claude CLI ex
 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/modules/execution/runtime/queue-manager.ts` `_startJob`, and `loop-executors.ts` `planInteractiveAiStep`). That
-makes every job — `/specrails:implement`, `/specrails:batch-implement`, distilled loop commands,
+makes every job — `/specrails:implement`, distilled loop commands,
 custom commands — transport-compatible, so the default flipped to interactive for every
 persistent-stdin-capable provider.
 
@@ -73,7 +73,7 @@ slipped in meanwhile queues/writes a new turn and **extends the session** instea
 
 ## Loop-step ownership and routing
 
-All dashboard rail launches (factory `Implement`/`Batch`/`Freestyle` and custom loops) run
+All dashboard rail launches (factory `Implement`/`Freestyle`/SDD Quick 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):

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

@@ -6,6 +6,38 @@ The explorer does **not** introduce a second log pipeline. It consumes the exact
 
 ## Event contract
 
+### Core v2 topology and concurrent attempts
+
+For v2 runs, `runtime-graph.graph` is the recorded public Core topology, including
+component references and outcome-labelled edges. The collapsible **Run graph**
+renders this snapshot without inventing transitions or exposing executable prompts.
+Selecting a component opens its nested graph; Back restores the parent and fits
+the viewport. Editing remains in Loop Builder.
+
+Selecting a node lists its recorded attempts by scope and attempt ID. Each entry
+focuses that exact log segment, including concurrent map branches. Status uses the
+latest attempt within each scope; a successful sibling cannot hide a failed one.
+Trace/span identifiers appear only when present in the recorded event. Core v2
+uses the same stable event-span identity in JSONL and optional OTLP export, so a
+selected attempt's recorded `step_started` span can be located in a collector.
+These are point events, not provider-duration spans. Identifiers do not prove
+that a collector was configured or accepted the export. Malformed
+topology is ignored without interrupting the normal log view. Legacy snapshots
+retain the existing overview strip.
+
+The v2 projection adds `attemptId`, `nodePath`, `scopeId`, `traceId` and optional
+`spanId` to step metadata. Log correlation uses an attempt-index map so parallel
+output is not assigned to whichever step happened to arrive last.
+
+For custom review roles, the root workflow inspector's **Review evidence node**
+selects an exact role-turn path, including component/map instances such as
+`checks/security`. The frozen run request carries that selection into fresh and
+recovered delivery evidence. Automatic mode reads native implementation reviews.
+Structured custom-role output must provide a review verdict; a role name alone
+does not qualify. Parallel scoped verdicts stay separate and do not acquire an
+invented aggregate confidence score. AI review never replaces host verification,
+and a file-based confidence score retains precedence over the runtime projection.
+
 Emitted by `server/modules/loops/runtime/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
@@ -144,3 +176,13 @@ All explorer strings live under the `jobs` namespace, `loopExplorer.*` (16 keys
 | `client/src/features/loops/components/loop-log/LoopStepSection.tsx` | Per-step / Setup collapsible sections (memoized) |
 | `client/src/features/loops/components/loop-log/loop-node-visuals.ts` | Node-kind icon + accent mapping |
 | `client/src/components/loop-log/__tests__/` | Model + explorer tests |
+
+### Repeat from an exact attempt
+
+Recorded v2 attempts expose **Repeat from here**, including internal component
+nodes. The request carries the node path, scope and visit; Core rejects ambiguous
+cuts. A stable request ID survives lost responses through the recovery endpoint.
+The linked child opens in the same project and starts paused for an explicit
+resume. Its original frozen inputs, worktree and delivery settlement are retained.
+The source remains historical; its resume/cancel/settlement effects are fenced once
+ownership moves. The engine does not roll back working-tree files automatically.

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

@@ -56,7 +56,7 @@ Mission mode (Agent Mode) replaces the routed dashboard, so `RailsBoard`, `Specs
 Parser pair `server/modules/delivery/runtime/rail-launch-parser.ts` ⇄ `client/src/features/rails/lib/rail-launch-draft.ts` (byte-identical except the mirror note; `server/modules/delivery/runtime/rail-launch-parser.test.ts` enforces parity). `extractRailLaunchProposals(content, streaming)` returns `{ body, proposals, rejected, pending, truncated, repaired }`:
 
 - tolerant JSON repair (`json-tolerant`) before rejecting; `repaired` flags it;
-- unknown keys dropped; `ticketIds` accepts `12`, `"12"`, `"#12"` (also under `specs` / `tickets`); `mode` accepts `batch` for `batch-implement`, `newRail: true` for an unnamed rail; `railIndex` is ignored when `newRail` is set;
+- unknown keys dropped; `ticketIds` accepts `12`, `"12"`, `"#12"` (also under `specs` / `tickets`); `mode` folds the removed `batch` / `batch-implement` into `implement`, `newRail: true` for an unnamed rail; `railIndex` is ignored when `newRail` is set;
 - rejection reasons: `invalid_json | not_object | unsupported_version | no_tickets | invalid_mode`, each with a ≤160-char excerpt — never silent;
 - while streaming an open fence is cut from the body (`pending`); once settled an unreadable open fence is cut and reported `truncated`;
 - every valid block is kept in order: a batch proposal is N blocks, N cards.

package/docs/internals/operations-runbook.md

@@ -207,3 +207,25 @@ Regenerates every icon size (PNG/ICNS/ICO) from `src-tauri/icons/icon.svg` via `
 - [CLI reference](../cli.md) — every command and flag in detail
 - [Architecture](architecture.md) — server modules, data flow, WebSocket protocol
 - [macOS](../platforms/macos.md) · [Windows](../platforms/windows.md) — platform-specific operations
+
+## CI verification lanes
+
+The `CI` workflow runs quality checks (types, compatibility, scripts, build, npm
+package, module boundaries and generated source map), server/CLI coverage and
+client coverage on independent runners. Both coverage suites retain their existing
+thresholds and publish separate reports. Native macOS, Windows Core assembly and
+runtime portability jobs remain required. The final `test` job preserves the check
+name used by branch protection and rejects any failed, skipped or cancelled lane.
+
+Push CI still runs on every branch: native release validation requires a trusted
+push run for the exact branch and commit. PR and merge-queue runs remain enabled.
+Concurrency cancels superseded runs within the same event/ref. No path filters
+exclude runtime or package verification during the engine migration.
+
+Before this split, CI run [36225340897](https://github.com/fjpulidop/specrails-desktop/actions/runs/36225340897)
+spent 18m40s in the sequential `test` job, including 6m13s server coverage and
+10m11s client coverage. The split removes that serial dependency; actual runtime
+and runner-minute changes must be measured from subsequent runs.
+
+
+CI partitioning and reuse of verified frontend assets are described in [CI performance](ci-performance.md).

package/docs/internals/programmatic-agent-runtime.md

@@ -1,6 +1,6 @@
 # Programmatic agent runtime
 
-Desktop can hand implementation to Core's **runtime API 1**. Core runs architect, developer, deterministic verification, reviewer and archive as separate LangGraph phases. Desktop keeps project/worktree selection, rail lifecycle, logs, accounting and delivery ownership.
+Desktop can hand implementation to Core's **runtime API 1**. Core runs architect, developer, fixer, deterministic verification, reviewer and archive as separate LangGraph phases. Desktop keeps project/worktree selection, rail lifecycle, logs, accounting and delivery ownership.
 
 This is the only implementation engine in the current source tree. It applies to implementation rail steps and their Core completion check. Mission chat and unrelated AI features keep their existing transports. Provider-native implementation prompts and skills are not invoked inside the programmatic phases.
 
@@ -29,7 +29,7 @@ npm run build:server
 node scripts/smoke-agent-runtime-pair.mjs
 ```
 
-This runs the compiled Desktop bridge and real bundled Core against a temporary localhost model fixture. It checks tool writes, a real verification subprocess, archive approval, resume, usage and host Git ownership. It uses a temporary repository and deletes it afterward. Pass `--core /absolute/path/to/Core/dist/agent-runtime/index.js` to exercise another built Core checkout.
+This runs the compiled Desktop bridge and real bundled Core against a temporary localhost model fixture. It checks tool writes, a real verification subprocess, archive approval, resume, usage and host Git ownership. The fixture explicitly selects the `free` agent loop; Core's compact pipeline has its own protocol tests. It uses a temporary repository and deletes it afterward. Pass `--core /absolute/path/to/Core/dist/agent-runtime/index.js` to exercise another built Core checkout.
 
 For web development, an explicit runtime override can point to the built module:
 
@@ -64,6 +64,19 @@ Desktop negotiates `runtime api` and sends configuration to `runtime validate --
 
 Settings are saved at `<project execution .specrails directory>/agent-runtime.json`. Missing configuration uses the default agent runtime. The retired enabled flag cannot select another engine. Malformed configuration blocks admission; it is not ignored. Saving verifies that Core exposes the expected API. Connections are stored globally in `~/.specrails/runtime-providers.json`; project files retain role references, models, limits and verification. Existing embedded connections migrate once, with stable disambiguated IDs on endpoint conflicts. New runs freeze the resolved configuration, while saved runs retain their original snapshot.
 
+With a paired Core advertising `openRoles: 1`, **Custom roles** adds named project
+roles with their own provider, model, prompt and explicit source/artifact access.
+New roles start with read-only source access and no artifact writes. Artifact
+access is independent: an analyst may read code and write OpenSpec documents
+without gaining source write access. Optional OpenSpec skills use the provider's
+native syntax. Custom roles reuse effort, turns and escalation controls; escalation
+can use the one permitted protocol repair and does not add another retry. Existing
+architect/developer/reviewer policies remain fixed. Removing a custom role affects
+future runs; admitted runs retain their frozen role configuration. Older Core
+packages keep ordinary settings available and reject saving unsupported roles.
+
+**A package of a larger checkout.** A repository registered as a subdirectory of its git checkout (for example `apps/web` inside a monorepo) is isolated in a worktree of the whole checkout, so Desktop passes that directory to Core as the repository `scope` in `desktop-context.json` (Core capability `repositoryScope`). Configured checks run inside the package: a check without `cwd`, or with a `cwd` relative to the registered directory, never runs at the checkout root, where a monorepo test script fans out to every workspace. Core keeps the change inside the scope: after each developer or fixer turn it undoes edits outside it, the reviewer judges only the git change set measured against the run's base, a check that fails for missing credentials, variables or registry access stops the run for the host instead of starting a correction round, and a correction loop that stops converging stops with the reason instead of repeating the same checks. Runs admitted before scopes existed keep their frozen whole-checkout context.
+
 Core owns role instructions and permissions. The developer role edits and runs commands inside its CLI sandbox (the same autonomy as the legacy Implement step); architect and reviewer are read-only. A legacy rail profile/model selection does not override the runtime's per-role provider configuration. The JSON schema is [server/schemas/agent-runtime.schema.json](../../server/schemas/agent-runtime.schema.json), mirrored from Core. For a complete configuration, custom executor examples, Kimi capabilities and API tooling details, see [Core's runtime guide](https://github.com/fjpulidop/specrails-core/blob/main/docs/agent-runtime.md) in the paired revision.
 
 The built-in Claude adapter supports its native dollar cap. Built-in Codex, Gemini, Kimi and OpenAI-compatible adapters reject `maxCostUsd`; remove that limit for mixed-provider/local runs. Kimi also rejects token caps because its usage is unavailable. Unknown cost/tokens remain unknown in accounting, rather than becoming zero. Attempt, timeout and tool limits remain available. Existing provider services, licenses and inference costs are separate from the free open-source orchestration runtime.
@@ -107,15 +120,37 @@ All routes are under `/api/projects/:projectId`:
 | `POST /agent-runtime/runs/:runId/resume` | Accept `{}`, `{ "approve": ["archive"] }`, `{ "recover": ["developer"] }`, explicit `invalidate` phase IDs, or `{ "answer": "…" }` for a pending question (required while one is open) |
 | `POST /agent-runtime/runs/:runId/cancel` | Cancel a continuation owned by this controller |
 
-Resume responds `202` after admission and continues asynchronously. The valid phase IDs are `architect`, `developer`, `verify`, `reviewer` and `archive`. Core's lease remains the cross-process concurrency guard. A run cannot be resumed while its original Desktop execution is active.
+Resume responds `202` after admission and continues asynchronously. Legacy phase IDs are `architect`, `developer`, `fixer`, `verify`, `reviewer` and `archive`. For engine v2, use `POST /loop-runs/:runId/resume` instead. `recover` contains exact attempt IDs from `GET /loop-runs/:runId/recovery`; approval and answer controls use pending interrupt IDs. Node paths are display context, not recovery identities. The saved-execution panel and job header expose explicit per-attempt selection. Core's lease and Desktop's execution/mount claim jointly prevent competing writers. Resident human pauses keep their original settlement callback; restart recovery reconnects to the frozen delivery allocation and terminal outbox.
 
-Desktop launches `node <Core>/dist/agent-runtime/cli.js` with structured argv (`--approve`, `--recover`, `--invalidate`, `--answer <text>` on resume) and consumes JSON lines for phase events (`workflow-event`), agent output (`agent-event`), verification output, trace spans (`span`: `{ traceId, spanId, name, stepId, attempt, visit, startedAt, endedAt, status, usage?, error? }`) and the terminal `runtime-result`. Spans are stored verbatim as job events for diagnostics and are not narrated in the log. `runtime status --compact` returns `state.traceId`, `pendingApproval`, `pendingQuestion` and per-step `{ status, visits }`. Desktop probes `runtime api` once per Core CLI file revision (path plus mtime/size); `runtime validate --stdin` runs on every save. The job log shows phase transitions (`[runtime] step_started: developer`), live tool activity per role (`[developer] Read src/app.ts`, `[developer] Bash npm test`) and Core's own phase notes (architecture written, verification passed, review approved or corrections requested); the final JSON of architect and reviewer is not echoed. The narrated view (Relato) derives its milestones from the same events: each runtime phase, the tools used, correction loops and a stopped workflow with Core's structural reason. Accounting uses the invocation's new attempts, so resuming a completed phase does not bill its cumulative history twice. Status queries use `--compact`, are read-only and do not invoke providers; accumulated logs stay in Core's checkpoint instead of overflowing the process status response.
+Desktop launches `node <Core>/dist/agent-runtime/cli.js` with structured argv (`--approve`, `--recover`, `--invalidate`, `--answer <text>` on resume) and consumes JSON lines for phase events (`workflow-event`), agent output (`agent-event`), verification output, trace spans (`span`: `{ traceId, spanId, name, stepId, attempt, visit, startedAt, endedAt, status, usage?, error? }`) and the terminal `runtime-result`. Spans are stored verbatim as job events for diagnostics and are not narrated in the log. `runtime status --compact` returns `state.traceId`, `pendingApproval`, `pendingQuestion` and per-step `{ status, visits }`. Desktop probes `runtime api` once per executable package content digest; `runtime validate --stdin` runs on every save. The job log shows phase transitions (`[runtime] step_started: developer`), live tool activity per role (`[developer] Read src/app.ts`, `[developer] Bash npm test`) and Core's own phase notes (architecture written, verification passed, review approved or corrections requested); the final JSON of architect and reviewer is not echoed. The narrated view (Relato) derives its milestones from the same events: each runtime phase, the tools used, correction loops and a stopped workflow with Core's structural reason. Accounting uses the invocation's new attempts, so resuming a completed phase does not bill its cumulative history twice. Status queries use `--compact`, are read-only and do not invoke providers; accumulated logs stay in Core's checkpoint instead of overflowing the process status response.
 
 Provider invocation/cancellation supports native macOS processes and Windows executables/npm shims. Actual provider behavior still depends on the installed CLI version and capabilities. The offline tests cover fake CLI/ACP frames, Windows argv rules, a local HTTP coding fixture and real verification subprocesses; live provider smoke tests and Windows CI remain separate validation.
 
+## Definition catalog compatibility (D0)
+
+Desktop accepts optional `engineVersion`, `nodeKindsVersion`, `nodeKinds` and
+`builtins` metadata from `runtime api`; malformed descriptors are protocol errors.
+An empty catalog can use version 0. The integration contract target is 5.1;
+engine/catalog/builtin metadata is informational and older supported Core
+packages remain compatible. D0 does not enable definition execution.
+
+`validateWorkflowDefinition` invokes `workflows validate --stdin` only when Core
+advertises `workflowDefinitions: 1`. Core returns the canonical hash and graph or
+structured node errors, including valid error responses with exit 1. Desktop
+does not calculate a competing definition hash.
+
+Compact v2 status normalizes `nextNodePath` to existing controls and accepts
+metrics from the top-level response. Resume validates syntax first, then exact
+membership in the run's step catalog. Role metrics use the frozen runtime config,
+so later settings changes cannot add roles to an existing run. Legacy readers
+remain the fallback when no catalog exists. Historical projections will gain the
+authoritative graph catalog in D2; D0 does not infer one from metrics themselves.
+V2 inspection is uncached because a legacy journal does not track SQLite/WAL
+changes. C0 published-package pairing remains a separate release gate.
+
 ## Rollout and release pairing
 
-The committed registry bundle lock and `CORE_BUNDLE_VERSION` currently pin **Core 5.1.1**, a previously published package. That pin does not incorporate these source changes. Source assembly is the supported development route until the paired Core runtime release is available.
+The committed registry bundle lock and `CORE_BUNDLE_VERSION` currently pin **Core 6.0.0**, a previously published package. The inspected source pair is Core 6.0.1 with workflow identity 7 and role instructions 10; D0 keeps those identities intact. That pin does not incorporate these source changes. Source assembly is the supported development route until the paired Core runtime release is available.
 
 A production release must:
 
@@ -123,7 +158,7 @@ A production release must:
 2. Update `scripts/assemble-bundled-core.lock.json` and `CORE_BUNDLE_VERSION` together to that exact release, capturing the full dependency integrity closure.
 3. Run Core package checks, Desktop compatibility/package checks and both macOS/Windows native validation before packaging the paired app.
 
-Do not relabel an old 5.1.1 bundle or copy only `dist/agent-runtime`: LangGraph and the complete runtime dependency closure are required. Source assembly writes `source-bundle.json` with the Core version, runtime API and lock hash for traceability; it does not publish Core or update the production registry lock.
+Do not relabel an existing 6.0.0 bundle or copy only `dist/agent-runtime`: LangGraph and the complete runtime dependency closure are required. Source assembly writes `source-bundle.json` with the Core version, runtime API and lock hash for traceability; it does not publish Core or update the production registry lock.
 
 Verify role outputs, delivery ownership and saved-run recovery before releasing the paired app. Implementation has no legacy fallback; profile v1 remains only for other workflows. Core's programmatic archive writes reviewed **complete specification replacements**; it does not merge partial OpenSpec delta snippets. Preserve unchanged requirements in the architect's output and inspect that behavior during the pilot.
 
@@ -135,7 +170,7 @@ The [implementation verification record](programmatic-agent-runtime-validation.m
 
 Core's additive runtime metrics v1 are passed from compact status to each saved run's optional `metrics` field. The contextual run panels and Jobs history render a collapsed **Usage and time** panel with reported cost, active execution/agent time, calls and token/cache totals, plus per-phase attempts, duration, provider calls and cost. All eight locales include the panel labels.
 
-Older Core versions continue to work without the panel. The server validates numeric fields and known phase IDs, drops unsupported/malformed metrics and projects only the supported fields; it never forwards arbitrary transcripts from the metrics object. Missing billing is displayed as unavailable rather than zero. Cache tokens are already included in input tokens, and agent duration already includes native tool work. The panel does not estimate savings or measure implementation quality.
+Older Core versions continue to work without the panel. The server validates numeric fields and legacy phase IDs, or the authoritative step and frozen-role catalogs of a v2 run, drops unsupported/malformed metrics and projects only the supported fields; it never forwards arbitrary transcripts from the metrics object. Missing billing is displayed as unavailable rather than zero. Cache tokens are already included in input tokens, and agent duration already includes native tool work. The panel does not estimate savings or measure implementation quality.
 
 The paired `agent-runtime-efficiency` OpenSpec change in specrails-core documents verification ownership, efficient API tools and the measurement contract. Core exposes the same report through `runtime status` / `runtime-result`, so a fixed set of real tasks can be compared without a Desktop database migration.
 
@@ -204,3 +239,91 @@ uses Core's existing evidence/receipt store and cannot mark workflow phases done
 OpenSpec checks validate real files without copying or archiving them. Old retained
 Core packages lacking `scopedRecovery` are not upgraded/migrated behind the run's
 back: the tool returns a manual-repair limitation rather than recommending Relaunch.
+
+### Definition cancellation after restart
+
+`POST /loop-runs/:runId/cancel` accepts an optional stable `requestId`. A `202`
+means the retained Core inbox acknowledged cancellation. The original resident
+execution still owns its callback. For a restarted execution, Desktop observes
+Core until its writer lease is inactive, then replays terminal events through
+Loop Manager and reconnects the original isolated settlement. A completed result
+that wins the race remains completed; cancellation never rewrites its verdict.
+
+The observer stops on project shutdown and leaves Core's durable intent for
+startup recovery. Unavailable status or a lease that remains active beyond the
+bounded observation window records a `definition-control-error` event in the
+original job. That diagnostic does not mark the job or delivery successful.
+Recovery preserves repository mounts, frozen verification policy, accounting,
+worktree ownership and the terminal outbox. Missing original isolated allocation
+data blocks settlement instead of treating the execution as a standalone job.
+For historical v2 multi-repository records, explicit recovery can reconstruct a
+missing allocation snapshot when the original frozen manifest/context, worktree
+ledger and delivery branch records agree, including the captured initial SHA and
+never-commit exclusions. All repository legs restore atomically. Reconstruction
+checks the original Git common directory, grants no automatic cleanup permission
+and does not infer missing values from current checkouts or project settings.
+Incomplete records and borrowed-PR continuations without their original contract
+remain blocked with a recovery diagnostic.
+
+### Lost fork acknowledgement
+
+Once Desktop adopts a child, the parent remains immutable history. Restart does
+not mark that historical parent as a new interrupted execution. Active-run counts,
+workflow edit guards and repository execution references follow the child; a
+completed child therefore does not leave its paused parent blocking edits forever.
+The host crash fixture kills the settlement process between two repository legs,
+reopens the real project database and replays startup reconciliation before retry.
+It checks one commit and one provenance receipt per leg, cleared orphan claims,
+verified delivery to review and unchanged parent database/journal state.
+
+Core forks may include a stable `requestId`. The retained engine stores the exact
+fork request and original receipt before publication. Desktop preserves a child
+if acknowledgement or host metadata writing fails, and reuses that request ID to
+finish missing frozen files. Existing files must match exactly. A conflicting
+request or destination is rejected; the source and child Core databases are never
+replaced by host cleanup. Older children without receipts cannot be adopted by a
+new request.
+
+### Workflow decision role
+
+Factories and starters use `loop-decider` for evidence-based continuation. The
+bridge binds this role only when the compiled definition declares it, after
+effective provider/model overrides. Its default inherits the review engine with
+`access: read`, `artifacts: none` and no OpenSpec skill. Explicit project engine
+and prompt settings win; incompatible permission/skill settings fail before
+execution. The generated descriptor and selection origin are frozen per run,
+without modifying the project config. The config endpoint exposes available
+workflow defaults separately for builder choices. Native implementation's
+reviewer still requires its original OpenSpec workflow.
+
+### Paired engine CI
+
+The required `paired-core-engine` matrix builds the commit-pinned Core checkout
+on Linux, macOS and Windows and exports both source-root variables. It checks
+schema parity, four factories, custom-role read-only CLI arguments, durable
+fork/control recovery, real host/Core crashes during read/write/human pauses or between nodes,
+and two-repository settlement. Crash acceptance retains production lease TTLs,
+requires exact write-attempt recovery and verifies frozen configuration plus
+idempotent physical-call accounting. Transport fixtures make no
+paid provider calls. Review and advance the Core pin with paired changes; ordinary
+coverage lanes may omit optional source fixtures, but the required matrix cannot.
+
+### Inspecting released workflow mounts
+
+Definition recovery can inspect an existing retained Core journal after its
+original repository mount disappears. This uses the read-only `status --run-dir`
+operation against the original owned journal, rejects redirected journal paths,
+and does not recreate a worktree or replace frozen paths with current settings.
+Status retains Core's recorded completion or pause and reports
+`runtime_scope_unavailable`; resume remains disabled until the original scope is
+available and validated. Inspection alone does not authorize delivery settlement.
+
+### Per-piece invocation limits
+
+With a Core catalog that exposes them, `prompt`, `role-turn` and `decider` accept
+`timeoutMs` and `idleTimeoutMs` in their parameter forms. An explicit `0` disables
+that invocation timer; removing the optional field restores the inherited
+default. Workflow duration/cost/token budgets and cancellation still apply.
+Role repair and session fallback retain the selected bounds, including Kimi ACP
+transport. A verification prompt reporting `LOOP_BLOCKED` pauses for the human
+answer before its success sentinel can be accepted.

package/docs/internals/project-builder.md

@@ -2,11 +2,12 @@
 
 > OpenSpec change `add-project-builder`. Greenfield project creation from an
 > idea: a day-0 blueprint conversation, an orchestrated bootstrap commit, and a
-> milestone lifecycle (Launch M1 batch rail, sidebar re-entry, Generate M2+).
+> milestone lifecycle (Launch M1 — one spec per rail, sequential —, sidebar
+> re-entry, Generate M2+).
 
 > **Kimi capability boundary:** Kimi may be selected as a target provider for
 > the materialized project, and it may launch an already committed milestone
-> through the normal agentic Batch rail. Day-0 blueprint snapshots and M2+
+> through ordinary agentic Implement rails. Day-0 blueprint snapshots and M2+
 > milestone generation are pure structured-output actions and therefore fail
 > closed for Kimi 0.27 `-p`; no Kimi process is spawned for them.
 
@@ -505,22 +506,29 @@ step 6 it is an ordinary project missing only the remote.
 
 Generating detailed M2+ specs uses the same pure-output capability gate as
 day-0 blueprint generation. Kimi cannot be selected for that generation turn.
-Launching the already committed M1/M2+ tickets is ordinary Batch rail
-execution and can use Kimi.
+Launching the already committed M1/M2+ tickets is ordinary Implement rail
+execution (one spec per rail) and can use Kimi.
 
 - **Launch Milestone N is SERVER-owned** (premium-milestone-progress D3):
-  `POST /api/projects/:id/blueprint/milestones/:n/launch { mode }`
+  `POST /api/projects/:id/blueprint/milestones/:n/launch { autoAdvance? }`
+  (always sequential: the retired `mode: 'parallel'` is still accepted from
+  old clients and runs sequentially — the 202 echoes `mode: 'sequential'`;
+  any other `mode` is a 400)
   (`client/src/features/builder/lib/milestone-launch.ts` `launchMilestone` is one POST; the
   old browser-local `MilestoneSequencerContext` + its `localStorage` plan are
   GONE — `dropLegacySequentialPlans()` forgets the leftover key on load).
   `server/modules/builder/runtime/milestone-chain.ts` `MilestoneChainManager` gathers the `M<n>`
-  `todo` tickets, chunks them (≤3, `chainRailName` → `M<n>` / `M<n> · k`),
+  `todo` tickets, orders them by dependencies (`orderChainTickets`: stable
+  topological order over `prerequisites` inside the set, ties by
+  `execution_order` then id; a cycle never blocks), puts ONE spec on each
+  rail (`MAX_TICKETS_PER_CHAIN_CHUNK = 1`, `chainRailName` → `M<n> · #<id>`,
+  launch body `mode: 'implement'`),
   persists ONE `milestone_launch_chains` row (`server/modules/builder/runtime/milestone-chain-store.ts`,
   migration 58, partial unique index = one non-terminal chain per milestone;
   CAS `updateChain`) and launches chunk 1 through the app's OWN rails launch
   route over loopback (`server/internal-api.ts`, lifted from the MCP tools'
   `apiCall`) so every existing guard applies and each 4xx becomes a typed
-  `pause_reason` (`launch_rejected:<error>`). **Sequential (default)** chains
+  `pause_reason` (`launch_rejected:<error>`). The chain
   the next chunk when the in-flight chunk's DELIVERY settles — the manager taps
   the project's bound broadcast for `rail.pr_state` (the engine's
   `onLoopRunFinished` fires BEFORE the delivery row leaves `building`, so it is
@@ -546,12 +554,23 @@ execution and can use Kimi.
   the same milestone likewise reuses a rail already named for the chunk
   (`io.findRailByName` → `rails-store` `getRails`) when it holds no undecided
   delivery, so relaunching M1 never piles up duplicate "M1 · 1" rails;
+  **Rail limit (MAX_RAILS 12).** Before creating a rail the manager reuses a
+  free builder-owned rail — the retried chunk's rail, a rail already named for
+  the spec, a rail this chain used, then any `M<n>`-named rail — where "free"
+  means no undecided delivery, no active job/loop run (`io.railBusy`) and no
+  other chain mid-flight on it; a reused rail is renamed after its spec
+  (`io.renameRail`, best effort). When no rail is free and `POST /rails`
+  answers `rail_limit_reached`, a later spec PAUSES the chain with
+  `pause_reason: rail_limit_reached` (localized: decide pending PRs to free a
+  rail, then Resume launches the same spec); on the FIRST spec nothing
+  launches, the row is cancelled and the route relays 409
+  `rail_limit_reached`.
   `…/cancel` stops the chain and leaves in-flight rails alone. Startup
   recovery (`recoverOnStartup`, run once the HTTP server listens) replays a
   chunk that settled while the server was down exactly once.
-  **Wave checkpoints (D9).** The row carries `auto_advance` (default 1 for
-  API callers; the UI sends the user's stored preference
-  `localStorage['specrails-desktop:milestone-auto-advance']`, default OFF)
+  **Wave checkpoints (D9).** The row carries `auto_advance` (default 1 when
+  omitted; the UI sends the user's stored preference
+  `localStorage['specrails-desktop:milestone-auto-advance']`, default ON)
   and a non-terminal status `awaiting_approval`. When a chunk's delivery
   settles successfully and auto-advance is off (and chunks remain), the
   manager records the head and parks the chain at `awaiting_approval`
@@ -563,13 +582,13 @@ execution and can use Kimi.
   counts as active (one non-terminal chain per milestone, cancellable) and is
   ignored by startup recovery (waiting for the user is the point); a failure
   always PAUSES regardless of the flag (checkpoints are reached only by
-  success). Client: `launchMilestone(projectId, n, mode, { autoAdvance })`,
+  success). Client: `launchMilestone(projectId, n, { autoAdvance })`,
   `setChainAutoAdvance`, `readMilestoneAutoAdvance`/`saveMilestoneAutoAdvance`
   (`milestone-launch.ts`); `chainAtCheckpoint` + `isMilestoneLaunchable`
-  excludes a checkpoint (`milestone-progress.ts`). **Parallel**
-  launches every chunk at once from the integration branch (row recorded
-  `completed` so the progress model still orders the rails). Kill switch
-  `SPECRAILS_MILESTONE_CHAIN=false` ⇒ parallel, no row. Merging a STACKED
+  excludes a checkpoint (`milestone-progress.ts`). The former **Parallel**
+  option and the `SPECRAILS_MILESTONE_CHAIN=false` kill switch were removed
+  (`remove-batch-and-sequential-builder`); completed `mode: 'parallel'` rows
+  already in the database still render ("Parallel launch"). Merging a STACKED
   chunk sweeps its merged ancestors (`sweepMergedChainAncestors` in
   `rail-pr-decision.ts`: chain-local, `git merge-base --is-ancestor`, same
   CAS + ticket effect + Jira hook) and merge-local integrates into the CHAIN's
@@ -577,7 +596,7 @@ execution and can use Kimi.
   discarding a delivery a later chunk was built on pauses its chain
   (`pauseChainsForDiscardedHead`) and the decision surfaces warn first
   (`discardStackedNote` ×3 namespaces). Offered on the Builder done screen and
-  the sidebar entry with the Sequential | Parallel toggle.
+  the sidebar entry with the auto-continue switch (no launch-mode toggle).
 - **Milestone progress is SERVER-derived** (premium-milestone-progress D2):
   `server/modules/builder/runtime/milestone-progress.ts` `deriveMilestoneProgress` builds, per
   milestone, counts by spec state (`total/done/onReview/inProgress/todo/failed`