specrails-desktop 2.29.4 → 2.29.5

package/server/dist/contract-refine-runner.js

@@ -5,8 +5,9 @@
  * Standalone runner that spawns a single Claude turn to produce the
  * Contract Layer for a just-committed Explore Spec ticket. Lives outside the
  * ChatManager lifecycle for now (design.md D3 — "thin sibling helper" option):
- * the refine is fire-and-forget, single-attempt, 60 s budget, no idle-kill /
- * crash-respawn semantics.
+ * the refine is fire-and-forget with a 60 s budget per invocation and no
+ * idle-kill / crash-respawn semantics. Only the exact relocated missing-session
+ * diagnostic permits one fresh compatibility retry.
  *
  * See openspec/changes/explore-spec-contract-refine.
  */
@@ -35,6 +36,7 @@ const workspace_resolution_1 = require("./workspace-resolution");
 const process_admission_1 = require("./process-admission");
 const transient_children_1 = require("./transient-children");
 const REFINE_TIMEOUT_MS = 60_000;
+const CLAUDE_MISSING_SESSION_DIAGNOSTIC = 'No conversation found with session ID';
 /**
  * Relocate-artifacts: resolve the ticket store path honouring the gate.
  * Relocated ⇒ the registry entry's tickets path (workspace); legacy ⇒
@@ -83,6 +85,46 @@ function buildRefineArgs(model, systemPrompt, sessionId) {
         '-p', explore_contract_refine_1.CONTRACT_MARKER_USER_MESSAGE,
     ];
 }
+/** Build the pure-output, no-resume invocation used by Quick Refine and by the
+ * one-time compatibility recovery for cwd-scoped Explore sessions. */
+function buildFreshRefineArgs(model, title, description) {
+    const systemPrompt = [
+        (0, explore_contract_refine_1.buildContractRefineSystemPrompt)(),
+        '',
+        '## Spec under refinement',
+        '',
+        '### Title',
+        title,
+        '',
+        '### Description',
+        description,
+    ].join('\n');
+    return [
+        '--model', model,
+        '--tools', '__none__',
+        '--output-format', 'stream-json',
+        '--verbose',
+        '--system-prompt', systemPrompt,
+        '--max-turns', '1',
+        '-p', explore_contract_refine_1.CONTRACT_MARKER_USER_MESSAGE,
+    ];
+}
+/** Match only Claude's missing cwd-scoped session diagnostic. The CLI has
+ * emitted it both as stderr and inside structured result payloads, so inspect
+ * all captured provider output while keeping unrelated failures ineligible. */
+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;
+    }
+}
 /**
  * Build the spawn argv + cwd for the refine turn. Exported for tests.
  */
@@ -103,19 +145,26 @@ function prepareContractRefineSpawn(deps, conversation) {
     // different per-cwd session store and fails with "No conversation found with
     // session ID …" (the Desktop-tier bug). chat-manager `_resolveSpawnCwd` for an
     // Explore turn uses:
-    //   - mcp ON  → `project.path` (NOT the relocated workspace),
+    //   - mcp ON  → the relocate-artifacts gate (workspace when relocated, else
+    //     `project.path`); `SPECRAILS_EXPLORE_LEGACY_CWD=1` forces `project.path`,
     //   - mcp OFF → the app-managed explore-cwd.
     // We mirror that EXACTLY here. The refine uses no tools (`--tools __none__`)
     // and its prompt rides on `--system-prompt`, so it needs
-    // neither the workspace's `.mcp.json` nor its `.claude/commands`. Env still
-    // carries SPECRAILS_REPO_DIR when relocated (harmless; no tools consume it).
+    // neither the workspace's `.mcp.json` nor its `.claude/commands`. The env is
+    // mirrored too so the legacy-cwd escape hatch remains byte-identical.
     const exec = (0, workspace_resolution_1.resolveProjectExecution)({ slug: deps.projectSlug, path: deps.projectPath });
-    let env = exec.relocated ? { ...process.env, ...exec.env } : undefined;
+    let env;
     let cwd;
     if (mcpEnabled) {
-        // Match the Explore mcp-on spawn cwd (`this._cwd` = project.path), even when
-        // relocated (where exec.cwd would be the workspace ≠ project.path).
-        cwd = deps.projectPath;
+        // Match the Explore mcp-on spawn cwd through the same gate + escape hatch.
+        if (process.env.SPECRAILS_EXPLORE_LEGACY_CWD === '1') {
+            cwd = deps.projectPath;
+        }
+        else {
+            cwd = exec.cwd;
+            if (exec.relocated)
+                env = { ...process.env, ...exec.env };
+        }
     }
     else {
         try {
@@ -126,7 +175,9 @@ function prepareContractRefineSpawn(deps, conversation) {
             });
         }
         catch {
-            cwd = exec.cwd;
+            // Match ChatManager's fail-closed fallback for an unavailable
+            // app-managed Explore cwd.
+            cwd = deps.projectPath;
         }
     }
     const args = buildRefineArgs(conversation.model ?? 'sonnet', systemPrompt, conversation.session_id ?? '');
