specrails-desktop 2.55.0 → 2.56.0

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

@@ -1,12 +1,12 @@
 # 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 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/features/jobs/pages/JobDetailPage.tsx`, `variant="page"`) and the mission-mode job modal (`client/src/features/jobs/components/JobDetailModal.tsx`, `variant="glass"`) — mount `LoopStepExplorer` (`client/src/features/loops/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.
+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
 
@@ -137,10 +137,10 @@ All explorer strings live under the `jobs` namespace, `loopExplorer.*` (16 keys
 
 | 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 |
+| `server/modules/loops/runtime/loop-run-manager.ts` | Event emission (`emitStep` / `emitStepEnd` / `loop_graph`), exported payload types, seq allocator |
+| `client/src/features/loops/components/loop-log/loop-log-model.ts` | Pure grouping/status/chip model |
+| `client/src/features/loops/components/loop-log/LoopStepExplorer.tsx` | Container: follow mode, filter, copy, toolbar |
+| `client/src/features/loops/components/loop-log/LoopOverviewStrip.tsx` | Live chip strip + iteration counter |
+| `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 |

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

@@ -6,7 +6,7 @@
 
 Mission mode (Agent Mode) replaces the routed dashboard, so `RailsBoard`, `SpecsBoard`, `RailRow` (with `RailPrDecisionStrip` and `AgentRuntimeRuns`) are never mounted there. The only object a mission had for an implementation run was the PR-decision card. On 2026-09-18 three gaps were verified:
 
-1. **No git ⇒ no object.** The shared-cwd launch path in `server/rails-router.ts` (`isolationUnavailable = 'no-git' | 'no-commits'`) never received `originConversationId`; no `rail_pr_deliveries` row, no card, only a `202 { isolationUnavailable }` the agent rarely mentioned.
+1. **No git ⇒ no object.** The shared-cwd launch path in `server/modules/delivery/runtime/rails-router.ts` (`isolationUnavailable = 'no-git' | 'no-commits'`) never received `originConversationId`; no `rail_pr_deliveries` row, no card, only a `202 { isolationUnavailable }` the agent rarely mentioned.
 2. **Failure was mute.** `discarded` swallowed `statusDetail` (gated on `deliveryBlocked`); `implementation_failed` offered Discard only; no WS event wrote into the conversation or started a turn; `/agent-runtime/runs` (resume / approve / recover) was absent from MCP.
 3. **Assignment was prose.** Rails were not a palette entity; assigning specs meant dictating rail / engine / profile / loop in sentences, so users went to Board mode.
 
@@ -53,7 +53,7 @@ Mission mode (Agent Mode) replaces the routed dashboard, so `RailsBoard`, `Specs
 }
 ```
 
-Parser pair `server/rail-launch-parser.ts` ⇄ `client/src/lib/rail-launch-draft.ts` (byte-identical except the mirror note; `server/rail-launch-parser.test.ts` enforces parity). `extractRailLaunchProposals(content, streaming)` returns `{ body, proposals, rejected, pending, truncated, repaired }`:
+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;
@@ -67,29 +67,29 @@ Parser pair `server/rail-launch-parser.ts` ⇄ `client/src/lib/rail-launch-draft
 
 | Piece | Where | Notes |
 |---|---|---|
-| Operator prompt | `server/agent-operator-prompt.ts` `RAIL_LAUNCH_CARD_SECTION`, `RAIL_LAUNCH_CARD_SYSTEM_CLAUSE`, `buildOperatorSystemPrompt()` | Propose = block; launch directly only on an explicit "now"; failure briefing reply ≤ 6 lines + one action, no mutation. Gated on `isMissionRailCardsEnabled()`. |
+| Operator prompt | `server/modules/missions/runtime/agent-operator-prompt.ts` `RAIL_LAUNCH_CARD_SECTION`, `RAIL_LAUNCH_CARD_SYSTEM_CLAUSE`, `buildOperatorSystemPrompt()` | Propose = block; launch directly only on an explicit "now"; failure briefing reply ≤ 6 lines + one action, no mutation. Gated on `isMissionRailCardsEnabled()`. |
 | Message intent | desktop-db migration 29 (`agent_messages.intent`, column-guarded); `agent-store.ts` `setAgentMessageIntent`; `PATCH /api/agent/conversations/:id/messages/:mid/intent` | JSON ARRAY of decisions keyed by `proposalIndex`; append-only; 409 `already_decided`; 403 when the feature is off. Rows expose `intents[]`. |
 | Envelope | `server/types.ts` `PrDecisionCardEnvelope` (+ `MissionRunPhase`, `MissionRunRuntime`, `MissionRunFailure`) | `hasDelivery`, `phase`, `railName`, `runtime` — all optional; `decision` vocabulary unchanged. |
-| Run-only cards | `server/mission-run-notify.ts` `runCardId` / `isRunCardId` / `buildRunCardEnvelope` / `postRunCard` / `settleRunCard` / `failureForLoopOutcome` / `runtimeFromSummary` | Synthetic `prDeliveryId = 'run:<runId>'`, `hasDelivery:false`. Wired in the shared-cwd branch of `rails-router.ts` (origin stored on `railLoopRuns` meta; 202 returns `runIds`). |
+| Run-only cards | `server/modules/missions/runtime/mission-run-notify.ts` `runCardId` / `isRunCardId` / `buildRunCardEnvelope` / `postRunCard` / `settleRunCard` / `failureForLoopOutcome` / `runtimeFromSummary` | Synthetic `prDeliveryId = 'run:<runId>'`, `hasDelivery:false`. Wired in the shared-cwd branch of `rails-router.ts` (origin stored on `railLoopRuns` meta; 202 returns `runIds`). |
 | Run-only dismiss | `POST /rails/pr-decision { prDeliveryId:'run:…', action:'dismiss', expectedDecision, conversationId }` → `AgentChatManager.dismissRunCard` | Other actions ⇒ 400 `run_card_dismiss_only`; unknown card ⇒ 404 `run_card_not_found`. |
 | Failure trigger | `notifyMissionRunFailure` (`mission-run-notify.ts`) | Envelope update with `runtime.failure` → `AgentChatManager.postRunFailureRow` (one `system` row per run, WS `agent_run_failure`) → `AgentChatManager.startSystemTurn` (queueId `mission-failure:<runId>`, gated `isMissionFailureTurnEnabled()`). Callers: shared-cwd run promise, isolated settle (`implementation_failed`), `closeFailedGeneration` (`launch_failed`). Cancel updates the card, no turn. No origin ⇒ no-op. |
