@stigmer/runner 3.12.4 → 3.12.5

package/src/shared/skill-writer.ts

@@ -1,5 +1,5 @@
 /**
- * Skill writing and prompt generation for the deep-agent execution path.
+ * Skill mounting and prompt generation for the deep-agent execution path.
  *
  * Follows the Agent Skills specification progressive disclosure model:
  *
@@ -10,19 +10,33 @@
  * 3. Resources (on demand) — scripts, references, and assets are
  *    loaded by the agent only when required.
  *
- * Skills live under `.stigmer/skills/{name}/` relative to the workspace root.
- * Returned paths are workspace-relative so that the agent's sandbox backend
- * resolves them correctly regardless of mount strategy.
+ * Skills physically live in the session's platform directory
+ * (`{platformDir}/skills/{name}/` — the SAME location the Cursor harness
+ * mounts into), and the agent sees them as `.stigmer/skills/{name}/`
+ * through the per-turn workspace symlink (see workspace/stigmer-link.ts).
+ * Returned paths are the agent-visible `.stigmer/…` form.
+ *
+ * Mounts are cached by the skill's content-addressed version hash via the
+ * shared skill-mount mechanics (issue #337, mirroring the Cursor harness's
+ * #672 fix): metadata is fetched every execution — a pushed skill update
+ * still lands on the very next message — but an unchanged skill skips the
+ * artifact download and rewrite entirely.
  */
 
-import type { WorkspaceBackend } from "./workspace/types.js";
+import { join } from "node:path";
 import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
 import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import type { StigmerClient } from "../client/stigmer-client.js";
-import { extractZipFileEntries } from "./zip-extract.js";
+import {
+  SKILLS_SUBDIR,
+  mountIsFresh,
+  downloadArtifact,
+  writeSkillMount,
+} from "./skill-mount.js";
+import { STIGMER_LOCAL_STATE_DIR } from "./workspace/stigmer-link.js";
 
-const SKILLS_RELATIVE_BASE = ".stigmer/skills";
-const SCRIPT_EXTENSIONS = new Set([".sh", ".py", ".js", ".ts", ".rb", ".pl"]);
+/** Agent-visible base of the skills tree (via the workspace `.stigmer` symlink). */
+const SKILLS_RELATIVE_BASE = `${STIGMER_LOCAL_STATE_DIR}/${SKILLS_SUBDIR}`;
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -81,114 +95,100 @@ export async function fetchSkillsByRefs(
   return results;
 }
 
-// ─── Write ───────────────────────────────────────────────────────────────
+// ─── Mount ───────────────────────────────────────────────────────────────
 
 /**
- * Write skill artifacts to the workspace. Returns a map of
- * skill-id -> workspace-relative directory path.
+ * Mount skills into the session's platform directory, downloading each
+ * skill's artifact only on a version-hash cache miss (see skill-mount.ts
+ * for the marker mechanics). Returns a map of skill-id -> agent-visible
+ * directory path.
+ *
+ * The returned map is a NAMING function, not a success record: every skill
+ * gets its path entry so prompt generation stays total, while mount
+ * failures degrade that one skill (loud log, no throw) — one broken skill
+ * must never kill the run.
  *
- * For each skill:
- * - If a ZIP artifact is available, extract it to .stigmer/skills/{name}/
- * - Otherwise, write just the SKILL.md from the spec
- * - Make scripts executable
+ * Skills mount in parallel (each owns an independent directory), EXCEPT
+ * when two skills resolve to the same directory name (same `spec.name`
+ * from different orgs): concurrent remove-and-rewrite passes on one
+ * directory would corrupt the mount, so only the first claimant mounts and
+ * the collision is logged loudly. (The sequential code this replaced
+ * silently let the last writer win — no better, just quieter.)
  */
