cool-workflow 0.2.2 → 0.2.3

package/dist/shell/drive.js

@@ -51,6 +51,7 @@ exports.MAX_SUB_WORKFLOW_DEPTH = exports.DRIVE_SCHEMA_VERSION = void 0;
 exports.maybeExpandLoop = maybeExpandLoop;
 exports.driveStep = driveStep;
 exports.drive = drive;
+exports.driveAsync = driveAsync;
 exports.drivePreview = drivePreview;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -153,15 +154,22 @@ function loadRun(ctx) {
 /** Runs `fn` with `runId`'s loadRun calls served from one shared cached
  *  object (seeded fresh from disk), and always clears the cache entry
  *  afterward — even on throw — so a round never leaks its cache into a
- *  later, unrelated drive call. */
+ *  later, unrelated drive call. Re-entrant: a nested call (e.g. the
+ *  serial drive loop's own round-cache wrapping a driveStep that itself
+ *  runs inside a caller's round cache) reuses the outer seed instead of
+ *  re-reading disk, and only the OUTERMOST call clears the entry — so
+ *  nesting never re-reads a run mid-round nor drops the cache early out
+ *  from under an enclosing scope. */
 function withRoundCache(ctx, fn) {
-    const seed = (0, run_store_1.loadRunFromCwd)(ctx.runId, ctx.cwd);
-    roundCache.set(ctx.runId, seed);
+    const alreadyActive = roundCache.has(ctx.runId);
+    if (!alreadyActive)
+        roundCache.set(ctx.runId, (0, run_store_1.loadRunFromCwd)(ctx.runId, ctx.cwd));
     try {
         return fn();
     }
     finally {
-        roundCache.delete(ctx.runId);
+        if (!alreadyActive)
+            roundCache.delete(ctx.runId);
     }
 }
 function resultCachePath(run, task, promptDigest, incremental, delegationDigest) {
@@ -551,7 +559,8 @@ function maybeExpandLoop(run) {
         const latest = loopPhases.reduce((a, b) => ((b.loopRound || 1) >= (a.loopRound || 1) ? b : a));
         if (phase.id !== latest.id)
             continue;
-        const roundTasks = run.tasks.filter((t) => latest.taskIds.includes(t.id));
+        const latestTaskIds = new Set(latest.taskIds);
+        const roundTasks = run.tasks.filter((t) => latestTaskIds.has(t.id));
         if (roundTasks.length === 0 || !roundTasks.every((t) => t.status === "completed"))
             continue;
         const round = latest.loopRound || 1;
@@ -560,7 +569,8 @@ function maybeExpandLoop(run) {
             .sort((a, b) => compareBytes(a.id, b.id))
             .map((t) => t.result);
         const roundResults = ordered(roundTasks);
-        const allLoopTasks = run.tasks.filter((t) => t.status === "completed" && loopPhases.some((p) => p.taskIds.includes(t.id)));
+        const loopTaskIds = new Set(loopPhases.flatMap((p) => p.taskIds));
+        const allLoopTasks = run.tasks.filter((t) => t.status === "completed" && loopTaskIds.has(t.id));
         const allResults = ordered(allLoopTasks);
         const ctx = {
             round,
@@ -597,7 +607,8 @@ function maybeExpandLoop(run) {
         // Expand: clone the ROUND-1 template tasks into a fresh phase appended
         // right after the latest round.
         const nextRound = round + 1;
-        const templateTasks = run.tasks.filter((t) => origin.taskIds.includes(t.id));
+        const originTaskIds = new Set(origin.taskIds);
+        const templateTasks = run.tasks.filter((t) => originTaskIds.has(t.id));
         const { phase: nextPhase, tasks: newTasks } = (0, loop_expansion_1.cloneLoopRoundTasks)(origin, templateTasks, nextRound);
         const insertAt = run.phases.findIndex((p) => p.id === latest.id);
         run.phases.splice(insertAt + 1, 0, nextPhase);
@@ -732,8 +743,9 @@ function driveConcurrentRound(ctx, limit) {
             return [driveStep(ctx)];
         const phase = (0, dispatch_1.firstRunnablePhase)(run);
         const width = Math.max(1, Math.floor(limit) || 1);
+        const phaseTaskIds = new Set(phase.taskIds);
         const batch = run.tasks
-            .filter((task) => phase.taskIds.includes(task.id) && (task.status === "pending" || task.status === "running"))
+            .filter((task) => phaseTaskIds.has(task.id) && (task.status === "pending" || task.status === "running"))
             .slice(0, width)
             .map((task) => task.id);
         const prepared = prepareConcurrentOutcomes(ctx, batch);
@@ -762,13 +774,37 @@ function driveConcurrentRound(ctx, limit) {
         return steps.length > 0 ? steps : [driveStep(ctx)];
     });
 }
-/** Drive a run: `--once` advances exactly one step; otherwise run to
- *  completion, park, or a blocked stop. */
-function drive(runId, cwd, options = {}) {
+// A bare Ctrl-C (SIGINT) or an external SIGTERM used to kill the process
+// outright between steps -- no handler was ever installed, so the default
+// kernel action ran: instant termination, no `finally` anywhere gets a
+// chance to run. If that landed mid-`withFileLock` critical section (e.g.
+// the state.json or trust-audit-log lock in run-store.ts/trust-audit.ts),
+// the lock's release `finally` never ran either, leaving a stale `.lock`
+// file that makes the NEXT command retry for ~6s before failing outright
+// (well under the 30s stale-lock steal window).
+//
+// The FIRST fix for this (installing onStopSignal below) assumed the
+// signal would at least be caught BETWEEN rounds, only missing it
+// mid-spawnSync. That assumption was wrong: Node.js does not dispatch a
+// queued POSIX signal to a JS `process.on(signal, ...)` listener until
+// the event loop actually gets a turn, and drive()'s whole multi-round
+// loop -- every round's agent spawn uses spawnSync, and nothing between
+// rounds ever awaits anything -- is ONE continuous synchronous span with
+// no such turn anywhere inside it. A signal landing at any point during
+// that whole span (confirmed live: even a plain CPU-only busy loop with
+// no spawnSync at all drops it the same way) sits queued until the loop
+// finishes on its own, by which point the `finally` below has already
+// removed the listener -- so it is never invoked at all. `drive()` keeps
+// this exact (buggy but byte-identical) shape for full backward
+// compatibility; `driveAsync()` below is the actual fix, for callers
+// that need a live run to really respond to Ctrl-C/SIGTERM.
+const DRIVE_STOP_SIGNALS = ["SIGINT", "SIGTERM"];
+const DRIVE_STOP_EXIT_CODE = { SIGINT: 130, SIGTERM: 143 };
+function buildDriveContext(runId, cwd, options) {
     const now = options.now || new Date().toISOString();
     const config = options.agentConfig || (0, agent_config_1.resolveAgentConfig)(options.args || {});
     const policy = { ...drive_decide_1.DEFAULT_SCHEDULING_POLICY, ...(options.policy || {}) };
-    const ctx = {
+    return {
         runId,
         cwd,
         now,
@@ -779,22 +815,22 @@ function drive(runId, cwd, options = {}) {
         visitedAppIds: options.visitedAppIds || [],
         policy,
     };
-    const steps = [];
-    const run0 = loadRun(ctx);
-    const plannedWorkers = run0.tasks.length;
-    const maxIter = (0, drive_decide_1.maxIterations)(plannedWorkers, (0, loop_expansion_1.maxLoopExpansion)(run0), policy);
-    // Phase-boundary progress (brew-style): announce each phase when it
-    // becomes active and when it finishes — `==> Map ✓ (6/6)` / `==> Assess
-    // ⇉ (3/6)`. Describes CW's OWN phases (vendor-neutral); goes to stderr
-    // via emitProgress so stdout stays clean data. Byte-exact port of the
-    // old build's src/drive.ts emitPhaseProgress. term.phaseProgressLine
-    // renders the line; this closure decides WHEN to emit each boundary.
+}
+// Phase-boundary progress (brew-style): announce each phase when it becomes
+// active and when it finishes — `==> Map ✓ (6/6)` / `==> Assess ⇉ (3/6)`.
+// Describes CW's OWN phases (vendor-neutral); goes to stderr via
+// emitProgress so stdout stays clean data. Byte-exact port of the old
+// build's src/drive.ts emitPhaseProgress. term.phaseProgressLine renders
+// the line; the returned closure decides WHEN to emit each boundary.
+// Shared by drive() and driveAsync() so the two never drift apart.
+function createPhaseProgressEmitter() {
     const announcedPhaseComplete = new Set();
     let activePhaseId;
     const titleCase = (s) => (s ? s.charAt(0).toUpperCase() + s.slice(1) : s);
-    const emitPhaseProgress = (run) => {
+    return (run) => {
         for (const ph of run.phases || []) {
-            const phaseTasks = run.tasks.filter((task) => ph.taskIds.includes(task.id));
+            const phaseTaskIds = new Set(ph.taskIds);
+            const phaseTasks = run.tasks.filter((task) => phaseTaskIds.has(task.id));
             const total = phaseTasks.length;
             if (total === 0)
                 continue;
@@ -814,38 +850,113 @@ function drive(runId, cwd, options = {}) {
             return; // only the first not-yet-complete phase is "active"
         }
     };
-    let exhaustedMaxIterations = !options.once;
-    for (let i = 0; i < maxIter; i++) {
+}
+/** Runs exactly one round -- a single driveStep, or a full concurrent
+ *  round when width>1 -- and records its steps. Returns false when the
+ *  round loop should stop (a terminal step, or `--once`'s single-round
+ *  contract), true to go on to another round. Shared by drive()'s plain
+ *  loop and driveAsync()'s interruptible one so the two never drift
+ *  apart. */
+function driveOneRound(ctx, options, steps, emitPhaseProgress) {
+    // One round-cache scope for the WHOLE round, not just driveConcurrentRound's
+    // own batch: the width check and (for a serial round) driveStep/
+    // processSelectedTask's several loadRun(ctx) calls otherwise each
+    // re-read+re-parse state.json even though nothing on disk changed
+    // between them — reads that only reflect the mutations THIS round's
+    // own steps make, which the shared in-memory object already carries.
+    const roundSteps = withRoundCache(ctx, () => {
         const width = (0, drive_decide_1.roundWidth)(loadRun(ctx), options.concurrency);
         // width>1 (an explicit --concurrency>1, or an auto-width parallel
         // phase) runs the whole round through driveConcurrentRound — one or
-        // more steps recorded in deterministic batch order, one flush at
-        // round end. `--once` still stops after this ONE outer-loop
-        // iteration even though a round can yield multiple steps.
-        const roundSteps = width > 1 ? driveConcurrentRound(ctx, width) : [driveStep(ctx)];
-        for (const stepResult of roundSteps)
-            steps.push(stepResult);
-        // Brew-style phase boundaries: after each round, announce a
-        // newly-active phase and any phase that just finished. Cheap — reuses
-        // the run we just advanced; goes to stderr so stdout stays clean.
-        emitPhaseProgress(loadRun(ctx));
-        const last = roundSteps[roundSteps.length - 1];
-        if (options.once) {
-            exhaustedMaxIterations = false;
-            break;
-        }
-        if (last && (last.status === "complete" || last.status === "parked" || last.status === "blocked")) {
-            exhaustedMaxIterations = false;
-            break;
+        // more steps recorded in deterministic batch order, one flush at round
+        // end. `--once` still stops after this ONE round even though a round
+        // can yield multiple steps.
+        return width > 1 ? driveConcurrentRound(ctx, width) : [driveStep(ctx)];
+    });
+    for (const stepResult of roundSteps)
+        steps.push(stepResult);
+    // Brew-style phase boundaries: after each round, announce a newly-active
+    // phase and any phase that just finished. Cheap — reuses the run we just
+    // advanced; goes to stderr so stdout stays clean.
+    emitPhaseProgress(loadRun(ctx));
+    const last = roundSteps[roundSteps.length - 1];
+    if (options.once)
+        return false;
+    if (last && (last.status === "complete" || last.status === "parked" || last.status === "blocked"))
+        return false;
+    return true;
+}
+/** One JS EventEmitter listener per SIGINT/SIGTERM, installed for the span
+ *  of one drive()/driveAsync() call and removed by that caller's own
+ *  `finally` (this function recurses for nested sub-workflow runs, and
+ *  many tests call it repeatedly in one process, so nothing must
+ *  accumulate on `process`'s listener list across calls). The FIRST
+ *  signal sets a flag the round loop checks at the top of its next
+ *  iteration -- never mid-round -- so the in-flight round always
+ *  finishes its own bookkeeping first. A SECOND signal means the caller
+ *  wants out right now, not a graceful stop, and force-exits immediately
+ *  with the conventional 128+signum code. */
+function createStopSignalController() {
+    let interruptedBy;
+    let stopSignalHits = 0;
+    const onStopSignal = (signal) => {
+        stopSignalHits += 1;
+        if (stopSignalHits === 1) {
+            interruptedBy = signal;
+            emitProgress(`received ${signal} — stopping after the current step (run again with the same run id to resume)`);
+            return;
         }
-    }
+        // A second signal means the caller wants out right now, not a graceful stop.
+        emitProgress(`received a second ${signal} — exiting immediately`);
+        process.exit(DRIVE_STOP_EXIT_CODE[signal] ?? 1);
+    };
+    return {
+        install: () => {
+            for (const signal of DRIVE_STOP_SIGNALS)
+                process.on(signal, onStopSignal);
+        },
+        remove: () => {
+            for (const signal of DRIVE_STOP_SIGNALS)
+                process.off(signal, onStopSignal);
+        },
+        getInterruptedBy: () => interruptedBy,
+    };
+}
+/** Forces one real turn of the Node.js event loop. `setImmediate` (a
+ *  genuine macrotask, unlike a bare Promise microtask, which never leaves
+ *  the current turn) is the only thing that actually lets libuv's poll
+ *  phase run and dispatch a queued SIGINT/SIGTERM to its JS listener --
+ *  confirmed live: a real external `kill -INT` sent to a busy synchronous
+ *  process is dropped for as long as the process never yields, and fires
+ *  within ~1ms of the very next event-loop turn once it does. */
+function yieldToEventLoop() {
+    return new Promise((resolve) => setImmediate(resolve));
+}
+/** Everything drive()/driveAsync() do once their round loop has stopped:
+ *  fold the interrupted/exhausted-iterations signal into the right
+ *  "blocked" step, then assemble the DriveResult. Shared so the two
+ *  loops can never report status differently for the same outcome. */
+function finalizeDriveResult(ctx, options, steps, plannedWorkers, maxIter, exhaustedMaxIterationsAtLoopExit, interruptedBy) {
+    let exhaustedMaxIterations = exhaustedMaxIterationsAtLoopExit;
     const run = loadRun(ctx);
     const completedWorkers = (0, drive_decide_1.countCompleted)(run);
     const parkedWorkers = (0, drive_decide_1.countParked)(run);
     const committed = (0, drive_decide_1.hasTerminalCommit)(run);
     const last = steps[steps.length - 1];
-    if (exhaustedMaxIterations) {
-        steps.push((0, drive_decide_1.makeStep)("blocked", "blocked", { runId, reason: `drive reached max iteration limit (${maxIter}) before a terminal state` }));
+    // A signal can land on the very last step (the terminal commit itself) --
+    // the run is already fully done, same "complete" check the `once` branch
+    // of finalDriveStatus below already uses. Reporting "blocked" here anyway
+    // would be a real user-visible lie (e.g. pipeline-cli.ts's `--bundle` gate
+    // reads status, so a genuinely finished run would wrongly skip sealing).
+    const alreadyComplete = completedWorkers === plannedWorkers && committed;
+    if (interruptedBy) {
+        exhaustedMaxIterations = false;
+        if (!alreadyComplete) {
+            steps.push((0, drive_decide_1.makeStep)("blocked", "blocked", { runId: ctx.runId, reason: `drive interrupted by ${interruptedBy} — run again with the same run id to resume` }));
+        }
+    }
+    else if (exhaustedMaxIterations) {
+        steps.push((0, drive_decide_1.makeStep)("blocked", "blocked", { runId: ctx.runId, reason: `drive reached max iteration limit (${maxIter}) before a terminal state` }));
     }
     const statusInputs = {
         once: Boolean(options.once),
@@ -862,7 +973,7 @@ function drive(runId, cwd, options = {}) {
     const committedCommit = (run.commits || []).find((c) => c.reason && c.reason.startsWith("agent-delegation-drive"));
     return {
         schemaVersion: 1,
-        runId,
+        runId: ctx.runId,
         workflowId: run.workflow.id,
         status,
         steps,
@@ -872,9 +983,92 @@ function drive(runId, cwd, options = {}) {
         commitId: committedCommit?.id,
         reportPath: run.paths.report,
         statePath: run.paths.state,
-        agentConfigured: agentConfigured(config),
+        agentConfigured: agentConfigured(ctx.config),
     };
 }
+/** Drive a run: `--once` advances exactly one step; otherwise run to
+ *  completion, park, or a blocked stop. Fully synchronous, byte-identical
+ *  to every prior release -- see the file comment above DRIVE_STOP_SIGNALS
+ *  for why a real SIGINT/SIGTERM sent during a live multi-round call is
+ *  queued but never actually reaches onStopSignal below; that limitation
+ *  is deliberately kept here for backward compatibility (recursive
+ *  sub-workflow runs, and every existing caller/test that depends on this
+ *  exact synchronous shape) and fixed only in driveAsync(). */
+function drive(runId, cwd, options = {}) {
+    const ctx = buildDriveContext(runId, cwd, options);
+    const steps = [];
+    const run0 = loadRun(ctx);
+    const plannedWorkers = run0.tasks.length;
+    const maxIter = (0, drive_decide_1.maxIterations)(plannedWorkers, (0, loop_expansion_1.maxLoopExpansion)(run0), ctx.policy);
+    const emitPhaseProgress = createPhaseProgressEmitter();
+    let exhaustedMaxIterations = !options.once;
+    const stopSignal = createStopSignalController();
+    stopSignal.install();
+    try {
+        for (let i = 0; i < maxIter; i++) {
+            if (stopSignal.getInterruptedBy())
+                break;
+            if (!driveOneRound(ctx, options, steps, emitPhaseProgress)) {
+                exhaustedMaxIterations = false;
+                break;
+            }
+        }
+    }
+    finally {
+        stopSignal.remove();
+    }
+    return finalizeDriveResult(ctx, options, steps, plannedWorkers, maxIter, exhaustedMaxIterations, stopSignal.getInterruptedBy());
+}
+/** Same contract and same DriveResult as drive() -- but actually
+ *  interruptible. After every round it awaits yieldToEventLoop(), a real
+ *  setImmediate-based turn of the event loop, giving Node.js an actual
+ *  chance to dispatch a queued SIGINT/SIGTERM to onStopSignal before the
+ *  next round's synchronous spawnSync work begins; the loop then sees
+ *  the interrupted flag at the top of its next iteration exactly like
+ *  drive() already checks it. Shares driveOneRound/createStopSignalController/
+ *  finalizeDriveResult with drive(), so the two can only ever differ in
+ *  this one respect. Intended for the live, potentially-long-running
+ *  entry points (CLI `--drive`, the MCP run.drive.step tool) where a
+ *  user's Ctrl-C or a supervisor's SIGTERM must actually be able to stop
+ *  the run; internal/recursive/test callers that don't need this keep
+ *  calling the plain drive() above, unaffected.
+ *
+ *  A signal arriving while a NESTED sub-workflow's own drive() call
+ *  (runSubWorkflow, below) is running is still not caught until that
+ *  nested call finishes on its own -- an accepted, documented limitation:
+ *  the same "cannot interrupt an already in-flight blocking operation,
+ *  only checked at explicit boundaries" shape as the pre-existing
+ *  cannot-interrupt-mid-spawnSync limit, just one level of recursion
+ *  deeper. Fixing that would require threading interruptibility through
+ *  the entire recursive call graph (driveStep/processSelectedTask/
+ *  runSubWorkflow/handleHop), a materially larger change left for a
+ *  future cycle if it proves needed in practice. */
+async function driveAsync(runId, cwd, options = {}) {
+    const ctx = buildDriveContext(runId, cwd, options);
+    const steps = [];
+    const run0 = loadRun(ctx);
+    const plannedWorkers = run0.tasks.length;
+    const maxIter = (0, drive_decide_1.maxIterations)(plannedWorkers, (0, loop_expansion_1.maxLoopExpansion)(run0), ctx.policy);
+    const emitPhaseProgress = createPhaseProgressEmitter();
+    let exhaustedMaxIterations = !options.once;
+    const stopSignal = createStopSignalController();
+    stopSignal.install();
+    try {
+        for (let i = 0; i < maxIter; i++) {
+            if (stopSignal.getInterruptedBy())
+                break;
+            if (!driveOneRound(ctx, options, steps, emitPhaseProgress)) {
+                exhaustedMaxIterations = false;
+                break;
+            }
+            await yieldToEventLoop();
+        }
+    }
+    finally {
+        stopSignal.remove();
+    }
+    return finalizeDriveResult(ctx, options, steps, plannedWorkers, maxIter, exhaustedMaxIterations, stopSignal.getInterruptedBy());
+}
 function drivePreview(runId, cwd, args = {}) {
     const run = (0, run_store_1.loadRunFromCwd)(runId, cwd);
     const config = (0, agent_config_1.resolveAgentConfig)(args);

package/dist/shell/eval-text.js

@@ -167,7 +167,7 @@ function formatMultiAgentEval(value) {
             `  replay=${value.paths.replayRunPath}`,
             "",
             "Next Action",
-            `  node scripts/cw.js eval compare ${value.paths.snapshotPath} ${value.paths.replayRunPath}`,
+            `  cw eval compare ${value.paths.snapshotPath} ${value.paths.replayRunPath}`,
         ].join("\n");
     }
     if (isSnapshot(value)) {
@@ -201,7 +201,7 @@ function formatMultiAgentEval(value) {
             "  snapshot-ready",
             "",
             "Next Action",
-            `  node scripts/cw.js eval replay ${value.paths.snapshotPath}`,
+            `  cw eval replay ${value.paths.snapshotPath}`,
         ].join("\n");
     }
     if (isReport(value)) {

package/dist/shell/evidence-reasoning.js

@@ -65,10 +65,10 @@ function buildEvidenceReasoningReport(run, options = {}) {
     if (persisted && persisted.sourceFingerprint !== currentFingerprint)
         status = "stale";
     const nextAction = status === "stale" || status === "absent"
-        ? `node scripts/cw.js multi-agent reasoning ${run.id} --refresh`
+        ? `cw multi-agent reasoning ${run.id} --refresh`
         : totals.unexplained > 0
-            ? `node scripts/cw.js multi-agent reasoning ${run.id} --json`
-            : `node scripts/cw.js multi-agent evidence ${run.id} --json`;
+            ? `cw multi-agent reasoning ${run.id} --json`
+            : `cw multi-agent evidence ${run.id} --json`;
     return {
         schemaVersion: exports.EVIDENCE_REASONING_SCHEMA_VERSION,
         runId: run.id,
@@ -343,7 +343,7 @@ function refreshEvidenceReasoning(run) {
         totals: report.totals,
         entries: entries.sort((a, b) => (0, collate_1.stableCompare)(a.id, b.id)),
         paths: { reasoningDir: dir, indexPath, reportPath },
-        nextAction: `node scripts/cw.js multi-agent reasoning ${run.id}`,
+        nextAction: `cw multi-agent reasoning ${run.id}`,
     };
     (0, fs_atomic_1.writeJson)(indexPath, index);
     (0, fs_atomic_1.writeJson)(reportPath, { ...report, freshness: { ...report.freshness, status: "valid", persistedFingerprint: report.sourceFingerprint } });

package/dist/shell/execution-backend/agent.js

@@ -408,15 +408,34 @@ function runAgentProcess(descriptor, policy, request, label, attestation) {
             const built = buildAgentChildEnv(policy);
             const childEnv = built.env;
             forwardedEnvVars = built.forwarded;
+            const timeoutMs = resolved.timeoutMs || 600000;
             const child = (0, node_child_process_1.spawnSync)(resolved.binary, realArgs, {
                 cwd: request.cwd,
                 env: childEnv,
                 encoding: "utf8",
-                timeout: resolved.timeoutMs || 600000,
+                timeout: timeoutMs,
                 maxBuffer: 32 * 1024 * 1024,
                 shell: false,
+                // SIGKILL, not the default SIGTERM: an agent wrapper that ignores
+                // SIGTERM would leave this blocking spawnSync waiting forever (no
+                // second-stage escalation is possible from inside a sync call), and
+                // a timed-out agent's output is discarded by the refusal below
+                // anyway — so a hard kill loses nothing and cannot wedge cw.
+                killSignal: "SIGKILL",
                 stdio: ["ignore", "pipe", streamStderr ? "inherit" : "pipe"],
             });
+            // A timeout surfaces as child.error with code ETIMEDOUT (status null,
+            // signal set). Classify it FIRST: without this, the generic spawnError
+            // branch below reported "agent process failed to spawn: ...ETIMEDOUT"
+            // and the null-exit-code "timed out or killed" branch was dead code
+            // for real timeouts.
+            if (child.error && child.error.code === "ETIMEDOUT") {
+                const handleOut = recordedAgentHandle(resolved.binary, undefined, recordedArgs, resolved.model, "unreported", undefined, undefined, forwardedEnvVars);
+                return (0, envelopes_1.refusedEnvelope)(descriptor, policy, label, "delegation-failed", `agent process timed out after ${timeoutMs}ms and was killed (SIGKILL)`, {
+                    ...attestation,
+                    handle: handleOut,
+                });
+            }
             outcome = {
                 ...(child.error ? { spawnError: messageOf(child.error) } : {}),
                 exitCode: typeof child.status === "number" ? child.status : null,

package/dist/shell/execution-backend/container.js

@@ -56,7 +56,10 @@ function runContainer(descriptor, policy, request, label, handle, attestation) {
         }
     }
     runArgs.push(handle.ref, command, ...args);
-    const result = (0, node_child_process_1.spawnSync)(runtime, runArgs, { cwd, encoding: "utf8", timeout: request.timeoutMs, maxBuffer: 32 * 1024 * 1024 });
+    // An unset timeoutMs must not mean "no timeout" — spawnSync would then
+    // block forever on a hung container with no kill path. 600000 matches the
+    // agent backend's own default fallback (execution-backend/agent.ts).
+    const result = (0, node_child_process_1.spawnSync)(runtime, runArgs, { cwd, encoding: "utf8", timeout: request.timeoutMs || 600000, maxBuffer: 32 * 1024 * 1024 });
     if (result.error) {
         return (0, envelopes_1.refusedEnvelope)(descriptor, policy, label, "delegation-failed", `${runtime} run failed: ${messageOf(result.error)}`, attestation);
     }

package/dist/shell/execution-backend/local.js

@@ -65,7 +65,10 @@ function executeLocal(descriptor, request, label, attestation, spawnStyle) {
         cwd: request.cwd,
         env,
         encoding: "utf8",
-        timeout: request.timeoutMs,
+        // An unset timeoutMs must not mean "no timeout" — spawnSync would then
+        // block forever on a hung child with no kill path. 600000 matches the
+        // agent backend's own default fallback (execution-backend/agent.ts).
+        timeout: request.timeoutMs || 600000,
         maxBuffer: 32 * 1024 * 1024,
     };
     if (spawnStyle === "shell") {

package/dist/shell/feedback-cli.js

@@ -67,15 +67,15 @@ function feedbackSummaryCli(args) {
     const run = (0, run_store_1.loadRunFromCwd)(req(args.runId, "run id"), cwdFor(args));
     return (0, error_feedback_1.summarizeFeedback)((0, feedback_operations_1.listFeedback)(run));
 }
+// collect/task/resolve mutate the run and saveCheckpoint (transitively,
+// in feedback-operations -> error-feedback-io), so they hold the state.json
+// lock across the whole load -> change -> save cycle (lost-update class).
 function feedbackCollectCli(args) {
-    const run = (0, run_store_1.loadRunFromCwd)(req(args.runId, "run id"), cwdFor(args));
-    return (0, feedback_operations_1.collectFeedback)(run);
+    return (0, run_store_1.withRunStateLock)(req(args.runId, "run id"), cwdFor(args), (run) => (0, feedback_operations_1.collectFeedback)(run));
 }
 function feedbackTaskCli(args) {
-    const run = (0, run_store_1.loadRunFromCwd)(req(args.runId, "run id"), cwdFor(args));
-    return (0, feedback_operations_1.createFeedbackTask)(run, req(args.feedbackId, "feedback id"), args);
+    return (0, run_store_1.withRunStateLock)(req(args.runId, "run id"), cwdFor(args), (run) => (0, feedback_operations_1.createFeedbackTask)(run, req(args.feedbackId, "feedback id"), args));
 }
 function feedbackResolveCli(args) {
-    const run = (0, run_store_1.loadRunFromCwd)(req(args.runId, "run id"), cwdFor(args));
-    return (0, feedback_operations_1.resolveFeedback)(run, req(args.feedbackId, "feedback id"), args);
+    return (0, run_store_1.withRunStateLock)(req(args.runId, "run id"), cwdFor(args), (run) => (0, feedback_operations_1.resolveFeedback)(run, req(args.feedbackId, "feedback id"), args));
 }