@@ -280,7 +331,8 @@ function applyContractLayerToTicket(filePath, ticketId, layer, nowIso) {
     return updated;
 }
 /**
- * Fire a single Contract Refine attempt for the given conversation + ticket.
+ * Run Contract Refine for the given conversation + ticket (normally one
+ * invocation; at most two for the narrow missing-session compatibility path).
  *
  * Returns a Promise that resolves with the outcome. Side effects:
  *  - On success: patches the ticket's description, broadcasts `ticket_updated`
@@ -353,59 +405,97 @@ async function runContractRefine(deps, conversationId, ticketId) {
     const startedAt = now().toISOString();
     // Spawn/stream/timeout/settlement is owned by the shared spawn-lifecycle; the
     // contract-refine-specific raw parse (fullText from assistant text blocks,
-    // the raw result event) and ALL finalize/record/broadcast logic stay here,
-    // byte-for-byte, so behaviour is unchanged (it still records via the legacy
-    // recordSafely path).
-    let fullText = '';
-    let resultEvent = null;
-    const run = await (0, spawn_lifecycle_1.runAiCliInvocation)({
-        adapter: (0, registry_1.getAdapter)('claude'),
-        binary: 'claude',
-        argv: args,
-        cwd,
-        env: refineEnv ?? process.env,
-        spawn,
-        timeoutMs,
-        onSpawn: (child) => (0, transient_children_1.trackTransientChild)(deps.projectId, child),
-        onStdoutLine: (line) => {
-            let parsed = null;
-            try {
-                parsed = JSON.parse(line);
-            }
-            catch {
-                return;
-            }
-            if (!parsed)
-                return;
-            const type = parsed.type;
-            if (type === 'result') {
-                resultEvent = parsed;
-            }
-            else if (type === 'assistant') {
-                const message = parsed.message;
-                for (const b of (message?.content ?? [])) {
-                    if (b.type === 'text' && typeof b.text === 'string')
-                        fullText += b.text;
+    // the raw result event) and all finalize/record/broadcast logic stay here.
+    // Keeping the invocation result in one shape also lets the narrowly-gated
+    // missing-session recovery re-enter the exact same finalization path.
+    const invoke = async (invocationArgs) => {
+        let fullText = '';
+        let resultEvent = null;
+        const run = await (0, spawn_lifecycle_1.runAiCliInvocation)({
+            adapter: (0, registry_1.getAdapter)('claude'),
+            binary: 'claude',
+            argv: invocationArgs,
+            cwd,
+            env: refineEnv ?? process.env,
+            spawn,
+            timeoutMs,
+            onSpawn: (child) => (0, transient_children_1.trackTransientChild)(deps.projectId, child),
+            onStdoutLine: (line) => {
+                let parsed = null;
+                try {
+                    parsed = JSON.parse(line);
                 }
-            }
-        },
-    });
+                catch {
+                    return;
+                }
+                if (!parsed)
+                    return;
+                const type = parsed.type;
+                if (type === 'result') {
+                    resultEvent = parsed;
+                }
+                else if (type === 'assistant') {
+                    const message = parsed.message;
+                    for (const b of (message?.content ?? [])) {
+                        if (b.type === 'text' && typeof b.text === 'string')
+                            fullText += b.text;
+                    }
+                }
+            },
+        });
+        return {
+            fullText,
+            resultEvent,
+            code: run.code,
+            timedOut: run.timedOut,
+            spawnFailed: run.spawnFailed,
+            stderrTail: run.stderrTail,
+        };
+    };
+    let result = await invoke(args);
     if (!admission.isCurrent()) {
         return { ok: false, reason: 'aborted', ticketId, conversationId };
     }
-    if (run.spawnFailed) {
-        recordSafely(deps, conversationId, ticketId, conversation.model, startedAt, now().toISOString(), 'failed', null);
+    // A pre-relocation Explore session was created under the repo cwd and cannot
+    // be resumed after the corrected mcp=true route moves to the workspace.
+    // Recover only that exact provider failure, once, and never by returning to
+    // the repo. The fresh turn is explicitly seeded because it has no resumed
+    // conversation context.
+    const resumedFromRelocatedWorkspace = refineEnv?.SPECRAILS_WORKSPACE_DIR === cwd && cwd !== deps.projectPath;
+    const resumeFailed = !result.spawnFailed &&
+        !result.timedOut &&
+        (result.code !== 0 || !result.resultEvent || isResultErrorEvent(result.resultEvent));
+    const missingSessionDiagnostic = containsMissingClaudeSessionDiagnostic(result.fullText) ||
+        containsMissingClaudeSessionDiagnostic(result.resultEvent) ||
+        containsMissingClaudeSessionDiagnostic(result.stderrTail);
+    if (resumedFromRelocatedWorkspace && resumeFailed && missingSessionDiagnostic) {
+        let ticket = null;
+        try {
+            ticket = (0, ticket_store_1.readStore)(resolveContractTicketsPath(deps.projectPath)).tickets[String(ticketId)] ?? null;
+        }
+        catch (err) {
+            console.error('[contract-refine-runner] unable to read ticket for missing-session recovery:', err);
+        }
+        if (ticket) {
+            console.warn(`[contract-refine-runner] resume session unavailable; retrying once fresh from workspace ticket=${ticketId}`);
+            result = await invoke(buildFreshRefineArgs(conversation.model ?? 'sonnet', ticket.title, ticket.description));
+            if (!admission.isCurrent()) {
+                return { ok: false, reason: 'aborted', ticketId, conversationId };
+            }
+        }
+    }
+    const finishedAt = now().toISOString();
+    if (result.spawnFailed) {
+        recordSafely(deps, conversationId, ticketId, conversation.model, startedAt, finishedAt, 'failed', null);
         deps.broadcast({
             type: 'explore.contract_refine_failed',
             projectId: deps.projectId,
             ticketId,
             reason: 'crashed',
-            timestamp: now().toISOString(),
+            timestamp: finishedAt,
         });
         return { ok: false, reason: 'crashed', ticketId, conversationId };
     }
-    const result = { fullText, resultEvent, code: run.code, timedOut: run.timedOut };
-    const finishedAt = now().toISOString();
     console.log(`[contract-refine-runner] spawn done code=${result.code} timedOut=${result.timedOut} hasResult=${!!result.resultEvent} textBytes=${result.fullText.length}`);
     if (result.timedOut) {
         recordSafely(deps, conversationId, ticketId, conversation.model, startedAt, finishedAt, 'aborted', result.resultEvent);
@@ -515,26 +605,7 @@ async function runContractRefineForQuick(deps, ticketId, generatedTitle, generat
         return { ok: false, reason: 'disabled', ticketId, conversationId: '' };
     }
     const admission = (0, process_admission_1.captureProcessAdmission)(deps.projectId);
-    const systemPrompt = [
-        (0, explore_contract_refine_1.buildContractRefineSystemPrompt)(),
-        '',
-        '## Spec under refinement',
-        '',
-        `### Title`,
-        generatedTitle,
-        '',
-        `### Description`,
-        generatedDescription,
-    ].join('\n');
-    const args = [
-        '--model', model ?? 'sonnet',
-        '--tools', '__none__',
-        '--output-format', 'stream-json',
-        '--verbose',
-        '--system-prompt', systemPrompt,
-        '--max-turns', '1',
-        '-p', explore_contract_refine_1.CONTRACT_MARKER_USER_MESSAGE,
-    ];
+    const args = buildFreshRefineArgs(model ?? 'sonnet', generatedTitle, generatedDescription);
     const startedAt = now().toISOString();
     deps.broadcast({
         type: 'explore.contract_refine_started',

package/server/dist/rail-isolated-launch.js

@@ -408,10 +408,18 @@ async function launchIsolatedRail(input, io = {}) {
     // overlay their repo's own untracked on-disk entries instead. Resolved ONCE
     // per launch; a resolution failure degrades to the legacy (repo) source.
     let overlaySourceRoot = baseRepo;
+    let overlayFallbackRoots;
     try {
         const exec = resolveExecution({ slug, path: baseRepo });
-        if (exec.relocated && exec.workspaceDir)
+        if (exec.relocated && exec.workspaceDir) {
             overlaySourceRoot = exec.workspaceDir;
+            // The repo as FALLBACK root: repo-resident untracked carve-outs
+            // (OpenSpec's `/opsx:*` commands, `openspec-*` skills, user extras)
+            // are absent from both the checkout (untracked) and the workspace
+            // (the framework ships only `specrails/`), so without this the claude
+            // CLI reports `Unknown command: /opsx:ff` inside isolated rails.
+            overlayFallbackRoots = [baseRepo];
+        }
     }
     catch { /* legacy fallback */ }
     let overlayProviderDir = '.claude';
