specrails-desktop 2.29.4 → 2.29.5

package/docs/customizing.md

@@ -161,7 +161,7 @@ Most settings live in the UI. A few app-level switches are env-only because they
 | `SPECRAILS_GEMINI_BETA=0` | Emergency rollback — disable the Gemini provider (default unset = enabled; only the exact string `0` disables; **no legacy fallback name**) |
 | `SPECRAILS_SMASH=0` | Kill switch for SMASH spec decomposition (`0` / `false` / `off`; endpoints return 409) |
 | `SPECRAILS_EXPLORE_CONTRACT_REFINE=0` | App-wide kill switch for Contract Refine (auto-fire + retry endpoint; accepts `0` / `false` / `off`) |
-| `SPECRAILS_EXPLORE_LEGACY_CWD=1` | Force Explore spawns to use the project root instead of the app-managed `explore-cwd/` |
+| `SPECRAILS_EXPLORE_LEGACY_CWD=1` | Force every Explore spawn to use the project root instead of the app-managed `explore-cwd/` or a relocated workspace |
 | `SPECRAILS_FILE_SUMMARY_MODEL` | Override the model used for Code-section file summaries. Per-provider overrides take precedence: `SPECRAILS_FILE_SUMMARY_MODEL_CLAUDE` (Claude) and `SPECRAILS_FILE_SUMMARY_MODEL_CODEX` (Codex); the generic var is the fallback |
 | `SPECRAILS_ALLOW_LOCAL_WEBHOOKS=1` | Allow outbound webhooks to target loopback / private-network addresses |
 

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

@@ -38,7 +38,7 @@ loads** for gemini:
 |---|---|---|
 | Plugins on rails (`server/plugin-manager.ts`, e.g. Serena) | surgical merge into `<project>/.mcp.json` for `project-json` providers | plugin installs "successfully", MCP server never loads in gemini rail spawns |
 | Workspace MCP (`server/agent-mcp-config.ts` `mergeSpecrailsIntoWorkspaceMcp`, via `workspace-manager.ts`) | writes `<workspace>/.mcp.json` | not read by gemini |