-| Briefing | `server/agent-failure-briefing.ts` `buildFailureBriefing`, `failureBriefingRef`, `FAILURE_CODE_LABELS`, `FAILURE_BRIEFING_MAX_TAIL` | Fixed text: rail, specs, failure code + detail, bounded verify tail, recovery options, "do not relaunch by yourself". Persisted as a `user` row whose `context_refs[0].kind === 'system-briefing'`. |
+| Briefing | `server/modules/missions/runtime/agent-failure-briefing.ts` `buildFailureBriefing`, `failureBriefingRef`, `FAILURE_CODE_LABELS`, `FAILURE_BRIEFING_MAX_TAIL` | Fixed text: rail, specs, failure code + detail, bounded verify tail, recovery options, "do not relaunch by yourself". Persisted as a `user` row whose `context_refs[0].kind === 'system-briefing'`. |
 | Settle snapshots | `rail-isolated-launch.ts` settle, `rail-pr-store.ts` `toPrDecisionCardEnvelope`, `agent-runtime-controls-router.ts` `runtimeRunSummary()` | `phase` + `runtime` on `implementation_failed` and launch-failed `discarded`; `statusDetail` as text. |
 | Rails availability | `GET /:projectId/rails` | `availability: 'free' \| 'busy' \| 'pending_decision' \| 'on_review'` per rail. |
 | MCP | `server/mcp/tools/jobs.ts` `runtime_runs`, `runtime_evidence` (read) · `runtime_resume`, `runtime_recover` (ai-spawn) · `runtime_approve`, `runtime_settle`, `runtime_dismiss` (write) · `runtime_cancel` (destructive); `mcp/guide.ts` recovery section | Over the existing `/agent-runtime/runs` routes; approve/recover are `resume` bodies. |
-| Palette | `server/agent-chat-router.ts` `CONTEXT_KINDS` += `rail`; `server/agent-context-resolver.ts` `formatRail` | `@rail-N` reference serialization. |
+| Palette | `server/modules/missions/runtime/agent-chat-router.ts` `CONTEXT_KINDS` += `rail`; `server/modules/missions/runtime/agent-context-resolver.ts` `formatRail` | `@rail-N` reference serialization. |
 
 WS messages: `agent_pr_decision` (existing, now carries the new fields), `agent_run_failure` (new, app-global, `AgentRunFailureMessage`).
 
 ## Client components
 
