specrails-desktop 2.36.0 → 2.42.2

package/server/dist/loop-executors.js

@@ -1,7 +1,4 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createLoopExecutors = createLoopExecutors;
 /**
@@ -12,45 +9,62 @@ exports.createLoopExecutors = createLoopExecutors;
  * from coverage; the engine's traversal/decision logic is unit-tested against
  * fake executors in `loop-run-manager.test.ts`.
  */
+const core_execution_1 = require("./core-execution");
+const codex_spawn_1 = require("./plugins/codex-spawn");
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
-const tree_kill_1 = __importDefault(require("tree-kill"));
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const win_spawn_1 = require("./util/win-spawn");
 const providers_1 = require("./providers");
 const workspace_manager_1 = require("./workspace-manager");
 const claude_trust_1 = require("./claude-trust");
 const spawn_lifecycle_1 = require("./spawn-lifecycle");
 const result_event_1 = require("./result-event");
+const terminal_result_1 = require("./providers/terminal-result");
+const claude_background_tasks_1 = require("./providers/claude-background-tasks");
+const loop_constants_1 = require("./loop-constants");
 const loop_decider_1 = require("./loop-decider");
 const rail_isolation_1 = require("./rail-isolation");
 const repo_map_1 = require("./repo-map");
 const feature_flags_1 = require("./feature-flags");
+const loop_step_idle_1 = require("./loop-step-idle");
 const runtime_1 = require("./providers/runtime");
+const loop_shell_invocation_1 = require("./loop-shell-invocation");
 // Per-step wall-clock caps so a single hung step can't block the engine's
 // overall deadline check (which only runs between nodes).
 const AI_STEP_TIMEOUT_MS = 15 * 60_000;
 const DECIDER_TIMEOUT_MS = 3 * 60_000;
 const SHELL_TIMEOUT_MS = 10 * 60_000;
 const SHELL_OUTPUT_CAP = 256 * 1024;
