specrails-desktop 2.64.2 → 2.65.1

package/docs/internals/architecture.md

@@ -92,7 +92,7 @@ Each project in the `ProjectRegistry` gets its own `ProjectContext`:
 | `db` | SQLite connection to `projects/<slug>/jobs.sqlite` |
 | `QueueManager` | Serialized job queue for this project (one active job at a time) |
 | `ChatManager` | Isolated conversation manager (Explore + sidebar chat) |
-| `SetupManager` | Wizard state for projects being onboarded |
+| `SetupManager` | Background workspace assembly for added projects (plus the legacy API/MCP install flow) |
 | `cwd` | Absolute path to the project directory on disk |
 
 The `boundBroadcast` closure injects `projectId` into all WebSocket messages, so managers don't need per-project constructor arguments.
@@ -110,18 +110,19 @@ The `boundBroadcast` closure injects `projectId` into all WebSocket messages, so
 | `desktop-router.ts` | `/api/*` routes: projects, settings, themes, specrails-tech proxy, cross-project analytics |
 | `project-router.ts` | `/api/projects/:id/*` routes: all project-scoped operations |
 | `db.ts`, `db/` | Stable persistence facade with separate connection, migrations and domain repositories; see [source boundaries](source-architecture.md) |
-| `queue-manager.ts` | Job queue: spawn provider CLI processes serially per project |
-| `chat-manager.ts` | Chat/Explore: spawn provider CLI for conversational turns |
-| `setup-manager.ts` | Setup wizard: orchestrate `specrails-core` install + `/setup` chat |
+| `modules/execution/runtime/queue-manager.ts` | Legacy job queue: spawn provider CLI processes serially per project |
+| `modules/loops/runtime/loop-run-manager.ts` | Loop runs: the default rail execution path, concurrent across rails |
+| `modules/conversations/runtime/chat-manager.ts` | Chat/Explore: spawn provider CLI for conversational turns |
+| `setup-manager.ts` | Silent workspace assembly (`startSilentAssemble`) plus the legacy API/MCP install and `/setup` chat |
 | `config.ts` | Command discovery: scan `<project>/.claude/commands/sr/*.md` |
 | `hooks.ts` | Pipeline event handler: process phase transition events |
-| `spending.ts` | Cost/analytics aggregation (single source of truth) |
-| `ai-invocations.ts` | `recordInvocation` — writes one billable row per AI CLI call |
-| `pricing.ts` | Rate-card cost fallback for providers without native billing |
-| `result-event.ts` | `finaliseInvocationResult` — combines adapter result + pricing |
-| `telemetry-receiver.ts` | OTLP/JSON receiver mounted at `/otlp` |
-| `desktop-analytics.ts` | App-level analytics aggregated across all projects |
-| `metrics.ts` | Per-project health metrics |
+| `modules/accounting/runtime/spending.ts` | Cost/analytics aggregation (single source of truth) |
+| `modules/accounting/runtime/ai-invocations.ts` | `recordInvocation` — writes one billable row per AI CLI call |
+| `modules/accounting/runtime/pricing.ts` | Rate-card cost fallback for providers without native billing |
+| `modules/accounting/runtime/result-event.ts` | `finaliseInvocationResult` — combines adapter result + pricing |
+| `modules/accounting/runtime/telemetry-receiver.ts` | OTLP/JSON receiver mounted at `/otlp` |
+| `modules/accounting/runtime/desktop-analytics.ts` | App-level analytics aggregated across all projects |
+| `modules/accounting/runtime/metrics.ts` | Per-project health metrics |
 | `docs-router.ts` | Serve the embedded docs portal (`/api/docs`) |
 | `path-resolver.ts` | Resolve a usable PATH for GUI-launched desktop spawns |
 | `types.ts` | Shared TypeScript interfaces |
@@ -135,38 +136,28 @@ Provider, terminal, profile, plugin, code-explorer, and explore subsystems each
 ```
 client/src/
 ├── App.tsx                     # Mounts DesktopProvider + DesktopApp unconditionally
-├── components/
-│   ├── TabBar.tsx              # Project tab switcher
+├── components/                 # App shell and shared primitives
+│   ├── ArcSidebar.tsx          # Collapsible Arc-style left sidebar (projects, Loops, Plugins, …) — see Sidebar shell
 │   ├── ProjectLayout.tsx       # Per-project three-panel wrapper
-│   ├── ProjectNavbar.tsx       # Left/right sidebar pin + collapse toggles
-│   ├── ArcSidebar.tsx          # Collapsible Arc-style left sidebar
 │   ├── ProjectRightSidebar.tsx # Project nav (Jobs, Analytics, Agents, Code, …)
 │   ├── TitleBar.tsx            # Custom frameless titlebar (desktop)
-│   ├── CommandGrid.tsx         # Command launcher
-│   ├── RecentJobs.tsx          # Job history card list
-│   ├── ProjectHealthWidget.tsx # Per-project health indicators
-│   ├── AddProjectDialog.tsx    # Register project modal (provider multi-select)
-│   ├── WelcomeScreen.tsx       # Zero-state landing
-│   └── SetupWizard.tsx         # Configure / Install / Done onboarding wizard
+│   └── WelcomeScreen.tsx       # Zero-state landing
+├── features/<capability>/      # One folder per capability: pages/, components/, hooks/, lib/
+│   ├── dashboard/pages/DashboardPage.tsx     # Specs board + Rails board
+│   ├── analytics/pages/AnalyticsPage.tsx     # Per-project cost analytics (+ DesktopAnalyticsPage)
+│   ├── agents/pages/AgentsPage.tsx           # Agent profiles + catalog
+│   ├── code/pages/CodePage.tsx               # Code explorer
+│   ├── jobs/pages/JobDetailPage.tsx          # Full log viewer for a single job (+ JobsPage)
+│   ├── settings/pages/                       # SettingsPage (project route), GlobalSettingsPage
+│   └── projects/components/                  # AddProjectDialog, OnboardingWizard (product tour)
 ├── hooks/
 │   ├── useDesktop.tsx          # DesktopProvider context: project list, active project
 │   ├── useProjectCache.ts      # Stale-while-revalidate per-project cache
-│   ├── useSpecGenTracker.tsx   # Quick-spec generation state (localStorage)
-│   ├── usePipeline.ts          # Pipeline phase state
 │   └── useSharedWebSocket.tsx  # Single WS connection, per-project filtering
-├── pages/
-│   ├── DashboardPage.tsx       # Specs board + Rails board + pipeline state
-│   ├── AnalyticsPage.tsx       # Per-project cost analytics
-│   ├── DesktopAnalyticsPage.tsx # Cross-project spending roll-up
-│   ├── AgentsPage.tsx          # Agent profiles + catalog
-│   ├── CodePage.tsx            # Code explorer: file tree + Monaco viewer + edit (flag-gated)
-│   ├── SettingsPage.tsx        # Per-project settings
-│   ├── GlobalSettingsPage.tsx  # App settings
-│   └── JobDetailPage.tsx       # Full log viewer for a single job
-└── lib/
-    ├── api.ts                  # getApiBase(): dynamic API prefix per active project
-    ├── pending-specs.ts        # Quick-spec state persistence (localStorage)
-    └── route-memory.ts         # Per-project URL route save/restore
+├── lib/
+│   ├── api.ts                  # getApiBase(): dynamic API prefix per active project
+│   └── route-memory.ts         # Per-project URL route save/restore
+└── locales/<lang>/*.json       # i18n strings for the 8 supported locales
 ```
 
 ### App bootstrap
