@stigmer/runner 3.40.0 → 3.41.0

package/src/shared/workspace/stigmer-link.ts

@@ -11,10 +11,10 @@
  * `.stigmer/…` paths those agents are prompted with (skill locations,
  * `.stigmer/inputs/…` attachments) actually resolve. The native harness's
  * FILE tools are the exception: their virtual-rooted backend refuses a path
- * whose real location leaves the workspace, so they read the platform dir
- * through a read-only `.stigmer/` route instead
- * (`activities/execute-deep-agent/platform-route.ts`), mounted on exactly
- * the turns this link exists ({@link stigmerSymlinkPointsAt}).
+ * whose real location leaves the workspace, so they reach `.stigmer/` through
+ * a route instead (`activities/execute-deep-agent/platform-route.ts`),
+ * mounted on every turn and exposing the platform dir on exactly the turns
+ * this link exists ({@link stigmerSymlinkPointsAt}).
  *
  * Lifecycle contract (same for both harnesses):
  * - Created per turn, under the workspace turn lock — the link is a
@@ -29,26 +29,35 @@
  * - {@link ensureStigmerSymlink} is idempotent, so multiple populaters may
  *   run in any order within a turn.
  *
- * OWNERSHIP SHARP EDGE: the platform owns the `.stigmer` name inside a
- * workspace. {@link ensureStigmerSymlink} REPLACES a real (non-symlink)
- * `.stigmer` directory it finds there — deliberate, so a directory left
- * behind by an older runner can never shadow the platform mount. (A user's
- * own `.stigmer` content is unreachable anyway: the runner's
- * `LocalWorkspaceBackend` routes every `.stigmer/…` path to the platform
- * dir.) Turn-end removal is the conservative half: it only ever removes a
- * SYMLINK.
+ * OWNERSHIP: the platform owns the `.stigmer` name inside a workspace, but
+ * never deletes what it did not make. A real (non-symlink) `.stigmer` entry
+ * found where the link goes — left by an older runner, or written by a shell
+ * command or a Cursor edit on a turn with no link, where nothing sits between
+ * those tools and the disk (#1123) — is MOVED out of the workspace to the
+ * session's `displaced/` dir (platform-dir.ts `getDisplacedDir`) and named in
+ * a warning; an empty directory is simply removed. Out of the workspace
+ * because a write-back commits everything the tree holds (`git add -A`) and
+ * git excludes only the exact `.stigmer` name. One case is refused outright:
+ * a `.stigmer` that is, or holds, the platform dir itself — a workspace
+ * rooted at the home directory, whose `.stigmer` is the Stigmer home (#1424).
+ * Turn-end removal is the conservative half: it only ever removes a SYMLINK.
  */
 
-import { symlink, readlink, unlink, rm, lstat } from "node:fs/promises";
-import { join } from "node:path";
+import { cp, lstat, mkdir, readdir, readlink, realpath, rename, rm, rmdir, symlink, unlink } from "node:fs/promises";
+import type { Stats } from "node:fs";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { getDisplacedDir } from "./platform-dir.js";
 
 /** The workspace-visible name of the platform namespace. */
 export const STIGMER_LOCAL_STATE_DIR = ".stigmer";
 
 /**
  * Ensure the workspace `.stigmer` symlink points to the platform dir.
- * Idempotent: an existing correct link is kept; a stale link (or a non-link
- * left behind by an older runner) is replaced.
+ * Idempotent: an existing correct link is kept and a stale link is
+ * re-pointed. A real entry in the link's place is moved to the session's
+ * `displaced/` dir first (an empty directory is removed); a real `.stigmer`
+ * that holds the platform dir is refused with an error naming it, before
+ * anything is touched. See the module header, OWNERSHIP.
  */
 export async function ensureStigmerSymlink(
   workspaceDir: string,
@@ -56,24 +65,85 @@ export async function ensureStigmerSymlink(
 ): Promise<void> {
   const linkPath = join(workspaceDir, STIGMER_LOCAL_STATE_DIR);
 
+  let entry: Stats | undefined;
   try {
-    const existing = await readlink(linkPath);
-    if (existing === platformDir) return;
+    entry = await lstat(linkPath);
+  } catch (err) {
+    if (errnoCode(err) !== "ENOENT") throw err;
+  }
+
+  if (entry?.isSymbolicLink()) {
+    if ((await readlink(linkPath)) === platformDir) return;
     await unlink(linkPath);
-  } catch (err: any) {
-    if (err.code === "ENOENT") {
-      // No existing symlink
-    } else if (err.code === "EINVAL") {
-      // Exists but is not a symlink — remove the directory
-      await rm(linkPath, { recursive: true, force: true });
-    } else {
-      throw err;
-    }
+  } else if (entry !== undefined) {
+    await displaceRealEntry(linkPath, platformDir, entry);
   }
 
   await symlink(platformDir, linkPath, "dir");
 }
 
+/**
+ * Clear a real `.stigmer` entry out of the link's place without losing it:
+ * refuse the Stigmer home, remove an empty directory, move anything else.
+ */
+async function displaceRealEntry(linkPath: string, platformDir: string, entry: Stats): Promise<void> {
+  if (entry.isDirectory()) {
+    await refuseDirHoldingPlatform(linkPath, platformDir);
+    if ((await readdir(linkPath)).length === 0) {
+      await rmdir(linkPath);
+      return;
+    }
+  }
+  const destination = getDisplacedDir(platformDir, displacementStamp(new Date()));
+  await mkdir(dirname(destination), { recursive: true });
+  await moveEntry(linkPath, destination);
+  console.warn(
+    `ensureStigmerSymlink: moved the real ${linkPath} out of the workspace to ${destination}; ` +
+    "the platform owns the .stigmer name, so the link to the session's platform dir takes its place",
+  );
+}
+
+/**
+ * Throw when the real `.stigmer` directory is, or contains, the platform dir:
+ * a workspace rooted at the home directory resolves `.stigmer` to the Stigmer
+ * home, where the platform dir, the CLI's config and every session live.
+ * Compared by real path, so a symlinked or `HOME`-overridden spelling of
+ * either side cannot slip past.
+ */
+async function refuseDirHoldingPlatform(linkPath: string, platformDir: string): Promise<void> {
+  const [realLink, realPlatform] = await Promise.all([realpath(linkPath), realpath(platformDir)]);
+  const fromLink = relative(realLink, realPlatform);
+  const outside = fromLink === ".." || fromLink.startsWith(`..${sep}`) || isAbsolute(fromLink);
+  if (!outside) {
+    throw new Error(
+      `The workspace's ${linkPath} is the Stigmer home (it holds this session's platform dir, ${platformDir}); ` +
+      "use a project directory as the workspace, not the home directory",
+    );
+  }
+}
+
+/** Rename, or copy then remove when the destination is on another filesystem (a cloud workspace volume and `$HOME` are). */
+async function moveEntry(source: string, destination: string): Promise<void> {
+  try {
+    await rename(source, destination);
+  } catch (err) {
+    if (errnoCode(err) !== "EXDEV") throw err;
+    await cp(source, destination, { recursive: true, errorOnExist: true, force: false, verbatimSymlinks: true });
+    await rm(source, { recursive: true, force: true });
+  }
+}
+
+/** A compact UTC stamp with milliseconds (`20260929T101500123Z`): sortable, and free of the colons a path should not carry. */
+function displacementStamp(now: Date): string {
+  return now.toISOString().replace(/[-:.]/g, "");
+}
+
+/** The errno code of a Node filesystem error, or `undefined` for anything else. */
+function errnoCode(err: unknown): string | undefined {
+  if (typeof err !== "object" || err === null || !("code" in err)) return undefined;
+  return typeof err.code === "string" ? err.code : undefined;
+}
+
 /**
  * Whether the workspace's `.stigmer` is, right now, the link
  * {@link ensureStigmerSymlink} makes to `platformDir`. A turn that mounts no
@@ -105,8 +175,8 @@ export async function removeStigmerSymlink(workspaceDir: string): Promise<void>
     if (stat.isSymbolicLink()) {
       await unlink(linkPath);
     }
-  } catch (err: any) {
-    if (err?.code !== "ENOENT") {
+  } catch (err) {
+    if (errnoCode(err) !== "ENOENT") {
       console.warn(
         `removeStigmerSymlink: failed to remove ${linkPath} (non-fatal): ` +
         `${err instanceof Error ? err.message : err}`,

package/src/tools/__tests__/url-guard.test.ts

@@ -131,7 +131,25 @@ describe("validateFetchUrl", () => {
 
   it("rejects unresolvable hostnames", async () => {
     await expect(
-      validateFetchUrl("http://definitely-not-a-real-host.stigmer.invalid/", "strict"),
+      validateFetchUrl("http://definitely-not-a-real-host.stigmer.invalid/", "relaxed"),
     ).rejects.toThrow(/Could not resolve/);
   });
+
+  it("on a strict runner, a name that does not resolve and one that resolves to a refused address read alike and name no address", async () => {
+    const refusals = await Promise.all(
+      ["http://localhost:9999/", "http://definitely-not-a-real-host.stigmer.invalid/"].map((url) =>
+        validateFetchUrl(url, "strict").then(
+          () => {
+            throw new Error(`expected ${url} to be refused`);
+          },
+          (error: unknown) => (error instanceof UrlGuardError ? error.message : String(error)),
+        ),
+      ),
+    );
+    expect(refusals).toEqual([
+      "Refusing to fetch localhost: it does not resolve to a public address.",
+      "Refusing to fetch definitely-not-a-real-host.stigmer.invalid: it does not resolve to a public address.",
+    ]);
+    expect(refusals.join(" ")).not.toMatch(/127\.0\.0\.1|::1|loopback/);
+  });
 });

package/src/tools/url-guard.ts

@@ -12,7 +12,11 @@
  * IPv4-mapped IPv6 is unwrapped, how every resolved address is judged) has
  * one home, `@stigmer/outbound/egress`, shared with the control plane, which
  * dials user-supplied URLs too. This module keeps what is the runner's:
- * deriving the posture from its mode, and the sentence a model reads.
+ * deriving the posture from its mode, and the sentence a model reads. What
+ * that sentence may say is the shared rule too (`refusalWithholdsResolution`):
+ * on a strict runner a name that does not resolve and one that resolves to
+ * a refused address read alike and name no address, because the runner
+ * resolves through a network its caller does not own.
  *
  * Posture is mode-aware because locality differs, not trust:
  *
@@ -41,6 +45,7 @@ import {
   checkEgress,
   egressPolicyForPosture,
   nodeLookup,
+  refusalWithholdsResolution,
   blockedReason as sharedBlockedReason,
   type EgressPosture,
 } from "@stigmer/outbound/egress";
@@ -91,6 +96,9 @@ export async function validateFetchUrl(
   if (check.ok) return check.url;
 
   const refusal = check.refusal;
+  if (refusalWithholdsResolution(refusal) && (refusal.kind === "unresolvable" || refusal.kind === "blocked")) {
+    throw new UrlGuardError(`Refusing to fetch ${refusal.hostname}: it does not resolve to a public address.`);
+  }
   switch (refusal.kind) {
     case "invalid-url":
       throw new UrlGuardError(`Invalid URL: ${refusal.url}`);

package/src/worker.ts

@@ -34,7 +34,17 @@ export interface StartWorkerOptions {
   payloadCodecs?: PayloadCodec[];
 }
 
-export async function startWorker(opts: StartWorkerOptions): Promise<Worker> {
+/**
+ * The worker and the connection it polls on. The caller owns both: it runs
+ * and shuts down the worker, then closes the connection once `run()` has
+ * resolved (the SDK refuses to close a connection a worker still holds).
+ */
+export interface StartedWorker {
+  readonly worker: Worker;
+  readonly connection: NativeConnection;
+}
+
+export async function startWorker(opts: StartWorkerOptions): Promise<StartedWorker> {
   const { config, activities, payloadCodecs } = opts;
 
   const connection = await NativeConnection.connect({
@@ -109,5 +119,5 @@ export async function startWorker(opts: StartWorkerOptions): Promise<Worker> {
     },
   });
 
-  return worker;
+  return { worker, connection };
 }

package/src/workflow-engine/__tests__/golden-execution.test.ts

@@ -164,7 +164,8 @@ describe("Golden Execution — Tier 1c: External Calls", () => {
   it("#03 foreach-loop — for loop with HTTP call per item", async () => {
     const model = loadWorkflowFromYaml(loadGolden("03-foreach-loop.yaml"));
     const state = createState();
-    state.data = { items: ["item1", "item2", "item3"] };
+    // The workflow's input, where the engine puts it (engine-core.ts: state.input = workflow_input).
+    state.input = { items: ["item1", "item2", "item3"] };
 
     const mockCallHttp = vi.fn(async () => fakeHttpResponse());
     const ctx = makeCtx({ callHttp: mockCallHttp });

package/src/workflow-engine/__tests__/loader.test.ts

@@ -391,7 +391,7 @@ do:
       expect(forEntry).toBeDefined();
       if (forEntry?.task.kind === "for") {
         expect(forEntry.task.for.each).toBe("item");
-        expect(forEntry.task.for.in).toBe("${ $data.items }");
+        expect(forEntry.task.for.in).toBe("${ $input.items }");
         expect(forEntry.task.do.length).toBeGreaterThan(0);
       }
     });

package/src/workflow-engine/__tests__/tasks/human-input.test.ts

@@ -1,5 +1,8 @@
 import { describe, it, expect, vi } from "vitest";
-import { executeHumanInputTask } from "../../tasks/human-input.js";
+import {
+  HUMAN_INPUT_FAIL_TIMEOUT_RESOLVED_PATCH,
+  executeHumanInputTask,
+} from "../../tasks/human-input.js";
 import { createState } from "../../state.js";
 import { evaluateExpressionBatch } from "../../expression.js";
 import { TaskStatusAccumulator } from "../../task-status-accumulator.js";
@@ -8,6 +11,7 @@ import type {
   TaskExecutionContext,
   HumanInputExecutionConfig,
   HumanInputResult,
+  HumanInputTimeout,
   AwaitHumanInputFn,
   EmitEventsFn,
   ExpressionEvaluator,
@@ -17,12 +21,16 @@ import type {
 
 const notAvailable = () => { throw new Error("not available in test"); };
 
+/** What the workflow layer reports when the gate's timer wins. */
+const TIMED_OUT: HumanInputTimeout = { timedOut: true };
+
 interface CtxOptions {
   readonly awaitFn?: AwaitHumanInputFn;
   readonly emitFn?: EmitEventsFn;
   readonly evaluateExpressions?: ExpressionEvaluator;
   readonly promoteTaskOutput?: PromoteTaskOutputFn;
   readonly taskStatusAccumulator?: TaskStatusAccumulator;
+  readonly isPatched?: (changeId: string) => boolean;
 }
 
 function makeCtx(
@@ -45,6 +53,7 @@ function makeCtx(
     emitEvents: emitFn,
     promoteTaskOutput: options?.promoteTaskOutput,
     taskStatusAccumulator: options?.taskStatusAccumulator,
+    isPatched: options?.isPatched,
   };
 }
 
@@ -156,11 +165,11 @@ describe("executeHumanInputTask", () => {
       expect(capturedConfig!.timeoutSeconds).toBe(0);
     });
 
-    it("passes onTimeout policy from config", async () => {
+    it("hands the wait only the signal and the timeout; the policy stays with the kernel", async () => {
       let capturedConfig: HumanInputExecutionConfig | undefined;
       const awaitFn: AwaitHumanInputFn = async (config) => {
         capturedConfig = config;
-        return { outcome: "approve", auto_resolved: true, reason: "timeout" };
+        return { outcome: "approve" };
       };
 
       const taskDef: HumanInputTaskDef = {
@@ -170,31 +179,27 @@ describe("executeHumanInputTask", () => {
 
       await executeHumanInputTask(taskDef, "t", createState(), makeCtx(awaitFn));
 
-      expect(capturedConfig!.onTimeout).toBe("approve");
+      expect(capturedConfig).toEqual({ signalName: "human_input_t", timeoutSeconds: 60 });
     });
 
-    it("defaults onTimeout to 'fail' when not set", async () => {
-      let capturedConfig: HumanInputExecutionConfig | undefined;
-      const awaitFn: AwaitHumanInputFn = async (config) => {
-        capturedConfig = config;
-        return { outcome: "approve" };
-      };
-
+    it("fails the task on a timeout when onTimeout is not set", async () => {
       const taskDef: HumanInputTaskDef = {
         kind: "human_input",
         humanInput: { prompt: "Review", timeout: 60 },
       };
 
-      await executeHumanInputTask(taskDef, "t", createState(), makeCtx(awaitFn));
-
-      expect(capturedConfig!.onTimeout).toBe("fail");
+      await expect(
+        executeHumanInputTask(taskDef, "t", createState(), makeCtx(async () => TIMED_OUT)),
+      ).rejects.toThrow("human_input task timed out waiting for signal 'human_input_t'");
     });
   });
 
   describe("error propagation", () => {
-    it("propagates timeout failure errors from orchestrator", async () => {
+    it("propagates an error from the wait untouched and logs no resolution", async () => {
+      const emitted: WorkflowEventDescriptor[][] = [];
+      const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
       const awaitFn: AwaitHumanInputFn = async () => {
-        throw new Error("human_input task timed out");
+        throw new Error("workflow cancelled");
       };
 
       const taskDef: HumanInputTaskDef = {
@@ -203,18 +208,86 @@ describe("executeHumanInputTask", () => {
       };
 
       await expect(
-        executeHumanInputTask(taskDef, "t", createState(), makeCtx(awaitFn)),
+        executeHumanInputTask(taskDef, "t", createState(), makeCtx(awaitFn, emitFn)),
+      ).rejects.toThrow("workflow cancelled");
+      expect(emitted.flat().map((e) => e.type)).toEqual(["approval_requested"]);
+    });
+  });
+
+  // A fail-policy timeout ends the gate without a decision. It still closes
+  // the approval in the event log, so a reader never sees a request left
+  // open, and then fails the task with the error it always raised
+  // (stigmer/stigmer#1442).
+  describe("fail-policy timeout", () => {
+    const taskDef: HumanInputTaskDef = {
+      kind: "human_input",
+      humanInput: { prompt: "Review", timeout: 10, onTimeout: "fail" },
+    };
+
+    it("logs one approval_resolved with auto_resolved and no outcome, then fails the task", async () => {
+      const emitted: WorkflowEventDescriptor[][] = [];
+      const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
+      const state = createState();
+
+      await expect(
+        executeHumanInputTask(taskDef, "gate", state, makeCtx(async () => TIMED_OUT, emitFn)),
+      ).rejects.toThrow("human_input task timed out waiting for signal 'human_input_gate'");
+
+      const resolutions = emitted.flat().filter((e) => e.type === "approval_resolved");
+      expect(resolutions).toHaveLength(1);
+      expect(resolutions[0]).toMatchObject({
+        taskName: "gate",
+        outcome: "",
+        resolvedBy: "",
+        resolvedByActor: undefined,
+        comment: "",
+        autoResolved: true,
+      });
+      expect(state.data.gate, "a failed gate records no decision").toBeUndefined();
+    });
+
+    it("asks the patch gate by its pinned id before logging", async () => {
+      const isPatched = vi.fn(() => true);
+
+      await expect(
+        executeHumanInputTask(taskDef, "gate", createState(), makeCtx(async () => TIMED_OUT, undefined, { isPatched })),
       ).rejects.toThrow("timed out");
+
+      expect(HUMAN_INPUT_FAIL_TIMEOUT_RESOLVED_PATCH).toBe("human-input-fail-timeout-resolved");
+      expect(isPatched).toHaveBeenCalledWith(HUMAN_INPUT_FAIL_TIMEOUT_RESOLVED_PATCH);
+    });
+
+    it("replays a history from before the patch in the old order: no resolution, the same failure", async () => {
+      const emitted: WorkflowEventDescriptor[][] = [];
+      const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
+
+      await expect(
+        executeHumanInputTask(
+          taskDef, "gate", createState(),
+          makeCtx(async () => TIMED_OUT, emitFn, { isPatched: () => false }),
+        ),
+      ).rejects.toThrow("human_input task timed out waiting for signal 'human_input_gate'");
+
+      expect(emitted.flat().map((e) => e.type)).toEqual(["approval_requested"]);
+    });
+
+    it("never asks the patch gate for a gate a policy or a reviewer decided", async () => {
+      const isPatched = vi.fn(() => true);
+      const approveOnTimeout: HumanInputTaskDef = {
+        kind: "human_input",
+        humanInput: { prompt: "Review", timeout: 10, onTimeout: "approve" },
+      };
+
+      await executeHumanInputTask(approveOnTimeout, "a", createState(), makeCtx(async () => TIMED_OUT, undefined, { isPatched }));
+      await executeHumanInputTask(taskDef, "b", createState(), makeCtx(async () => ({ outcome: "approve" }), undefined, { isPatched }));
+
+      expect(isPatched).not.toHaveBeenCalled();
     });
   });
 
   describe("auto-resolved results", () => {
     it("handles auto-approve timeout result", async () => {
-      const awaitFn: AwaitHumanInputFn = async () => ({
-        outcome: "approve",
-        auto_resolved: true,
-        reason: "timeout",
-      });
+      const awaitFn: AwaitHumanInputFn = async () => TIMED_OUT;
 
       const taskDef: HumanInputTaskDef = {
         kind: "human_input",
@@ -229,11 +302,7 @@ describe("executeHumanInputTask", () => {
     });
 
     it("handles auto-deny timeout result", async () => {
-      const awaitFn: AwaitHumanInputFn = async () => ({
-        outcome: "deny",
-        auto_resolved: true,
-        reason: "timeout",
-      });
+      const awaitFn: AwaitHumanInputFn = async () => TIMED_OUT;
 
       const taskDef: HumanInputTaskDef = {
         kind: "human_input",
@@ -260,11 +329,7 @@ describe("executeHumanInputTask", () => {
     ];
 
     it("maps timeout auto-approve to the FIRST outcome and routes its then", async () => {
-      const awaitFn: AwaitHumanInputFn = async () => ({
-        outcome: "approve",
-        auto_resolved: true,
-        reason: "timeout",
-      });
+      const awaitFn: AwaitHumanInputFn = async () => TIMED_OUT;
 
       const taskDef: HumanInputTaskDef = {
         kind: "human_input",
@@ -288,11 +353,7 @@ describe("executeHumanInputTask", () => {
     });
 
     it("maps timeout auto-deny to the LAST outcome", async () => {
-      const awaitFn: AwaitHumanInputFn = async () => ({
-        outcome: "deny",
-        auto_resolved: true,
-        reason: "timeout",
-      });
+      const awaitFn: AwaitHumanInputFn = async () => TIMED_OUT;
 
       const taskDef: HumanInputTaskDef = {
         kind: "human_input",
@@ -310,11 +371,7 @@ describe("executeHumanInputTask", () => {
     // — the ordinary name lookup finds the "escalate" outcome and routes its
     // `then`, regardless of the outcome's position in the list.
     it("resolves timeout escalate to the escalate-named outcome and routes its then", async () => {
-      const awaitFn: AwaitHumanInputFn = async () => ({
-        outcome: "escalate",
-        auto_resolved: true,
-        reason: "timeout",
-      });
+      const awaitFn: AwaitHumanInputFn = async () => TIMED_OUT;
 
       const escalateOutcomes = [
         { name: "proceed", label: "Proceed", then: "deployStep" },
@@ -347,11 +404,7 @@ describe("executeHumanInputTask", () => {
     it("reports the mapped outcome on the approval_resolved event", async () => {
       const emitted: WorkflowEventDescriptor[][] = [];
       const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
-      const awaitFn: AwaitHumanInputFn = async () => ({
-        outcome: "approve",
-        auto_resolved: true,
-        reason: "timeout",
-      });
+      const awaitFn: AwaitHumanInputFn = async () => TIMED_OUT;
 
       const taskDef: HumanInputTaskDef = {
         kind: "human_input",
@@ -385,11 +438,7 @@ describe("executeHumanInputTask", () => {
     });
 
     it("keeps plain approve/deny for binary gates without custom outcomes", async () => {
-      const awaitFn: AwaitHumanInputFn = async () => ({
-        outcome: "approve",
-        auto_resolved: true,
-        reason: "timeout",
-      });
+      const awaitFn: AwaitHumanInputFn = async () => TIMED_OUT;
 
       const taskDef: HumanInputTaskDef = {
         kind: "human_input",
@@ -474,10 +523,40 @@ describe("executeHumanInputTask", () => {
       expect(resolved.outcome).toBe("reject");
       expect(resolved.resolvedBy).toBe("carol");
       expect(resolved.resolvedByActor).toBeUndefined();
+      expect(resolved.comment).toBe("");
       expect(resolved.autoResolved).toBe(false);
       expect(resolved.waitDurationMs).toBeGreaterThanOrEqual(0);
     });
 
+    it("carries the reviewer's comment into approval_resolved and the task output", async () => {
+      const emitted: WorkflowEventDescriptor[][] = [];
+      const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
+      const awaitFn: AwaitHumanInputFn = async () => ({
+        outcome: "deny",
+        reviewer: "ida_01abc",
+        comment: "Rollback plan is missing",
+        responded_at: "2026-05-20T10:00:00Z",
+      });
+
+      const taskDef: HumanInputTaskDef = {
+        kind: "human_input",
+        humanInput: { prompt: "Confirm?" },
+      };
+
+      const state = createState();
+      await executeHumanInputTask(taskDef, "gate", state, makeCtx(awaitFn, emitFn));
+
+      const resolved = emitted[1][0];
+      if (resolved.type !== "approval_resolved") throw new Error("unexpected");
+      expect(resolved.comment).toBe("Rollback plan is missing");
+      expect(state.data.gate).toEqual({
+        outcome: "deny",
+        reviewer: "ida_01abc",
+        comment: "Rollback plan is missing",
+        responded_at: "2026-05-20T10:00:00Z",
+      });
+    });
+
     it("carries the reviewer_actor display snapshot into approval_resolved and the task output", async () => {
       const emitted: WorkflowEventDescriptor[][] = [];
       const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
@@ -607,11 +686,7 @@ describe("executeHumanInputTask", () => {
     it("emits approval_resolved with autoResolved true on timeout auto-approve", async () => {
       const emitted: WorkflowEventDescriptor[][] = [];
       const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
-      const awaitFn: AwaitHumanInputFn = async () => ({
-        outcome: "approve",
-        auto_resolved: true,
-        reason: "timeout",
-      });
+      const awaitFn: AwaitHumanInputFn = async () => TIMED_OUT;
 
       const taskDef: HumanInputTaskDef = {
         kind: "human_input",
@@ -625,6 +700,7 @@ describe("executeHumanInputTask", () => {
 
       expect(resolved.autoResolved).toBe(true);
       expect(resolved.outcome).toBe("approve");
+      expect(resolved.comment).toBe("");
     });
   });