+// Match the queue's idle budget: a long implementation may keep running while
+// producing output; a silent, wedged CLI must eventually release its rail.
+const DEFAULT_INACTIVITY_TIMEOUT_MS = 30 * 60_000;
 function runShellCommand(command, cwd, env, timeoutMs, onLine, onSpawn) {
     return new Promise((resolve) => {
         const isWin = process.platform === 'win32';
-        const shell = isWin ? process.env.ComSpec || 'cmd.exe' : '/bin/sh';
-        const args = isWin ? ['/d', '/s', '/c', command] : ['-c', command];
+        const shellEnv = isWin ? (0, win_spawn_1.windowsSpawnEnv)(env) : env;
         const start = Date.now();
         let stdout = '';
         let stderr = '';
         let settled = false;
         let child;
         try {
-            child = (0, node_child_process_1.spawn)(shell, args, {
+            const bundled = (0, loop_shell_invocation_1.bundledLoopShellInvocation)(command);
+            const options = {
                 cwd,
-                env,
+                env: shellEnv,
                 stdio: ['ignore', 'pipe', 'pipe'],
-                windowsVerbatimArguments: isWin,
-            });
+                windowsHide: true,
+            };
+            // Node wraps /d /s /c with the required outer quotes. Passing a raw
+            // command ourselves with verbatim argv loses the first executable's quotes.
+            child = bundled ? (0, node_child_process_1.spawn)(bundled.binary, bundled.args, options) : isWin
+                ? (0, node_child_process_1.spawn)(command, { ...options, shell: shellEnv.ComSpec || 'cmd.exe' })
+                : (0, node_child_process_1.spawn)('/bin/sh', ['-c', command], options);
         }
-        catch {
-            resolve({ stdout: '', stderr: 'failed to spawn shell', exitCode: -1, durationMs: 0 });
+        catch (error) {
+            resolve({ stdout: '', stderr: `failed to spawn shell: ${error instanceof Error ? error.message : String(error)}`, exitCode: -1, durationMs: 0 });
             return;
         }
         onSpawn?.(child);
@@ -64,7 +78,7 @@ function runShellCommand(command, cwd, env, timeoutMs, onLine, onSpawn) {
         const timer = setTimeout(() => {
             if (child.pid) {
                 try {
-                    (0, tree_kill_1.default)(child.pid, 'SIGKILL', () => { });
+                    (0, win_spawn_1.treeKillSafe)(child.pid, 'SIGKILL', () => { });
                 }
                 catch { /* gone */ }
             }
@@ -94,12 +108,12 @@ function runShellCommand(command, cwd, env, timeoutMs, onLine, onSpawn) {
  * app's own draft-PR delivery. Default ON (flag=0/false/off disables). See
  * rail-isolation + the specrails-core SPECRAILS_GIT_AUTO contract.
  */
-function aiStepEnv(env, repoDir) {
-    const base = repoDir ? { ...env, SPECRAILS_REPO_DIR: repoDir } : env;
+function aiStepEnv(env, repoDir, manifest) {
+    const base = { ...env, ...(repoDir ? { SPECRAILS_REPO_DIR: repoDir } : {}), ...(manifest ? { SPECRAILS_EXECUTION_MANIFEST: JSON.stringify(manifest), SPECRAILS_REPOSITORIES: JSON.stringify(manifest.repositories.map((repo) => ({ id: repo.repositoryId, name: repo.name, path: repo.worktreePath }))) } : {}) };
     // Deterministic repo map (zero-AI) so the pipeline's exploration phase
     // starts oriented instead of spending its first turns on `ls`/`find`.
     const withMap = (0, repo_map_1.injectRepoMapEnv)(base, repoDir);
-    return (0, rail_isolation_1.isRailPrDeliveryEnabled)() ? { ...withMap, SPECRAILS_GIT_AUTO: 'false' } : withMap;
+    return manifest || (0, rail_isolation_1.isRailPrDeliveryEnabled)() ? { ...withMap, SPECRAILS_GIT_AUTO: 'false' } : withMap;
 }
 /**
  * Relocated cwd is the workspace; the source repo is reached via the
@@ -113,27 +127,45 @@ function aiStepEnv(env, repoDir) {
  *    (and cwd, defensively) to codex's sandbox writable_roots. Harmless
  *    no-op under danger-full-access on iteration 1.
  */
-function aiStepExtraArgs(adapter, cwd, repoDir) {
+function aiStepExtraArgs(adapter, cwd, repoDir, manifest) {
     if (!repoDir)
         return undefined;
-    const args = (0, runtime_1.buildProviderRepoAccessArgs)(adapter, [repoDir, ...(adapter.id === 'codex' ? [cwd] : [])]);
+    const args = (0, runtime_1.buildProviderRepoAccessArgs)(adapter, [...new Set([repoDir, ...(manifest?.repositories.map((repo) => repo.worktreePath) ?? []), ...(adapter.id === 'codex' ? [cwd] : [])])]);
     return args.length > 0 ? args : undefined;
 }
 function createLoopExecutors(opts = {}) {
     const resolveEnv = () => typeof opts.env === 'function' ? opts.env() : opts.env ?? process.env;
+    const inactivityTimeoutMs = () => {
+        const env = resolveEnv();
+        const configuredIdle = env.SPECRAILS_LOOP_STEP_IDLE_TIMEOUT_MS ?? process.env.SPECRAILS_LOOP_STEP_IDLE_TIMEOUT_MS;
+        if (configuredIdle != null)
+            return (0, loop_step_idle_1.resolveLoopStepIdleTimeoutMs)({ ...env, SPECRAILS_LOOP_STEP_IDLE_TIMEOUT_MS: configuredIdle });
+        const raw = env.SPECRAILS_LOOP_INACTIVITY_MS ?? process.env.SPECRAILS_LOOP_INACTIVITY_MS;
+        const value = raw?.trim() ? Number(raw) : DEFAULT_INACTIVITY_TIMEOUT_MS;
+        return Number.isFinite(value) && value >= 0 ? value : DEFAULT_INACTIVITY_TIMEOUT_MS;
+    };
     // Deciders deliberately excluded: they run no pipeline agents.
-    const withProfileEnv = (env, provider) => {
+    const withProfileEnv = (env, provider, profileName) => {
+        if (profileName === null) {
+            const legacyEnv = { ...env };
+            delete legacyEnv.SPECRAILS_PROFILE_PATH;
+            return legacyEnv;
+        }
         try {
-            const profilePath = opts.profilePathFor?.(provider) ?? null;
+            const profilePath = opts.profilePathFor?.(provider, profileName) ?? null;
             return profilePath ? { ...env, SPECRAILS_PROFILE_PATH: profilePath } : env;
         }
-        catch {
+        catch (error) {
+            if (profileName)
+                throw error;
             return env;
         }
     };
     return {
         // Cheap working-tree fingerprint for the engine's non-convergence guard:
-        // HEAD sha + the porcelain dirty set, hashed. Two identical fingerprints
+        // HEAD, tracked diffs and untracked file contents, hashed. Status/path names
+        // alone stay identical while a fixer keeps improving the same files.
+        // Two identical fingerprints
         // across consecutive Decider 'continue' verdicts ⇒ the loop changed nothing
         // ⇒ abort `stalled`. Synchronous + best-effort: any git failure (no repo,
         // detached, etc.) returns null so the guard simply stays off. Never throws.
@@ -144,13 +176,34 @@ function createLoopExecutors(opts = {}) {
                 // `-z` NUL-delimited + include untracked so a brand-new file counts as
                 // a change; stable ordering makes the hash deterministic per tree state.
                 const porcelain = (0, node_child_process_1.execFileSync)('git', ['status', '--porcelain', '-z', '--untracked-files=all'], opt);
-                return (0, node_crypto_1.createHash)('sha256').update(head).update('\0').update(porcelain).digest('hex');
+                const hash = (0, node_crypto_1.createHash)('sha256').update(head).update('\0').update(porcelain);
+                // Separate index/worktree diffs preserve staged-only changes and staged
+                // content subsequently edited back to HEAD. Binary patches include
+                // actual bytes; disable external diff/textconv so this is read-only.
+                for (const args of [
+                    ['diff', '--no-ext-diff', '--no-textconv', '--binary', '--'],
+                    ['diff', '--cached', '--no-ext-diff', '--no-textconv', '--binary', '--'],
+                ])
+                    hash.update('\0').update((0, node_child_process_1.execFileSync)('git', args, { ...opt, maxBuffer: 16 * 1024 * 1024 }));
+                const untracked = (0, node_child_process_1.execFileSync)('git', ['ls-files', '--others', '--exclude-standard', '-z'], opt);
+                for (const relative of untracked.split('\0').filter(Boolean).sort()) {
+                    const file = (0, node_path_1.resolve)(dir, relative);
+                    const stat = (0, node_fs_1.lstatSync)(file);
+                    hash.update('\0').update(relative).update('\0').update(String(stat.mode));
+                    // Never follow a symlink outside the worktree. If an unreadable file
+                    // or a racing delete defeats the snapshot, disable this sample.
+                    if (stat.isSymbolicLink())
+                        hash.update((0, node_fs_1.readlinkSync)(file));
+                    else if (stat.isFile())
+                        hash.update((0, node_fs_1.readFileSync)(file));
+                }
+                return hash.digest('hex');
             }
             catch {
                 return null;
             }
         },
-        async runAiStep({ prompt, sessionId, provider, model, effort, cwd, repoDir, onLine, onRawLine, onSpawn, aiStepTimeoutMs }) {
+        async runAiStep({ coreRun, prompt, sessionId, provider, model, effort, profileName, cwd, repoDir, executionManifest, onLine, onRawLine, onSpawn, aiStepTimeoutMs, idleTimeoutMs }) {
             const adapter = (0, providers_1.getAdapter)(provider);
             // First iteration spawns headless (rail-job); subsequent iterations resume
             // the session so the agent keeps prior context across iterations.
@@ -160,14 +213,22 @@ function createLoopExecutors(opts = {}) {
             // for the pipeline's I/O exactly like QueueManager: SPECRAILS_REPO_DIR +
             // claude `--add-dir <repoDir>` (see the shared helpers above). Best-effort
             // agent self-heal on Windows.
-            const stepEnv = withProfileEnv(aiStepEnv(resolveEnv(), repoDir), provider);
-            const extraArgs = aiStepExtraArgs(adapter, cwd, repoDir);
-            const effectivePrompt = (0, runtime_1.formatProviderCommand)(adapter, prompt, cwd, sessionId ?? undefined);
+            const baseStepEnv = withProfileEnv(aiStepEnv(resolveEnv(), repoDir, executionManifest), provider, profileName);
+            const core = coreRun ? (0, core_execution_1.prepareCoreExecution)({ run: coreRun, cwd, repoDir, manifest: executionManifest, env: baseStepEnv }) : undefined;
+            const stepEnv = core?.env ?? baseStepEnv;
+            let extraArgs = aiStepExtraArgs(adapter, cwd, repoDir, executionManifest);
+            const pluginScope = adapter.id === 'codex' ? opts.pluginScope?.() : undefined;
+            const pluginArgs = (0, codex_spawn_1.buildCodexPluginArgs)({ providerId: adapter.id, stateRoot: pluginScope?.stateRoot ?? stepEnv.SPECRAILS_WORKSPACE_DIR ?? cwd, repositoryPath: repoDir ?? cwd, legacyProviderId: pluginScope?.legacyProviderId });
+            if (pluginArgs.length)
+                extraArgs = [...(extraArgs ?? []), ...pluginArgs];
+            const effectivePrompt = (0, runtime_1.formatProviderCommand)(adapter, [core?.promptPrefix, prompt].filter(Boolean).join('\n\n'), cwd, sessionId ?? undefined);
             const buildOpts = {
                 prompt: effectivePrompt,
+                ...(adapter.id === 'claude' ? { systemPrompt: loop_constants_1.FOREGROUND_RULE } : {}),
                 model,
                 sessionId: sessionId ?? undefined,
                 reasoning_effort: effort,
+                ...(executionManifest ? { scopedWorkingDirectories: true } : {}),
                 extraArgs,
             };
             if (repoDir) {
@@ -180,15 +241,32 @@ function createLoopExecutors(opts = {}) {
             // Pre-trust the spawn dir so headless claude honours the overlaid
             // `.claude/settings.json` permissions.allow (else "workspace not trusted").
             try {
-                (0, claude_trust_1.ensureClaudeTrusted)(adapter.id, [cwd, repoDir]);
+                (0, claude_trust_1.ensureClaudeTrusted)(adapter.id, [cwd, repoDir, ...(executionManifest?.repositories.map((repo) => repo.worktreePath) ?? [])]);
             }
             catch { /* best-effort */ }
+            // Gemini acknowledges project agents before headless execution. Rails
+            // using the loop engine need the same adapter preparation as queue jobs.
+            try {
+                adapter.prepareHeadlessSpawn?.(cwd);
+            }
+            catch (err) {
+                console.warn(`[loop] provider preparation failed: ${err.message}`);
+            }
             let text = '';
             // The adapter parses provider failures (codex `turn.failed`, etc.) into a
             // structured `error` event on the stdout stream — capture its message so we
             // surface the REAL reason (e.g. "You've hit your usage limit") instead of
             // the `stderrTail`, which often holds only an informational line.
             let errorText;
+            // Idle watchdog (loop-step-idle): the child produced NO stdout/stderr for
+            // the idle budget — a wedge, not a slow step. Flagged separately from the
+            // wall-clock timeout so the engine can retry the step once by resume.
+            let stalled = false;
+            // The provider flagged the final `result` as an error (claude
+            // `is_error: true` — a usage/rate-limit notice returned AS the reply).
+            let resultIsError = false;
+            let liveBackgroundTasks = [];
+            const effectiveIdleTimeoutMs = idleTimeoutMs ?? inactivityTimeoutMs();
             const wallStartedAt = Date.now();
             const res = await (0, spawn_lifecycle_1.runAiCliInvocation)({
                 adapter,
@@ -199,13 +277,25 @@ function createLoopExecutors(opts = {}) {
                 // 0 ⇒ watchdog disabled (factory loops run untimed; the loop's
                 // maxIterations / cost cap remain the runaway guards).
                 timeoutMs: (aiStepTimeoutMs ?? AI_STEP_TIMEOUT_MS) > 0 ? (aiStepTimeoutMs ?? AI_STEP_TIMEOUT_MS) : undefined,
+                // The engine's explicit bound wins, including 0. Direct callers retain
+                // the existing env-resolved watchdog when no bound was supplied.
+                inactivityTimeoutMs: effectiveIdleTimeoutMs > 0 ? effectiveIdleTimeoutMs : undefined,
+                onInactivityTimeout: () => { stalled = true; },
                 onSpawn,
                 // Two complementary streams, mirroring QueueManager's contract:
                 //  • RAW JSONL via onStdoutLine → engine emits parsed `event`s that drive
                 //    JobStatusPanel activity (LogViewer SKIPS these to avoid dupes).
                 //  • display text/tools via onEvent → engine emits `log` lines that
                 //    LogViewer actually RENDERS (the visible transcript).
-                onStdoutLine: onRawLine,
+                onStdoutLine: (line) => {
+                    if (adapter.id === 'claude') {
+                        try {
+                            liveBackgroundTasks = (0, claude_background_tasks_1.readClaudeBackgroundTasks)(JSON.parse(line)) ?? liveBackgroundTasks;
+                        }
+                        catch { /* ordinary output */ }
+                    }
+                    onRawLine?.(line);
+                },
                 onEvent: (ev) => {
                     if (ev.kind === 'text-delta') {
                         text += ev.text;
@@ -215,18 +305,39 @@ function createLoopExecutors(opts = {}) {
                         onLine?.(`🔧 ${ev.name} ${ev.inputPreview ?? ''}`.trim());
                     else if (ev.kind === 'error' && ev.message)
                         errorText = ev.message;
+                    else if (ev.kind === 'result') {
+                        const terminalError = (0, terminal_result_1.terminalResultError)(ev.payload);
+                        errorText = terminalError ?? errorText;
+                        if (ev.isError || terminalError)
+                            resultIsError = true;
+                    }
                 },
             });
+            // The kill-switch one-shot transport cannot continue a resident parent.
+            // Never certify a clean CLI exit as completed work if its workers were
+            // still pending. Interactive mode can join them in the same session.
+            if (liveBackgroundTasks.length > 0 && !errorText) {
+                errorText = `Agent exited with ${liveBackgroundTasks.length} unfinished background task(s); implementation step is incomplete.`;
+            }
             const failed = res.spawnFailed ||
                 res.timedOut ||
-                (res.code != null && res.code !== 0) ||
-                errorText !== undefined;
+                res.code !== 0 ||
+                errorText !== undefined ||
+                resultIsError;
             if (res.spawnFailed) {
                 errorText = errorText ?? `failed to spawn "${adapter.binary}" (on PATH?)`;
                 const msg = `AI step: ${errorText}`;
                 console.error(`[loop] ${msg}`);
                 onLine?.(msg, 'stderr');
             }
+            else if (stalled) {
+                // The inactivity watchdog tore the child down (settles timedOut too, so
+                // this branch must precede the wall-clock one). The engine retries once.
+                errorText = loop_step_idle_1.AI_STEP_STALLED_ERROR;
+                const msg = `AI step: ${adapter.binary} produced no output for ${Math.round(effectiveIdleTimeoutMs / 1000)}s — stalled`;
+                console.error(`[loop] ${msg}`);
+                onLine?.(msg, 'stderr');
+            }
             else if (res.timedOut) {
                 // A wedged/unresponsive provider settles with code=null + timedOut. Count
                 // it as a failure so the engine's fail-fast can bail instead of paying the
@@ -236,11 +347,20 @@ function createLoopExecutors(opts = {}) {
                 console.error(`[loop] ${msg}`);
                 onLine?.(msg, 'stderr');
             }
-            else if (res.code != null && res.code !== 0) {
+            else if (resultIsError) {
+                // The provider returned an error AS the reply (claude `is_error: true`
+                // — typically a usage/rate-limit notice). The text IS the reason.
+                errorText = errorText ?? (text.trim().slice(-300) || 'the provider returned an error result');
+                const msg = `AI step: provider returned an error result — ${errorText}`;
+                console.error(`[loop] ${msg}`);
+                onLine?.(msg, 'stderr');
+            }
+            else if (res.code !== 0) {
                 // Prefer the adapter's structured error (e.g. codex `turn.failed`:
                 // "You've hit your usage limit") over `stderrTail`, which for codex holds
                 // only the informational "Reading additional input from stdin…" line.
                 const reason = errorText ?? (res.stderrTail ? res.stderrTail.slice(0, 300) : '');
+                errorText = reason || `${adapter.binary} terminated without a successful exit (code=${res.code})`;
                 const msg = `AI step: ${adapter.binary} exited code=${res.code}${reason ? ` — ${reason}` : ''}`;
                 console.error(`[loop] ${msg}`);
                 onLine?.(msg, 'stderr');
@@ -286,6 +406,8 @@ function createLoopExecutors(opts = {}) {
                 estimated,
                 failed,
                 errorText,
+                ...(stalled ? { stalled: true } : {}),
+                ...(resultIsError ? { resultIsError: true } : {}),
             };
         },
         /**
@@ -298,14 +420,16 @@ function createLoopExecutors(opts = {}) {
          * spike-verified on claude 2.1.198). Null ⇒ the engine one-shots the step
          * (non-claude providers, or the kill-switch) — byte-identical legacy.
          */
-        planInteractiveAiStep({ provider, model, effort, cwd, repoDir, sessionId, aiStepTimeoutMs }) {
+        planInteractiveAiStep({ coreRun, provider, model, effort, profileName, cwd, repoDir, executionManifest, sessionId, aiStepTimeoutMs, idleTimeoutMs }) {
             if (!(0, feature_flags_1.isInteractiveJobsEnabled)())
                 return null;
             const adapter = (0, providers_1.getAdapter)(provider);
             if (!adapter.capabilities.persistentStdin)
                 return null;
-            const stepEnv = withProfileEnv(aiStepEnv(resolveEnv(), repoDir), provider);
-            const extraArgs = aiStepExtraArgs(adapter, cwd, repoDir);
+            const baseStepEnv = withProfileEnv(aiStepEnv(resolveEnv(), repoDir, executionManifest), provider, profileName);
+            const core = coreRun ? (0, core_execution_1.prepareCoreExecution)({ run: coreRun, cwd, repoDir, manifest: executionManifest, env: baseStepEnv }) : undefined;
+            const stepEnv = core?.env ?? baseStepEnv;
+            const extraArgs = aiStepExtraArgs(adapter, cwd, repoDir, executionManifest);
             if (repoDir) {
                 try {
                     (0, workspace_manager_1.ensureFrameworkAgents)(cwd, adapter.projectDirName);
@@ -316,9 +440,15 @@ function createLoopExecutors(opts = {}) {
             // Pre-trust the spawn dir so headless claude honours the overlaid
             // `.claude/settings.json` permissions.allow (else "workspace not trusted").
             try {
-                (0, claude_trust_1.ensureClaudeTrusted)(adapter.id, [cwd, repoDir]);
+                (0, claude_trust_1.ensureClaudeTrusted)(adapter.id, [cwd, repoDir, ...(executionManifest?.repositories.map((repo) => repo.worktreePath) ?? [])]);
             }
             catch { /* best-effort */ }
+            try {
+                adapter.prepareHeadlessSpawn?.(cwd);
+            }
+            catch (err) {
+                console.warn(`[loop] provider preparation failed: ${err.message}`);
+            }
             const buildOpts = {
                 // chat-stream feeds the prompt over stdin per-turn, so the argv `prompt`
                 // is unused — pass empty to satisfy the shared SpawnOptions shape.
@@ -329,28 +459,36 @@ function createLoopExecutors(opts = {}) {
                 // drops the session id at an iterate-loop's loop-back).
                 sessionId: sessionId ?? undefined,
                 reasoning_effort: effort,
+                ...(executionManifest ? { scopedWorkingDirectories: true } : {}),
                 extraArgs,
             };
             const args = adapter.buildArgs('chat-stream', buildOpts);
+            const effectiveIdleTimeoutMs = idleTimeoutMs ?? inactivityTimeoutMs();
             return {
                 adapter,
                 spec: { binary: adapter.binary, args, cwd, env: (0, runtime_1.buildProviderEnv)(adapter, buildOpts, stepEnv) },
                 // The loop's ai-step timeout bounds the WHOLE step, interactive
                 // included. 0 ⇒ unbounded (the engine skips arming the step timer).
+                ...(core?.promptPrefix ? { promptPrefix: core.promptPrefix } : {}),
                 stepTimeoutMs: aiStepTimeoutMs ?? AI_STEP_TIMEOUT_MS,
+                // Keep the old field for callers that already inspect the plan.
+                inactivityTimeoutMs: effectiveIdleTimeoutMs,
+                ...(effectiveIdleTimeoutMs > 0 ? { idleTimeoutMs: effectiveIdleTimeoutMs } : {}),
             };
         },
-        async runShell({ command, cwd, onLine, onSpawn }) {
-            return runShellCommand(command, cwd, resolveEnv(), SHELL_TIMEOUT_MS, onLine, onSpawn);
+        async runShell({ command, cwd, repoDir, onLine, onSpawn, timeoutMs }) {
+            const env = resolveEnv();
+            return runShellCommand(command, repoDir ?? cwd, repoDir ? { ...env, SPECRAILS_REPO_DIR: repoDir } : env, timeoutMs ?? SHELL_TIMEOUT_MS, onLine, onSpawn);
         },
-        async runDecider({ systemPrompt, userPrompt, provider, model, effort, cwd, repoDir, onRawLine, onSpawn }) {
+        async runDecider({ systemPrompt, userPrompt, provider, model, effort, cwd, repoDir, executionManifest, onRawLine, onSpawn, timeoutMs }) {
             const adapter = (0, providers_1.getAdapter)(provider);
             let text = '';
+            let errorText;
             const baseEnv = resolveEnv();
-            const decEnv = repoDir ? { ...baseEnv, SPECRAILS_REPO_DIR: repoDir } : baseEnv;
+            const decEnv = aiStepEnv(baseEnv, repoDir, executionManifest);
             // spec-gen is a one-shot, system-prompted invocation (workspace-write on
             // codex, not full-access) — appropriate for a read-only judgment.
-            const buildOpts = { prompt: userPrompt, systemPrompt, model, maxTurns: 1, reasoning_effort: effort, toolPolicy: 'read-only' };
+            const buildOpts = { prompt: userPrompt, systemPrompt, model, maxTurns: 1, reasoning_effort: effort, toolPolicy: 'read-only', ...(executionManifest ? { extraArgs: aiStepExtraArgs(adapter, cwd, repoDir, executionManifest) } : {}) };
             const wallStartedAt = Date.now();
             const res = await (0, spawn_lifecycle_1.runAiCliInvocation)({
                 adapter,
@@ -358,13 +496,24 @@ function createLoopExecutors(opts = {}) {
                 buildOpts,
                 cwd,
                 env: (0, runtime_1.buildProviderEnv)(adapter, buildOpts, decEnv),
-                timeoutMs: DECIDER_TIMEOUT_MS,
+                timeoutMs: timeoutMs ?? DECIDER_TIMEOUT_MS,
                 onSpawn,
                 onStdoutLine: onRawLine,
-                onEvent: (ev) => { if (ev.kind === 'text-delta')
-                    text += ev.text; },
+                onEvent: (ev) => {
+                    if (ev.kind === 'text-delta')
+                        text += ev.text;
+                    else if (ev.kind === 'error' && ev.message)
+                        errorText = ev.message;
+                    else if (ev.kind === 'result')
+                        errorText = (0, terminal_result_1.terminalResultError)(ev.payload) ?? errorText;
+                },
             });
-            const decision = (0, loop_decider_1.parseDeciderDecision)(text);
+            // A streamed verdict from an interrupted/failed invocation is not an
+            // authoritative completion gate, even when the partial JSON parses.
+            const failed = res.spawnFailed || res.timedOut || res.code !== 0 || errorText !== undefined;
+            const decision = failed
+                ? { continue: true, blocked: false, parsed: false, reasoning: errorText ?? (res.timedOut ? 'Decider timed out; verification is incomplete.' : res.stderrTail || 'Decider failed; verification is incomplete.') }
+                : (0, loop_decider_1.parseDeciderDecision)(text);
             const { result, estimated } = (0, result_event_1.finaliseInvocationResult)(adapter, res.events, {
                 fallbackModel: model,
                 durationMs: Math.max(0, Date.now() - wallStartedAt),

package/server/dist/loop-factory.js

@@ -6,7 +6,7 @@ exports.isFactoryLoopId = isFactoryLoopId;
 exports.factoryLoopMode = factoryLoopMode;
 exports.factoryLoopForMode = factoryLoopForMode;
 const loop_templates_1 = require("./loop-templates");
-const GREEN_GOAL = 'Stop only when the latest verification step reports {{const:VERIFICATION_PASS}} and the history proves the spec is implemented with all required tests/build checks passing.';
+const GREEN_GOAL = 'Stop only when the latest verification step reports {{const:VERIFICATION_PASS}} and the history proves every acceptance criterion is implemented across all required tickets and repositories, with the relevant behavioral checks and configured tests/build passing. Green baseline checks, setup, or planning alone do not prove completion.';
 // Factory loops run the WHOLE architect→developer→reviewer pipeline inside a
 // single AI step (`/specrails:implement` etc.), so no fixed wall-clock budget is
 // honest — a legit implement outran the old 60-min step cap and got killed
@@ -29,7 +29,7 @@ exports.FACTORY_LOOPS = [
     {
         id: 'factory:implement',
         name: 'Implement',
-        description: 'Fully autonomous: implement the spec, verify, and refine (fix) on failure — looping until all tests pass.',
+        description: 'Implement the spec, verify its acceptance criteria and project checks, then complete missing work or fix defects until the full change passes.',
         mode: 'implement',
         graph: (0, loop_templates_1.fixLoopGraph)(['{{cmd:implement}}'], GREEN_GOAL, FACTORY_MAX_ITERATIONS, FACTORY_LOOP_TIMEOUT_MIN, FACTORY_AI_STEP_TIMEOUT_MIN),
     },
@@ -60,9 +60,16 @@ exports.FACTORY_LOOPS = [
         // renders as an EMPTY string, so a hand-launched run would have a blank
         // central instruction. The launch route refuses it; the prompt guards too.
         launchable: false,
-        description: "Apply the ONE change the user asked for on top of work already delivered, re-grade it with the reviewer, then verify + refine until green. No re-planning. Runs automatically when you ask for changes on a review — it is not started by hand.",
+        description: "Apply the ONE change the user asked for on top of work already delivered, then run one independent reviewer-owned verification gate and refine until green. No re-planning. Runs automatically when you ask for changes on a review — it is not started by hand.",
         mode: 'loop',
-        graph: (0, loop_templates_1.fixLoopGraph)(['{{cmd:revise}}'], GREEN_GOAL, FACTORY_MAX_ITERATIONS, FACTORY_LOOP_TIMEOUT_MIN, FACTORY_AI_STEP_TIMEOUT_MIN),
+        // Revision is the ONLY factory loop that swaps the generic `{{cmd:verify}}`
+        // gate: `{{cmd:revision-verify}}` owns reviewer re-grading AND the full pass
+        // of record in ONE read-only step, so the mutator no longer runs sr-reviewer
+        // itself and no second repository-wide gate follows it. The trailing `true`
+        // makes verify/fix run in a FRESH provider session — the gate's verdict and
+        // its confidence artifact then describe the candidate on disk rather than
+        // the mutator's own account of it.
+        graph: (0, loop_templates_1.fixLoopGraph)(['{{cmd:revise}}'], GREEN_GOAL, FACTORY_MAX_ITERATIONS, FACTORY_LOOP_TIMEOUT_MIN, FACTORY_AI_STEP_TIMEOUT_MIN, '{{cmd:revision-verify}}', true),
     },
     SDD_QUICK_OPENSPEC_FACTORY,
 ];

package/server/dist/loop-graph.js

@@ -10,6 +10,7 @@
  * trivially unit-testable and reused verbatim by both the store and the engine.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertLoopShellRepositoryScope = assertLoopShellRepositoryScope;
 exports.emptyLoopGraph = emptyLoopGraph;
 exports.validateLoopGraph = validateLoopGraph;
 exports.nodesById = nodesById;
@@ -17,6 +18,15 @@ exports.findStartNode = findStartNode;
 exports.successors = successors;
 exports.loopNeedsTicket = loopNeedsTicket;
 exports.interpolateSpec = interpolateSpec;
+/** A named shell target must never silently fall back to another checkout. */
+function assertLoopShellRepositoryScope(graph, repositoryIds) {
+    for (const node of graph.nodes) {
+        const target = node.type === 'shell' ? node.data?.repositoryId : undefined;
+        if (target !== undefined && (typeof target !== 'string' || !repositoryIds.includes(target))) {
+            throw new Error(`Shell step ${node.id} targets a repository outside this launch`);
+        }
+    }
+}
 /** A minimal, structurally-valid empty graph (used to seed a new Draft). */
 function emptyLoopGraph() {
     return { nodes: [], edges: [], config: { maxIterations: 10, timeoutMinutes: 30 } };
@@ -34,8 +44,32 @@ function emptyLoopGraph() {
  */
 function validateLoopGraph(graph) {
     const errors = [];
-    const nodes = graph.nodes ?? [];
-    const edges = graph.edges ?? [];
+    if (!graph || !Array.isArray(graph.nodes) || !Array.isArray(graph.edges)) {
+        return { valid: false, errors: [{ code: 'INVALID_CONFIG', message: 'A loop graph must contain nodes and edges arrays.' }] };
+    }
+    const nodes = graph.nodes;
+    const edges = graph.edges;
+    const kinds = new Set(['start', 'ai-step', 'shell', 'decider', 'condition', 'end']);
+    if (nodes.some((node) => !node || typeof node.id !== 'string' || !node.id.trim() || !kinds.has(node.type))) {
+        return { valid: false, errors: [{ code: 'INVALID_NODE', message: 'Every node needs a non-empty id and a supported node type.' }] };
+    }
+    if (edges.some((edge) => !edge || typeof edge.id !== 'string' || !edge.id.trim() || typeof edge.source !== 'string' || typeof edge.target !== 'string')) {
+        return { valid: false, errors: [{ code: 'DANGLING_EDGE', message: 'Every edge needs a non-empty id, source and target.' }] };
+    }
+    for (const [items, code] of [[nodes, 'DUPLICATE_NODE'], [edges, 'DUPLICATE_EDGE']]) {
+        const ids = new Set();
+        for (const item of items) {
+            if (ids.has(item.id))
+                errors.push({ code, message: `Duplicate ${code === 'DUPLICATE_NODE' ? 'node' : 'edge'} id "${item.id}".` });
+            ids.add(item.id);
+        }
+    }
+    for (const node of nodes) {
+        if (node.type === 'shell' && node.data?.repositoryId !== undefined &&
+            (typeof node.data.repositoryId !== 'string' || !node.data.repositoryId.trim())) {
+            errors.push({ code: 'INVALID_NODE', nodeId: node.id, message: 'A shell repositoryId must be a non-empty registered repository id.' });
+        }
+    }
     // ── Start cardinality ──────────────────────────────────────────────────────
     const starts = nodes.filter((n) => n.type === 'start');
     if (starts.length === 0) {
@@ -61,10 +95,12 @@ function validateLoopGraph(graph) {
         cfg.maxIterations < 1 ||
         typeof cfg.timeoutMinutes !== 'number' ||
         !Number.isFinite(cfg.timeoutMinutes) ||
-        cfg.timeoutMinutes < 0) {
+        cfg.timeoutMinutes < 0 ||
+        (cfg.aiStepTimeoutMinutes !== undefined && (!Number.isFinite(cfg.aiStepTimeoutMinutes) || cfg.aiStepTimeoutMinutes < 0)) ||
+        (cfg.maxCostUsd !== undefined && !Number.isFinite(cfg.maxCostUsd))) {
         errors.push({
             code: 'INVALID_CONFIG',
-            message: 'maxIterations must be ≥ 1 and timeoutMinutes ≥ 0 (0 = no timeout).',
+            message: 'maxIterations must be ≥ 1; timeouts must be finite and ≥ 0 (0 = no timeout); maxCostUsd must be finite.',
         });
     }
     // ── Dangling edges ────────────────────────────────────────────────────────────
@@ -78,6 +114,33 @@ function validateLoopGraph(graph) {
             });
         }
     }
+    // The executor follows one successor at a time. Publishing a branching AI,
+    // shell or condition node would silently skip all but its first branch.
+    for (const node of nodes) {
+        const out = edges.filter((edge) => edge.source === node.id);
+        if (node.type === 'end') {
+            if (out.length)
+                errors.push({ code: 'INVALID_BRANCH', nodeId: node.id, message: 'End nodes cannot have outgoing edges.' });
+        }
+        else if (node.type === 'decider') {
+            const labeled = out.some((edge) => edge.branch !== undefined);
+            const validBranches = labeled
+                ? out.length === 2 && out.filter((edge) => edge.branch === 'continue').length === 1 && out.filter((edge) => edge.branch === 'stop').length === 1
+                : out.length === 2 && out.filter((edge) => nodes.find((candidate) => candidate.id === edge.target)?.type === 'end').length === 1;
+            if (!validBranches)
+                errors.push({ code: 'INVALID_BRANCH', nodeId: node.id, message: 'A Decider needs exactly one continue branch and one stop branch.' });
+            const cont = out.find((edge) => edge.branch === 'continue');
+            if (cont && nodes.find((candidate) => candidate.id === cont.target)?.type === 'end') {
+                errors.push({ code: 'INVALID_BRANCH', nodeId: node.id, message: 'The continue branch must lead to another step, not End.' });
+            }
+        }
+        else if (!out.length) {
+            errors.push({ code: 'DEAD_END', nodeId: node.id, message: `Node "${node.id}" needs a next step or an End.` });
+        }
+        else if (out.length !== 1) {
+            errors.push({ code: 'UNSUPPORTED_BRANCHING', nodeId: node.id, message: `Node "${node.id}" has multiple successors; use sequential steps or a Decider with explicit branches.` });
+        }
+    }
     // ── Reachability from Start (orphan detection) ──────────────────────────────
     // Only meaningful with exactly one Start; otherwise the start-cardinality
     // errors above already explain the shape problem.
@@ -151,6 +214,29 @@ function loopNeedsTicket(graph) {
 }
 function interpolateSpec(text, spec) {
     return text.replace(/\{\{\s*spec\.(\w+)\s*\}\}/g, (_match, key) => {
+        if (key === 'scope') {
+            if (!spec)
+                return '';
+            const changeName = typeof spec.openspecChangeName === 'string' ? spec.openspecChangeName.trim()
+                : typeof spec.metadata?.openspecChangeName === 'string' ? spec.metadata.openspecChangeName.trim() : undefined;
+            // Explicit task data, not arbitrary metadata or injected template code.
+            // Preserve all batch descriptions so later fresh verification/repair
+            // sessions do not have to reconstruct acceptance scope from short logs.
+            const scope = JSON.stringify({
+                id: spec.id,
+                ticketIds: spec.ticketIds,
+                title: spec.title,
+                description: spec.description,
+                repositoryIds: spec.repositoryIds,
+                openspecChangeName: changeName || undefined,
+                tickets: spec.tickets?.map(ticket => ({ id: ticket.id, title: ticket.title, description: ticket.description, repositoryIds: ticket.repositoryIds })),
+            }, null, 2);
+            if (scope === '{}')
+                return '';
+            // Constants/run-vars expand after spec data. Escape their delimiters
+            // inside JSON strings, along with the surrounding data block delimiter.
+            return scope.replace(/\{\{/g, '\\u007b\\u007b').replace(/\}\}/g, '\\u007d\\u007d').replace(/</g, '\\u003c').replace(/>/g, '\\u003e');
+        }
         // `{{spec.ids}}` → all rail ticket ids as `#1 #2 #3` (used by implement/batch).
         if (key === 'ids') {
             const ids = spec?.ticketIds ?? (spec?.id != null ? [spec.id] : []);