-| Explore `context_scope.mcp` (`server/chat-manager.ts`) | spawns from `<project.path>` so `.mcp.json` loads | loads nothing on gemini |
+| Explore `context_scope.mcp` (`server/chat-manager.ts`) | spawns from the relocation-aware artifact cwd (workspace when relocated, `<project.path>` when legacy) so `.mcp.json` loads | loads nothing on gemini |
 
 Fixing these means writing into the repo's / workspace's `.gemini/settings.json`, which
 intersects the **pristine-repo / artifact-relocation policy** (the app must not mutate the

package/docs/internals/global-artifacts-alignment-contract.md

@@ -239,7 +239,7 @@ $HOME/.specrails/
 ├── jira-secret.key               # keyfile AES-256-GCM (0600), desktop-only
 ├── doctor.log                    # log append-only, core-only (única lectura $HOME de core hoy)
 └── projects/<slug>/
-    ├── workspace/                # = artifactRoot. cwd de spawn de todas las AI-CLI
+    ├── workspace/                # = artifactRoot. cwd de jobs y Explore mcp=true relocalizados
     │   ├── .specrails/
     │   │   ├── local-tickets.json (+ .lock)   ← SPECRAILS_TICKETS_PATH        [core escribe/lee · desktop escribe]
     │   │   ├── backlog-config.json            ← SPECRAILS_BACKLOG_CONFIG_PATH  [desktop escribe · core lee]
@@ -365,9 +365,9 @@ El lado desktop ya tiene el precedente load-bearing en producción (`explore-cwd
 
 ### 6.1 cwd de spawn + env por provider
 
-`ExploreCwdManager` se generaliza a un `WorkspaceManager` que materializa `~/.specrails/projects/<slug>/workspace/` con `./project -> <project.path>` (symlink/junction, fallback `project-path.txt` — la lógica existente `ensureProjectLink`). **Todas las AI-CLI mueven cwd al workspace.**
+`ExploreCwdManager` se generaliza a un `WorkspaceManager` que materializa `~/.specrails/projects/<slug>/workspace/` con `./project -> <project.path>` (symlink/junction, fallback `project-path.txt` — la lógica existente `ensureProjectLink`). **Las AI-CLI relocalizadas usan el workspace salvo los procesos deliberadamente repo-bound y Explore con `mcp=false`, que conserva su `explore-cwd`.**
 
-**Managers que MUEVEN cwd → workspace:** `QueueManager._startJob` (rails — el grande), `ChatManager` (Explore + sidebar), `AgentRefineManager` (ai-edit), `ContractRefineRunner`, `project-router /tickets/generate-spec` (quick-spec), `FileSummaryManager`, `SetupManager.startInstall` (corre `npx specrails-core init --root-dir <project.path> --workspace-dir <workspace>`).
+**Managers que MUEVEN cwd → workspace:** `QueueManager._startJob` (rails — el grande), `ChatManager` (sidebar + Explore con `mcp=true`), `AgentRefineManager` (ai-edit), `ContractRefineRunner` cuando refleja un Explore `mcp=true`, `project-router /tickets/generate-spec` (quick-spec), `FileSummaryManager`, `SetupManager.startInstall` (corre `npx specrails-core init --root-dir <project.path> --workspace-dir <workspace>`). Explore y Contract Refine con `mcp=false` permanecen en el app-managed `explore-cwd`.
 
 **Managers que CONSERVAN cwd = `project.path`:** `TerminalManager` (shell repo-bound), `file-provenance.ts` (git repo-bound), `code-explorer-router` (lee fuente), lecturas de fuente de `FileSummaryManager`, `metrics.ts` (coverage).
 
@@ -380,7 +380,7 @@ El lado desktop ya tiene el precedente load-bearing en producción (`explore-cwd
   - **Smoke check (manual):** en un proyecto relocalizado con provider=codex, lanzar un loop "Implement" cuyo paso de fix deba editar una fuente del repo; confirmar en el transcript que (a) `apply_patch`/edit a `<repoDir>/...` **NO** devuelve `Operation not permitted`, y (b) `npm run build`/`tsc -b` puede escribir `node_modules/.tmp/*.tsbuildinfo`. Reproducción del fallo: revertir el `extraArgs` de codex → la edición del repo en la iteración ≥2 vuelve a fallar con `Operation not permitted`. Cubierto por `server/loop-executors.test.ts` (assert del arg `writable_roots`).
 - **gemini**: inyecta `GEMINI_CLI_TRUST_WORKSPACE=true` (ancla el root confiable al workspace). **Re-keya** `~/.gemini/acknowledgments/agents.json` al workspace.
 - Los tres: el workspace **estrictamente fuera del repo** y el discovery no debe seguir `./project` (mitiga la fuga por ancestor-walk de codex/gemini).
-- **Caso especial Explore `mcp=true`**: hoy `chat-manager.ts:326` conmuta cwd a `project.path` para cargar el `.mcp.json` del repo — tras relocalizar, `.mcp.json` está en el workspace, así que este special-case se **ELIMINA**, no se re-apunta.
+- **Caso especial Explore `mcp=true` (implementado):** `ChatManager` resuelve el cwd mediante la misma puerta de relocalización: workspace cuando el proyecto está relocalizado, `project.path` en legacy. Las rutas persistent-stdin, crash-respawn y Contract Refine conservan esa misma pareja cwd/env. Una sesión anterior creada bajo el cwd del repo que devuelve exactamente `No conversation found with session ID` se invalida y reintenta fresh una sola vez desde el workspace (transcript persistido acotado para Explore; ticket sembrado y tools deshabilitadas para Contract Refine), nunca volviendo al repo. `SPECRAILS_EXPLORE_LEGACY_CWD=1` sigue forzando `project.path`.
 
 ### 6.2 Sitios de re-apuntado de path (`project.path` → workspace)
 

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

@@ -193,25 +193,35 @@ seeded instruction file), which lives in `~/.specrails/projects/<slug>/workspace
 absent from the worktree: the claude CLI reported `Unknown command: /specrails:implement`
 and the loop "succeeded" through verify/fix without implementing (live evidence: run
 01f41203). Legacy projects have the sibling gap for their UNTRACKED on-disk `.claude`
-entries. Each allocated worktree therefore gets `applyWorktreeOverlay(...)` at launch:
-
-- **Source root** = the project's effective artifact root, resolved once per launch via
-  `resolveProjectExecution`: the workspace when relocated, else the repo itself.
-- **Merge-only symlinks** under `<worktree>/<providerDir>/`: dir links where a dir is
-  wholly absent, per-file/per-child where the checkout is partially present; checkout
-  content is NEVER overwritten. `agent-memory` is linked (all runs share memory — the
-  pre-isolation shared-cwd semantics, deliberate). The providerDir root and the source's
-  `worktrees/` entry are never linked (nested pipeline worktrees stay local). `.mcp.json`
-  and the instruction file (CLAUDE.md/AGENTS.md/GEMINI.md per provider) are COPIED when
-  the checkout lacks them. Windows: junction → dereferencing-copy fallback.
-- **Never on the PR**: every allocator-created overlay path is excluded from staging with a literal
-  top-level pathspec. The writable worktree manifest is not cleanup authority; settlement persists
-  fingerprints captured from the trusted source/created entries. Cleanup atomically renames each
-  authenticated root into a unique sibling quarantine, revalidates it after the move, discloses
-  raced content there, and never deletes or restores quarantined paths automatically over a
-  possibly recreated source. A modified or
-  concurrently extended overlay is preserved as user data, while a no-op
-  overlay keeps the byte-identical ordinary staging behavior.
+entries. Relocated projects also need repo-resident carve-outs that are intentionally not
+part of the workspace framework, notably OpenSpec's untracked `/opsx:*` commands and
+`openspec-*` skills. Each allocated worktree therefore gets `applyWorktreeOverlay(...)`
+at launch:
+
+- **Ordered source roots** are resolved once per launch. The primary root is the effective
+  artifact root (`resolveProjectExecution`: workspace when relocated, repo when legacy).
+  A relocated launch additionally passes the repo as a lower-priority fallback so its
+  untracked provider entries reach the worktree. Earlier roots win per entry; legacy stays
+  on its byte-identical single-root path.
+- **Merge-only links/copies** under `<worktree>/<providerDir>/`: one contributing directory
+  stays a whole-dir link; when several roots contribute children, the destination is a REAL
+  directory of per-child links. Checkout content is NEVER overwritten, including source
+  file/directory type conflicts. On resume, only an authenticated prior-manifest whole-dir
+  link/copy may be rebuilt into recorded leaves; a foreign symlink is untouched even when it
+  targets a configured source. Converted parents are revoked from the manifest. `agent-memory`
+  remains linked (shared pre-isolation semantics). The providerDir root and every source's
+  `worktrees/` entry are never linked. `.mcp.json` and the provider instruction file are COPIED
+  from the first root containing them when checkout lacks them. Windows: junction →
+  dereferencing-copy fallback.
+- **Never on the PR**: the resume-safe manifest records authenticated overlay leaves against
+  any configured root; settlement persists immutable fingerprints. Commit delivery deliberately
+  runs plain `git add -A`, audits the index, resets forbidden literal top-level paths, re-audits,
+  and makes those exclusions authoritative with `git commit --only`. The writable manifest alone
+  never grants cleanup authority. Cleanup atomically renames each authenticated root into a unique
+  sibling quarantine, revalidates it after the move, discloses raced content there, and never
+  deletes or restores quarantined paths automatically over a possibly recreated source. A modified
+  or concurrently extended overlay is preserved as user data, while a no-op overlay keeps the
+  byte-identical ordinary staging behavior.
   Successful quarantine batches deliberately remain beside the former worktree; automatic GC is
   out of scope because deleting a path still writable through an open descriptor would reintroduce
   the data-loss race. A future cleanup flow must be explicit and inspectable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.29.4",
+  "version": "2.29.5",
   "license": "MIT",
   "repository": {
     "type": "git",

package/server/dist/chat-manager.js

@@ -25,6 +25,92 @@ const workspace_resolution_1 = require("./workspace-resolution");
 const COMMAND_INSTRUCTION = 'When you want to suggest a SpecRails command for the user to execute, wrap it in a command block like this: ' +
     ':::command\n/specrails:implement #42\n::: ' +
     'The user will be prompted to confirm before the command runs.';
+/** Claude stores resumable sessions under the spawn cwd. Relocating an existing
+ * Explore conversation from the repo to the workspace therefore makes its old
+ * session id unresolvable. Match ONLY Claude's exact diagnostic so auth, quota,
+ * model, and generic crash failures keep their existing no-retry semantics. */
+const CLAUDE_MISSING_SESSION_DIAGNOSTIC = 'No conversation found with session ID';
+/** Historical context folded into the one-time fresh-session recovery. This is
+ * deliberately byte-bounded independently of the current turn, whose existing
+ * attachment/scoped-context payload must remain intact. */
+const RESUME_RECOVERY_TRANSCRIPT_MAX_BYTES = 48 * 1024;
+function containsMissingClaudeSessionDiagnostic(value) {
+    if (typeof value === 'string') {
+        return value.includes(CLAUDE_MISSING_SESSION_DIAGNOSTIC);
+    }
+    if (value == null)
+        return false;
+    try {
+        return JSON.stringify(value).includes(CLAUDE_MISSING_SESSION_DIAGNOSTIC);
+    }
+    catch {
+        return false;
+    }
+}
+function isMissingClaudeSessionErrorResult(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const payload = value;
+    const markedAsError = payload.is_error === true ||
+        (typeof payload.subtype === 'string' && payload.subtype.startsWith('error'));
+    return markedAsError && containsMissingClaudeSessionDiagnostic(value);
+}
+function takeUtf8Tail(text, maxBytes) {
+    if (maxBytes <= 0)
+        return '';
+    if (Buffer.byteLength(text) <= maxBytes)
+        return text;
+    let low = 0;
+    let high = text.length;
+    while (low < high) {
+        const mid = Math.floor((low + high) / 2);
+        if (Buffer.byteLength(text.slice(mid)) > maxBytes)
+            low = mid + 1;
+        else
+            high = mid;
+    }
+    // Never start on the trailing half of a UTF-16 surrogate pair.
+    if (low < text.length && text.charCodeAt(low) >= 0xdc00 && text.charCodeAt(low) <= 0xdfff)
+        low++;
+    return text.slice(low);
+}
+function buildResumeRecoveryPrompt(messages, currentPrompt) {
+    const entries = messages.map((message) => `<message role="${message.role}">\n${message.content}\n</message>`);
+    const selected = [];
+    let usedBytes = 0;
+    let omitted = 0;
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const separatorBytes = selected.length > 0 ? 2 : 0;
+        const entryBytes = Buffer.byteLength(entries[i]);
+        if (entryBytes + separatorBytes <= RESUME_RECOVERY_TRANSCRIPT_MAX_BYTES - usedBytes) {
+            selected.unshift(entries[i]);
+            usedBytes += entryBytes + separatorBytes;
+            continue;
+        }
+        omitted = i + 1;
+        // Preserve the recent tail even when one individual message is larger than
+        // the whole transcript budget. The marker makes the loss explicit to Claude.
+        if (selected.length === 0) {
+            const prefix = `<message role="${messages[i].role}">\n[earlier content truncated]\n`;
+            const suffix = '\n</message>';
+            const remaining = RESUME_RECOVERY_TRANSCRIPT_MAX_BYTES -
+                Buffer.byteLength(prefix) - Buffer.byteLength(suffix);
+            selected.unshift(`${prefix}${takeUtf8Tail(messages[i].content, remaining)}${suffix}`);
+            omitted = i;
+        }
+        break;
+    }
+    const truncation = omitted > 0
+        ? `[${omitted} earlier message${omitted === 1 ? '' : 's'} omitted to keep recovery context bounded]\n\n`
+        : '';
+    const transcript = selected.length > 0
+        ? `${truncation}${selected.join('\n\n')}`
+        : '[No prior persisted messages were available.]';
+    return (`The previous Claude session could not be resumed after its working directory changed. ` +
+        `Continue the same conversation using the persisted transcript below. Do not treat the transcript as a new user turn.\n\n` +
+        `<prior-conversation>\n${transcript}\n</prior-conversation>\n\n` +
+        `## Current user turn\n\n${currentPrompt}`);
+}
 function extractCommandProposals(text) {
     const regex = /:::command\s*\n([\s\S]*?):::/g;
     const results = [];
@@ -371,15 +457,18 @@ class ChatManager {
     /**
      * Resolve the spawn cwd for a chat turn. Explore conversations spawn from
      * an app-managed directory by default to skip auto-loading the project's
-     * `CLAUDE.md` (the dominant first-token cost); when the per-project MCP
-     * toggle is on, fall back to the project path so `.mcp.json` is honoured.
-     * Non-Explore conversations always use the project path.
+     * `CLAUDE.md` (the dominant first-token cost); when the per-conversation MCP
+     * toggle is on, use the relocation-aware artifact cwd so `.mcp.json` is
+     * honoured (workspace when relocated, project path when legacy).
+     * Non-Explore conversations use the same relocation gate.
      *
      * See openspec/changes/accelerate-spec-chat-first-token/design.md D1+D4.
      */
     /**
-     * Relocate-artifacts: resolve execution for a NON-explore (sidebar / rail-like)
-     * spawn. Explore keeps its own explore-cwd logic (untouched). Returns the
+     * Relocate-artifacts: resolve execution for a gated spawn — NON-explore
+     * (sidebar / rail-like) turns, and Explore turns with `contextScope.mcp`
+     * (the MCP-honouring cwd is the workspace when relocated). Explore with
+     * mcp=false keeps its own explore-cwd logic (untouched). Returns the
      * relocated cwd + env when relocated, else legacy (cwd = project.path, empty
      * env). Cached per call — cheap registry read.
      */
@@ -409,8 +498,19 @@ class ChatManager {
         // Per-conversation scope.mcp is the only source of truth. Legacy null
         // scope is treated as mcp=false (spawn from app-managed cwd).
         const mcpEnabled = scope ? !!scope.mcp : false;
-        if (mcpEnabled)
-            return this._cwd;
+        if (mcpEnabled) {
+            // The escape hatch keeps its documented force-`<project.path>` semantics.
+            if (process.env.SPECRAILS_EXPLORE_LEGACY_CWD === '1')
+                return this._cwd;
+            // MCP-honouring cwd through the relocate-artifacts gate: for a RELOCATED
+            // project `.mcp.json` AND `.specrails/` live in the WORKSPACE — spawning
+            // from the repo made the system prompt's cwd-relative ticket-store
+            // instruction create `<repo>/.specrails/local-tickets.json` (a store the
+            // app never reads), breaking the pristine-repo guarantee. Legacy
+            // projects resolve to project.path — byte-identical.
+            const exec = this._resolveNonExploreExecution();
+            return exec ? exec.cwd : this._cwd;
+        }
         try {
             const cwd = (0, explore_cwd_manager_1.ensureExploreCwd)({
                 slug: this._projectSlug,
@@ -613,8 +713,14 @@ class ChatManager {
             }
             // Check if this is turn 1 (session_id was null before this message)
             const isFirstTurn = conversation.session_id === null;
-            // Persist user message
-            (0, db_1.addMessage)(this._db, { conversation_id: conversationId, role: 'user', content: userText });
+            // Persist the user message exactly once. Its row id is retained so a
+            // stale-session recovery can fold prior history into a fresh prompt without
+            // duplicating this current turn (getMessages already includes it by then).
+            const persistedUserMessage = (0, db_1.addMessage)(this._db, {
+                conversation_id: conversationId,
+                role: 'user',
+                content: userText,
+            });
             // Resolve slash commands (e.g. /specrails:propose-spec → prompt content)
             let resolvedText = (0, command_resolver_1.resolveCommand)(userText, this._cwd ?? process.cwd());
             // Fold attachments into the prompt as <user-attachment> text blocks under
@@ -713,6 +819,9 @@ class ChatManager {
                     promptForAdapter = `${dashboardContext}\n\n## User turn\n\n${promptForAdapter}`;
                 }
             }
+            const buildRecoveryPrompt = () => buildResumeRecoveryPrompt((0, db_1.getMessages)(this._db, conversationId)
+                .filter((message) => message.id !== persistedUserMessage.id)
+                .map((message) => ({ role: message.role, content: message.content })), promptForAdapter);
             let args = adapter.buildArgs(action, {
                 prompt: promptForAdapter,
                 systemPrompt,
@@ -732,11 +841,18 @@ class ChatManager {
             // not pipeline jobs. Telemetry is scoped to QueueManager pipeline runs only.
             // spawnAiCli reroutes multi-line argv values through stdin on Windows.
             const spawnCwd = this._resolveSpawnCwd(conversation.kind, conversationScope, adapter.id);
-            // Relocate-artifacts env for NON-explore (sidebar) spawns. Explore keeps its
-            // own explore-cwd path (no relocation env — it reaches the repo via the
-            // explore-cwd `./project` link). Legacy ⇒ process.env (byte-identical).
+            // Relocate-artifacts env for gated spawns: NON-explore (sidebar) turns, and
+            // Explore turns with `contextScope.mcp` (they spawn from the workspace when
+            // relocated — see `_resolveSpawnCwd`; the env makes the workspace's
+            // `${SPECRAILS_REPO_DIR:-.}` indirection resolve to the repo). Explore with
+            // mcp=false keeps its explore-cwd path (no relocation env — it reaches the
+            // repo via the explore-cwd `./project` link). Legacy ⇒ process.env
+            // (byte-identical).
             let spawnEnv = process.env;
-            if (conversation.kind !== 'explore') {
+            const exploreMcp = conversation.kind === 'explore' &&
+                !!conversationScope?.mcp &&
+                process.env.SPECRAILS_EXPLORE_LEGACY_CWD !== '1';
+            if (conversation.kind !== 'explore' || exploreMcp) {
                 const exec = this._resolveNonExploreExecution();
                 if (exec?.relocated) {
                     spawnEnv = { ...process.env, ...exec.env };
@@ -744,6 +860,11 @@ class ChatManager {
                         spawnEnv = { ...spawnEnv, GEMINI_CLI_TRUST_WORKSPACE: 'true' };
                 }
             }
+            const allowMissingSessionRecovery = adapter.id === 'claude' &&
+                conversation.kind === 'explore' &&
+                exploreMcp &&
+                spawnCwd !== this._cwd &&
+                spawnEnv.SPECRAILS_WORKSPACE_DIR === spawnCwd;
             // Big bet #3 fast-path: persistent-stdin multi-turn for Explore (claude
             // only, flag-gated default OFF). Reuses a single long-lived child across
             // turns so turns 2+ skip spawn + session rehydration. Full fallback to the
@@ -753,8 +874,9 @@ class ChatManager {
                 adapter.capabilities.persistentStdin === true) {
                 return await this._streamPersistentExploreTurn({
                     conversationId, conversation, adapter, binary, model, systemPrompt,
-                    scopeFlags, spawnCwd, promptForAdapter, isFirstTurn, userText,
-                    lightweight, conversationScope,
+                    scopeFlags, spawnCwd, spawnEnv, promptForAdapter, isFirstTurn, userText,
+                    lightweight, conversationScope, buildRecoveryPrompt,
+                    allowMissingSessionRecovery,
                 });
             }
             const child = this._spawnOwned(binary, args, {
@@ -802,6 +924,7 @@ class ChatManager {
              *  `error`). When set, the turn failed for a concrete reason (usage limit,
              *  auth, model) that a respawn cannot fix — surface it instead of retrying. */
             let capturedErrorMessage = null;
+            let resumeRecoveryAttempted = false;
             const turnStartedAt = new Date().toISOString();
             const stdoutReader = (0, readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
             const emitDelta = (newText) => {
@@ -924,6 +1047,124 @@ class ChatManager {
                     console.log(`[chat-manager] ${adapter.id} exited code=${code} conv=${conversationId}`);
                     const fullText = this._buffers.get(conversationId) ?? '';
                     const wasAborting = this._abortingConversations.has(conversationId);
+                    // A session created before relocated MCP Explore moved from repo cwd to
+                    // workspace cwd cannot be found in Claude's per-cwd session store. This
+                    // is not a generic crash retry: recover ONLY the exact provider
+                    // diagnostic, only before any text/tool side effect, and only once.
+                    const missingPriorSession = allowMissingSessionRecovery &&
+                        action === 'chat-resume' &&
+                        !resumeRecoveryAttempted &&
+                        !wasAborting &&
+                        fullText.length === 0 &&
+                        !adapterEvents.some((event) => event.kind === 'tool-use') &&
+                        (containsMissingClaudeSessionDiagnostic(capturedErrorMessage) ||
+                            containsMissingClaudeSessionDiagnostic(stderrBuf) ||
+                            adapterEvents.some((event) => event.kind === 'result' &&
+                                isMissingClaudeSessionErrorResult(event.payload)));
+                    if (missingPriorSession) {
+                        resumeRecoveryAttempted = true;
+                        // The old id is provably unusable from the corrected cwd. Clearing it
+                        // before the fresh attempt prevents every later turn from paying the
+                        // same failed lookup if this recovery spawn itself cannot complete.
+                        (0, db_1.updateConversation)(this._db, conversationId, { session_id: null });
+                        const recoveryPrompt = buildRecoveryPrompt();
+                        const recoveryArgs = adapter.buildArgs('chat-turn', {
+                            prompt: recoveryPrompt,
+                            systemPrompt,
+                            model,
+                            maxTurns: options?.maxTurns,
+                            extraArgs: scopeFlags,
+                            loadUserEnv: adapter.id === 'claude' && !!conversationScope?.userMcp,
+                        });
+                        console.warn(`[chat-manager] stale Explore session; retrying fresh for ${conversationId}`);
+                        try {
+                            const newChild = this._spawnOwned(binary, recoveryArgs, {
+                                env: spawnEnv,
+                                stdio: ['ignore', 'pipe', 'pipe'],
+                                cwd: spawnCwd,
+                            });
+                            currentChild = newChild;
+                            closeChildren.add(newChild);
+                            args = recoveryArgs;
+                            // The failed lookup reached a terminal result but burned no model
+                            // turn. Keep it visible in analytics, then isolate the fresh turn's
+                            // canonical result/session id from the stale frame.
+                            this._recordChatInvocation({
+                                conversationId,
+                                kind: conversation.kind,
+                                adapter,
+                                events: adapterEvents,
+                                model,
+                                status: 'failed',
+                                startedAt: turnStartedAt,
+                            });
+                            this._buffers.set(conversationId, '');
+                            this._streamFilters.set(conversationId, { inBlock: false, pendingTail: '' });
+                            adapterEvents.length = 0;
+                            capturedSessionId = null;
+                            capturedErrorMessage = null;
+                            sawResult = false;
+                            stderrBuf = '';
+                            // Consume the normal Explore crash budget so a failed fresh retry is
+                            // surfaced rather than replaying the same user turn a third time.
+                            const life = this._exploreLifecycle.get(conversationId);
+                            if (life)
+                                life.crashCount = 1;
+                            this._activeProcesses.set(conversationId, newChild);
+                            newChild.stderr?.on('data', (chunk) => {
+                                if (this._disposed)
+                                    return;
+                                const text = chunk.toString();
+                                stderrBuf += text;
+                                console.error(`[chat-manager] ${binary} stderr (${conversationId}):`, text.trim());
+                            });
+                            newChild.on('error', (err) => {
+                                if (this._disposed) {
+                                    cancelForShutdown();
+                                    return;
+                                }
+                                console.error(`[chat-manager] stale-session recovery spawn failed for ${conversationId}: ${err.message}`);
+                                this._recordChatInvocation({
+                                    conversationId,
+                                    kind: conversation.kind,
+                                    adapter,
+                                    events: adapterEvents,
+                                    model,
+                                    status: 'failed',
+                                    startedAt: turnStartedAt,
+                                });
+                                this._activeProcesses.delete(conversationId);
+                                this._buffers.delete(conversationId);
+                                this._emittedProposals.delete(conversationId);
+                                this._abortingConversations.delete(conversationId);
+                                this._streamFilters.delete(conversationId);
+                                const activeLife = this._exploreLifecycle.get(conversationId);
+                                if (activeLife) {
+                                    activeLife.isStreaming = false;
+                                    activeLife.lastActivityAt = Date.now();
+                                    if (activeLife.isMinimized)
+                                        this._startIdleTimer(conversationId);
+                                }
+                                this._drainExploreQueue();
+                                this._broadcast({
+                                    type: 'chat_error',
+                                    conversationId,
+                                    error: `Failed to launch ${binary}: ${err.message}`,
+                                    timestamp: new Date().toISOString(),
+                                });
+                                complete();
+                            });
+                            const newReader = (0, readline_1.createInterface)({ input: newChild.stdout, crlfDelay: Infinity });
+                            readers.add(newReader);
+                            newReader.on('line', readerHandler);
+                            newChild.on('close', onClose);
+                            return;
+                        }
+                        catch (err) {
+                            console.error('[chat-manager] stale-session recovery spawn failed:', err);
+                            // Fall through and surface the original missing-session error.
+                        }
+                    }
                     // Crash auto-respawn for Explore: if the child exited non-zero before
                     // emitting a `result` event, the user did not explicitly abort, and
                     // we have not yet retried, respawn the same turn once via chat-resume
@@ -931,6 +1172,7 @@ class ChatManager {
                     // See design.md D7.
                     if (conversation.kind === 'explore' &&
                         !wasAborting &&
+                        !resumeRecoveryAttempted &&
                         code !== 0 &&
                         !sawResult &&
                         // A provider-reported failure (usage limit, auth, unsupported model)
@@ -958,7 +1200,7 @@ class ChatManager {
                             console.warn(`[chat-manager] explore crash respawn for ${conversationId}`);
                             try {
                                 const newChild = this._spawnOwned(binary, respawnArgs, {
-                                    env: process.env,
+                                    env: spawnEnv,
                                     stdio: ['ignore', 'pipe', 'pipe'],
                                     cwd: spawnCwd,
                                 });
@@ -1180,7 +1422,7 @@ class ChatManager {
     async _streamPersistentExploreTurn(p) {
         if (this._disposed)
             return;
-        const { conversationId, conversation, adapter, binary, model, systemPrompt, scopeFlags, spawnCwd, promptForAdapter, isFirstTurn, userText, lightweight, conversationScope, } = p;
+        const { conversationId, conversation, adapter, binary, model, systemPrompt, scopeFlags, spawnCwd, spawnEnv, promptForAdapter, isFirstTurn, userText, lightweight, conversationScope, buildRecoveryPrompt, } = p;
         const sessionArgs = adapter.buildArgs('chat-stream', {
             prompt: '',
             systemPrompt,
@@ -1190,7 +1432,7 @@ class ChatManager {
             loadUserEnv: adapter.id === 'claude' && !!conversationScope?.userMcp,
         });
         const { child, isNew } = this._stdinSessions.getOrSpawn(conversationId, {
-            binary, args: sessionArgs, cwd: spawnCwd, env: process.env, spawn: this._spawnOwned.bind(this),
+            binary, args: sessionArgs, cwd: spawnCwd, env: spawnEnv, spawn: this._spawnOwned.bind(this),
         });
         this._trackPersistentProcess(conversationId, child);
         // MED-1: a fresh child restarts claude's session-cumulative counters at 0,
@@ -1344,6 +1586,51 @@ class ChatManager {
             // turn; flip to 'failed' (the cost is still kept — the result carries real
             // usage). Set at result time, read by finishTurn.
             let resultIsError = false;
+            const recoverMissingSession = (diagnostic) => {
+                if (settled ||
+                    !p.allowMissingSessionRecovery ||
+                    !conversation.session_id ||
+                    p.resumeRecoveryAttempted ||
+                    this._abortingConversations.has(conversationId) ||
+                    (this._buffers.get(conversationId) ?? '').length > 0 ||
+                    adapterEvents.some((event) => event.kind === 'tool-use') ||
+                    !(containsMissingClaudeSessionDiagnostic(diagnostic) ||
+                        containsMissingClaudeSessionDiagnostic(stderrBuf))) {
+                    return false;
+                }
+                // The persistent child was launched with the stale --resume before its
+                // first stdin turn. Evict it, but keep the Explore lifecycle slot held
+                // while a brand-new stream child receives the same turn exactly once.
+                settled = true;
+                // Persist the invalidation before replacing the old stream child. A
+                // failed fresh attempt must not leave the known-bad repo-cwd id behind.
+                (0, db_1.updateConversation)(this._db, conversationId, { session_id: null });
+                this._stdinSessions.clearHandlers(conversationId);
+                cleanupTurnState();
+                recordInv('failed');
+                this._stdinSessions.kill(conversationId);
+                console.warn(`[chat-manager] stale persistent Explore session; retrying fresh for ${conversationId}`);
+                void this._streamPersistentExploreTurn({
+                    ...p,
+                    conversation: { ...conversation, session_id: null },
+                    promptForAdapter: buildRecoveryPrompt(),
+                    isFirstTurn: false,
+                    resumeRecoveryAttempted: true,
+                }).then(complete).catch((err) => {
+                    if (!this._disposed) {
+                        console.error(`[chat-manager] persistent stale-session recovery failed for ${conversationId}:`, err);
+                        markStreamingEnded(false);
+                        this._broadcast({
+                            type: 'chat_error',
+                            conversationId,
+                            error: err instanceof Error ? err.message : String(err),
+                            timestamp: new Date().toISOString(),
+                        });
+                    }
+                    complete();
+                });
+                return true;
+            };
             const finishTurn = () => {
                 if (settled)
                     return;
@@ -1410,6 +1697,8 @@ class ChatManager {
                     cancelForShutdown();
                     return;
                 }
+                if (recoverMissingSession(stderrBuf))
+                    return;
                 settled = true;
                 this._stdinSessions.clearHandlers(conversationId);
                 const wasAborting = this._abortingConversations.has(conversationId);
@@ -1449,6 +1738,8 @@ class ChatManager {
                         break;
                     case 'result': {
                         const payload = ev.payload;
+                        if (recoverMissingSession(isMissingClaudeSessionErrorResult(payload) ? payload : null))
+                            break;
                         if (payload.session_id)
                             capturedSessionId = payload.session_id;
                         // LOW-7: detect a failed turn reported through the result frame.

package/server/dist/context-scope.js

@@ -2,12 +2,15 @@
 // Context Scope — per-spec configuration that controls what context is fed
 // into the Add Spec flow (Quick `generate-spec` and Explore chat turns).
 //
-// Four orthogonal toggles:
+// Six orthogonal toggles:
 //   - specrails: concat <project>/.specrails/local-tickets.json (all tickets)
 //                into the system prompt
 //   - openspec:  concat <project>/openspec/specs/**/spec.md into the system prompt
-//   - full:      allow Read/Grep/Glob (Bash is never auto-allowed)
-//   - mcp:       Explore-only — spawn from <project> so .mcp.json is honored
+//   - full:      enable source inspection; with an MCP toggle the high tier
+//                retains Bash/MCP tools while denying GUI file-writer tools
+//   - mcp:       Explore-only — spawn from the relocation-aware artifact cwd so
+//                .mcp.json is honored (workspace when relocated, repo when legacy)
+//   - contractRefine: run the post-commit structural refinement turn
 //   - userMcp:   Explore-only — inject the user's own already-approved MCP
 //                servers (claude: ~/.claude.json user+local scope, fed via
 //                `--mcp-config`; codex: ~/.codex is read natively). Independent