specrails-desktop 2.36.0 → 2.42.2

package/docs/internals/browser-native-retina-audit.md

@@ -0,0 +1,39 @@
+# Browser performance and Retina audit
+
+Date: 2026-09-05. Implemented on `feat/codex-gpt-6-astra`.
+
+## Cause
+
+The mission browser opened `BrowserCaptureModal`, which displayed a headless Chromium screencast. Only links opened the existing native browser. Navigation in missions therefore encoded JPEG frames, transferred them through WebSocket, decoded them, and painted them on a canvas; every input went through the reverse path. The default stream had one physical pixel per CSS pixel, so Retina screens enlarged a low-resolution image.
+
+Increasing JPEG quality or setting `deviceScaleFactor` alone does not solve this. The local Chromium experiment confirmed that a context at DPR 2 still emitted 1280×800 screencast frames for a 1280×800 CSS viewport. An ordinary screenshot and an actual native browser can retain the physical pixels.
+
+The user then reproduced a development-browser regression: the streamed page occupied only the upper-left quarter of the pane. The initial Retina change enlarged the compositor surface with `Emulation.setVisibleSize`, but the actual JPEG content still occupied its original dimensions. Checking bitmap dimensions alone missed the white padding. Regression checks now inspect page markers at all four corners of actual screencast JPEG frames, as well as layout, input coordinates and screenshot crops.
+
+## Implemented
+
+- **Native mission browsing on macOS.** `AgentBrowserCapture` checks native capture support before mounting a browser. The supported route uses the real WKWebView; no Playwright session, frame stream, canvas repaint or input relay runs during navigation. The address bar accepts HTTP localhost development servers and remembers the last URL per project.
+- **Capture the page the user is actually viewing.** Rust evaluates a fixed selector in WebKit's isolated client world and calls WKWebView's snapshot API. Screenshots preserve the display's backing resolution, including zoom and clipped visible element bounds. There is no second navigation or transfer to another cookie profile. Element selection suppresses page actions, including long presses. Custom application commands are rejected centrally for any webview other than the main app view; this also covers the native page and login popups. Tauri otherwise allowed custom commands without an app ACL manifest, so merely omitting remote capability origins was insufficient.
+- **Keep annotations and retry failures.** The native pane is hidden while the shared image editor annotates the captured bitmap, then shown again without reloading when returning to the page. Flattening uses natural image dimensions. Image redaction is opaque in both preview and PNG, avoiding the unsupported canvas blur path in WebKit. Rendering/upload failures retain the editor and its changes instead of silently sending the original uncensored image. Both the native and advanced flows await the attachment destination before closing. Advanced captures run from the pointer event, outside React state updaters, so StrictMode does not execute each capture twice.
+- **Scope pane operations to their owner.** Each mount has a distinct owner ID, propagated through commands and events. Open/close calls are serialized; stale cleanup cannot close another pane. Late listeners are released, changed URLs navigate the existing pane, geometry updates are deduplicated, and transient startup probe failures can recover.
+- **Correct sizing for advanced capture and fallback.** Both fallback browser surfaces fit their actual containers. The interactive Chromium page keeps its normal CSS viewport and DPR 1. `Page.captureScreenshot` uses `clip.scale` to render PNGs at the host display density, bounded by a 3840×2400 raster budget and scale 2, without changing page state. Its live screencast remains CSS-sized: enlarging the surface with `setVisibleSize` caused the quarter-pane regression; an explicit viewport clip failed after scrolling; changing compositor scale or page DPR altered pointer/wheel semantics. Those approaches were removed. Viewport updates are retained before connection, deduplicated, and follow monitor density changes. Desktop native browsing supplies actual display-resolution rendering without that CDP limitation.
+- **Recover the capture transport.** Failed screencast starts release the partial CDP state and can retry; permanently failed streams disconnect clearly. Stale popup frames are ignored. Chromium uses its default graphics path, with an explicit environment opt-out for incompatible drivers.
+
+## Verification
+
+Reproducible checks include:
+
+- `scripts/smoke-browser-rendering.mjs`: isolated local Chromium fixture; full-page coverage at all four corners of real JPEG frames, CSS input and wheel events after resizing/scrolling, and Retina screenshot crops, including fractional density. Half-pixel patterns verify that the 2× PNG retains detail unavailable in an interpolated 1× bitmap. It checks image content as well as dimensions. No production profile or database is used.
+- The macOS native browser smoke under `src-tauri`: actual WKWebView snapshots, same-page element selection, long-press suppression, zoom, isolated picker state and stale-owner cleanup. A 900×550 logical view produced a 1800×1100 PNG on the Mac's 2× display. `src-tauri/examples/native-browser-selector-smoke.mjs` uses real WebKit clicks to verify cross-origin iframe selection without activating page buttons, open Shadow DOM, long presses and restored browsing.
+- `scripts/smoke-browser-annotations.mjs`: real client CSS and the shared editor in Chromium and WebKit; landscape/portrait Retina images fit the editor, controls remain visible, exported pixels preserve redactions, and encoding failures retain annotations for retry.
+- A separate read-only check opened `https://specrails.dev/` with a fresh temporary Chromium profile, the production `PlaywrightPageHandle`, a 1984×1068 CSS viewport and requested capture density 2. The actual streamed JPEG was visually inspected: the page filled the surface and its hero was centered, reproducing the user's page without the quarter-frame padding.
+- Frontend regression tests cover native/fallback routing, pane lifetime, deferred listeners, native capture/annotation, stable viewport synchronization, uploads and preservation of annotations after failures. Failed native selector polling releases its input shield; if native cleanup itself fails, the UI keeps the selector active with an error and allows cancellation to be retried.
+- Full server/client coverage, TypeScript and production builds passed; coverage thresholds are retained.
+
+Completed checks include full server coverage (282 files, 7,408 tests; 88.32% lines, 78.39% branches, 90.02% functions), full client coverage (354 files, 4,417 tests; 89.24% statements/lines, 83.04% branches, 74.60% functions), plus all 11 native-pane tests after the final selector cleanup fix; all 25 Rust tests and `cargo check --offline --all-targets`; global TypeScript; the production server/client/CLI build; and core compatibility. The Chromium rendering smoke passed all ten size/density/graphics combinations. Native snapshots and selector input were checked with actual macOS WebKit, and the annotation smoke passed in Chromium and WebKit.
+
+The Chromium benchmark reports observed timing on a local synthetic page, not a controlled comparison with Cursor. The architectural change removes the continuous streaming path from native mission browsing; it does not establish identical performance on every website or machine. Native capture is currently macOS-specific; other runtimes keep the compatible Chromium path. This change does not replace the installed signed desktop application.
+
+## References
+
+Cursor documents its integrated browser and element-to-agent workflow in its [Browser documentation](https://prod.cursor.com/docs/agent/tools/browser). Tauri exposes the platform webview through [`with_webview`](https://docs.rs/tauri/2.10.3/tauri/webview/struct.Webview.html#method.with_webview). The implementation was checked against the locally installed Tauri, Wry and Objective-C crate sources, not inferred from newer API versions.

package/docs/internals/ci-cd-audit.md

@@ -0,0 +1,39 @@
+# CI/CD and README audit — 6 September 2026
+
+This audit covers the current Desktop and Core source branches. It does not publish either package, modify repository protection rules, configure npm accounts, or exercise production hosting/signing credentials.
+
+## Findings and changes
+
+| Finding | Change |
+| --- | --- |
+| Release automation ran independently of CI and could publish after failed verification. | Publication now requires successful main-branch CI for the exact release commit; tag/package identity is checked before distribution. Stale main pushes cannot advance release metadata. |
+| Tests against a checkout did not prove the npm payload was usable. Desktop omitted its compiled MCP bridge and filesystem-loaded server resources. | Both repositories install and inspect the actual tarball in a temporary consumer. Desktop builds and ships MCP, schemas, shell-integration shims and Serena templates. Core exercises both CLI entries, four provider assemblies and installed pipeline journals. |
+| Credential-bearing release jobs also performed package installation/build work. | Preparation and tests use read-only jobs. npm publication consumes verified bytes with lifecycle scripts disabled; npm credentials are limited to the publish step. |
+| Concurrent or late releases could move mutable `latest` channels backwards. | Global publication serialization and numeric version guards reject older promotions. Exact existing npm versions require matching integrity for retry. |
+| Core notified the former web repository but not Desktop; Desktop's compatibility check could skip the intended package. | Core dispatches to both consumers with their expected version formats. Desktop validates an explicitly installed candidate and fails if its contract cannot be checked. Only actual drift opens a deduplicated issue. |
+| Workflow syntax and downloaded CI utilities had incomplete verification; native dependency update coverage was missing. | Actionlint becomes a CI gate; utilities are checksum-verified, actions are commit-pinned, and Desktop dependency automation includes Cargo and the MCP bridge. |
+| Native download promotion uploaded its public manifest directly and used plaintext FTP. | Host publication requires FTPS and promotes the manifest using a server-side rename after uploading and checking the referenced installers. Hosting support must be verified during deployment acceptance. |
+| Chromium's optional macOS bundle concealed ad-hoc binaries in an encoded archive, and the launcher's sandbox comment did not match Playwright's default. | New assembly uses transparent archives and a release signing/notarization gate. The resolver prefers those archives, preserves framework links and rolls back failed cache publication. macOS/Windows launches explicitly enable Chromium's sandbox. Hosted signing and clean-machine browser acceptance remain pending. |
+| READMEs contained older architecture, installation claims, unsupported comparisons and incomplete native development steps. | Both READMEs now distinguish the native app, npm/browser use, provider workflows, source development and published releases, with links to detailed feature and release documentation. |
+
+## Verification boundaries
+
+Package checks do not invoke a model or read the user's project registry. Desktop's package smoke verifies CLI execution and runtime resource discovery with dependency lifecycle scripts disabled; it does not certify native SQLite/PTY ABI behavior or launch a complete installed server. Native fixtures and installer gates cover separate parts of that acceptance surface.
+
+Local workflow syntax, helper regression, build, typecheck, package and coverage results are recorded in the [verification report](../../openspec/changes/ci-cd-documentation-hardening/verification.md). Windows/Linux runner execution and real signed publication require the hosted workflows after these changes are merged. Coverage thresholds were retained.
+
+### Native Chromium signing: implementation repaired, hosted acceptance pending
+
+The former optional macOS bundle used XOR-encoded `chromium.pak` to prevent inspection of Chromium's ad-hoc signatures. Outer-app notarization therefore did not establish that the extracted browser met distribution-signing requirements. The audit also found that omitting `--no-sandbox` was insufficient: Playwright disables its Chromium sandbox by default unless `chromiumSandbox` is explicitly enabled.
+
+The new `scripts/assemble-chromium.mjs` packages Chromium as transparent `chromium.tar.gz`, preserving versioned framework symlinks. Release mode on macOS requires Developer ID signing from inner components to their enclosing bundles, Hardened Runtime, the appropriate Chromium component entitlements, signature verification and notarization before distribution. Local assembly invokes the same packager without release credentials, producing an explicitly unsigned development artifact. `scripts/obfuscate-chromium.mjs` remains only for legacy compatibility and fixtures; new release assembly does not produce `.pak` files.
+
+The resolver selects `.tar.gz` and `.tar` before legacy `.pak`, binds cache reuse to the selected archive's path and filesystem revision, rechecks deleted caches and preserves the prior extraction if replacement fails. Regression fixtures exercise transparent/legacy migration and framework symlinks. The production Playwright launcher explicitly sets `chromiumSandbox: true` on macOS and Windows; Linux retains its existing compatibility fallback.
+
+These code changes do not certify an unsigned local browser or a future signed release. Acceptance still requires the real Developer ID/notary workflow and a clean Mac run of the **extracted distributed** browser, including renderer and GPU processes with the sandbox enabled, plus the relevant hosted Windows checks. No signing credential, quarantine attribute or production installer was modified to claim that acceptance locally. A blanket `codesign --deep` substitution is insufficient. See [Chromium's signing process](https://chromium.googlesource.com/chromium/src/+/main/chrome/installer/mac/signing/README.md) and [Apple's distribution signing guidance](https://developer.apple.com/documentation/xcode/creating-distribution-signed-code-for-the-mac/).
+
+## Observed production release failure
+
+Desktop [CI run 33986784637](https://github.com/fjpulidop/specrails-desktop/actions/runs/33986784637) and the [v2.41.0 native release run](https://github.com/fjpulidop/specrails-desktop/actions/runs/33986801426) succeeded. The separate [npm publication run 33986784639](https://github.com/fjpulidop/specrails-desktop/actions/runs/33986784639) failed with `E404` on `PUT https://registry.npmjs.org/specrails-desktop`. The package remains readable in the registry. This result requires checking npm publication authorization; it does not establish exactly which credential or account setting is wrong. Source changes cannot prove that the configured secret can publish.
+
+Follow [Desktop CI and releases](../ci-cd.md) and [Core CI and publishing](https://github.com/fjpulidop/specrails-core/blob/main/docs/ci-cd.md) when configuring credentials or retrying publication. npm trusted publishing needs repository/workflow configuration in the npm account before token authentication can be removed. The implementation follows [GitHub's workflow permission rules](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax) and [npm's provenance requirements](https://docs.npmjs.com/generating-provenance-statements/).

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

@@ -0,0 +1,68 @@
+# Core runtime selection and updates
+
+Desktop resolves one Core runtime for framework materialization, project setup,
+compatibility checks and execution helpers. `server/core-runtime.ts` performs
+read-only discovery; it does not execute a PATH shim or install a global package.
+
+An explicit `SPECRAILS_CORE_BIN` wins when it resolves to a usable compatible
+package. Otherwise Desktop selects the newest compatible package from its
+activated managed installation, bundled resources, local dependency and external
+CLI on PATH. Core 4 and 5 remain supported. A runtime older than the active
+framework is rejected rather than silently replacing an update.
+
+## Persistence and publication
+
+Desktop updates retain the complete npm installation, including dependencies,
+under `~/.specrails/core/<version>/`. The registry home override applies to this
+directory. Only the managed package corresponding to the active framework is
+eligible; an unpublished staging directory is not an installation candidate.
+
+Updates verify the downloaded version, retain the package, materialize every
+requested provider without swapping, and persist recovery state before moving
+`framework/current`. Incomplete retained packages are moved to a retained
+`.previous-<version>-*` directory before their verified replacement is published.
+Previous framework versions are retained. Windows repair reads the activated
+version instead of choosing the highest directory, which could be an unfinished
+stage.
+
+Changing the shared pointer does not update copied project files. The update
+therefore waits for all affected workspaces to be assembled again. Existing
+provider installation configuration and MCP configuration are preserved. A
+workspace's version marker and any runtime helper declared by the selected Core
+contract are verified before that workspace is considered refreshed.
+
+## Partial refresh and recovery
+
+The global `core/update-status.json` stores a pending version before publication.
+Affected workspaces receive `.specrails/core-update-pending.json` before the
+first asynchronous assembly. New implementations in those workspaces are
+blocked until verification clears the marker; reading projects and conversations
+remains available. The global pending state also protects an old workspace whose
+local marker could not be written.
+
+If one workspace fails after publication, Desktop reports a partial update and
+retains the pending state across restart. It does not claim that a global pointer
+rollback restored already updated copies. **Finish updating** retries with the
+retained package and works offline. Successful completion is emitted only after
+all workspace refreshes and the final recovery-state write succeed.
+
+## Version reporting
+
+Global status distinguishes the selected runtime and its source, the active
+framework, the version included in Desktop, and the last successful registry
+check. Installing an explicit target does not overwrite a newer known registry
+version. Registry-check cache failures do not erase installed-version information;
+recovery-state write failures prevent publication or successful completion.
+
+Project status reports provider link versions separately from the workspace seed
+marker. Mixed links/copies or a pending refresh produce `mixed: true` and no
+single claimed installed version. Copied and deliberately pinned projects retain
+their own version instead of inheriting global `current`.
+
+Core 5 uses deterministic installation. Legacy enrichment entry points complete
+only when the native Core 5 role and command artifacts are present; otherwise
+they request installation repair and never invoke a removed enrichment command.
+
+Tests use temporary installations and fake CLI processes, including a fresh Node
+process that resolves an updated package and materializes another provider
+offline. No global CLI or user project is updated by these tests.

package/docs/internals/embedded-browser-native-webview-evaluation.md

@@ -1,5 +1,7 @@
 # Embedded browser: native-webview evaluation (Cursor-class experience)
 
+> Update 2026-09-05: mission browsing now also uses the native pane on macOS, with same-page Retina snapshots, DOM selection and annotations. The original evaluation below is historical; current behavior and validation are documented in [the browser audit](browser-native-retina-audit.md).
+
 > Status: **implemented (phases 0–1 + devtools/zoom from phase 2)** — researched
 > 2026-07-26, shipped via OpenSpec change `native-embedded-browser`. As-built:
 > `src-tauri/src/browser.rs`, `client/src/lib/native-browser.ts`,

package/docs/internals/implementation-reliability-audit.md

@@ -0,0 +1,93 @@
+# Implementation reliability audit — 2026-09-05
+
+Scope: built-in Implement, Batch Implement, Freestyle and SDD Quick loops;
+custom-loop execution; mission-to-rail launches; delivery review, local
+integration and Git worktree checkout. Implemented on `feat/codex-gpt-6-astra`,
+preserving the unfinished Astra catalog changes already on that branch.
+
+The subsequent startup/update disconnection investigation is documented in
+[Startup and update recovery audit](./startup-recovery-audit.md).
+
+The 2026-09-06 Claude Implement follow-up is documented in
+[Claude implementation reliability](../../openspec/changes/claude-implement-reliability/verification.md).
+It corrects early termination of pending architect tasks, explicitly registers
+the packaged `opsx:*` commands, and makes verification/refinement retain the
+complete frozen multi-repository spec scope. Passing baseline checks cannot
+substitute for implementing the requested behavior.
+
+## Findings and changes
+
+| Area | Failure found | Resulting behavior |
+| --- | --- | --- |
+| Loop outcome | AI/shell errors could reach a successful End; a Decider STOP could override a failed step. | Failed passes cannot succeed. Repair must be followed by a successful verification. |
+| Verification | A successful CLI invocation or parseable Decider reply was insufficient proof of verification. | Built-in verification requires an explicit final `VERIFICATION: PASS` line and a successful invocation. Failed/absent verdicts trigger repair. |
+| Decider execution | JSON from a timed-out or failed CLI could be accepted. | Transport/process errors invalidate the decision. |
+| Resident CLI errors | A terminal Claude error result could be treated as a successful turn while the process remained alive; an earlier PASS could survive when the error omitted text. | Terminal result errors stop the failed step after recording usage. Recoverable individual tool errors remain available for the agent to fix. |
+| Progress detection | Hashing only HEAD and status/path names treated edits to the same files as no progress. | The fingerprint includes tracked/index binary diffs and untracked content, without following external symlinks. |
+| Deadlines | The run deadline was checked only between steps; untimed built-ins could remain silent forever. | Remaining deadlines reach each executor. Both AI transports have a configurable inactivity watchdog; active long implementations retain their untimed behavior. |
+| Inactivity retry | Retrying a stalled invocation reused its checkpoint and lost the first attempt's cost. | Every attempt has its own recorded checkpoint and usage; retries respect the remaining budget and deadline. |
+| Provider limits | A throwing notification subscriber could disrupt settlement after a provider limit. | Reporting the provider limit cannot replace or interrupt the persisted execution outcome. |
+| Run isolation | Shared settlement options could carry one run's stall reason into another run. | Each run receives independently derived settlement options. |
+| SDD shell steps | Relocated projects executed shell commands in the artifact workspace. | Shell steps execute in the actual repository/worktree. |
+| Gemini | Loop spawns skipped the provider's headless initialization. | The provider preparation hook runs before spawning, matching QueueManager. |
+| Isolation failure | Operational worktree allocation failures fell back to the user's checkout. | Launch fails explicitly without executing the implementation in the shared checkout. Initial non-Git/unborn repositories retain their explicit degraded path. |
+| Batch review | The Decider received only the first ticket's spec. | Every ticket's launch snapshot reaches the evaluation context. |
+| Custom graphs | Duplicate IDs, invalid limits, ambiguous branches and unsupported fan-out could skip work silently. | Validation rejects graphs the sequential engine cannot execute faithfully. This does not add AND/OR execution semantics. |
+| Rail profiles | The selected profile was resolved by the route but dropped before loop execution. | Isolated/shared launches and interactive/one-shot steps receive the selection. Named profiles get immutable snapshots and the orchestrator model is honored; explicit model selection wins. Missing named profiles fail before launch. |
+| Model handoff | Mission launches could inherit effort while dropping the selected model. | Matching-engine launches inherit both together unless explicitly overridden. |
+| Local integration | Any dirty checkout blocked integration, even unrelated files; a different checked-out branch also blocked it. | Integration assembles away from the user's checkout and uses a non-forced fast-forward. Compatible edits survive; conflicting tracked, untracked and ignored files remain protected. Another active branch remains untouched while the integration branch is updated through a temporary worktree. |
+| Commit authority | Missing delivery SHA could fall back to a mutable branch tip. | Integration requires recorded, available commits; stale/missing evidence cannot authorize unrelated work. |
+| Stacked milestone acceptance | With no assembled delivery SHA, proving only the first unit could complete tickets and clean branches for the whole delivery. | Every unit must have a valid immutable SHA and proven ancestry before acceptance or cleanup; incomplete evidence retains review state. |
+| Integration races | A checkout change near the final advance could make cleanup unsafe. | Destination identity is checked before and after the advance; failure preserves work and does not mark tickets done. |
+| Checkout | The UI required a remote PR, and dirty/cleanup guards blocked compatible local handoffs. | A single verified local result can be checked out before creating a PR. Branch/SHA checks remain mandatory. Cleanup warnings from other retained worktrees do not prevent a valid checkout. |
+| Cleanup | A directory listed as ignored at settlement could gain new files before cleanup. | Its contents are preserved in a recorded safety archive before release, including subsequent additions. |
+| Review evidence | Persisted `{line}` log envelopes were read as raw JSON; interrupted verification could still advertise PASS. | Logs are decoded, verdicts must occupy a verdict line, and incomplete/failed verification cannot provide green evidence. |
+| Mission/board state | Every 409 was treated as already resolved; failed aborts could hide a running job; late Git responses could overwrite current state. | Only stale decisions reconcile neutrally. Real errors remain visible, rejected aborts retain the active session, and old responses cannot overwrite newer project state. |
+| Project routing | A mission review card could open using the currently active project's API. | The review opens in the delivery's own project. |
+| Agent instructions | The operator conflated implementation success with Done and omitted the local Git handoff contract. | Instructions distinguish `on_review`, acceptance, checkout and integration, and preserve user data when an action is blocked. |
+| Astra | Partial catalog work omitted standalone loops and had an unresolved test import. Generic effort lists also offered unsupported model tiers. | Astra is available throughout the selectors and Max preset, with GPT-5.5 still the default and no invented pricing. Current Codex model-specific effort lists are reflected in client and server. |
+
+## Verification
+
+Regression tests exercise real temporary Git repositories for dirty indexes,
+compatible and conflicting edits, untracked/ignored files, detached HEAD,
+other checked-out branches, branch occupation, exact commit identity, retries,
+batch conflicts, external branch changes and worktree cleanup. Provider process
+tests inject controlled CLI streams, failures and inactivity rather than
+spending quota on real model calls. UI tests cover mission and board actions,
+project switching, stale responses, abort rejection and error presentation.
+
+Final validation on 2026-09-05:
+
+| Check | Result |
+| --- | --- |
+| `npm run test:coverage` (server/CLI/MCP) | 272 files, **7,263 tests passed**. |
+| Server/CLI coverage | **87.81% lines**, 85.43% statements, 77.62% branches, 89.52% functions; all configured thresholds passed. |
+| Client `npm run test:coverage -- --maxWorkers=2` | 348 files, **4,310 tests passed**. |
+| Client coverage | **89.06% lines/statements**, 82.87% branches, 74.21% functions; all configured thresholds passed. |
+| `npm run typecheck` | Passed across server, CLI, MCP bridge and client. |
+| `npm run build` | Passed (server, client and CLI); existing Vite chunk-size advisory remains. |
+| `npm run check-core-compat` | Passed against locally installed `specrails-core@4.11.1`. |
+| `git diff --check` | Passed. |
+
+Total: **11,573 passing tests**. The final terminal-result regression reproduced
+eight failures before its fix. No test thresholds were lowered or files excluded
+to obtain coverage. HTTP/IPC/Git suites ran outside the filesystem sandbox where
+necessary for their temporary local sockets and repositories.
+
+## Operational boundaries
+
+`SPECRAILS_LOOP_INACTIVITY_MS` controls the AI-step inactivity watchdog
+(milliseconds; default 1,800,000 = 30 minutes; `0` disables it). Output resets
+this timer. Explicit graph run/step deadlines still apply independently.
+
+Actual source conflicts and another checkout holding the integration branch
+remain actionable blocks; local user data is never forcibly overwritten to
+make an action appear successful. A preserved directory is exposed through the
+delivery's safety-archive metadata and cleanup warnings.
+
+These changes remove reproduced application faults. Provider quota, service
+availability, model decisions, external Git writers and project-specific build
+failures remain external inputs; the application must report and preserve work
+when they fail. No live provider execution, remote PR publication or release
+deployment is part of the automated validation.

package/docs/internals/interactive-jobs.md

@@ -63,7 +63,7 @@ spawnInteractive = isInteractiveJobsEnabled()            // SPECRAILS_INTERACTIV
 | Who gets it | freestyle/Freestyle QueueManager jobs (claude) | every other interactive job + ALL loop ai-steps |
 | End of session | explicit human **Finalize** only (SIGTERM → 2s → SIGKILL) | **quiescence**: a turn `result` arrived, nothing queued, no write in flight — torn down GRACEFULLY: stdin EOF (the CLI exits itself, flushing its session transcript so the next loop step can `--resume`), SIGTERM only after a grace window (`quiescentEofGraceMs`, default 5s) or when stdin is already gone |
 | Idle between turns | by design (awaiting the human) | only transiently (microtask window) |
-| Wedge detector | never armed | the queue's zombie-timeout budget, reset on any raw child output; silence for the whole budget → fold in-flight turn, settle `crashed` |
+| Wedge detector | never armed | the queue's zombie-timeout budget (QueueManager) / the loop-step idle budget (loop ai-steps — `server/loop-step-idle.ts`, default 30 min, `SPECRAILS_LOOP_STEP_IDLE_TIMEOUT_MS`), reset on any raw child output; silence for the whole budget → fold in-flight turn, settle `crashed` (loop steps: tagged `stalled`, retried once by resume) |
 | Composer action | **Finalize Job** | **Wrap up now** (QueueManager) / **Settle this step** (loop step) |
 
 **Quiescence detail:** the auto-settle is deferred to a microtask after the `result` so anything
@@ -98,9 +98,16 @@ persistent stdin, each claude **ai-step** runs as its own `InteractiveJobSession
   quiescence / explicit finalize → `'finalized'` (step ok); step timeout → `session.abort()` →
   fold in-flight turn → `'crashed'`; run cancel → `abort()` → `'crashed'` → engine settles the
   run `'stopped'` at the next boundary; manager shutdown / project removal → `dispose()` (kill,
-  NO settle; the startup orphan sweeps reconcile rows on next boot). No zombie timer is armed on
-  loop steps — the loop's ai-step timeout bounds the whole step and is the sole watchdog
-  (byte-parity with the one-shot loop path, which has no zombie detector either).
+  NO settle; the startup orphan sweeps reconcile rows on next boot). The session's zombie timer
+  IS the loop step's **idle watchdog** (`zombieTimeoutMs = plan.idleTimeoutMs`, `onZombieTimeout`
+  tags the settle `stalled`): factory loops are UNTIMED (`aiStepTimeoutMinutes = 0`), so before
+  this bound a wedged provider left the run `running` forever. Silence for the idle budget →
+  `loop_step_end { status:'stalled', reason:'idle_timeout', idleMs }` → the engine retries the
+  SAME step once by resuming the captured session (`loop_step { attempt: 2 }`); a second stall
+  settles the run `stalled` (tickets → `todo`, delivery row auto-closes). The one-shot loop path
+  arms the same bound through `runAiCliInvocation`'s `inactivityTimeoutMs`. Contract:
+  `server/loop-step-idle.ts` — `SPECRAILS_LOOP_STEP_IDLE_TIMEOUT_MS` (default 30 min; `0|false|off`
+  disables; clamped ≥ the stuck-notification threshold so `job.stuck` always precedes teardown).
 
 ## Accounting reconciliation
 
@@ -159,6 +166,100 @@ command didn't actually run, the settle is FAILED.**
   from the step result's accumulated signals (one-shot `text` accumulates only from assistant
   text-deltas, so non-empty text ⇒ assistant events were seen).
 
+## CLI notification turns, orphaned background tasks, resume misses (run `5c958db2`)
+
+Live evidence (loop run `5c958db2`, claude 2.1.260, factory Freestyle): the **verify** step
+backgrounded the CI chain (`run_in_background`), replied *"I'll deliver the final verdict line
+when it lands"*, and quiesced. The auto-settle EOF'd stdin; the CLI kept the process alive for
+its background tasks, so the 5 s grace expired and SIGTERM tore it down — orphaning the tasks.
+The Decider (rightly) said *continue*, and the **fix** step `--resume`d the same session. On
+resume the CLI reported the orphans (`system/task_notification … "Orphaned by a previous Claude
+Code process exit"`) and emitted a **turn of its own** BEFORE processing our prompt: a `result`
+frame with `origin: {kind:'task-notification'}`, `num_turns: 0`, `stop_reason: null`, empty
+`result`, zero usage. The session took it as our turn's terminal result → quiescent auto-settle →
+the real turn (already thinking) was killed 5 s later as a zero-work FAILED step in "0.1 s". Three
+guards now cover the chain:
+
+- **Notification frames are not turn results.** `isClaudeNotificationResultFrame`
+  (`server/providers/claude-adapter.ts`) recognises `origin.kind === 'task-notification'`; the
+  adapter surfaces such a frame as a NON-terminal `{kind:'other', type:'result'}` event, so every
+  adapter-event consumer (persistent Explore turns, agent chat, `extractResult`, crash recovery)
+  ignores it. `InteractiveJobSession._handleStdoutLine` classifies through the adapter BEFORE the
+  drop logic: a result frame with no `kind:'result'` adapter event leaves the turn armed, is NOT
+  persisted as a `result` row (recovery counts persisted result rows as completed turns), and
+  logs `↷ claude reported a background-task notification (not this turn's result) — continuing.`
+  The caller's own turns carry no `origin` at all; other `origin.kind` values the CLI bundle
+  knows (`human`, `auto-continuation`, `observer-activity`, `channel`) are deliberately NOT
+  special-cased — only the observed no-op kind is.
+- **Resume miss ⇒ one fresh retry (loop engine).** `isResumeMiss` (`loop-run-manager.ts`): a
+  step that resumed the previous step's session and settled zero-work WITHOUT an
+  `Unknown command:` text and WITHOUT the step timeout was answered by session bookkeeping, not
+  the model — the prompt never ran. The engine logs
+  `↻ Resuming session <id> produced no work — retrying this step in a fresh session.` and re-runs
+  the SAME prompt once with no `sessionId`, inside the same step (one `loop_step`/`loop_step_end`
+  pair, one `record()` row from the final attempt; the empty attempt has nothing to account).
+  A fresh (non-resumed) zero-work step, an Unknown-command, a timeout, a cancel, or a zero-work
+  retry all keep the existing FAILED path. This is the belt-and-braces for the OTHER resume-miss
+  cause — a transcript the SIGTERM escalation raced (the graceful-EOF fix in `_finalizeQuiescent`
+  made that rare, not impossible).
+- **Backgrounding is forbidden and visible.** `FOREGROUND_RULE` (`loop-constants.ts`) rides
+  `{{const:GUARDRAILS}}` and the verify / fix / freestyle templates (plus the default Freestyle
+  pre-prompt): run every command in the foreground, never `run_in_background`/`&`, the reply ends
+  the step. At quiescent auto-settle the session mirrors claude's
+  `system/background_tasks_changed` roster and, when tasks are still running, persists
+  `⚠️ The agent ended its turn with N background task(s) still running (…) — long commands must
+  run in the foreground.` so a verdict-less verify step explains itself. Finalize mode (idling by
+  design) never emits it.
+- **User cancel is not a provider failure.** The `AI_FAILFAST_THRESHOLD` streak skips a step
+  torn down by `cancel()`, so the run settles `stopped` instead of `failed` with a misleading
+  *"provider appears down"* (the live run hit exactly that when the user stopped it mid-verify).
+
+## Provider usage / rate limits (run `52124009`, 2026-09-04)
+
+The claude subscription hit its session limit mid-batch. The CLI answered
+every later spawn in ~0.5 s with a `result` frame whose text was
+*"You've hit your session limit · resets 3am (Europe/Madrid)"* and
+`is_error: true`. The engine saw a non-empty, exit-0 reply → step `ok` →
+verify → decider (unparseable → continue) → fix … three full cycles until the
+no-progress stall guard finally stopped the run — nine steps of nothing after
+the real cause. A limit is not something to iterate on.
+
+- **Structural signal.** The claude adapter now carries `is_error` on the
+  `result` AdapterEvent (`isError`); `InteractiveJobSession` captures it per
+  turn (`SettleInfo.resultIsError`) and the one-shot executor reads it off the
+  result event. Both AI-step paths mark such a step `failed` with the result
+  text as `errorText` (`AiStepResult.resultIsError`), and the engine's
+  fail-fast counts an error result even though it carried text (two in a row
+  ⇒ "provider appears down", as for no-output crashes).
+- **Limit classifier (`server/provider-limit.ts`).** `classifyProviderLimit`
+  judges only the TAIL of a step's final text / error text (a spec discussing
+  rate limiting never trips it): claude session/usage limits and the API
+  wrapper (`error type rate_limit`, `HTTP 429`), codex quota notices, gemini
+  `RESOURCE_EXHAUSTED`; `extractLimitReset` pulls the provider's reset hint
+  ("3am (Europe/Madrid)", "in 2 hours").
+- **Engine stop.** On a hit the AI step closes `loop_step_end { status:
+  'failed', reason: 'provider_limit' }`, logs `■ Provider limit reached
+  (<provider>): <the provider's sentence> — relaunch or Recover & retry after
+  the reset`, records the invocation as failed, broadcasts the project-scoped
+  `loop.provider_limit { runId, provider, kind, message, resetsAt }` and
+  settles the run `stalled` with `LoopRunResult.stallReason = 'provider_limit'`
+  (+ `providerLimit`) — no verify, no decider, no retry. The other stall paths
+  now name their reason too (`idle_timeout`, `no_progress`).
+- **Propagation.** Every run-finished caller forwards `stallReason` to
+  `onLoopRunFinished(runId, outcome, { stallReason })`; the milestone chain
+  records `last_run_outcome = 'provider_limit'` and pauses with its OWN reason
+  `provider_limit` (Resume after the reset relaunches the same chunk). Client:
+  `useOsNotifications` toasts `loop.provider_limit` (provider + reset hint +
+  the provider's sentence, OS notification when permitted), the step section
+  shows a **Provider limit** badge, narration says "Step N stopped — the
+  provider's usage limit was reached", the chain row/toast localise the reason.
+  i18n `jobs:loopExplorer.providerLimit*`, `narration:step.providerLimit`,
+  `commands:notifications.providerLimit*`,
+  `builder:milestoneProgress.chain.reasons.provider_limit` ×8.
+- **Not detected (by design):** a Decider whose own reply is the limit
+  notice — the executor exposes no raw text; in practice the preceding AI
+  step already stopped the run.
+
 ## Zombie / timeout interplay
 
 - **One-shot jobs**: unchanged — the queue's zombie timer kills a silent child.
@@ -166,8 +267,11 @@ command didn't actually run, the settle is FAILED.**
   stdout/stderr `data`); firing folds the in-flight turn and settles `'crashed'`.
 - **Interactive `'finalize'`**: no timer at all — an idle session awaiting Finalize is the
   feature. QueueManager's queue-level timer is never armed for interactive jobs.
-- **Loop ai-steps**: no zombie timer; the step timeout aborts the session (`'crashed'`,
-  `errorText: 'AI step timed out'`), partial work accounted.
+- **Loop ai-steps**: the idle watchdog (`loop-step-idle`) is armed as the session's zombie timer
+  (`'crashed'` + `stalled` flag, `errorText: 'AI step stalled'`, retried once by resume); the
+  optional step timeout still aborts the session (`'crashed'`, `errorText: 'AI step timed out'`),
+  partial work accounted either way. `job.stuck` carries `actions: ['stop']` — the client toast
+  offers **Stop run** through the existing `POST /jobs/:id/cancel` route.
 - **Finalize hard-deadline**: SIGTERM → 2s → SIGKILL, plus a forced settle if the child never
   emits `close` (D-state / signal-swallowing) so the queue slot can never leak.
 - **Undeliverable turns**: a confirmed-failed stdin write (destroyed/EPIPE) is surfaced as a

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

@@ -0,0 +1,76 @@
+# MCP and mission operator reliability audit
+
+Date: 2026-09-05. Branch: `feat/codex-gpt-6-astra`.
+
+This audit covers the embedded MCP server, stdio bridge, tool contracts and
+mission operator context. It builds on the implementation/worktree and startup
+recovery fixes already present on this branch. No production AI runs were
+launched, no project state was changed through the audited operational tools,
+and no remote PRs were created. Source changes are retained on this branch.
+
+## Findings and corrections
+
+| Failure | Correction |
+| --- | --- |
+| A missing scoped spec/job could resolve to an entity in another project; references were deduplicated without their project scope. | Treat a project id as an exact address, retain scope in deduplication, report ambiguous/unavailable references, and never substitute another repository. |
+| Missions received a project id but little current project context. A fresh provider session could lose conversation history. | Add bounded live project/provider/backlog/job orientation per turn and restore recent persisted history only on fresh invocations. Historical messages are labelled as data; current settings and live evidence take precedence. |
+| An empty resumed reply could trigger a replay after tools had already executed. Missing MCP wiring silently launched a tool-less paid agent. | Retry only explicit stale-session errors without tool activity. Fail before provider launch if MCP preparation fails. |
+| Project selection was process-global across external MCP clients. Mission selection could claim success despite its immutable capability pin. | Isolate defaults per MCP session. Preserve the mission pin, including Home; explicit project ids address intentional operations elsewhere. |
+| Invalid/revoked mission capabilities could fall through to external-client permissions. Sessions were not bound to their originating capability. | Reject invalid capabilities, bind session ownership to the capability, close revoked/expired/idle sessions, and fail explicitly when the bridge cannot read its capability file. |
+| Token rotation and session loss left clients disconnected or hanging. | Refresh bridge authentication on each request, retry a rejected 401 only after a token change, reinitialize after a protocol session 404, and terminate remote sessions on close. Network failures never replay a possibly-started mutation. |
+| MCP admin tier edits could partially apply before returning 400; token rotation left old streams alive. | Validate all tier fields before writes; rotating the token closes existing sessions. Failed token persistence cannot silently publish an unusable token. |
+| Mixed read/write facades advertised read-only MCP annotations. Some draft commits that can spawn Contract Refine were classified as Write. | Publish conservative facade annotations, expose precise action/argument tier previews, and enforce AI-spawn for potentially cost-incurring commits. |
+| The project catalog and diagnostics hid registered projects whose databases were unavailable. | Use durable registry rows for tools/resources, preserve identity and show availability explicitly. Context sections fail independently rather than implying empty state. |
+| Tool discovery ignored action names and nested argument structure. | Search names/actions/schema descriptions, support common Spanish intents, expose full SDK-generated JSON schemas, and validate prospective arguments without execution. |
+| Watch only observed future events and could wait for completed jobs/loops; whole-payload substring matching could settle on the wrong entity. | Read durable job/loop state before waiting, match typed identity fields, retain bounded events, distinguish failure, and support cancellation. |
+| Raw file reads and job histories could consume excessive model context; Code Explorer only searched filenames. | Add literal content search, bounded source pages with line/column continuations and revision hashes, compact spec/job lists and paginated event history. Partial results explicitly report their limits. |
+| Operational tools omitted useful review evidence and conversational launch defaults. | Add PR candidates/review packets, Git/worktree information, PR lookup and phase breakdowns. Preserve conversation provider/model/effort when launching compatible jobs/loops, and report when isolation is unavailable. |
+| Binary attachments were forwarded through a text response path. | Return attachment metadata and a download reference instead of decoding arbitrary bytes as text. |
+
+## New investigation workflow
+
+1. Identify the intended project from the conversation pin or durable catalog.
+2. Read `specrails_context` sections relevant to the question: `overview`,
+   `backlog`, `runs`, `git`, `blueprint`. Each result names its source and reports
+   unavailable data; these independent reads are not an atomic snapshot.
+3. Locate behavior/tests with `specrails_code(search)` and read exact source
+   ranges. Use the returned hash when continuing to detect intervening edits.
+4. Discover exact tool arguments and permissions with `specrails_describe`.
+   Schema validation does not execute the tool or replace backend checks.
+5. Inspect execution evidence and the verified review packet before describing
+   completion. Refresh affected context after operations.
+
+The catalog now has 22 tools. Existing domain tools gain focused read actions;
+implementation and delivery still use the app's existing validated routes.
+
+## Validation
+
+Focused regression suites cover real HTTP/SDK session isolation and recovery,
+capability revocation, tier boundaries, temporary project databases, source
+search/read bounds, historical context and no-replay behavior.
+
+- Server/CLI/MCP: 281 test files, 7,394 passing tests. Coverage: statements
+  85.97%, branches 78.38%, functions 90.02%, lines 88.31%; all thresholds pass.
+- Client: 348 test files, 4,335 passing tests. Coverage: statements/lines 89.13%,
+  branches 82.86%, functions 74.35%; all thresholds pass.
+- TypeScript, app/server/CLI build and the bundled MCP bridge build pass.
+- Core compatibility passes: core 4.11.1 with desktop 2.40.0.
+- `git diff --check` passes. The app build retains the existing Vite large-chunk
+  advisory; it is not a build failure.
+
+Total for this audit's complete run: 11,729 passing tests, including 120 more
+server/CLI/MCP tests than the preceding startup-recovery audit. Test fixtures
+use temporary databases/repositories and local HTTP servers.
+
+## Practical limits
+
+- This establishes deterministic platform behavior under the tested failures;
+  it cannot guarantee the quality or success of every future model-generated
+  implementation or third-party provider/GitHub operation.
+- Durable watch recovery covers jobs and loop runs. Other async operations use
+  future bus events and their domain reads; there is no generic durable replay.
+- Context is deliberately bounded, and blueprint milestones are plans rather
+  than proof that work is done. Truncated or unavailable results require a
+  narrower source read, never a fabricated conclusion.
+- The application sources and bundles are updated on this branch. Updating the
+  installed native application remains a separate release/install operation.