@@ -187,6 +178,20 @@ On project switch:
 
 State-bearing hooks key off `activeProjectId` as a `useEffect` dependency. `useSpecGenTracker` (via `lib/pending-specs.ts`) and `lib/route-memory.ts` persist Quick-spec progress and the active URL route per project to `localStorage`, surviving refreshes and project switches.
 
+### Sidebar shell
+
+The left `ArcSidebar` and the right sidebar (`ProjectRightSidebar` on the board, `AgentWorkspaceSidebar` in Agent Mode) share one behaviour contract:
+
+- **Modes** live in `context/SidebarPinContext.tsx`: `pinned-open`, `pinned-collapsed`, `unpinned`, persisted per side in `localStorage`. A new user starts with the left sidebar **pinned open** and the right one **unpinned**. `effectiveLeftMode` / `effectiveRightMode` render a pinned-open sidebar as unpinned when the window is at most 1100px wide (`NARROW_WINDOW_QUERY`), without rewriting the stored choice. Sidebars read the effective mode; pin buttons show the stored one.
+- **Overlay, never reflow.** Each sidebar is an in-flow `<aside>` wrapper plus an absolutely positioned panel (`z-30`). The wrapper reserves the expanded width only when pinned open (`useResizableSidebar(..., { docked })` writes both widths imperatively, also during a drag); a hover- or focus-expanded unpinned panel grows over the content with `shadow-xl` while the wrapper stays at the 44px rail.
+- **Hover intent and focus** (`hooks/useSidebarHoverIntent.ts`): open after 150ms of hover, close 250ms after the pointer leaves, open while keyboard focus is inside, collapse on blur only when focus and pointer have both left. A portalled flyout that belongs to a sidebar (the Builder panel) carries `data-sidebar-flyout` so focus moving into it keeps the rail open. A resize drag never collapses the panel.
+- **Rows** are plain containers holding a real `<button>` (select) with the row actions as sibling buttons; actions reveal on hover *and* `focus-within`. Destructive confirmations ("Remove?" / "Delete?") stay armed for 5 s.
+- **Mission roll-up.** A project, Home ("Unassigned missions") or Favorites group whose tree is not on screen shows the attention mark of its missions (warning triangle for a failed run, dot for a waiting decision), an unread dot, and an accent icon while an agent works; on the collapsed rail the attention mark is a badge on the project's monogram tile.
+- **Right-side button.** `lib/sidebar-layout.ts` (`isGlobalRoute`, `hasRightSidebar`) decides whether a right sidebar is mounted; `App.tsx` and the title bar share it, so the title bar never shows a button for a sidebar that is not on screen.
+- **Shortcuts:** `⌘B` / `Ctrl+B` cycles the left sidebar, `⌥⌘B` / `Ctrl+Alt+B` the right one (`hooks/useKeyboardShortcuts.ts`).
+- **Places (Back / Forward / links).** Where the user is lives in the URL, so router history is the navigation history: `?spec=<id>` (spec modal), `?mission=<id>` (selected mission, Mission mode), `?overlay=loops|plugins|docs|analytics`, `?review=<id>` / `?job=<id>` (Mission-mode forms of `/review/:id`, `/jobs/:id`) and a `?p=<projectId>` marker on the entry a project switch pushes. Filters, sort, search, tabs, run-strip focus, the terminal and the Board/Mission toggle are not places. The model and the key rules (what counts as the same place in each mode) are `lib/places.ts`; `hooks/usePlaceHistory.tsx` mirrors the stack, labels targets, skips entries that are meaningless in the current mode or whose target was deleted, restores the project of an entry, and owns the mouse buttons; `hooks/usePlaceParam.ts` is the push-on-open / pop-on-close primitive. See [client features](../../client/src/features/README.md#places-back--forward--links).
+- **Workspace panes** (Agent Mode Jobs / Files / Analytics) are mutually exclusive (`AgentWorkspaceContext`); the conversation column keeps a 360px floor.
+
 ---
 
 ## Authentication
@@ -250,8 +255,9 @@ App-level messages (no `projectId`) are processed by all handlers.
 
 `QueueManager` and `ChatManager` spawn the project's provider CLI (`claude`, `codex`, `gemini`, or `kimi`) as subprocesses, always with `cwd` set so the process runs in the correct directory. The exact binary and argv are chosen by the resolved `ProviderAdapter` — managers never branch on the provider id (see [Multi-provider adapters](#feature-subsystems)).
 
-- **Within a project, jobs run strictly one at a time.** Each `ProjectContext` has exactly one `QueueManager` with a single `_activeJobId`; `_drainQueue()` early-returns while a job is active, so the next rail job queues behind the current one.
-- **Parallelism is across projects only** — each project has its own `QueueManager`, so jobs in different projects run simultaneously. There is no "max concurrent jobs" setting; the only automatic queue-pause is budget-based (daily budget / per-job cost alert).
+- **The legacy job queue is serial per project.** Each `ProjectContext` has exactly one `QueueManager` with a single `_activeJobId`; `_drainQueue()` early-returns while a job is active, so the next queued job waits behind the current one.
+- **Rails run concurrently.** With Loops enabled (the default), each rail launch is a `LoopRunManager` run, not a queued job, so several rails in one project run at the same time. Repo-mutating runs get their own git worktree (default-on; `SPECRAILS_RAIL_WORKTREES=0` restores the shared cwd), and a launch whose tickets are already in flight on another rail is refused with `409 tickets_in_flight`.
+- **Projects never contend.** Each project has its own `QueueManager` and loop runs. There is no "max concurrent jobs" setting; the only automatic queue-pause is budget-based (daily budget / per-job cost alert).
 - **Cancelling a job** sends `SIGTERM`, waits **5 seconds**, then `SIGKILL`. (The terminal panel's 2-second shutdown grace is a separate subsystem.)
 - A zombie-job watchdog terminates a stuck job after a default of **30 minutes**, overridable via `WM_ZOMBIE_TIMEOUT_MS`.
 - Log lines stream back over WebSocket in real time.
@@ -265,30 +271,30 @@ The app is more than the job pipeline. Each subsystem owns its modules; this is
 | Subsystem | Server modules | Notes |
 |-----------|---------------|-------|
 | **Multi-provider adapters** | `server/providers/{types,claude-adapter,codex-adapter,gemini-adapter,kimi-adapter,registry,index}.ts`, `server/provider-selection.ts` | **Four first-class providers — Claude, Codex, Gemini, and Kimi — enabled by default** behind a `ProviderAdapter` contract. Claude reports native cost and supports persistent stdin; Codex (`≥ 0.128.0`) and Gemini (`≥ 0.11.0`) expose estimated usage; Kimi (`≥ 0.27.0`) runs CLI-only prompt-mode JSONL, resumes through terminal hints, uses `.kimi-code` skills/MCP, and leaves absent cost/tokens unavailable. A project can install any subset; `providers[]` is a JSON column, the first entry is primary. Per-invocation provider is late-bound. Provider availability is gated by executable detection, Core target compatibility, and the existing Codex/Gemini emergency switches. See [`adding-a-provider.md`](adding-a-provider.md), [`../codex.md`](../codex.md), [`../gemini.md`](../gemini.md), and [`../kimi.md`](../kimi.md). |
-| **Spending analytics** | `server/modules/accounting/runtime/spending.ts`, `server/modules/accounting/runtime/ai-invocations.ts`, `server/modules/accounting/runtime/pricing.ts` | `recordInvocation` writes an `ai_invocations` row per AI CLI call across six surfaces (`job`, `quick-spec`, `explore-spec`, `ai-edit`, `smash`, `file-summary`); powers the Analytics page and `spending.invalidated`. |
-| **Agent profiles** | `server/modules/agents/runtime/profile-manager.ts`, `server/modules/agents/runtime/profiles-router.ts` | Declarative JSON in `.specrails/profiles/*.json`, snapshot-per-job, `SPECRAILS_PROFILE_PATH` env injection. Requires `specrails-core ≥ 4.1.0` in general and the Core 4.12 Kimi target for Kimi roles (the app-wide install floor is `^4.12.0`). Claude and Kimi advertise profile support; other adapters force legacy/no-profile mode. |
+| **Spending analytics** | `server/modules/accounting/runtime/spending.ts`, `server/modules/accounting/runtime/ai-invocations.ts`, `server/modules/accounting/runtime/pricing.ts` | `recordInvocation` writes an `ai_invocations` row per AI CLI call across twelve surfaces (`job`, `loop`, `quick-spec`, `explore-spec`, `ai-edit`, `smash`, `file-summary`, `chat-sidebar`, `spec-launcher`, `proposal`, `agent-studio`, `setup`); mission turns record to the app-level `agent_invocations` ledger and are folded into a pinned project's spending. Powers the Analytics page and `spending.invalidated`. |
+| **Agent profiles** | `server/modules/agents/runtime/profile-manager.ts`, `server/modules/agents/runtime/profiles-router.ts` | Declarative JSON in `.specrails/profiles/*.json`, snapshot-per-job, `SPECRAILS_PROFILE_PATH` env injection. Requires `specrails-core ≥ 4.1.0` in general and the Core 4.12 Kimi target for Kimi roles (the app installs Core 6: `CORE_PACKAGE_SPEC` in `server/core-package.ts`). Claude and Kimi advertise profile support; other adapters force legacy/no-profile mode. |
 | **Plugins (Integrations)** | `server/plugin-manager.ts`, `server/plugins/` | Bundled-only, MCP-based, additivity invariant, surgical `.mcp.json` merge, `plugin.*` WS events. Serena ships today. |
 | **Terminal panel** | `server/modules/terminals/runtime/terminal-manager.ts` | `node-pty` sessions over the dedicated `/ws/terminal/:id` socket, OSC shell-integration marks. See [`../terminal.md`](../terminal.md). |
 | **Code explorer** | `server/modules/code/runtime/code-explorer-router.ts`, `server/modules/code/runtime/file-provenance.ts`, `server/modules/code/runtime/file-summary-manager.ts` | A non-developer-friendly file tree + Monaco viewer with plain-language AI summaries and *touched-by-AI* provenance chips per ticket/job, plus opt-in in-app editing of existing files (overwrite-only via `PUT /file` — no create/rename; refuses binaries `415`, enforces a 2 MB cap `413`, `404` on a missing path, respects deny-list/`.gitignore`). |
 | **Pipeline telemetry** | `server/modules/accounting/runtime/telemetry-receiver.ts` + QueueManager OTEL injection | Opt-in OTLP/JSON signals to `POST /otlp/v1/{traces,metrics,logs}`; blobs compacted after 7 days; diagnostic ZIP export. |
 | **Explore acceleration + Contract Refine** | `server/modules/conversations/runtime/explore-cwd-manager.ts`, `server/modules/specs/runtime/contract-refine-runner.ts` | App-managed Explore spawn cwd for fast first-token; optional post-commit Contract Layer enrichment. Kill switches: `SPECRAILS_EXPLORE_CONTRACT_REFINE`, `SPECRAILS_EXPLORE_LEGACY_CWD`. |
 | **Tickets / drafts** | `server/modules/specs/runtime/ticket-store.ts` | Spec tickets (incl. `draft` status) backing the Specs board and Save-as-Draft flow. |
-| **Jira integration** | `server/jira/*` (`jira-sync-manager`, `jira-client`, `jira-materializer`, `jira-status-resolver`, `jira-db`, `jira-credential-store`), `server/jira-router.ts` | Optional per-project sync that backs a project's specs with a Jira board (Cloud or Data Center). Desktop is the sync layer — specrails-core reads the materialized cache unchanged and stays read-only. Inbound polling + a durable outbox handle write-back; the encrypted token lives on-device. Routes under `/api/projects/:id/jira/*` (gated by `SPECRAILS_JIRA_SECTION`, 404 when off); project-scoped WS events `jira.synced`, `jira.sync_error`, `jira.auth_expired`, `jira.outbox_changed`, `jira.degraded`. See [`../jira-integration-plan.md`](../jira-integration-plan.md). |
+| **Jira integration** | `server/jira/*` (`jira-sync-manager`, `jira-client`, `jira-materializer`, `jira-status-resolver`, `jira-db`, `jira-credential-store`), `server/jira-router.ts` | Optional per-project sync that backs a project's specs with a Jira board (Cloud or Data Center). Desktop is the sync layer — specrails-core reads the materialized cache unchanged and stays read-only. Inbound polling + a durable outbox handle write-back (`transition`, `comment`, `update`, and `create` — durable promotion of a local ticket enqueued by `enqueuePromote`, idempotent on its key and on an existing link, sharing `promoteTicketToJira`'s create-link-flip logic; created issues carry an invisible `sh.specrails.created-from` property, so a retry recovers an issue whose create response was lost instead of creating a duplicate); the encrypted token lives on-device. Routes under `/api/projects/:id/jira/*` (gated by `SPECRAILS_JIRA_SECTION`, 404 when off); project-scoped WS events `jira.synced`, `jira.sync_error`, `jira.auth_expired`, `jira.outbox_changed`, `jira.degraded`. See [`../jira-integration-plan.md`](../jira-integration-plan.md). |
 | **Theme system** | `server/desktop-router.ts` (`GET/PATCH /api/theme`) | Five built-in themes (`dracula`, `aurora-light`, `obsidian-dark`, `matrix`, `specrails`), default `specrails`, persisted app-wide with an anti-FOUC inline script. |
 
 Most client feature sections are gated by VITE flags, and they share one polarity: `VITE_FEATURE_TERMINAL_PANEL`, `VITE_FEATURE_AGENTS_SECTION`, `VITE_FEATURE_EXPLORE_PREMIUM_UX`, and `VITE_FEATURE_CODE_EXPLORER` are all **opt-out** — default ON, set the flag to `false` to hide that section. See [`configuration.md`](configuration.md) for the full flag and settings reference.
 
 ---
 
-## Setup wizard flow
+## Project add and workspace assembly
 
-When a project is added without specrails-core, the setup wizard runs. The client renders a **3-step** indicator: **Configure → Install → Done**.
+There is no setup wizard in the app UI. `POST /api/projects` (`server/desktop-router.ts`) registers the project with the auto-detected providers, answers `201`, and then calls `SetupManager.startSilentAssemble` in the background (skipped when the workspace is already populated):
 
-1. **Configure** — confirm path and pick provider(s) and model presets. (Multi-provider projects get one Configure step per provider.)
-2. **Install** — the app writes `.specrails/install-config.yaml` and runs `npx --yes --prefer-online specrails-core@^4.12.0 init --yes --from-config <tempPath>`, streaming the log. The package spec is the constant `CORE_PACKAGE_SPEC` — a deliberately pinned major range (the floor is `4.12.0`, the release that ships the Kimi provider target), so a future core `5.x` doesn't auto-land. Override the binary locally with `SPECRAILS_CORE_BIN`. For multi-provider projects each provider's install runs sequentially.
-3. **Done** — per-provider completion summary.
+1. **Assemble** — one specrails-core `init` per detected provider, sequential, with per-provider failure isolation. The bundled Core is preferred (`spawnBundledCoreInit` in `server/offline-assemble.ts`, offline, with the bundled OpenSpec); without a bundle the fallback is `npx` with `CORE_PACKAGE_SPEC` from `server/core-package.ts` (currently `specrails-core@^6.0.0`, a deliberately pinned major range). `SPECRAILS_CORE_BIN` overrides the binary locally. Local (OpenAI-compatible) engines have no Core target and are skipped.
+2. **Relocation** — the framework lands in `~/.specrails/projects/<slug>/workspace` (`workspacePathFor`), never in the user's repository.
+3. **Progress** — the app-level `project.assemble_progress` WS event (`{projectId, provider, status}`) drives the sidebar indicator; a failure never rolls back registration, and `POST /api/projects/:id/assemble-retry` re-runs only the failed providers.
 
-`SetupManager` (server) owns wizard state; `DesktopProvider` (client) tracks which projects are in setup via `setupProjectIds`. The wizard does spawn a real AI CLI for the `/setup` chat, but that spawn is deliberately left uninstrumented (it writes no `ai_invocations` row).
+After a Core update swap, `reseedStaleWorkspaces` (`server/framework-reseed.ts`) re-assembles stale workspaces. The legacy per-project `/setup/*` and `/enrich/*` routes (`server/project-router-setup.ts`) stay mounted for the MCP `specrails_setup` tool and API callers; their AI turns record under the `setup` spending surface.
 
 ---
 

package/docs/internals/companion-inbox-decisions.md

@@ -0,0 +1,42 @@
+# Companion inbox decisions
+
+BB3 turns the paired companion from a monitor into a decision remote for the
+[Needs-you inbox](../../server/modules/inbox/README.md). It adds no authentication
+mechanism: it rides the Mobile Gateway (`/v1`, per-device bearer token bound to the
+current certificate fingerprint, per-device project grant) over the same WebRTC RPC
+and WebSocket bridge as the rest of the companion.
+
+Code: [mobile-inbox.ts](../../server/mobile/mobile-inbox.ts) (routes and the pure action policy),
+[mobile-ws.ts](../../server/mobile/mobile-ws.ts) (the `inbox.changed` nudge), tests in
+[mobile-inbox.test.ts](../../server/mobile/mobile-inbox.test.ts). Endpoints are listed in the
+[API reference](api-reference.md#companion-inbox-decisions-v1inbox-paired-devices-only).
+
+## Safe actions
+
+| Action | Offered when | Same use case as Desktop | Tier |
+| --- | --- | --- | --- |
+| Answer | `question` item (run paused for a human decision) | run "Answer" (`resume` with an answer, pinned to the pending question) | `write` |
+| Resume | `resume-run` item (budget paused, interrupted), or a failed / blocked run whose primary remedy is `resume`; a run paused at its per-run cap takes Continue (`runCap: ignore`) or Raise (`runCapUsd`) | run card Resume | `ai-spawn` |
+| Retry | failed / blocked item whose first remedy a phone can act on (not `open-logs` / `edit-spec`) is `retry`, with a known rail | the recovery cockpit's relaunch (`/rails/:n/relaunch`) | `ai-spawn` |
+| Create draft PR | delivery `on_review` | PR decision `create-pr` | `destructive` |
+
+The server computes the offered actions per item (`companion.actions`) so the phone never
+shows what the gateway would refuse. `enabled: false` means the permission tier is off.
+
+## Not exposed
+
+Merge, Discard, Publish, force-push, settings, delete, raising a spend cap and Jira retry have
+no companion route; `/v1/projects/:pid/inbox/<other>` answers `403 action_not_allowed_for_companion`
+and the raw `pr-decision`, `loop-runs/*/cancel` and settings routes are not in the gateway allow-list
+(`404`). Tests assert both.
+
+**Discard is deliberately excluded.** Desktop's Discard closes the PR, releases the worktree and
+deletes the owned branches. It has no undo and no soft state, so it cannot honour "undoable from the
+phone". Adding it requires a server-side grace window in the delivery decision first.
+
+## Isolation and failure
+
+Every action is addressed to one project in the path; the gateway's project grant gates it, and the
+desktop route re-checks that the run / delivery belongs to that project. `GET /v1/inbox` drops items
+and project counts outside the grant. Retry and Create PR rely on the desktop's own stale-source and
+`expectedDecision` checks, so a repeated tap is rejected rather than duplicated.

package/docs/internals/companion-rails-as-loops-contract.md

@@ -2,16 +2,27 @@
      "Verified routing clarification" first — it corrects an internal tension in
      the body about which engine a bare-mode launch uses. -->
 
-# ⚠️ Verified routing clarification (read first)
+# Current status (verified against code 2026-10-21) — read first
 
-The single fact that scopes the whole gap, verified directly in code:
+The body below is the original gap analysis from 2026-06-25. **Every desktop-side
+change it requested (Phase 0, sections 4.1–4.5) has shipped.** Where the body says
+"today", "dropped" or "stripped", it describes the pre-fix state. Current behaviour:
 
-`server/modules/delivery/runtime/rails-router.ts:301` — `if (isLoopsEnabled() && loopId) → LoopRunManager (loop.run_*, no jobId); else → QueueManager (jobId, rail.job_*)`.
+| Item | Status | Where |
+| --- | --- | --- |
+| 4.1 Forward `loopId`, `reasoning_effort`, `interactive` on launch | Shipped | `v1.post('/projects/:pid/rails/:i/launch')` in `server/mobile/mobile-router.ts` narrows and forwards all three |
+| 4.2 Loop read routes on the allow-list | Shipped | `GET /v1/loops`, `GET /v1/loops/factory`, `GET /v1/projects/:pid/loop-runs/:id` in `mobile-router.ts` and `MOBILE_ALLOWLIST` |
+| 4.3 Loop identity on the rails GET | Shipped | `activeLoopRuns[railIndex]` carries `loopRunId`, `loopId`, `loopName`, `provider`, `model`, `iteration`, `startedAt`, `steps`, `lines` (`rails-router.ts`) |
+| 4.4 `loop.run_*` WS reaches mobile | Shipped | `topicFor()` in `server/mobile/mobile-ws.ts` maps `loop.run_started/progress/stopped/completed` onto the existing `'rails'` topic (verbatim; no compat synthesis) |
+| 4.5 Drop `reasoning` at the mobile boundary | Shipped | `toMobileWire()` in `mobile-ws.ts` strips `reasoning` from `loop.run_progress` |
 
-- **Phone-initiated launches** send bare `{mode}` with **no `loopId`** (`desktop_repository.dart:116-123`) → fall to the **`else` / QueueManager** path → real `jobId` → `rail.job_*` → **the v1 companion mirrors them correctly (view + log tail + completion push). NO regression.**
-- **Desktop-initiated launches** now **always** send a `loopId`: the loop picker uses `effectiveLoopId = selectedLoopId || factoryIdForMode(mode)` (`client/src/features/rails/lib/rail-loops.ts:43-44`) so even a plain "Implement" rail sends `loopId='factory:implement'`, and `doLaunchRail` always passes it (`client/src/features/dashboard/pages/DashboardPage.tsx:824,869`) → **LoopRunManager** → `loop.run_*` (no `jobId`) → **dropped at the mobile boundary** (`mobile-ws.ts topicFor` default→null).
+Two further facts supersede the body:
 
-**Net:** the mirror gap is NOT in the phone's own launches — it is in **mirroring rails the user launches from the desktop** (the normal case), which now emit `loop.run_*` the boundary never forwards. So a connected phone shows desktop-launched loop rails as **idle, with no live progress and no completion notification.** The frozen wire is untouched (additive only). Everything below stands with this scoping.
+- **Bare-`mode` launches also run as loops now.** With Loops enabled (the default), a launch without `loopId` (MCP, mobile, direct REST) resolves the factory loop for its mode (`factoryLoopForMode` in `rails-router.ts`), so phone launches go through `LoopRunManager` and emit `loop.run_*`, exactly like dashboard launches. The QueueManager/`jobId` path is used only when Loops are disabled.
+- **Accepted launch modes:** `VALID_MODES = {implement, freestyle, loop}`. `batch-implement`/`batch` normalize to `implement`, and the pre-rename `ultracode` (sent by older Companion builds) normalizes to `freestyle` (`normalizeRailMode`).
+
+The Companion-side items (section 5, Phases 1–2) live in the Companion repository
+and are tracked there.
 
 ---
 

package/docs/internals/configuration.md

@@ -39,7 +39,7 @@ To rotate the token, stop the app, delete `~/.specrails/desktop.token`, and star
 
 ## App settings
 
-App settings apply across all projects. Open them from the **left sidebar → Settings**, or via the Command Palette (`Cmd/Ctrl+K`) → **Desktop Settings**. They are persisted in `~/.specrails/desktop.sqlite` under the `desktop_settings` key/value table.
+App settings apply across all projects. Open them from the **left sidebar → App settings**, or via the Command Palette (`Cmd/Ctrl+K`) → **Desktop Settings**. They are persisted in `~/.specrails/desktop.sqlite` under the `desktop_settings` key/value table.
 
 The Global Settings page is organised into the sections below (it also surfaces a read-only **Registered Projects** list, an **Onboarding** replay button, and a **Desktop Information** diagnostics block, which carry no stored settings):
 
@@ -49,7 +49,7 @@ The Global Settings page is organised into the sections below (it also surfaces
 | **Language** | App-wide UI language (hot-switch, no restart). Eight built-ins: `en`, `es`, `fr`, `de`, `pt`, `it`, `zh`, `ja`. | `ui_language` (unset = follow the OS language; only an explicit pick is persisted) |
 | **Mobile Access** | Enable the mobile-companion gateway, pair/revoke devices, and rotate the device cert identity. | — (loopback + token still enforced server-side) |
 | **specrails-tech** | Base URL for the external specrails-tech agents service. | `specrails_tech_url` = `http://localhost:3000` (the `SPECRAILS_TECH_URL` env var is only a fallback when this setting is unset — the stored setting wins) |
-| **Budget & Alerts** | App-wide daily spend cap (queues auto-pause when exceeded) and a per-job cost alert threshold. | `desktop_daily_budget_usd`, `cost_alert_threshold_usd` (both unset by default = no cap / no alert) |
+| **Budget & Alerts** | App-wide daily spend cap (queues auto-pause when exceeded; rail/loop launches get `409 daily_budget_exceeded` and running loops pause `budget_paused` between AI steps; a running Core workflow (engine 2) whose retained Core announces `pauseRuns` is paused mid-run through `runtime pause --reason budget` as soon as recorded spend crosses the budget — its current step finishes, Core exits 2 with `state.pause`, and the run parks on the same resumable pause; an older Core keeps the between-invocation check — see [tracking cost](../tracking-cost.md#rails-and-loops-over-budget)) and a per-job cost alert threshold. | `desktop_daily_budget_usd`, `desktop_weekly_budget_usd`, `desktop_monthly_budget_usd`, `desktop_run_cap_usd`, `cost_alert_threshold_usd` (all unset by default = no cap / no alert). Weekly / monthly caps are edited in Analytics ▸ Budget |
 | **OS Notifications** | Desktop notification preferences for long-running jobs and budget events. | — |
 | **Outbound Webhooks** | HTTP webhooks fired on `job.completed`, `job.failed`, `job.canceled`, `daily_budget_exceeded`, and `desktop_daily_budget_exceeded`. | webhooks table (a hook created without an explicit events list defaults to `["job.completed","job.failed","job.canceled"]`) |
 | **Code section** | Plain-language file-summary language (`en` / `es`) and the monthly summary budget cap. | `summary_language` = `en`, `summary_monthly_budget_usd` = `5.00` |
@@ -65,16 +65,22 @@ The Global Settings page is organised into the sections below (it also surfaces
 
 ## Project settings
 
-Project settings apply to a single project. Open them from the project's **Settings** entry in the right sidebar (route: `/settings`). The page is titled **Project Settings** and has these sections:
+Project settings apply to a single project. Open them from the project's **Project settings** entry in the right sidebar (route: `/settings`). The page is titled **Project Settings** and has these sections:
 
 | Section | What it controls |
 |---------|------------------|
 | **Pipeline Telemetry** | Opt-in toggle that injects OpenTelemetry env vars into pipeline job spawns so they emit OTLP signals back to the app. Off by default. |
 | **Rail Pre-prompt** | Text prepended to every rail launch for this project. |
-| **Freestyle pre-prompt** | Text prepended to Freestyle-mode launches (Claude and Kimi advertise this autonomous rail mode). |
-| **Budget** | Per-project daily spend cap (with queue auto-pause) and a per-job cost alert threshold. |
+| **Freestyle pre-prompt** | Text prepended to Freestyle-mode launches (every CLI provider and local engine advertises this autonomous rail mode; only Claude adds the interactive in-job chat). |
+| **Worktree environment** | Names of environment variables passed to the project's agents (values are read at spawn time, never stored). |
+| **Agent environment** | `inherit` (default) or `minimal`. See [Agent environment mode](#agent-environment-mode). |
+| **Budget** | Per-project daily spend cap (with queue auto-pause) and a per-job cost alert threshold. Weekly and monthly caps and the per-run soft cap live in Analytics ▸ Budget (`queue_state` keys `config.weekly_budget_usd`, `config.monthly_budget_usd`, `config.run_cap_usd`). |
+| **Review limit** | `reviewWipLimit` (`config.review_wip_limit`): how many deliveries may wait for review at once. Running (`building`), undecided (`on_review`) and open app PRs (`pr_draft`/`pr_ready`) count, one per top-level delivery. Empty = no limit (default); the UI suggests 5. At the limit every rail launch door refuses a **new** delivery with `409 review_wip_limit_reached`. Changes to an existing delivery (revision, Relaunch, PR follow-up) stay allowed. See [safe PR flow](safe-pr-review-flow.md#review-wip-limit). |
+| **Agent actions audit** | `agentAuditRetentionDays` (default 30, 1–3650): how long the project keeps its log of what agents read, wrote, executed, called over MCP or fetched. Older rows are deleted 5 seconds after the project opens and then daily. See [agent actions audit](agent-actions-audit.md). |
+| **Existing-project anchoring** | Two opt-in switches (both off by default, each gated on a Core capability; without it the switch is disabled with an "update Core" note). `jiraPostClarifications` (`config.jira_post_clarifications`, Core `architectClarifications: 1`): when a run pauses with the architect's questions or proceeds on assumptions, post them as one comment on the linked Jira issue and record a reply there as a `clarification` addendum. `baselineOnTouch` (`config.baseline_on_touch`, Core `baselineOnTouch: 1`): forwarded to Core's runtime config so a change that reaches code no spec describes first writes characterization tests and an as-built spec. See [existing-project anchoring](existing-project-anchoring.md). |
+| **Project rules** | The rules inventory Core writes to `.specrails/rules.json` (Core `rulesInventory: 1`): the project's gates and every written rule classified as enforced, automatable, human-only or unclassified (Core's `init` inventories offline, so rules stay unclassified until **Re-run inventory** runs with a configured provider); **Create spec** turns an automatable rule into a spec (source `rules`). Human-only rules appear in every review packet as "Needs human eyes". |
 | **Terminal Settings** | Per-project overrides for the terminal panel defaults (project override → app default → built-in). |
-| **Verification commands** | Repository checks Core runs after the developer finishes; failures go back to the developer (or the fixer). Stored under `verification` in `.specrails/agent-runtime.json`; an empty list lets the architect propose the project's own checks. |
+| **Verification commands** | Repository checks Core runs after the developer finishes; failures go back to the developer (or the fixer). Stored under `verification` in `.specrails/agent-runtime.json`; an empty list lets the architect propose the project's own checks. The suggestions list offers the rules inventory's plain gate commands first (Core `rulesInventory: 1`), then the commands detected in each repository. |
 | **Setup commands** | Idempotent commands Core runs inside the repository checkout before every verification plan, for example `npx playwright install chromium`. Same entry shape as `verification` (`repositoryId`, `command`, `args`, optional `cwd`, `env`, `timeoutMs`, `key`, `label`), stored under `setup`, no auto-detection. Credential-like `env` keys are refused and `key` values must be unique across `setup` and `verification`. A failing setup command ends the run as blocked by the host environment. The list reaches Core only when the installed Core advertises the `setupCommands` capability; older cores receive the configuration without it and the run log records a one-line note. |
 
 > The project's **provider(s)** — **Claude, Codex, Gemini, Kimi, or any
@@ -143,12 +149,12 @@ specrails-desktop remove <project-id>    # Unregister a project by ID
 specrails-desktop implement "#42"                  # Queue /specrails:implement for spec #42
 specrails-desktop implement "#40" "#41" "#43"        # One aggregate implement run over several specs
 specrails-desktop "any raw prompt"                 # Pass a raw prompt straight to the AI CLI
-specrails-desktop /specrails:health-check          # Pass any slash command directly
+specrails-desktop /specrails:retry                 # Pass any slash command directly
 ```
 
 > **Always quote issue refs.** An unquoted `#` starts a shell comment, so `implement #40 #41` silently drops the refs. Quote each one: `"#40" "#41"`.
 
-**Known verbs** (automatically prefixed with `/specrails:`): `implement`, `why`, `get-backlog-specs`, `auto-propose-backlog-specs`, `propose-spec`, `refactor-recommender`, `health-check`, `compat-check`, `enrich`. The removed `batch-implement` verb is mapped to `implement`. Any other first argument is passed as a raw prompt.
+**Known verbs** (automatically prefixed with `/specrails:`; `KNOWN_VERBS` in `cli/args.ts`): `implement`, `retry` — the only `/specrails:*` commands Core 6 ships. The removed `batch-implement` verb is mapped to `implement`. Any other first argument (including retired Core commands such as `why` or `health-check`) is passed as a raw prompt.
 
 ### Port override example
 
@@ -221,6 +227,71 @@ receives one aggregated warning, for example
 `[environment] NODE_AUTH_TOKEN not available (probe-timeout); configure it in the login shell or launch from a terminal`.
 Statuses, logs and MCP output contain names and states only, never values.
 
+#### Agent environment mode
+
+The project setting `agentEnvMode` (Project Settings → **Agent environment**,
+stored as `config.agent_env_mode`) decides what the Desktop server environment
+an agent process receives.
+
+- **`inherit`** (default). Unchanged behavior: agents receive the Desktop
+  environment, plus the passthrough overlay on the paths that already applied it
+  (rail jobs, loops, runtime controls).
+- **`minimal`**. Agents receive a fresh environment built from:
+  - a shared allowlist: `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `LANG`,
+    `LANGUAGE`, `LC_*`, `TMPDIR`, `TMP`, `TEMP`, `TERM`, `COLORTERM`, `TZ`,
+    `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_CACHE_HOME`, `XDG_STATE_HOME`,
+    `XDG_RUNTIME_DIR`, `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, `ALL_PROXY` (both
+    cases), `SSL_CERT_FILE`, `SSL_CERT_DIR`, `NODE_EXTRA_CA_CERTS`;
+  - Windows essentials, matched case-insensitively on Windows: `SystemRoot`,
+    `SystemDrive`, `windir`, `ComSpec`, `PATHEXT`, `USERPROFILE`, `USERNAME`,
+    `USERDOMAIN`, `HOMEDRIVE`, `HOMEPATH`, `APPDATA`, `LOCALAPPDATA`,
+    `ProgramData`, `ALLUSERSPROFILE`, `PUBLIC`, `ProgramFiles`,
+    `ProgramFiles(x86)`, `ProgramW6432`, `CommonProgramFiles*`,
+    `NUMBER_OF_PROCESSORS`, `PROCESSOR_*` (architecture, identifier), `OS`,
+    `COMPUTERNAME`. `windowsSpawnEnv` still backfills the canonical values;
+  - Specrails' own variables (`SPECRAILS_*`), including the relocation,
+    profile, telemetry and repo-map overlays added per spawn;
+  - the auth/config names each provider adapter declares in `envAllowlist`:
+
+    | Provider | Names |
+    |----------|-------|
+    | Claude | `ANTHROPIC_*`, `CLAUDE_CONFIG_DIR`, `CLAUDE_CODE_*`, `DISABLE_AUTOUPDATER` |
+    | Codex | `CODEX_*`, `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_ORG_ID`, `OPENAI_ORGANIZATION`, `OPENAI_PROJECT` |
+    | Gemini | `GEMINI_*`, `GOOGLE_API_KEY`, `GOOGLE_APPLICATION_CREDENTIALS`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`, `GOOGLE_GENAI_USE_VERTEXAI`, `CLOUDSDK_CONFIG` |
+    | Kimi | `KIMI_*`, `MOONSHOT_*` |
+    | Local engine | the connection's `apiKeyEnv`, when set |
+
+    A spawn receives only its provider's names. Core-hosted work (loop
+    definitions, Implement runs driven by Core, runtime controls, mission
+    session hosts) receives every registered provider's names, because Core may
+    launch any configured role provider. Loop shell steps receive no provider
+    names;
+  - the project's passthrough names, with login-shell recovery as above.
+
+  Everything else (cloud credentials such as `AWS_*`, `GITHUB_TOKEN`, database
+  URLs, unrelated API keys) is withheld. Add a name to the passthrough list when
+  a tool needs it, for example `AWS_PROFILE` for Claude on Bedrock.
+
+Every project agent spawn path builds its base environment through one builder
+(`resolveProjectAgentEnv` / `projectAgentSourceEnv` in `server/project-env.ts`,
+pure policy in `server/modules/execution/domain/agent-env.ts`): rail jobs
+(headless and interactive), loop AI steps, deciders, shell steps and Core
+definition runs, runtime controls, missions (legacy runners and the Core session
+host of a project scope), project chats and Explore, spec generation, proposals,
+Contract Refine, SMASH, agent refinement and AI ticket edits. Not covered yet:
+the project setup wizard, project builder chat, file summaries, agent generation
+and conversation-title helpers; they keep the Desktop environment.
+
+The mode applies to processes started after the change. A running mission
+session host keeps the environment it started with until it restarts.
+
+`GET /api/projects/:projectId/agent-env/status` returns, without values, the
+mode, the shared allowlist patterns, the Desktop variable names that pass them,
+the configured passthrough names and, per provider, its patterns and the extra
+names they admit. The Project Settings card renders this list. The MCP
+`specrails_env` tool reports the mode in `get` but cannot change it, so an agent
+cannot widen its own environment.
+
 A few env vars are read directly by the app. The two most useful operational ones:
 
 | Variable | Description |
@@ -246,6 +317,12 @@ its native key/config, and Kimi via `kimi login` or user-managed
 `~/.kimi-code/config.toml`. See [Kimi](../kimi.md), [Codex](../codex.md), and
 [Gemini](../gemini.md).
 
+### Mission read-only policy
+
+| Variable | Effect |
+|----------|--------|
+| `SPECRAILS_MISSION_READ_ONLY` | Default on. Mission (agent chat) turns use the provider's native read-only boundary, and the `specrails_*` MCP tools stay callable. Claude spawns with only read-only built-in tools, Codex uses its read-only sandbox, Gemini uses plan mode plus a plan-scoped MCP policy, and local engines use the runner's read-only tool set. Core mission sessions get the matching `permissions`/`tools` policy. Kimi has no native read-only mode and is unchanged. Set to `false` to restore the previous write-capable mission argv and session policy without a release. See [read-only missions](mission-read-only-policy.md). |
+
 ### Core agent sessions (rollout)
 
 | Variable | Effect |
@@ -258,7 +335,8 @@ project-less missions. Session journals live in
 stores only a rebuildable projection. See
 [agent sessions](../../server/modules/agent-sessions/README.md).
 
-**Allow sub-agents** is a setting, not a flag, and it is off by default. The
+**Allow sub-agents** is a setting, not a flag, and it is on by default (only an
+explicit `'false'` row disables it). The
 project setting `allowSubagents` (`config.allow_subagents`) applies to that
 project's conversational agents (missions, explore, refinements). The app
 setting (`agent_allow_subagents` in `desktop_settings`) covers missions without
@@ -280,6 +358,36 @@ and no shared prompt cache. The UI asks for confirmation before leaving the
 default. The setting is read-only over the Specrails MCP. See
 [agent sessions](agent-sessions.md#sub-agent-runtime-who-launches-them).
 
+**Reviewer model family suggestion.** When two or more providers are usable, the
+loop editor suggests running the reviewer on a different model family than the
+developer (Claude ↔ Codex first, then Gemini, Kimi and local engines), since a
+different family catches different mistakes. It is advisory only: the default
+roles never change unless the user clicks **Apply**, which edits the loop draft.
+**Dismiss** stores `reviewerFamilySuggestionDismissed` (`config.reviewer_family_suggestion_dismissed`,
+row removed when `false`) for that project.
+
+### Spec triage and role engines
+
+| Variable | Effect |
+|----------|--------|
+| `SPECRAILS_SPEC_TRIAGE` | Default on. A created or edited `draft`/`todo` spec is triaged automatically (debounced, asynchronous). Set to `false` to stop the automatic triggers; **Recalculate** (`POST /tickets/:id/triage`) keeps working. See [spec triage](spec-triage.md). |
+
+Desktop-owned role engines live in `<workspace>/.specrails/loop-role-engines.json`
+(`GET/PUT /:projectId/agent-runtime/loop-roles`), next to Core's
+`agent-runtime.json`. Each role is `{ provider, model?, effort? }`; an absent
+role falls back as described:
+
+| Role | Used by | Default when absent |
+|------|---------|---------------------|
+| `verifier` | Loop ai-steps under a `roles` rail launch | The rail's primary engine |
+| `decider` | The Loop Decider under a `roles` rail launch | The rail's primary engine |
+| `triage` | [Spec triage](spec-triage.md), one structured-output call per spec; edited in project settings ▸ Agent runtime ▸ **Spec triage engine** | The project's primary provider and its cheapest priced catalog model (for example `haiku` on Claude) |
+
+A role whose provider is no longer detected falls back to its default. A stale
+model falls back to the provider's default model. The triage role must name a
+provider that can enforce a pure-output tool policy, otherwise the triage is
+recorded as unavailable.
+
 For the full catalogue of feature flags and kill switches (`SPECRAILS_*` server gates, `VITE_FEATURE_*` client flags, `SPECRAILS_CODEX_BETA`, `SPECRAILS_GEMINI_BETA`, `SPECRAILS_EXPLORE_*`), see [../customizing.md](../customizing.md#environment-variables).
 
 ---
@@ -329,3 +437,26 @@ rm -rf ~/.specrails/desktop.sqlite ~/.specrails/projects/
 - [Codex](../codex.md) — using the Codex CLI provider
 - [Gemini](../gemini.md) — using the Gemini CLI provider
 - [Adding a provider](adding-a-provider.md) — wiring a new AI CLI adapter
+
+## Spend caps (daily, weekly, monthly, per run)
+
+Caps are plain settings; there is no feature flag. The week starts on **Monday 00:00** and the month on the
+**1st 00:00**, both in the **local** time of the machine running the server (the day is local for a project cap;
+the app-wide *daily* budget keeps its historical UTC day). A cap counts the recorded `total_cost_usd` of
+`ai_invocations` (the same sum the daily budget has always used); the part priced from the local rate card is
+reported apart in the Budget panel.
+
+| Cap | Project key (`queue_state`) | App-wide key (`desktop_settings`) |
+| --- | --- | --- |
+| Daily | `config.daily_budget_usd` | `desktop_daily_budget_usd` |
+| Weekly | `config.weekly_budget_usd` | `desktop_weekly_budget_usd` |
+| Monthly | `config.monthly_budget_usd` | `desktop_monthly_budget_usd` |
+| Per run (soft) | `config.run_cap_usd` | `desktop_run_cap_usd` |
+
+All of them go through the one admission gate: rail and loop launches and resumes are refused with
+`409 daily_budget_exceeded` (`period` says which cap), queues auto-pause, and a running loop parks as
+`budget_paused` (a running Core workflow through its cooperative pause, `pauseRuns`). The tightest cap wins; the
+project scope is reported before the app-wide one. The per-run soft cap pauses a run when *its own*
+provider-reported cost reaches it (the tighter of the project and app-wide default, or the launch's `runCapUsd`);
+Continue waives it for that run and Raise moves it up (persisted in `loop_runs.run_cap_usd`, migration 85). A cap
+that is reached also appears in the inbox ("Raise cap").

package/docs/internals/core-runtime-updates.md

@@ -13,9 +13,9 @@ framework is rejected rather than silently replacing an update.
 
 ## Persistence and publication
 
-The release bundle pins Core 6.6.5 in `desktop-release.yml` and
+The release bundle pins Core 6.7.0 in `desktop-release.yml` and
 `scripts/assemble-bundled-core.lock.json`. Core 6 is the Desktop-only engine: it
-publishes integration contract 5.1 (no standalone `update`) and ships only the
+publishes integration contract 5.9 (no standalone `update`) and ships only the
 implement and retry workflows (Batch was folded into implement; Desktop no
 longer requires `batch-implement` but stays compatible with Cores that still ship it). Update both pins together and check compatibility against
 the staged published package; retained runs still use their original runtime.
@@ -27,8 +27,8 @@ dependency leaks into its tarball (today `@langchain/langgraph-sdk` ships
 module still loads while every staged path stays inside the MSI budget
 (`MAX_STAGED_RELATIVE_PATH`, 120 characters).
 
-The paired CI checkout uses the immutable Core 6.6.5 release commit
-`8d796502ceb3b95bebbac7df4084f0655b408a26`. Bundle smoke checks use Node 22.22.3,
+The paired CI checkout uses the immutable Core 6.7.0 release commit
+`8e969c6d7c65b2253d63d6a0cbaaae148cc8ff21`. Bundle smoke checks use Node 22.22.3,
 matching Core's minimum supported Node version and the Desktop release runtime.
 
 Desktop updates retain the complete npm installation, including dependencies,