@@ -668,6 +676,7 @@ async function launchIsolatedRail(input, io = {}) {
                             const res = overlay({
                                 worktreePath: handle.worktreePath,
                                 sourceRoot: overlaySourceRoot,
+                                fallbackSourceRoots: overlayFallbackRoots,
                                 providerDir: overlayProviderDir,
                                 instructionsFilename: overlayInstructions,
                             });
@@ -847,6 +856,7 @@ async function launchIsolatedRail(input, io = {}) {
             a.overlayCleanupEvidence = (0, worktree_overlay_1.revalidateOverlayCleanupEvidence)({
                 worktreePath: a.handle.worktreePath,
                 sourceRoot: overlaySourceRoot,
+                fallbackSourceRoots: overlayFallbackRoots,
                 providerDir: overlayProviderDir,
                 instructionsFilename: overlayInstructions,
             }, a.overlayCleanupEvidence);

package/server/dist/workspace-manager.js

@@ -99,7 +99,9 @@ function ensureFrameworkAgents(workspaceDir, providerDir, home) {
 }
 /** The framework subtrees `assemble` installs as a single DIR-symlink into
  *  `current/<provider>/` (unlike agents, which are per-file). `/specrails:*`
- *  and `/opsx:*` slash commands live under `commands/`. */
+ *  slash commands live under `commands/`. (`/opsx:*` is NOT framework — the
+ *  external OpenSpec binary installs it into the REPO's provider dir; isolated
+ *  rails receive it via the worktree overlay's repo fallback root.) */
 const DIR_LINKED_SUBTREES = ['commands', 'skills', 'rules'];
 /**
  * Windows repair for the DIR-symlinked framework subtrees (`commands`, `skills`,