-export async function writeSkills(
+export async function mountSkills(
+  client: StigmerClient,
   skills: readonly Skill[],
-  workspaceBackend: WorkspaceBackend,
-  artifacts: ReadonlyMap<string, Uint8Array>,
+  platformDir: string,
 ): Promise<SkillPathMap> {
   const paths = new Map<string, string>();
+  const claims = new Map<string, Skill>();
 
   for (const skill of skills) {
     const name = skill.spec?.name || skill.metadata?.slug || "unknown";
     const skillId = skill.metadata?.id ?? name;
-    const relativeDir = `${SKILLS_RELATIVE_BASE}/${name}`;
-    paths.set(skillId, relativeDir);
+    paths.set(skillId, `${SKILLS_RELATIVE_BASE}/${name}`);
 
-    const artifactBytes = artifacts.get(skillId);
-    if (skill.spec?.skillMd) {
-      const skillMdPath = `${relativeDir}/SKILL.md`;
-      await workspaceBackend.writeFile(skillMdPath, skill.spec.skillMd);
-      if (artifactBytes && artifactBytes.length > 0) {
-        await extractZipToWorkspaceExcluding(artifactBytes, "SKILL.md", relativeDir, workspaceBackend);
-      }
-    } else if (artifactBytes && artifactBytes.length > 0) {
-      await extractZipToWorkspace(artifactBytes, relativeDir, workspaceBackend);
+    // Impossible through the push pipeline (push.go hard-fails a ZIP
+    // without an extractable SKILL.md and always populates spec.skill_md),
+    // so an empty skillMd means a broken resource — skip, same as Cursor.
+    if (!skill.spec?.skillMd) {
+      console.warn(
+        `[skill-writer] skill ${name} (${skillId}) has no skillMd content — skipping mount`,
+      );
+      continue;
     }
 
-    await makeScriptsExecutable(relativeDir, workspaceBackend);
-  }
-
-  return { paths };
-}
-
-/**
- * Compute skill paths without writing anything (for resume integrity checks).
- */
-export function computeSkillPaths(skills: readonly Skill[]): Map<string, string> {
-  const paths = new Map<string, string>();
-  for (const skill of skills) {
-    const name = skill.spec?.name || skill.metadata?.slug || "unknown";
-    const skillId = skill.metadata?.id ?? name;
-    paths.set(skillId, `${SKILLS_RELATIVE_BASE}/${name}`);
+    const prev = claims.get(name);
+    if (prev) {
+      console.warn(
+        `[skill-writer] mount directory collision on '${name}': ` +
+        `${prev.metadata?.org}/${prev.metadata?.slug} already claims it, ` +
+        `skipping ${skill.metadata?.org}/${skill.metadata?.slug}`,
+      );
+      continue;
+    }
+    claims.set(name, skill);
   }
-  return paths;
-}
-
-/**
- * Check workspace integrity for resume fast-path.
- * Returns true if the sentinel SKILL.md file exists for the first skill.
- */
-export async function checkSkillIntegrity(
-  skills: readonly Skill[],
-  workspaceBackend: WorkspaceBackend,
-): Promise<boolean> {
-  if (skills.length === 0) return true;
-
-  const paths = computeSkillPaths(skills);
-  const firstPath = paths.values().next().value;
-  if (!firstPath) return true;
 
-  const sentinel = `${firstPath}/SKILL.md`;
-  return workspaceBackend.exists(sentinel);
-}
+  await Promise.all([...claims.entries()].map(async ([name, skill]) => {
+    const skillDir = join(platformDir, SKILLS_SUBDIR, name);
+    try {
+      const versionHash = skill.status?.versionHash ?? "";
+      const wantsArtifact = Boolean(skill.status?.artifactStorageKey);
 
-// ─── ZIP extraction ──────────────────────────────────────────────────────
+      if (versionHash !== "" && (await mountIsFresh(skillDir, versionHash, wantsArtifact))) {
+        console.log(
+          `[skill-writer] mount cache hit: ${name} (version ${versionHash.slice(0, 12)}) — skipping artifact transfer`,
+        );
+        return;
+      }
 
-async function extractZipToWorkspace(
-  zipBytes: Uint8Array,
-  targetDir: string,
-  backend: WorkspaceBackend,
-): Promise<void> {
-  const entries = await extractZipFileEntries(zipBytes);
-  for (const entry of entries) {
-    await backend.writeFileBuffer(`${targetDir}/${entry.path}`, Buffer.from(entry.content));
-  }
-}
+      let artifactBytes: Uint8Array | undefined;
+      if (wantsArtifact) {
+        try {
+          artifactBytes = await downloadArtifact(client, skill.status!.artifactStorageKey);
+        } catch (err) {
+          // Deliberate degradation, but LOUD (#675): the run still gets
+          // SKILL.md, and the marker records artifactMounted=false so the
+          // next execution retries the download.
+          console.error(
+            `[skill-writer] artifact download FAILED for ${name} ` +
+            `(key=${skill.status!.artifactStorageKey}) — mounting SKILL.md WITHOUT the skill's ` +
+            `supporting files (scripts/references will be missing): ${err instanceof Error ? err.message : err}`,
+          );
+        }
+      }
 
-async function extractZipToWorkspaceExcluding(
-  zipBytes: Uint8Array,
-  excludeName: string,
-  targetDir: string,
-  backend: WorkspaceBackend,
-): Promise<void> {
-  const entries = await extractZipFileEntries(zipBytes, { exclude: [excludeName] });
-  for (const entry of entries) {
-    await backend.writeFileBuffer(`${targetDir}/${entry.path}`, Buffer.from(entry.content));
-  }
-}
+      await writeSkillMount(skill, skillDir, artifactBytes);
+      console.log(`[skill-writer] wrote skill mount: ${name}`);
+    } catch (err) {
+      console.warn(
+        `[skill-writer] failed to mount skill ${name}: ${err instanceof Error ? err.message : err}`,
+      );
+    }
+  }));
 
-async function makeScriptsExecutable(
-  relativeDir: string,
-  backend: WorkspaceBackend,
-): Promise<void> {
-  const extensions = [...SCRIPT_EXTENSIONS].map(ext => `-name '*${ext}'`).join(" -o ");
-  const cmd = `find ${relativeDir} -type f \\( ${extensions} \\) -exec chmod +x {} \\; 2>/dev/null || true`;
-  try {
-    await backend.execute(cmd);
-  } catch {
-    // Non-fatal: scripts may not be executable in all environments
-  }
+  return { paths };
 }
 
 // ─── Prompt generation ───────────────────────────────────────────────────
@@ -264,37 +264,3 @@ export function generateAlsoAvailableSection(
     "read its SKILL.md at `.stigmer/skills/<name>/SKILL.md` to activate it.\n"
   );
 }
-
-// ─── Artifact fetching ───────────────────────────────────────────────────
-
-/**
- * Download skill artifacts for all skills that have a storage key.
- * Returns a map from skill ID to artifact bytes.
- */
-export async function fetchSkillArtifacts(
-  client: StigmerClient,
-  skills: readonly Skill[],
-): Promise<Map<string, Uint8Array>> {
-  const artifacts = new Map<string, Uint8Array>();
-
-  const fetches = skills
-    .filter(s => s.status?.artifactStorageKey)
-    .map(async (skill) => {
-      const key = skill.status!.artifactStorageKey;
-      const skillId = skill.metadata?.id ?? skill.spec?.name ?? "unknown";
-      try {
-        const response = await client.getSkillArtifact(key);
-        if (response.artifact && response.artifact.length > 0) {
-          artifacts.set(skillId, response.artifact);
-        }
-      } catch (err) {
-        console.warn(
-          `[skill-writer] Failed to download artifact for ${skill.spec?.name}: ` +
-          `${err instanceof Error ? err.message : String(err)}. Falling back to SKILL.md only.`,
-        );
-      }
-    });
-
-  await Promise.all(fetches);
-  return artifacts;
-}

package/src/shared/worker-shutdown.ts

@@ -0,0 +1,99 @@
+/**
+ * Per-task-queue worker-shutdown signals — the classification channel that
+ * lets an in-flight activity distinguish "my worker is shutting down" from
+ * "the orchestrator cancelled me" (a user pause).
+ *
+ * The signal carries NO lifecycle authority: aborting it never stops a
+ * worker or an activity (Temporal's own drain does that). It exists purely
+ * so the activity's cancellation handling can classify the interruption
+ * honestly — a shutdown is not a pause, and must surface as the
+ * worker-shutdown failure shape the control planes recognize (issue #776).
+ *
+ * Ownership contract:
+ *   - whoever creates a Worker registers a signal for its queue BEFORE the
+ *     worker starts polling;
+ *   - whoever initiates a full shutdown (SIGTERM handler, desktop quit)
+ *     aborts the signal BEFORE calling worker.shutdown(), so activities
+ *     cancelled by the drain observe it already aborted;
+ *   - a graceful single-worker teardown (view close, deferred teardown in
+ *     the runner-manager) must NOT abort — those paths only run once no
+ *     activity is in flight, and aborting earlier is exactly the regression
+ *     that killed running activities on a view close.
+ *
+ * Module-level (not per-manager) because activities resolve their signal by
+ * task-queue name via {@link getShutdownSignalForQueue} without a handle to
+ * the runner/manager instance that created their worker.
+ */
+
+const registry = new Map<string, AbortController>();
+
+/**
+ * Register a fresh shutdown signal for a task queue, replacing any previous
+ * registration (a re-created worker on a reused queue must not observe the
+ * old worker's aborted signal). Returns the controller so the worker's owner
+ * can abort it at shutdown.
+ */
+export function registerWorkerShutdownSignal(taskQueue: string): AbortController {
+  const controller = new AbortController();
+  registry.set(taskQueue, controller);
+  return controller;
+}
+
+/** The signal an activity on `taskQueue` should observe, if one is registered. */
+export function getShutdownSignalForQueue(taskQueue: string): AbortSignal | undefined {
+  return registry.get(taskQueue)?.signal;
+}
+
+/**
+ * Abort the queue's signal, marking any in-flight activity's imminent
+ * cancellation as a worker shutdown. Idempotent; no-op for an unknown queue.
+ */
+export function signalWorkerShutdown(taskQueue: string): void {
+  registry.get(taskQueue)?.abort();
+}
+
+/** Drop the registration once the queue's worker is fully torn down. */
+export function unregisterWorkerShutdownSignal(taskQueue: string): void {
+  registry.delete(taskQueue);
+}
+
+/** The evidence a turn's post-stream classification weighs (see below). */
+export interface TurnInterruptionEvidence {
+  /** The periodic heartbeat threw CancelledFailure with no shutdown signal. */
+  heartbeatCancelled: boolean;
+  /** The periodic heartbeat threw CancelledFailure with the signal aborted. */
+  heartbeatWorkerShutdown: boolean;
+  /** Temporal delivered cancellation to the activity. */
+  cancellationSignalAborted: boolean;
+  /** This queue's worker-shutdown signal is aborted. */
+  shutdownSignalAborted: boolean;
+}
+
+/**
+ * Classify how (whether) a turn's stream was interrupted, from the evidence
+ * available after the stream ends. Pure so the decision table is directly
+ * testable — the activities feed it their heartbeat flags and signals.
+ *
+ * The load-bearing rule is the grace-window guard (#776): an aborted
+ * shutdown signal ALONE is "none", because a run that completes normally
+ * inside the drain grace window reaches the classification with the signal
+ * already aborted and nothing actually interrupted. Shutdown requires
+ * interruption evidence (a heartbeat CancelledFailure or a delivered
+ * cancellation) alongside the signal; a heartbeat cancellation with no
+ * shutdown signal is the orchestrator's pause.
+ */
+export function classifyTurnInterruption(
+  evidence: TurnInterruptionEvidence,
+): "worker-shutdown" | "pause" | "none" {
+  const interrupted =
+    evidence.heartbeatCancelled ||
+    evidence.heartbeatWorkerShutdown ||
+    evidence.cancellationSignalAborted;
+  if (!interrupted) {
+    return "none";
+  }
+  if (evidence.heartbeatWorkerShutdown || evidence.shutdownSignalAborted) {
+    return "worker-shutdown";
+  }
+  return evidence.heartbeatCancelled ? "pause" : "none";
+}

package/src/shared/workspace/types.ts

@@ -49,8 +49,9 @@ export class WorkspaceProvisionError extends Error {
 /**
  * Abstraction for executing commands inside a workspace.
  *
- * In local mode, commands run via child_process. In cloud mode (Phase 3),
- * commands route through the Daytona sandbox proxy.
+ * Commands run via child_process in both modes: in cloud mode the runner
+ * itself lives inside the sandbox, so "local" execution is already
+ * sandbox-scoped there.
  *
  * When `platformDir` is set, paths under `.stigmer/` are transparently
  * routed to the platform directory instead of the workspace root, keeping

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

@@ -1528,6 +1528,57 @@ do:
       }
     });
 
+    // The server converter persists on_timeout as the proto enum NAME
+    // (HumanInputTimeoutPolicy.String()), so every applied workflow carries
+    // that form in its validated YAML. stigmer/stigmer#779: the loader used
+    // to cast it unvalidated, and the orchestrator's switch silently treated
+    // the unrecognized string as fail.
+    const humanInputYamlWithOnTimeout = (onTimeout: string) => `
+document:
+  dsl: '1.0.0'
+  name: test
+do:
+  - timedApproval:
+      call: human_input
+      with:
+        prompt: "Approve within time limit"
+        timeout: 3600
+        on_timeout: ${onTimeout}
+`;
+
+    it("call: human_input normalizes proto enum-name on_timeout values to the internal policy words", () => {
+      const cases = [
+        ["HUMAN_INPUT_TIMEOUT_FAIL", "fail"],
+        ["HUMAN_INPUT_TIMEOUT_APPROVE", "approve"],
+        ["HUMAN_INPUT_TIMEOUT_DENY", "deny"],
+      ] as const;
+      for (const [wireForm, internalForm] of cases) {
+        const model = loadWorkflowFromYaml(humanInputYamlWithOnTimeout(wireForm));
+        const task = model.do[0].task;
+        expect(task.kind).toBe("human_input");
+        if (task.kind === "human_input") {
+          expect(task.humanInput.onTimeout).toBe(internalForm);
+        }
+      }
+    });
+
+    it("call: human_input rejects the not-implemented escalate policy at load time", () => {
+      for (const form of ["HUMAN_INPUT_TIMEOUT_ESCALATE", "escalate"]) {
+        expect(() => loadWorkflowFromYaml(humanInputYamlWithOnTimeout(form)))
+          .toThrow(/timedApproval.*escalate.*not implemented/);
+      }
+    });
+
+    it("call: human_input rejects unknown on_timeout values instead of silently failing at timeout", () => {
+      expect(() => loadWorkflowFromYaml(humanInputYamlWithOnTimeout("sometimes")))
+        .toThrow(/timedApproval.*unknown on_timeout value 'sometimes'.*fail, approve, deny/);
+    });
+
+    it("call: human_input rejects non-string on_timeout values", () => {
+      expect(() => loadWorkflowFromYaml(humanInputYamlWithOnTimeout("42")))
+        .toThrow(/timedApproval.*on_timeout/);
+    });
+
     it("call: human_input with payload and ui_hint", () => {
       const yaml = `
 document:

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

@@ -246,6 +246,123 @@ describe("executeHumanInputTask", () => {
     });
   });
 
+  // HumanInputTaskConfig.outcomes contract (human_input.proto): with custom
+  // outcomes, timeout auto-approve resolves to the FIRST outcome and timeout
+  // auto-deny to the LAST — downstream `then` routing and outcome switches
+  // must see declared outcome names, never the internal approve/deny words a
+  // reviewer was never offered. stigmer/stigmer#779 made this path reachable
+  // for the first time.
+  describe("timeout outcome mapping with custom outcomes", () => {
+    const outcomes = [
+      { name: "proceed", label: "Proceed", then: "deployStep" },
+      { name: "needs_revision", label: "Needs revision", then: "gatherMore" },
+      { name: "reject", label: "Reject" },
+    ];
+
+    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 taskDef: HumanInputTaskDef = {
+        kind: "human_input",
+        humanInput: { prompt: "Review", timeout: 5, onTimeout: "approve", outcomes },
+      };
+
+      const state = createState();
+      const result = await executeHumanInputTask(taskDef, "gate", state, makeCtx(awaitFn));
+
+      expect(result).toEqual({
+        outcome: "proceed",
+        auto_resolved: true,
+        reason: "timeout",
+        __flow_directive__: "deployStep",
+      });
+      expect(state.data.gate).toEqual({
+        outcome: "proceed",
+        auto_resolved: true,
+        reason: "timeout",
+      });
+    });
+
+    it("maps timeout auto-deny to the LAST outcome", async () => {
+      const awaitFn: AwaitHumanInputFn = async () => ({
+        outcome: "deny",
+        auto_resolved: true,
+        reason: "timeout",
+      });
+
+      const taskDef: HumanInputTaskDef = {
+        kind: "human_input",
+        humanInput: { prompt: "Review", timeout: 5, onTimeout: "deny", outcomes },
+      };
+
+      const result = await executeHumanInputTask(taskDef, "gate", createState(), makeCtx(awaitFn));
+
+      // "reject" is the last outcome and declares no `then` — no directive.
+      expect(result).toEqual({ outcome: "reject", auto_resolved: true, reason: "timeout" });
+    });
+
+    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 taskDef: HumanInputTaskDef = {
+        kind: "human_input",
+        humanInput: { prompt: "Review", timeout: 5, onTimeout: "approve", outcomes },
+      };
+
+      await executeHumanInputTask(taskDef, "gate", createState(), makeCtx(awaitFn, emitFn));
+
+      const resolved = emitted.flat().find((e) => e.type === "approval_resolved");
+      expect(resolved).toMatchObject({ outcome: "proceed", autoResolved: true });
+    });
+
+    it("leaves reviewer-selected outcomes untouched", async () => {
+      const awaitFn: AwaitHumanInputFn = async () => ({
+        outcome: "needs_revision",
+        reviewer: "alice",
+      });
+
+      const taskDef: HumanInputTaskDef = {
+        kind: "human_input",
+        humanInput: { prompt: "Review", timeout: 5, onTimeout: "approve", outcomes },
+      };
+
+      const result = await executeHumanInputTask(taskDef, "gate", createState(), makeCtx(awaitFn));
+
+      expect(result).toEqual({
+        outcome: "needs_revision",
+        reviewer: "alice",
+        __flow_directive__: "gatherMore",
+      });
+    });
+
+    it("keeps plain approve/deny for binary gates without custom outcomes", async () => {
+      const awaitFn: AwaitHumanInputFn = async () => ({
+        outcome: "approve",
+        auto_resolved: true,
+        reason: "timeout",
+      });
+
+      const taskDef: HumanInputTaskDef = {
+        kind: "human_input",
+        humanInput: { prompt: "Review", timeout: 5, onTimeout: "approve" },
+      };
+
+      const result = await executeHumanInputTask(taskDef, "gate", createState(), makeCtx(awaitFn));
+
+      expect(result).toEqual({ outcome: "approve", auto_resolved: true, reason: "timeout" });
+    });
+  });
+
   describe("event emission", () => {
     it("emits approval_requested before blocking with correct fields", async () => {
       const emitted: WorkflowEventDescriptor[][] = [];

package/src/workflow-engine/loader.ts

@@ -608,6 +608,51 @@ function parseServiceTier(raw: unknown): string | undefined {
   return canonical;
 }
 
+/**
+ * Maps on_timeout values to the runner's internal policy words, mirroring
+ * SERVICE_TIER_SHORTHANDS. The persisted CNCF YAML carries the proto enum
+ * NAMES (the server converter emits `HumanInputTimeoutPolicy.String()`),
+ * while hand-written fixtures use the lowercase words — both are accepted.
+ * Unknown values are authoring errors: a timeout policy must never silently
+ * fall back to fail (stigmer/stigmer#779 — the unvalidated cast let every
+ * enum-name policy reach the orchestrator unrecognized, so gates configured
+ * to auto-approve/deny failed at their first real timeout instead).
+ */
+const ON_TIMEOUT_VOCABULARY: Record<string, "fail" | "approve" | "deny"> = {
+  fail: "fail",
+  approve: "approve",
+  deny: "deny",
+  HUMAN_INPUT_TIMEOUT_FAIL: "fail",
+  HUMAN_INPUT_TIMEOUT_APPROVE: "approve",
+  HUMAN_INPUT_TIMEOUT_DENY: "deny",
+};
+
+function parseOnTimeout(
+  taskName: string,
+  raw: unknown,
+): "fail" | "approve" | "deny" | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  if (typeof raw !== "string") {
+    throw new Error(`human_input task '${taskName}': 'on_timeout' must be a string`);
+  }
+  // The proto declares HUMAN_INPUT_TIMEOUT_ESCALATE but no runtime exists
+  // for it yet; refuse at load rather than misbehave at the gate's timeout.
+  if (raw === "HUMAN_INPUT_TIMEOUT_ESCALATE" || raw === "escalate") {
+    throw new Error(
+      `human_input task '${taskName}': on_timeout policy 'escalate' is not implemented — ` +
+      `use fail, approve, or deny (custom outcomes with 'then' cover reviewer-driven branching)`,
+    );
+  }
+  const policy = ON_TIMEOUT_VOCABULARY[raw];
+  if (!policy) {
+    throw new Error(
+      `human_input task '${taskName}': unknown on_timeout value '${raw}' ` +
+      `(expected: fail, approve, deny, or a HUMAN_INPUT_TIMEOUT_* enum name)`,
+    );
+  }
+  return policy;
+}
+
 function parseHumanInputConfig(taskName: string, raw: unknown): import("./types.js").HumanInputConfig {
   if (!raw || typeof raw !== "object") {
     throw new Error(`human_input task '${taskName}' requires a 'with' configuration block`);
@@ -630,7 +675,7 @@ function parseHumanInputConfig(taskName: string, raw: unknown): import("./types.
       ? obj.approvers.filter((a: unknown) => typeof a === "string") as string[]
       : undefined,
     timeout: typeof obj.timeout === "number" ? obj.timeout : undefined,
-    onTimeout: (obj.on_timeout as "fail" | "approve" | "deny") ?? undefined,
+    onTimeout: parseOnTimeout(taskName, obj.on_timeout),
     // Any JSON shape is a valid payload (expression string, object, array),
     // so only null/undefined mean "no payload" here.
     payload: obj.payload ?? undefined,