-- `client/src/components/agent-chat/AgentMessage.tsx` — extraction step after spec-draft (flag `FEATURE_MISSION_RAIL_CARDS`); renders `AgentRailLaunchCard` per proposal, `AgentRailLaunchPending`, `AgentRailLaunchUnreadable`.
+- `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`.
-- `client/src/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 dock; `AgentPrPinnedDock.tsx` — proposals pinned above PR cards.
 - `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`.
-- `client/src/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.
-- Palette: `client/src/lib/agent-context-palette.ts` (`rail` kind, `railsFromResponse`, `railChip`), `AgentComposer.tsx`, `AgentComposerEditor.tsx`, `AgentContextPalette.tsx`.
+- `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.
+- Palette: `client/src/features/missions/lib/agent-context-palette.ts` (`rail` kind, `railsFromResponse`, `railChip`), `AgentComposer.tsx`, `AgentComposerEditor.tsx`, `AgentContextPalette.tsx`.
 
 ## Honesty rules
 
@@ -120,11 +120,11 @@ Migration 29 and the envelope fields are additive; persisted intents are inert w
 
 | Area | Tests |
 |---|---|
-| Parser + promotion + mirror parity | `server/rail-launch-parser.test.ts` |
+| Parser + promotion + mirror parity | `server/modules/delivery/runtime/rail-launch-parser.test.ts` |
 | Intent store/route, `dismissRunCard` | `server/agent-message-intent.test.ts` |
-| Run-only cards, availability, run-card dismiss route | `server/rails-router.test.ts`, `server/mcp/tools/rails-origin.test.ts` |
-| Failure trigger / briefing / system turn | `server/mission-run-notify.test.ts`, `server/agent-failure-briefing.test.ts`, `server/agent-chat-mission-turn.test.ts`, `server/rail-isolated-launch.test.ts` |
+| Run-only cards, availability, run-card dismiss route | `server/modules/delivery/runtime/rails-router.test.ts`, `server/mcp/tools/rails-origin.test.ts` |
+| 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/components/agent-chat/__tests__/agent-rail-launch-card.test.tsx` |
+| 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` |
 | 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/modular-architecture.md

@@ -0,0 +1,107 @@
+# Architecture decision: capability modules with selective ports and adapters
+
+Status: capability ownership is implemented across the application, including
+server features, React features and CLI responsibilities. Hexagonal boundaries
+are applied to cores that benefit from substitutable effects. Runtime coordinators
+are explicitly effectful; this is not a claim that every class is infrastructure-free.
+
+## Decision and scope
+
+Keep a modular monolith and the existing deployment units. A change should have an
+identifiable owner, focused public entry points and adjacent behavioral tests.
+Use functions and composition; a generic repository, base-manager hierarchy,
+service locator or DI container would add machinery without solving the observed
+coupling. Folder moves alone do not constitute dependency inversion.
+
+| Area | Implemented ownership and boundary | Why this shape |
+| --- | --- | --- |
+| Server capabilities | [14 modules](../../server/modules/README.md), [195 production files and public subpaths](../../server/modules/boundaries.json) | Related stores, runtime coordination and tests are discoverable together; dependencies are reviewed explicitly |
+| React capabilities | [21 features](../../client/src/features/README.md), [public subpaths and dependencies](../../client/src/features/boundaries.json) | UI, hooks, state, feature clients and tests belong to the same feature; focused subpath imports avoid eagerly loading every view |
+| Project settings | [Domain, application, repository port, HTTP/SQLite adapters](../../server/modules/project-settings/README.md) | Validation is independent of transport; updates validate first and commit atomically |
+| Execution | [Scheduling, accounting, recovery and budget enforcement](../../server/modules/execution/README.md) | Policies run without a database/process manager; recovery reads ordered evidence through a lazy adapter and preserves native-vs-estimated usage |
+| Delivery | [Decision policy and workflows](../../server/modules/delivery/README.md) | Lifecycle vocabulary is independent of storage; publication, recovery, discard and local merge have separate workflows with an acyclic dependency guard |
+| Conversations | [Recovery context and stream policies](../../server/modules/conversations/README.md) | Byte limits, exact missing-session detection and chunk filtering are testable independently of provider processes |
+| Persistence | [Connection, migrations and domain repositories](../../server/db/) behind [the public facade](../../server/db.ts) | Preserve schema history, query behavior and transaction ownership while separating unrelated concerns |
+| CLI | [Parsing, formatting, output, HTTP transport, execution and lifecycle modules](../../cli/README.md) | The executable only dispatches; parsing/formatting have no infrastructure imports and commands cannot depend on the executable |
+
+## Boundaries deliberately retained
+
+These areas were assessed and keep their existing responsibility boundaries;
+moving them again would obscure package/resource contracts or duplicate adapters.
+
+| Area | Retained entry points | Rationale |
+| --- | --- | --- |
+| Server composition | [startup](../../server/index.ts), [project registry](../../server/project-registry.ts), [project routes](../../server/project-router.ts), [desktop routes](../../server/desktop-router.ts) | Own project lifetime, route ordering and dependency wiring |
+| Provider strategies | [provider contract](../../server/providers/types.ts), [registry](../../server/providers/registry.ts), [runtime](../../server/providers/runtime.ts) | Existing substitutable provider strategies already model different capabilities and stream semantics |
+| Integrations | [Jira](../../server/jira/), [plugins](../../server/plugins/), [mobile](../../server/mobile/), [MCP](../../server/mcp/) | Existing cohesive subsystems; preserve their public contracts rather than create parallel frameworks |
+| Resource/platform adapters | [Core compatibility](../../server/core-compat.ts), [command resolver](../../server/command-resolver.ts), [shell resources](../../server/terminal-shell-integration.ts), [MCP configuration](../../server/agent-mcp-config.ts) | Resource lookup depends on source/npm/sidecar locations; retain stable package anchors |
+| Local engine | [runner](../../local-runner/src/runner.ts), [HTTP client](../../local-runner/src/openai-client.ts), [tools](../../local-runner/src/tools.ts), [sessions](../../local-runner/src/sessions.ts) | The existing executable, protocol, transport, tools and session split is useful and contract-tested |
+| MCP bridge | [entry](../../mcp-bridge/src/index.ts), [bridge](../../mcp-bridge/src/bridge.ts), [HTTP transport](../../mcp-bridge/src/http-transport.ts) | Already separates process wiring, protocol handling and transport |
+| Native shell | [Tauri composition](../../src-tauri/src/lib.rs), [invoke guard](../../src-tauri/src/invoke_guard.rs), [browser ownership](../../src-tauri/src/browser_ownership.rs), [mission windows](../../src-tauri/src/mission_windows.rs) | Platform/window integration belongs at the native boundary, not behind JavaScript repository interfaces |
+| Shared frontend infrastructure | [App](../../client/src/App.tsx), [API context](../../client/src/lib/api.ts), [project cache](../../client/src/hooks/useProjectCache.ts), [UI primitives](../../client/src/components/ui/) | Application composition and reusable infrastructure remain shared; feature-specific code lives with its owner |
+
+## SOLID and patterns in the implemented design
+
+- **Single responsibility:** persistence repositories, CLI handlers, delivery
+  workflows and feature-owned source replace unrelated responsibilities in one
+  entry file. Runtime coordinators retain lifecycle/state ownership.
+- **Open/closed:** add real variation through existing provider strategies,
+  executor callbacks and use-case ports. Do not add an interface for every function.
+- **Liskov substitution:** fake and production ports must preserve atomic writes,
+  error propagation, unknown usage values, ordering and provider capability limits.
+- **Interface segregation:** settings exposes read/update; accounting exposes
+  write/identity; recovery exposes ordered evidence and provider interpretation;
+  budgets expose snapshots and exceeded effects. No complete project registry is
+  passed into these application cores.
+- **Dependency inversion:** domain/application files have fixed import allowlists.
+  SQLite and provider interpretation implement the recovery boundary; settings
+  HTTP/SQLite adapters are wired at composition.
+
+Retain strategies/adapters, explicit application use cases, compatibility facades,
+composition roots and durable outboxes. Preserve existing compare-and-set leases
+and transactions: replacing them with ephemeral pub/sub would break crash recovery.
+A state machine is useful for action legality; it does not require replacing the
+existing persisted lifecycle vocabulary with a competing model.
+
+## Enforcement and review
+
+[Server architecture tests](../../server/modules/architecture.test.ts) verify the
+reviewed [manifest](../../server/modules/boundaries.json), every core's fixed
+allowlist and the acyclic delivery workflow graph. Regenerating the runtime
+manifest cannot authorize an infrastructure dependency inside a protected core.
+[CLI architecture tests](../../cli/architecture.test.ts) protect pure parsing/
+formatting, entry-point direction and acyclic command dependencies.
+
+[Frontend boundary checks](../../scripts/audit-client-features.mjs) record public
+subpaths and direct capability dependencies and reject imports back into
+application composition. Existing cross-feature collaborations are explicit;
+this inventory does not claim that every feature is independent or acyclic.
+
+Use `npm run audit:architecture` after a boundary change. Regenerate manifests only
+after reviewing the new dependency and update the owning README. Typecheck enforces
+unused imports/locals; [source audit](../../scripts/audit-source.mjs) inventories
+reachability across application, demo, CLI, local-runner and MCP entry points.
+
+## Preserved behavior and limits
+
+- Source moves update imports, dynamic imports, test mocks, source-reading fixtures,
+  coverage paths, packaging probes and navigation links together.
+- Keep queue reservation synchronous; keep cancellation, durable promotion,
+  terminal settlement, replay and PR ownership idempotent.
+- No historical database migrations are rewritten. Settings updates are atomic;
+  accounting/recovery continue inside their original transaction owner.
+- Frontend project switching, streaming state, route shapes and UI behavior remain
+  unchanged. Coverage exclusions move to equivalent files; thresholds are unchanged.
+- Large stateful coordinators still exist inside `runtime/`. Their location is
+  explicit and their policies have narrower seams; no claim is made that every
+  controller is a pure application service or that all architectural debt is gone.
+- No blanket runtime-performance gain is claimed. The concrete query improvement
+  reads the six project settings in one query. Source ownership is intended to
+  reduce change scope and navigation cost, not to manufacture a benchmark result.
+
+## Human and AI navigation
+
+[AGENTS.md](../../AGENTS.md) supplies concise working rules and a feature map;
+[CLAUDE.md](../../CLAUDE.md) imports it. Feature READMEs expose public contracts,
+collaborators and test commands. The [generated source map](source-map.md) links
+source and adjacent tests; historical detail stays in optional reference documents.

package/docs/internals/profiles.md

@@ -151,7 +151,7 @@ update.
 A few internals worth knowing if you're working on this surface:
 
 - **Version gate.** Profile-aware spawns are gated by
-  `projectSupportsProfiles()` (`server/queue-manager.ts`), which reads the
+  `projectSupportsProfiles()` (`server/modules/execution/runtime/queue-manager.ts`), which reads the
   project's `.specrails/specrails-version` and requires
   `specrails-core >= 4.1.0`; Kimi additionally requires the Core 4.12 target.
   Below the applicable floor, the rail spawns in legacy mode and no profile

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

@@ -138,3 +138,69 @@ Core's additive runtime metrics v1 are passed from compact status to each saved
 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.
 
 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.
+
+## Diagnose before retrying
+
+`GET /agent-runtime/runs/:runId/diagnosis` (MCP: `specrails_jobs runtime_diagnose`)
+returns the original scope, historical completed steps, up to eight recent
+failed/interrupted attempts, verification and acceptance reasons, and a recovery
+recommendation. It performs no provider calls or mutations. Repeated matching
+step/error pairs recommend repairing the precondition before retrying. A missing
+history on an older retained Core is unknown, not zero failures.
+
+MCP `runtime_evidence` accepts `evidenceId`, `section`, `sourceId`, `cursor` and
+`limit` to inspect the actual evidence beyond its index. `canResume` only means
+resume is available. Changed receipts can still cause verification and review
+to repeat; no zero-cost promise is made. A succeeded run awaiting settlement
+should use `runtime_settle`, preserving the existing implementation.
+
+Paired Core now preserves OpenSpec's output when archive exits successfully
+without creating its destination, and distinguishes that from multiple matching
+destinations. Retrying a failed archive keeps valid verification/review receipts;
+changed candidate files or environment still require fresh evidence. These Core
+fixes require a newly bundled/released runtime; retained original runtimes are
+not silently replaced or migrated. Diagnosis does not add arbitrary file-write
+access: repairs without a supported scoped tool are reported as concrete manual
+steps instead of being disguised as a reason to relaunch.
+
+## Repair the original worktree
+
+`specrails_recovery` calls `POST /agent-runtime/runs/:runId/recovery` with a
+strict action-specific request. It never constructs a new context/worktree.
+
+| Action | Inputs and permission | Result |
+| --- | --- | --- |
+| inspect | read | Original repository IDs, registered check definitions, recent attempts |
+| list_files / read_file / diff | repositoryId + relative path; read | Bounded directory/line/diff output; read_file includes SHA-256 |
+| history | optional offset; read | Latest attempts first, pages of 20 with nextOffset |
+| patch | repositoryId, path, expectedHash, oldText, newText, operationId UUID, reason; write | One unique replacement in an existing file, atomic publication |
+| check | kind openspec or verification; saved checkId for verification; operationId + reason; destructive | Real validation evidence, bounded output and durable outcome |
+
+Patches are limited to 16 KiB fragments and files readable within 128 KiB.
+Runtime/provider metadata, secret paths, frozen OpenSpec changes/config/archives,
+agent instructions, traversal, symlinks and platform aliases are rejected. New
+files, deletions and arbitrary commands are not supported. Explicit repository IDs
+prevent cross-project resolution. Verification runs one registered command with a
+45-second deadline; full acceptance remains the normal resume/settlement path.
+
+Desktop blocks admission while project executions are active and reserves the
+run/rail. Core takes the same cross-process lease as Resume. An interrupted write
+requires `acknowledgeInterrupted` after inspecting partial changes. Completed or
+archived runs cannot be patched or checked through recovery. Inspection remains
+available. This is an application boundary, not an OS sandbox against unrelated
+processes modifying the worktree concurrently.
+
+Core stores at most 100 attempts in `recovery-history.json` beside the pipeline
+state, separate from checkpoints. Each mutation has a write-ahead operation ID,
+request fingerprint, cause, before/after hashes where relevant and final outcome.
+Reuse the exact request/ID after transport uncertainty. A pending patch whose
+after-hash is present is reconciled; other pending operations become interrupted
+and are not rerun. Repeating a failed check on unchanged candidate code requires
+a documented `changedPrecondition`; this records the operator's explanation, not
+an independent proof that an external prerequisite changed.
+
+Resume still enforces verification, review and acceptance. Scoped verification
+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.

package/docs/internals/project-builder.md

@@ -30,7 +30,7 @@ route).
   the in-flight builder turn (`POST /abort`) and resets every session slice.
   The agent's own chrome (project/mission selectors, conversation, queue,
   pinned cards) is hidden while active but NEVER unmounted.
-- Session logic in `client/src/hooks/useBuilderSession.ts` (extracted from the
+- Session logic in `client/src/features/builder/hooks/useBuilderSession.ts` (extracted from the
   retired shell): bootstrap, `blueprint.*` WS handling with NULL-SAFE identity
   checks (a pre-bootstrap/pre-commit null ref must never match a null/absent
   message id), phases, snapshot, send/commit/launch actions, `dirty` flag.
@@ -101,20 +101,20 @@ generator's pure-output policy. A direct Kimi request is rejected before
 `BlueprintChatManager` spawns. This does not prevent the approved blueprint
 from declaring Kimi among the new project's target providers.
 
-- **Manager**: `server/blueprint-chat-manager.ts` `BlueprintChatManager` — an
+- **Manager**: `server/modules/builder/runtime/blueprint-chat-manager.ts` `BlueprintChatManager` — an
   app-level sibling of `AgentChatManager` reusing `runAiCliInvocation`. Spawns
-  from `~/.specrails/builder-cwd/` (`server/builder-cwd-manager.ts`: always
-  re-written instruction files from `server/blueprint-operator-prompt.ts`, NO
+  from `~/.specrails/builder-cwd/` (`server/modules/builder/runtime/builder-cwd-manager.ts`: always
+  re-written instruction files from `server/modules/builder/runtime/blueprint-operator-prompt.ts`, NO
   `./project` symlink, NO MCP). Auto-heal: a resume that yields no text retries
   fresh once. Abort keeps partial text and records `aborted`.
 - **Persistence**: `blueprint_conversations` / `blueprint_messages` in
-  `desktop.sqlite` (migration 22; CRUD in `server/blueprint-store.ts`).
+  `desktop.sqlite` (migration 22; CRUD in `server/modules/builder/runtime/blueprint-store.ts`).
 - **WS**: app-global `blueprint.stream` / `blueprint.done` / `blueprint.error`
   (no `projectId`; NOT in the mobile-ws translation layer). `blueprint.done`
   carries the STRIPPED `fullText` plus the last valid `blueprint` snapshot.
 - **Accounting**: one `agent_invocations` row per settled turn with
   `project_id NULL` (the Home-turn precedent). No backfill after creation.
-- **REST**: `/api/blueprint/*` (`server/blueprint-router.ts`) — conversations
+- **REST**: `/api/blueprint/*` (`server/modules/builder/runtime/blueprint-router.ts`) — conversations
   CRUD, `/send` (202, 409 while streaming), `/abort`, `/models`, `/commit`.
   `/models` returns the provider's `efforts` catalog; `/send` accepts only a
   catalog-valid `reasoning_effort`, and providers without the capability omit
@@ -224,7 +224,7 @@ the provider session (later turns `--resume`); two-step inline discard →
 `DELETE`. The exit confirm copy no longer threatens to discard the blueprint —
 it says where to pick it up.
 
-**5. Readiness, made legible (client).** `client/src/lib/blueprint-readiness.ts`
+**5. Readiness, made legible (client).** `client/src/features/builder/lib/blueprint-readiness.ts`
 `deriveReadiness` turns the same deterministic report into three steps —
 **blueprint** (5 dimensions) · **specs** (count within 5–10 and
 `specsComplete`) · **audit** (issues excluding the two batch-level codes) —
@@ -285,8 +285,8 @@ Fenced ` ```blueprint-draft ` JSON blocks. FULL snapshots, LAST syntactically
 valid block wins, streaming tail cut (unterminated trailing fence never
 parsed/shown — `cutUnterminatedBlock`). Unknown keys dropped; missing or
 non-integer `blueprintVersion` rejects the block. Parser pair:
-`server/blueprint-draft-parser.ts` ⇄ `client/src/lib/blueprint-draft.ts` (keep
-coercion rules in sync). Schema types in `server/blueprint-types.ts`:
+`server/modules/builder/runtime/blueprint-draft-parser.ts` ⇄ `client/src/features/builder/lib/blueprint-draft.ts` (keep
+coercion rules in sync). Schema types in `server/modules/builder/runtime/blueprint-types.ts`:
 `product{name,pitch,audience}`, `coreFlow`, `platform`,
 `stack{language,framework,db,notes?}`, `assumptions[]`,
 `milestones[]{id,title,goal,status: planned|committed|done, plannedSpecs[],
@@ -318,7 +318,7 @@ files remain readable (and returns null for missing/corrupt input).
 
 There is no Builder-specific “lite spec” format. Every detailed Builder spec
 uses the normal Specrails contract, and since premium-milestone-progress the
-prose that teaches it lives in ONE module — `server/spec-contract-prompt.ts`
+prose that teaches it lives in ONE module — `server/modules/specs/runtime/spec-contract-prompt.ts`
 (`premiumSpecContract(mode)`, `premiumSpecContractCompact(mode)`,
 `PREMIUM_SCAFFOLD_EXAMPLE`, `SPEC_DEPTH_FLOORS`) — consumed by the Builder
 operator prompt, `ChatManager._buildMilestoneSystemPrompt` (M2+) and the
@@ -353,10 +353,10 @@ uncertainty. `PREMIUM_SCAFFOLD_EXAMPLE` is the mandatory first spec written
 at that depth; "shorter is a defect, not a style". The floors were raised
 because the old minima ("at least two bullets", 4–10 criteria) became the
 ceiling the model aimed at (design D6/D8). Test fixtures that need a
-gate-valid spec use `server/blueprint-spec-fixtures.ts` ⇄
+gate-valid spec use `server/modules/builder/runtime/blueprint-spec-fixtures.ts` ⇄
 `client/src/lib/__tests__/premium-spec-fixture.ts`.
 
-`server/blueprint-spec-quality.ts` is the shared deterministic authority. It
+`server/modules/builder/runtime/blueprint-spec-quality.ts` is the shared deterministic authority. It
 validates `specsComplete=true`, the complete-set size, all fields/sections
 above (including the depth floors — issue codes `section_depth` carries the
 heading + min chars, `section_bullets` the min, `criteria_count` the 6–10
@@ -449,7 +449,7 @@ the panel's spec card shows "writing…" / "not written yet" instead of
 `location_already_registered`; rich-spec failures include actionable spec/field
 detail) → 202 `{commitId}` → per-step
 `blueprint.commit_progress` → terminal `blueprint.commit_done{projectId}` /
-`commit_failed{step,error}`. Orchestrator: `server/blueprint-commit.ts`
+`commit_failed{step,error}`. Orchestrator: `server/modules/builder/runtime/blueprint-commit.ts`
 `createBlueprintCommitRunner` (DI IO bag — every step fail-injectable in
 tests). Step order:
 
@@ -468,7 +468,7 @@ tests). Step order:
    ("reinstall the app"). Verifies the workspace exists afterwards.
 4. `blueprint` — `writeBlueprintPair` into `<workspace>/.specrails/`
    (`blueprint.json` source of truth + deterministic `blueprint.md`,
-   `server/blueprint-render.ts`; repo stays pristine)
+   `server/modules/builder/runtime/blueprint-render.ts`; repo stays pristine)
 5. `tickets` — `mutateStore` on the workspace `local-tickets.json`: `todo`,
    label `M1`, `source='project-builder'`, `created_by='project-builder'`, spec
    order preserved, generated priority/short summary/domain labels retained,
@@ -510,12 +510,12 @@ execution and can use Kimi.
 
 - **Launch Milestone N is SERVER-owned** (premium-milestone-progress D3):
   `POST /api/projects/:id/blueprint/milestones/:n/launch { mode }`
-  (`client/src/lib/milestone-launch.ts` `launchMilestone` is one POST; the
+  (`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/milestone-chain.ts` `MilestoneChainManager` gathers the `M<n>`
+  `server/modules/builder/runtime/milestone-chain.ts` `MilestoneChainManager` gathers the `M<n>`
   `todo` tickets, chunks them (≤3, `chainRailName` → `M<n>` / `M<n> · k`),
-  persists ONE `milestone_launch_chains` row (`server/milestone-chain-store.ts`,
+  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'
@@ -579,7 +579,7 @@ execution and can use Kimi.
   (`discardStackedNote` ×3 namespaces). Offered on the Builder done screen and
   the sidebar entry with the Sequential | Parallel toggle.
 - **Milestone progress is SERVER-derived** (premium-milestone-progress D2):
-  `server/milestone-progress.ts` `deriveMilestoneProgress` builds, per
+  `server/modules/builder/runtime/milestone-progress.ts` `deriveMilestoneProgress` builds, per
   milestone, counts by spec state (`total/done/onReview/inProgress/todo/failed`
   — `failed` = specs back at `todo` whose NEWEST delivery unit failed), the
   milestone's rails (active runs + non-terminal deliveries, chunk-ordered), the

package/docs/internals/review-packet.md

@@ -20,7 +20,7 @@ verbs.
 
 This is the load-bearing design constraint, not a nicety. Three rules:
 
-1. **Every claim carries its source.** `server/review-packet.ts` splits proof
+1. **Every claim carries its source.** `server/modules/delivery/runtime/review-packet.ts` splits proof
    into three tiers and the tier travels with the item so the UI must label it:
 
    | Tier | Source | UI framing |
@@ -75,7 +75,7 @@ nothing-changed cases are exactly where a non-technical user is most abandoned:
 
 ## Decision verbs
 
-`client/src/lib/packet-verbs.ts` maps the FULL delivery state space (12
+`client/src/features/delivery/lib/packet-verbs.ts` maps the FULL delivery state space (12
 decisions × 9 actions × orthogonal outcome/status axes ≈ 14 presentation states)
 onto Accept / Request changes / Discard — and marks every state where that
 reduction would lie as `fineControlOnly`. Those states (the recovery family, a
@@ -84,7 +84,7 @@ instead of a friendly relabel of git work. The module header carries the full
 table; `resolvePacketVerbs` is total, defaulting to `fineControlOnly` rather
 than guessing.
 
-**Accept declares what it physically does.** `server/accept-ladder.ts`
+**Accept declares what it physically does.** `server/modules/execution/runtime/accept-ladder.ts`
 pre-resolves the ladder from shipped probes (`git remote`, offline
 `gh auth token`) and fails CLOSED to `merge-local`:
 
@@ -100,7 +100,7 @@ holds no optimistic state; a raced answer surfaces the neutral
 
 ## Surfaces
 
-- Routed page `/review/:prDeliveryId` (`client/src/pages/ReviewPacketPage.tsx`) —
+- Routed page `/review/:prDeliveryId` (`client/src/features/delivery/pages/ReviewPacketPage.tsx`) —
   chosen over a portal so the documented z-order ladder is irrelevant.
 - Entry points: a `Review` button on the rail strip's `on_review` row and on the
   agent-chat PR card. Both keep their precise git actions.
@@ -147,7 +147,7 @@ public catalog: its prompt consumes `{{const:REVISION_REQUEST}}`, which only a
 revision launch injects. The router forces this loop for any revision whatever
 the rail's stored mode is; without that, every tweak would re-run implement.
 
-**Fresh session by contract** (`server/revision-seed.ts`). The run is seeded from
+**Fresh session by contract** (`server/modules/execution/runtime/revision-seed.ts`). The run is seeded from
 durable state — the instruction, the frozen spec, the branch that carries the
 work, and what the previous run actually REPORTED (failure first). `--resume` of
 the prior session is not attempted: sessions are cwd-scoped to a released
@@ -177,7 +177,7 @@ rejected: it treats a 40-cent typo fix and a nine-dollar thrash identically.
 ## Narrated progress (Wave 3b)
 
 The third altitude on the job log surfaces, between the glance-level phase chips
-and the raw log. `client/src/components/loop-log/narration-model.ts`
+and the raw log. `client/src/features/loops/components/loop-log/narration-model.ts`
 `buildNarration` turns the persisted event stream into MILESTONES:
 
 - Each milestone is a stable i18n key plus factual values — nothing in the model
@@ -204,7 +204,7 @@ synthesised client-side.
 
 **The toggle** follows the Code explorer's Story|Log precedent and DEFAULTS to
 narrated, on both the routed Job Detail page and the mission-mode modal. The
-preference is one app-level key (`client/src/lib/job-log-mode.ts`) rather than
+preference is one app-level key (`client/src/features/jobs/lib/job-log-mode.ts`) rather than
 per-project: it describes the reader, not a project, and splitting it made the
 two surfaces disagree about what the same person had chosen. With
 `VITE_FEATURE_NARRATED_PROGRESS=false` both surfaces render byte-identically to
@@ -228,6 +228,6 @@ Observed: the section rendered the spec's *Proposed Solution* digest as raw mark
 
 ## 2026-09-19 — Programmatic-runtime evidence (host-run verification + reviewer verdict)
 
-Observed: a delivery built by the programmatic agent runtime (core-host) rendered **"The AI did not report any verification"** and **"No reviewer score"** although the host had run `npm test` (exit 0, output persisted) and the reviewer returned a structured verdict (score 92). The harvest only knew the legacy loop channels — the `VERIFICATION:` prose sentinel and `openspec/changes/**/confidence-score.json` — neither of which that runtime produces. Fix (`server/delivery-evidence.ts` `readRuntimeEvidence`, wired from `rail-isolated-launch.ts` via the new `EvidenceHarvestUnit.runtimeDir` = `<workspace>/.specrails/pipeline/<runId>`): read `state.json` `verification.commands[]` (+ each `verification/evidence/<id>.json` for exit code, duration, bounded output and `origin`), `acceptance.checks[]` / `acceptance.findings[]`, and the reviewer step output in `agent-workflow/<runId>/checkpoint.json` (`approved`, `score`, `aspects`, `issues`, `summary`). Every field is bounded; a malformed file degrades to nothing.
+Observed: a delivery built by the programmatic agent runtime (core-host) rendered **"The AI did not report any verification"** and **"No reviewer score"** although the host had run `npm test` (exit 0, output persisted) and the reviewer returned a structured verdict (score 92). The harvest only knew the legacy loop channels — the `VERIFICATION:` prose sentinel and `openspec/changes/**/confidence-score.json` — neither of which that runtime produces. Fix (`server/modules/delivery/runtime/delivery-evidence.ts` `readRuntimeEvidence`, wired from `rail-isolated-launch.ts` via the new `EvidenceHarvestUnit.runtimeDir` = `<workspace>/.specrails/pipeline/<runId>`): read `state.json` `verification.commands[]` (+ each `verification/evidence/<id>.json` for exit code, duration, bounded output and `origin`), `acceptance.checks[]` / `acceptance.findings[]`, and the reviewer step output in `agent-workflow/<runId>/checkpoint.json` (`approved`, `score`, `aspects`, `issues`, `summary`). Every field is bounded; a malformed file degrades to nothing.
 
 Tier placement (`review-packet.ts` `buildProof`): commands whose `origin` includes `host` are **app-verified** (`proof.hostCommandPassed|Failed` with exit code + seconds + output tail) — the runtime executed them and recorded the exit code, which is a measurement, not a claim; non-host acceptance checks, the reviewer summary and findings are **ai-reported** (`proof.acceptanceCheckPassed|Failed`, `proof.reviewerSummary`, `proof.reviewerFinding`); the structured verdict fills `confidence` (score/aspects/issues→flags) ONLY when no file-based score exists, so the **reviewer-score** tier and the human-review band work unchanged. `proof.noVerificationReported` is emitted only when no channel reported anything. Older deliveries heal lazily: `GET …/packet` runs `healRuntimeEvidence` over units lacking `runtime` and persists the result (`updatePrDeliverySettleEvidence`), so a packet stops claiming silence once the pipeline dir exists. Still never a numeric test-count claim: the "70 passed" line rides inside the labelled raw output, not as a number the app asserts.

package/docs/internals/safe-pr-review-flow.md

@@ -10,7 +10,7 @@
 ## The single source of truth
 
 `rail_pr_deliveries` (per-project `jobs.sqlite`, migrations 36/38/48–54; CRUD in
-`server/rail-pr-store.ts`) stores one durable **generation** per implementation launch. A partial
+`server/modules/delivery/runtime/rail-pr-store.ts`) stores one durable **generation** per implementation launch. A partial
 unique index enforces one non-terminal generation per rail. Reimplementing an attached PR creates
 generation B and atomically moves generation A to terminal `superseded`; A cannot reappear through
 ordinary replay after B closes. The sole exception is an allocation rollback committed in the same
@@ -110,7 +110,7 @@ branch or detached HEAD, a temporary checkout claims the base without switching
 A base already held by another worktree remains untouched and reports `integration_branch_busy`.
 Both temporary checkouts use non-force cleanup, including after a Git runner exception.
 
-## Launch and recovery wiring (`server/rail-isolated-launch.ts`)
+## Launch and recovery wiring (`server/modules/delivery/runtime/rail-isolated-launch.ts`)
 
 - `prMode` is captured once. Admission is rechecked inside the per-repository allocation lock;
   two requests cannot both create a generation or reuse the ticket-keyed worktree.
@@ -247,7 +247,7 @@ at launch:
 
 `POST /rails/pr-decision` `{ prDeliveryId, action, expectedDecision }` (replaces the stateless
 v1 `POST /rails/pr-review`). The route validates and delegates to
-`server/rail-pr-decision.ts` `executePrDecision` (deps injected — db/git/exec/broadcast/jira/
+`server/modules/delivery/runtime/rail-pr-decision.ts` `executePrDecision` (deps injected — db/git/exec/broadcast/jira/
 agent-chat — so the whole matrix unit-tests without git/gh/network).
 
 Before any Git, GitHub, cleanup or ticket effect, the endpoint atomically claims the row's leased
@@ -279,7 +279,7 @@ Transient observation failure keeps the evidence and fails retryably.
 Initial settlement records exact post-push `CLOSED` as `pr_closed`; exact post-push `MERGED` stays
 attached and ready for Verify so that explicit decision can commit terminal ticket intent atomically.
 
-- **create-pr** — deferred `deliverRailAsPr` (`server/rail-pr-delivery.ts`: 1 unit → its
+- **create-pr** — deferred `deliverRailAsPr` (`server/modules/delivery/runtime/rail-pr-delivery.ts`: 1 unit → its
   branch; N → assembled onto the conventional batch branch off the integration branch, one PR
   covering every ticket). The PR **title and canonical body are composed here** (see "Branch
   naming & PR content" below) from the ticket store + `jira_links` + the branch diffs — all
@@ -355,7 +355,7 @@ state → 409 (`stale_decision` + `reason: 'illegal_action'`).
 ## Branch naming & PR content (pr-naming.ts / pr-body.ts)
 
 Conventional, open-source-style naming for everything the user sees on GitHub. All pure string
-logic in `server/pr-naming.ts` (branches + titles) and `server/pr-body.ts` (canonical body +
+logic in `server/modules/delivery/runtime/pr-naming.ts` (branches + titles) and `server/modules/delivery/runtime/pr-body.ts` (canonical body +
 diff collection), fully unit-tested.
 
 - **`<ref>`** — the ticket's Jira key when Jira-linked, else the local ticket number. **JIRA
@@ -408,7 +408,7 @@ the `expectedDecision` they rendered.
   the exact `A.restoredFromDeliveryId=B` rollback after B terminalizes, and advance the same id only
   through newer `updatedAt` evidence. A delayed A snapshot without that paired proof cannot replace
   B, and a non-terminal replay cannot ordinarily reopen an id already observed terminal.
-- **Option A — dashboard.** `client/src/context/RailPrDecisionContext.tsx` (registerHandler on
+- **Option A — dashboard.** `client/src/features/delivery/context/RailPrDecisionContext.tsx` (registerHandler on
   the shared socket + `GET /rails` seed) feeds `RailPrDecisionStrip` on `RailRow` (both density
   branches): on_review → Create PR / Discard; pr_draft → Open PR + Publish / Discard (degraded →
   retry); pr_ready → Verify PR; no_changes → Done/refine; pr_closed → Reopen; pr_failed derives
@@ -433,7 +433,7 @@ the `expectedDecision` they rendered.
   no migration; TS unions widened) whose content is the `PrDecisionCardEnvelope` JSON.
   `AgentChatManager.postPrDecisionCard` / `updatePrDecisionCard` (idempotent update-in-place on
   every transition, transactionally consolidating legacy duplicate rows by delivery id) are reached via the
-  process-wide `server/agent-chat-registry.ts` singleton (null-safe: tests/disabled builds).
+  process-wide `server/modules/missions/runtime/agent-chat-registry.ts` singleton (null-safe: tests/disabled builds).
   Live updates ride the app-global `agent_pr_decision` WS event; the client renders
   `AgentPrDecisionCard` and POSTs the same project-scoped `/rails/pr-decision`. Client hydration,
   WS upsert and rendering also dedupe by delivery id, so stale blocked and current ready cards can
@@ -469,7 +469,7 @@ launches are unaffected.
 The launch body accepts an optional `targetPrNumber` — the user's explicit designation of an
 existing open PR as the delivery destination ("extend PR #151"). It bypasses the automatic-inference
 status gates (which never probe GitHub for a `todo` ticket) but keeps the authoritative validation
-ladder: `resolveExplicitPrTarget` (`server/active-pr-continuation.ts`) resolves the number to its
+ladder: `resolveExplicitPrTarget` (`server/modules/delivery/runtime/active-pr-continuation.ts`) resolves the number to its
 canonical URL, observes the lifecycle, and throws `ExplicitPrTargetError` with a distinct code —
 `target_pr_not_found` (404) / `target_pr_not_open` / `target_pr_fork` (`isCrossRepository !== false`)
 / `target_pr_invalid` / `target_pr_unfetchable` (all 409) — rejecting the launch BEFORE any delivery
@@ -498,7 +498,7 @@ the shared checkout, or isolation is unavailable), and resolved right before all
 never stacks on a guess). `launchIsolatedRail` threads it as `resolveIntegrationBranch({ explicit })`,
 so the delivery row records it as `base_branch` and `deliverRailAsPr` creates the PR STACKED on it
 (`gh pr create --base <branch>`). Today's only driver is the milestone launch chain
-(`server/milestone-chain.ts`): chunk k+1 of a sequential "Launch Milestone" launches with
+(`server/modules/builder/runtime/milestone-chain.ts`): chunk k+1 of a sequential "Launch Milestone" launches with
 `baseBranch = chunk k's delivered branch`, so a greenfield walking skeleton accumulates without waiting
 for a merge. MCP `specrails_rails(launch, baseBranch)` exposes the same parameter.
 
@@ -522,7 +522,7 @@ rewound to the previous chunk's branch, else the integration branch) and broadca
 
 ## Ticket lifecycle — `on_review`
 
-New status in `TicketStatus` / `VALID_STATUSES` (`server/ticket-store.ts`), between
+New status in `TicketStatus` / `VALID_STATUSES` (`server/modules/specs/runtime/ticket-store.ts`), between
 `in_progress` and `done`. Pipeline-owned:
 
 **Universal ask-first (both completion chokepoints).** Under the default-on PR-delivery flag
@@ -745,7 +745,7 @@ itself: the operator rewrote the ticket description (synced to Jira on linked
 projects) and the run still re-planned the whole feature. The follow-up is now a
 typed, frozen delta that travels with the DELIVERY, never with the spec.
 
-- **Shape** (`server/pr-follow-up.ts`): `comments[]` (id, source `user-paste` |
+- **Shape** (`server/modules/delivery/runtime/pr-follow-up.ts`): `comments[]` (id, source `user-paste` |
   `github`, author, path, line, body — bounded), `scope` (objective, required
   outcomes, excluded changes, verification), optional `openspecChangeName`.
   `freezeFollowUp` assigns an `id` and a sha256 `hash` of the canonical content: