@united-workforce/cli 0.2.1-rc.9 → 0.4.0

package/src/commands/thread.ts

@@ -1,6 +1,6 @@
 import { execFileSync, spawn } from "node:child_process";
 import { access, readFile } from "node:fs/promises";
-import { dirname, isAbsolute, resolve as resolvePath } from "node:path";
+import { dirname, isAbsolute, join, resolve as resolvePath } from "node:path";
 import type { VarStore } from "@ocas/core";
 import { validate } from "@ocas/core";
 import type {
@@ -22,6 +22,7 @@ import type {
 import {
   createThreadIndexEntry,
   markThreadSuspended,
+  SUSPEND_STATUS,
   updateThreadHead,
 } from "@united-workforce/protocol";
 import {
@@ -34,12 +35,20 @@ import type { AdapterOutput } from "@united-workforce/util-agent";
 import { getEnvPath, loadWorkflowConfig } from "@united-workforce/util-agent";
 import { config as loadDotenv } from "dotenv";
 import { parse } from "yaml";
-import { createMarker, deleteMarker, isThreadRunning } from "../background/index.js";
+import {
+  createMarker,
+  deleteMarker,
+  getProcessStartTime,
+  isMarkerValid,
+  isThreadRunning,
+  readMarker,
+} from "../background/index.js";
 import { createIncludeTag } from "../include.js";
-import { evaluate, isSuspendResult } from "../moderator/index.js";
+import { evaluate } from "../moderator/index.js";
 import {
   completeThread,
   createUwfStore,
+  findRegistryName,
   getThread,
   loadActiveThreads,
   loadHistoryThreads,
@@ -47,6 +56,7 @@ import {
   resolveWorkflowHash,
   setThread,
   type UwfStore,
+  type WorkflowRegistry,
 } from "../store.js";
 import { checkWorkflowFilenameConsistency, isCasRef, parseWorkflowPayload } from "../validate.js";
 import { validateWorkflow } from "../validate-semantic.js";
@@ -64,53 +74,49 @@ const END_ROLE = "$END";
 const START_ROLE = "$START";
 export const THREAD_READ_DEFAULT_QUOTA = 4000;
 
-function buildStepOutputFromEvaluation(
+/**
+ * Read the suspend reason from an agent output if it is an engine-level suspend
+ * (coroutine yield). Returns the reason string when `$status === "$SUSPEND"`,
+ * or `null` otherwise. A suspend output with no `reason` yields an empty string.
+ */
+function readSuspendReason(lastOutput: Record<string, unknown>): string | null {
+  if (lastOutput[STATUS_KEY] !== SUSPEND_STATUS) {
+    return null;
+  }
+  const reason = lastOutput.reason;
+  return typeof reason === "string" ? reason : "";
+}
+
+function buildSuspendStepOutput(
   workflowHash: CasRef,
   threadId: ThreadId,
   head: CasRef,
-  status: ThreadStatus,
-  evaluation: ReturnType<typeof evaluate>,
-  background: boolean | null,
+  suspendedRole: string,
+  suspendMessage: string,
 ): StepOutput {
-  const done = status === "completed";
-  let currentRole: string | null = null;
-  let suspendedRole: string | null = null;
-  let suspendMessage: string | null = null;
-  if (evaluation.ok) {
-    if (isSuspendResult(evaluation.value)) {
-      suspendedRole = evaluation.value.suspendedRole;
-      suspendMessage = evaluation.value.prompt;
-    } else if (evaluation.value.role !== END_ROLE) {
-      currentRole = evaluation.value.role;
-    }
-  }
   return {
     workflow: workflowHash,
     thread: threadId,
     head,
-    status,
-    currentRole,
+    status: "suspended",
+    currentRole: null,
     suspendedRole,
     suspendMessage,
-    done,
-    background,
+    done: false,
+    background: null,
+    error: null,
   };
 }
 
-function resolveSuspendFieldsFromGraph(
+function resolveSuspendFieldsFromOutput(
   uwf: UwfStore,
   head: CasRef,
-  workflowRef: CasRef,
 ): { suspendedRole: string | null; suspendMessage: string | null } {
   const chain = walkChain(uwf, head);
   const { lastRole, lastOutput } = resolveEvaluateArgs(uwf, chain);
-  const workflow = loadWorkflowPayload(uwf, workflowRef);
-  const result = evaluate(workflow.graph, lastRole, lastOutput);
-  if (result.ok && isSuspendResult(result.value)) {
-    return {
-      suspendedRole: result.value.suspendedRole,
-      suspendMessage: result.value.prompt,
-    };
+  const reason = readSuspendReason(lastOutput);
+  if (reason !== null) {
+    return { suspendedRole: lastRole, suspendMessage: reason };
   }
   return { suspendedRole: null, suspendMessage: null };
 }
@@ -120,7 +126,6 @@ function resolveSuspendFieldsForShow(
   status: ThreadStatus,
   uwf: UwfStore,
   head: CasRef,
-  workflowRef: CasRef,
 ): { suspendedRole: string | null; suspendMessage: string | null } {
   if (status !== "suspended") {
     return { suspendedRole: null, suspendMessage: null };
@@ -128,10 +133,10 @@ function resolveSuspendFieldsForShow(
   if (entry.suspendedRole !== null && entry.suspendMessage !== null) {
     return { suspendedRole: entry.suspendedRole, suspendMessage: entry.suspendMessage };
   }
-  const fromGraph = resolveSuspendFieldsFromGraph(uwf, head, workflowRef);
+  const fromOutput = resolveSuspendFieldsFromOutput(uwf, head);
   return {
-    suspendedRole: entry.suspendedRole ?? fromGraph.suspendedRole,
-    suspendMessage: entry.suspendMessage ?? fromGraph.suspendMessage,
+    suspendedRole: entry.suspendedRole ?? fromOutput.suspendedRole,
+    suspendMessage: entry.suspendMessage ?? fromOutput.suspendMessage,
   };
 }
 
@@ -155,7 +160,6 @@ async function resolveActiveThreadStatus(
   threadId: ThreadId,
   uwf: UwfStore,
   head: CasRef,
-  workflowRef: CasRef,
 ): Promise<ThreadStatus> {
   const runningMarker = await isThreadRunning(storageRoot, threadId);
   if (runningMarker !== null) {
@@ -163,10 +167,8 @@ async function resolveActiveThreadStatus(
   }
 
   const chain = walkChain(uwf, head);
-  const { lastRole, lastOutput } = resolveEvaluateArgs(uwf, chain);
-  const workflow = loadWorkflowPayload(uwf, workflowRef);
-  const result = evaluate(workflow.graph, lastRole, lastOutput);
-  if (result.ok && isSuspendResult(result.value)) {
+  const { lastOutput } = resolveEvaluateArgs(uwf, chain);
+  if (readSuspendReason(lastOutput) !== null) {
     return "suspended";
   }
 
@@ -180,12 +182,15 @@ async function resolveActiveThreadStatus(
 function resolveCurrentRole(uwf: UwfStore, head: CasRef, workflowRef: CasRef): string | null {
   const chain = walkChain(uwf, head);
   const { lastRole, lastOutput } = resolveEvaluateArgs(uwf, chain);
+  if (readSuspendReason(lastOutput) !== null) {
+    return null;
+  }
   const workflow = loadWorkflowPayload(uwf, workflowRef);
   const result = evaluate(workflow.graph, lastRole, lastOutput);
   if (!result.ok) {
     return null;
   }
-  if (isSuspendResult(result.value) || result.value.role === END_ROLE) {
+  if (result.value.role === END_ROLE) {
     return null;
   }
   return result.value.role;
@@ -195,10 +200,12 @@ const PL_THREAD_START = "7HNQ4B2X";
 const PL_MODERATOR = "M3K8V9T1";
 const PL_AGENT_SPAWN = "R5J2W8N4";
 const PL_AGENT_DONE = "C6P9E3H7";
+const PL_AGENT_ERROR = "Z3F7K8M2";
 const PL_THREAD_ARCHIVED = "F4D8Q2K5";
 const PL_STEP_ERROR = "B8T5N1V6";
 const PL_BACKGROUND_START = "X7Q4W9M2";
 const PL_THREAD_RESUME = "K2R7M4N8";
+const PL_THREAD_POKE = "P4Q9R3X7";
 
 type ResumeStepConfig = {
   role: string;
@@ -246,18 +253,19 @@ async function workflowFileExists(dir: string, name: string, ext: string): Promi
 }
 
 /**
- * Search for a workflow file in a given directory (checks both .workflow/ and .workflows/).
+ * Search for a workflow file in a given directory (checks both .workflows/ and .workflow/).
+ * `.workflows/` (primary) takes priority over `.workflow/` (legacy fallback).
  */
 async function findWorkflowInDir(dir: string, name: string): Promise<string | null> {
-  // Check .workflow/ directory first (preferred)
+  // Check .workflows/ directory first (primary)
   for (const ext of [".yaml", ".yml"]) {
-    const result = await workflowFileExists(resolvePath(dir, ".workflow"), name, ext);
+    const result = await workflowFileExists(resolvePath(dir, ".workflows"), name, ext);
     if (result !== null) {
       return result;
     }
   }
   for (const indexName of ["index.yaml", "index.yml"]) {
-    const candidate = resolvePath(dir, ".workflow", name, indexName);
+    const candidate = resolvePath(dir, ".workflows", name, indexName);
     try {
       await access(candidate);
       return candidate;
@@ -266,15 +274,15 @@ async function findWorkflowInDir(dir: string, name: string): Promise<string | nu
     }
   }
 
-  // Check .workflows/ directory as fallback (legacy)
+  // Check .workflow/ directory as fallback (legacy)
   for (const ext of [".yaml", ".yml"]) {
-    const result = await workflowFileExists(resolvePath(dir, ".workflows"), name, ext);
+    const result = await workflowFileExists(resolvePath(dir, ".workflow"), name, ext);
     if (result !== null) {
       return result;
     }
   }
   for (const indexName of ["index.yaml", "index.yml"]) {
-    const candidate = resolvePath(dir, ".workflows", name, indexName);
+    const candidate = resolvePath(dir, ".workflow", name, indexName);
     try {
       await access(candidate);
       return candidate;
@@ -286,8 +294,21 @@ async function findWorkflowInDir(dir: string, name: string): Promise<string | nu
   return null;
 }
 
+/** Check if a directory contains a .git marker (directory or file). */
+async function hasGitMarker(dir: string): Promise<boolean> {
+  try {
+    await access(join(dir, ".git"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
- * Traverse parent directories looking for `.workflow/<name>.yaml` or `.workflow/<name>.yml`.
+ * Traverse parent directories looking for a workflow named `name` under
+ * `.workflows/` (primary) or `.workflow/` (legacy fallback). Within each
+ * directory the lookup checks flat YAML files (`<name>.yaml`/`.yml`) and
+ * folder-based layouts (`<name>/index.yaml`/`.yml`).
  * Returns the absolute path if found, otherwise null.
  * Stops at filesystem root or .git directory.
  */
@@ -301,6 +322,11 @@ async function findWorkflowInParents(startDir: string, name: string): Promise<st
       return found;
     }
 
+    // Stop at .git boundary (repo root)
+    if (await hasGitMarker(currentDir)) {
+      break;
+    }
+
     // Stop at filesystem root
     if (currentDir === root) {
       break;
@@ -492,8 +518,8 @@ export async function cmdThreadShow(
     fail(`failed to resolve workflow from head: ${activeHead}`);
   }
 
-  // Determine if this is a completed/cancelled thread
-  if (entry.status === "completed" || entry.status === "cancelled") {
+  // Determine if this is an ended/cancelled thread
+  if (entry.status === "end" || entry.status === "cancelled") {
     const hint = null;
     return {
       workflow,
@@ -505,14 +531,15 @@ export async function cmdThreadShow(
       suspendMessage: null,
       done: true,
       background: null,
+      error: null,
       hint,
     };
   }
 
   // Active thread
-  const status = await resolveActiveThreadStatus(storageRoot, threadId, uwf, activeHead, workflow);
+  const status = await resolveActiveThreadStatus(storageRoot, threadId, uwf, activeHead);
   const currentRole = resolveCurrentRole(uwf, activeHead, workflow);
-  const suspendFields = resolveSuspendFieldsForShow(entry, status, uwf, activeHead, workflow);
+  const suspendFields = resolveSuspendFieldsForShow(entry, status, uwf, activeHead);
 
   const hint =
     status === "suspended"
@@ -529,6 +556,7 @@ export async function cmdThreadShow(
     suspendMessage: suspendFields.suspendMessage,
     done: false,
     background: null,
+    error: null,
     hint,
   };
 }
@@ -538,6 +566,8 @@ export type ThreadListItemWithStatus = ThreadListItem & {
   currentRole: string | null;
   /** Display label with status marker for suspended threads */
   statusDisplay: string;
+  /** Resolved workflow name from registry, or null if orphaned (hash not in registry) */
+  workflowName: string | null;
 };
 
 export type ThreadShowOutput = StepOutput & {
@@ -550,13 +580,23 @@ async function threadListItemFromActive(
   uwf: UwfStore,
   threadId: ThreadId,
   head: CasRef,
+  registry: WorkflowRegistry,
 ): Promise<ThreadListItemWithStatus | null> {
   const workflow = resolveWorkflowFromHead(uwf, head);
   if (workflow === null) {
-    return null;
+    // Head CAS node missing or unrecognized — treat as corrupt rather than silently skipping
+    return {
+      thread: threadId,
+      workflow: "" as CasRef,
+      head,
+      status: "corrupt",
+      currentRole: null,
+      statusDisplay: "corrupt",
+      workflowName: null,
+    };
   }
 
-  const status = await resolveActiveThreadStatus(storageRoot, threadId, uwf, head, workflow);
+  const status = await resolveActiveThreadStatus(storageRoot, threadId, uwf, head);
   const statusDisplay = status === "suspended" ? `${status} [suspended]` : status;
 
   return {
@@ -566,6 +606,7 @@ async function threadListItemFromActive(
     status,
     currentRole: resolveCurrentRole(uwf, head, workflow),
     statusDisplay,
+    workflowName: findRegistryName(registry, workflow),
   };
 }
 
@@ -573,12 +614,33 @@ async function collectActiveThreads(
   storageRoot: string,
   uwf: UwfStore,
   index: ThreadsIndex,
+  registry: WorkflowRegistry,
 ): Promise<ThreadListItemWithStatus[]> {
   const items: ThreadListItemWithStatus[] = [];
   for (const [threadId, entry] of Object.entries(index)) {
-    const item = await threadListItemFromActive(storageRoot, uwf, threadId as ThreadId, entry.head);
-    if (item !== null) {
-      items.push(item);
+    try {
+      const item = await threadListItemFromActive(
+        storageRoot,
+        uwf,
+        threadId as ThreadId,
+        entry.head,
+        registry,
+      );
+      if (item !== null) {
+        items.push(item);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`warning: thread ${threadId} is corrupt: ${message}\n`);
+      items.push({
+        thread: threadId as ThreadId,
+        workflow: "" as CasRef,
+        head: entry.head,
+        status: "corrupt",
+        currentRole: null,
+        statusDisplay: "corrupt",
+        workflowName: null,
+      });
     }
   }
   return items;
@@ -587,6 +649,7 @@ async function collectActiveThreads(
 function collectCompletedThreads(
   uwf: UwfStore,
   activeIds: Set<ThreadId>,
+  registry: WorkflowRegistry,
 ): ThreadListItemWithStatus[] {
   const items: ThreadListItemWithStatus[] = [];
   const history = loadHistoryThreads(uwf.varStore);
@@ -594,16 +657,31 @@ function collectCompletedThreads(
   for (const [threadId, entry] of Object.entries(history)) {
     if (!activeIds.has(threadId as ThreadId) && !seen.has(threadId as ThreadId)) {
       seen.add(threadId as ThreadId);
-      const status = entry.status;
-      const workflow = resolveWorkflowFromHead(uwf, entry.head);
-      items.push({
-        thread: threadId as ThreadId,
-        workflow: workflow ?? "",
-        head: entry.head,
-        status,
-        currentRole: null,
-        statusDisplay: status,
-      });
+      try {
+        const status = entry.status;
+        const workflow = resolveWorkflowFromHead(uwf, entry.head);
+        items.push({
+          thread: threadId as ThreadId,
+          workflow: workflow ?? "",
+          head: entry.head,
+          status,
+          currentRole: null,
+          statusDisplay: status,
+          workflowName: workflow !== null ? findRegistryName(registry, workflow) : null,
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`warning: completed thread ${threadId} is corrupt: ${message}\n`);
+        items.push({
+          thread: threadId as ThreadId,
+          workflow: "" as CasRef,
+          head: entry.head,
+          status: "corrupt",
+          currentRole: null,
+          statusDisplay: "corrupt",
+          workflowName: null,
+        });
+      }
     }
   }
   return items;
@@ -649,27 +727,35 @@ export async function cmdThreadList(
   beforeMs: number | null,
   skip: number | null,
   take: number | null,
+  showAll: boolean = false,
 ): Promise<ThreadListItemWithStatus[]> {
   const uwf = await createUwfStore(storageRoot);
   const index = loadActiveThreads(uwf.varStore);
+  const registry = loadWorkflowRegistry(uwf.varStore);
+
+  // Resolve the effective filter:
+  //   - explicit --status wins (showAll has no effect)
+  //   - otherwise: --all → no filter; default → ["idle", "running"]
+  const effectiveFilter: ThreadStatus[] | null =
+    statusFilter !== null ? statusFilter : showAll ? null : ["idle", "running", "corrupt"];
 
   // Collect active threads
-  let items = await collectActiveThreads(storageRoot, uwf, index);
+  let items = await collectActiveThreads(storageRoot, uwf, index, registry);
 
   // Collect completed threads (if relevant for status filter)
   const includeCompleted =
-    statusFilter === null ||
-    statusFilter.includes("completed") ||
-    statusFilter.includes("cancelled");
+    effectiveFilter === null ||
+    effectiveFilter.includes("end") ||
+    effectiveFilter.includes("cancelled");
   if (includeCompleted) {
     const activeIds = new Set(items.map((i) => i.thread));
-    const completedItems = collectCompletedThreads(uwf, activeIds);
+    const completedItems = collectCompletedThreads(uwf, activeIds, registry);
     items = items.concat(completedItems);
   }
 
   // Apply status filter
-  if (statusFilter !== null) {
-    items = items.filter((item) => statusFilter.includes(item.status));
+  if (effectiveFilter !== null) {
+    items = items.filter((item) => effectiveFilter.includes(item.status));
   }
 
   // Apply time range filters
@@ -985,18 +1071,14 @@ function resolveAgentConfig(
   return agentConfig;
 }
 
-function spawnAgent(
-  plog: ProcessLogger,
+function executeAgentCommand(
   agent: AgentConfig,
-  threadId: ThreadId,
-  role: string,
-  edgePrompt: string,
+  argv: readonly string[],
   cwd: string,
-): AdapterOutput {
-  const argv = [...agent.args, "--thread", threadId, "--role", role, "--prompt", edgePrompt];
-  let stdout: string;
+  plog: ProcessLogger,
+): string {
   try {
-    stdout = execFileSync(agent.command, argv, {
+    return execFileSync(agent.command, argv, {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
       maxBuffer: 50 * 1024 * 1024, // 50 MB — stream-json output can be large
@@ -1019,14 +1101,22 @@ function spawnAgent(
     const detail = stderr.trim() !== "" ? `: ${stderr.trim()}` : "";
     failStep(plog, `agent command failed (${agent.command})${detail}`);
   }
+}
 
+function parseAgentOutput(stdout: string, plog: ProcessLogger): unknown {
   const line = stdout.trim().split("\n").pop()?.trim() ?? "";
-  let parsed: unknown;
   try {
-    parsed = JSON.parse(line);
+    return JSON.parse(line);
   } catch {
     failStep(plog, `agent stdout last line is not valid JSON: ${line || "(empty)"}`);
   }
+}
+
+function validateAndNormalizeOutput(
+  parsed: unknown,
+  line: string,
+  plog: ProcessLogger,
+): AdapterOutput {
   const obj = parsed as Record<string, unknown>;
   if (
     typeof obj !== "object" ||
@@ -1036,11 +1126,44 @@ function spawnAgent(
   ) {
     failStep(plog, `agent stdout JSON missing valid stepHash: ${line}`);
   }
+  // Normalize isError / errorMessage so downstream code can rely on them.
+  // Legacy adapters that don't emit these fields default to isError=false.
+  if (obj.isError !== undefined && typeof obj.isError !== "boolean") {
+    failStep(plog, `agent stdout JSON has non-boolean isError: ${line}`);
+  }
+  if (obj.isError === undefined) {
+    obj.isError = false;
+  }
+  if (
+    obj.errorMessage !== undefined &&
+    obj.errorMessage !== null &&
+    typeof obj.errorMessage !== "string"
+  ) {
+    failStep(plog, `agent stdout JSON has non-string errorMessage: ${line}`);
+  }
+  if (obj.errorMessage === undefined) {
+    obj.errorMessage = null;
+  }
   return obj as unknown as AdapterOutput;
 }
 
+function spawnAgent(
+  plog: ProcessLogger,
+  agent: AgentConfig,
+  threadId: ThreadId,
+  role: string,
+  edgePrompt: string,
+  cwd: string,
+): AdapterOutput {
+  const argv = [...agent.args, "--thread", threadId, "--role", role, "--prompt", edgePrompt];
+  const stdout = executeAgentCommand(agent, argv, cwd, plog);
+  const line = stdout.trim().split("\n").pop()?.trim() ?? "";
+  const parsed = parseAgentOutput(stdout, plog);
+  return validateAndNormalizeOutput(parsed, line, plog);
+}
+
 function archiveThread(uwf: UwfStore, threadId: ThreadId, _workflow: CasRef, _head: CasRef): void {
-  completeThread(uwf.varStore, threadId, "completed");
+  completeThread(uwf.varStore, threadId, "end");
 }
 
 export async function cmdThreadResume(
@@ -1064,15 +1187,15 @@ export async function cmdThreadResume(
   const chain = walkChain(uwf, headHash);
   const workflowHash = chain.start.workflow;
 
-  // Check entry.status first for completed/cancelled (like in cmdThreadShow)
+  // Check entry.status first for end/cancelled (like in cmdThreadShow)
   let status: ThreadStatus;
-  if (entry.status === "completed" || entry.status === "cancelled") {
+  if (entry.status === "end" || entry.status === "cancelled") {
     status = entry.status;
   } else {
-    status = await resolveActiveThreadStatus(storageRoot, threadId, uwf, headHash, workflowHash);
+    status = await resolveActiveThreadStatus(storageRoot, threadId, uwf, headHash);
   }
 
-  if (status !== "suspended" && status !== "completed") {
+  if (status !== "suspended" && status !== "end") {
     fail(`thread cannot be resumed: ${threadId} (status: ${status})`);
   }
 
@@ -1082,7 +1205,7 @@ export async function cmdThreadResume(
   });
 
   if (status === "suspended") {
-    const suspendFields = resolveSuspendFieldsForShow(entry, status, uwf, headHash, workflowHash);
+    const suspendFields = resolveSuspendFieldsForShow(entry, status, uwf, headHash);
     if (suspendFields.suspendedRole === null) {
       fail(`thread is suspended but suspendedRole is missing: ${threadId}`);
     }
@@ -1104,21 +1227,18 @@ export async function cmdThreadResume(
     });
   }
 
-  // status === "completed"
+  // status === "end"
   const workflow = loadWorkflowPayload(uwf, workflowHash);
   const startResult = evaluate(workflow.graph, START_ROLE, { [STATUS_KEY]: "resume" });
   if (!startResult.ok) {
     fail(`failed to evaluate $START: ${startResult.error.message}`);
   }
-  if (isSuspendResult(startResult.value)) {
-    fail("workflow cannot start with $SUSPEND");
-  }
   if (startResult.value.role === END_ROLE) {
     fail("workflow cannot start with $END");
   }
 
   const startRole = startResult.value.role;
-  const completedResumePrompt = buildResumePrompt(startResult.value.prompt, supplement);
+  const endResumePrompt = buildResumePrompt(startResult.value.prompt, supplement);
 
   const updatedEntry = { ...entry, status: "idle" as const, completedAt: null };
   setThread(uwf.varStore, threadId, updatedEntry);
@@ -1131,10 +1251,155 @@ export async function cmdThreadResume(
 
   return cmdThreadStepOnce(storageRoot, threadId, agentOverride, plog, {
     role: startRole,
-    prompt: completedResumePrompt,
+    prompt: endResumePrompt,
   });
 }
 
+/**
+ * Validate that a thread can be poked. Returns the existing entry and the head StepNode payload.
+ * Fails (process exit) when the thread is missing, running, completed, cancelled, or has no
+ * StepNode at its head.
+ */
+async function validatePokePreconditions(
+  storageRoot: string,
+  uwf: UwfStore,
+  threadId: ThreadId,
+): Promise<{ entry: ThreadIndexEntry; oldHead: CasRef; oldHeadPayload: StepNodePayload }> {
+  const runningMarker = await isThreadRunning(storageRoot, threadId);
+  if (runningMarker !== null) {
+    fail(`thread already executing in background (PID: ${runningMarker.pid})`);
+  }
+
+  const entry = getThread(uwf.varStore, threadId);
+  if (entry === null) {
+    fail(`thread not active: ${threadId}`);
+  }
+
+  if (entry.status === "end" || entry.status === "cancelled") {
+    fail(`thread cannot be poked: ${threadId} (status: ${entry.status})`);
+  }
+
+  const oldHead = entry.head;
+  const oldHeadNode = uwf.store.cas.get(oldHead);
+  if (oldHeadNode === null) {
+    fail(`CAS node not found: ${oldHead}`);
+  }
+  if (oldHeadNode.type !== uwf.schemas.stepNode) {
+    fail("thread cannot be poked: no step to replace (head is StartNode)");
+  }
+
+  return { entry, oldHead, oldHeadPayload: oldHeadNode.payload as StepNodePayload };
+}
+
+/**
+ * Resolve the next role from the post-poke chain state, used for the StepOutput.currentRole field.
+ * Returns null when the next role is $END, evaluation fails, or the result is a suspend.
+ */
+function resolveCurrentRoleFromChain(
+  uwfAfter: UwfStore,
+  workflow: WorkflowPayload,
+  replacedHash: CasRef,
+): string | null {
+  const chainAfter = walkChain(uwfAfter, replacedHash);
+  const { lastRole, lastOutput } = resolveEvaluateArgs(uwfAfter, chainAfter);
+  if (readSuspendReason(lastOutput) !== null) {
+    return null;
+  }
+  const afterResult = evaluate(workflow.graph, lastRole, lastOutput);
+  if (!afterResult.ok) {
+    return null;
+  }
+  if (afterResult.value.role === END_ROLE) {
+    return null;
+  }
+  return afterResult.value.role;
+}
+
+/**
+ * Poke a thread: re-run the agent on the head step with a supplementary prompt,
+ * replacing the head step's output. The new step's `prev` points to the OLD head's
+ * `prev` — semantically replacing (not appending to) the head. The moderator is NOT
+ * re-evaluated for routing; the role of the head step is re-used.
+ */
+export async function cmdThreadPoke(
+  storageRoot: string,
+  threadId: ThreadId,
+  prompt: string,
+  agentOverride: string | null,
+): Promise<StepOutput> {
+  const uwf = await createUwfStore(storageRoot);
+  const { entry, oldHeadPayload } = await validatePokePreconditions(storageRoot, uwf, threadId);
+
+  const chain = walkChain(uwf, entry.head);
+  const workflowHash = chain.start.workflow;
+  const threadCwd = chain.start.cwd;
+
+  const plog = createProcessLogger({
+    storageRoot,
+    context: { thread: threadId, workflow: workflowHash },
+  });
+
+  // Resolve the agent: --agent override wins; otherwise read from old head step's `agent` field.
+  const config = await loadWorkflowConfig(storageRoot);
+  const workflow = loadWorkflowPayload(uwf, workflowHash);
+  const role = oldHeadPayload.role;
+  const agent =
+    agentOverride !== null
+      ? resolveAgentConfig(config, workflow, role, agentOverride)
+      : parseAgentOverride(oldHeadPayload.agent);
+
+  const effectiveCwd = oldHeadPayload.cwd !== "" ? oldHeadPayload.cwd : threadCwd;
+
+  plog.log(PL_THREAD_POKE, `poke role=${role} agent=${agent.command}`, null);
+  plog.log(PL_AGENT_SPAWN, `spawning agent command=${agent.command}`, {
+    args: [...agent.args, threadId, role].join(" "),
+  });
+
+  loadDotenv({ path: getEnvPath(storageRoot) });
+
+  // Spawn the agent. The agent will create a new StepNode with prev=oldHead (it reads
+  // the active thread head). After the agent returns, we rewrite that node's prev so
+  // that the new head replaces the old head instead of appending after it.
+  const agentResult = spawnAgent(plog, agent, threadId, role, prompt, effectiveCwd);
+  const agentStepHash = agentResult.stepHash as CasRef;
+
+  plog.log(PL_AGENT_DONE, `agent returned head=${agentStepHash}`, null);
+
+  const uwfAfter = await createUwfStore(storageRoot);
+  const agentNode = uwfAfter.store.cas.get(agentStepHash);
+  if (agentNode === null || agentNode.type !== uwfAfter.schemas.stepNode) {
+    failStep(plog, `agent returned hash that is not a StepNode: ${agentStepHash}`);
+  }
+  const agentPayload = agentNode.payload as StepNodePayload;
+
+  // Rewrite the new step so that its `prev` points to the OLD head's prev (replace semantics).
+  const replacedPayload: StepNodePayload = {
+    ...agentPayload,
+    prev: oldHeadPayload.prev,
+  };
+  const replacedHash = await uwfAfter.store.cas.put(uwfAfter.schemas.stepNode, replacedPayload);
+  const replacedNode = uwfAfter.store.cas.get(replacedHash);
+  if (replacedNode === null || !validate(uwfAfter.store, replacedNode)) {
+    failStep(plog, "rewritten StepNode failed schema validation");
+  }
+
+  // Update thread head to the replaced step. Status becomes idle (no moderator re-route).
+  setThread(uwfAfter.varStore, threadId, updateThreadHead(entry, replacedHash));
+
+  return {
+    workflow: workflowHash,
+    thread: threadId,
+    head: replacedHash,
+    status: "idle",
+    currentRole: resolveCurrentRoleFromChain(uwfAfter, workflow, replacedHash),
+    suspendedRole: null,
+    suspendMessage: null,
+    done: false,
+    background: null,
+    error: null,
+  };
+}
+
 export function validateCount(count: number): void {
   if (count < 1 || !Number.isInteger(count)) {
     throw new Error(`--count must be a positive integer, got: ${count}`);
@@ -1151,11 +1416,12 @@ export async function cmdThreadExec(
 ): Promise<StepOutput[]> {
   validateCount(count);
 
-  // Check if thread is already running in background (unless we ARE the background worker)
+  // Reject concurrent exec on the same thread (unless we ARE the background worker,
+  // which hasn't created its own marker yet at this point).
   if (!backgroundWorker) {
     const runningMarker = await isThreadRunning(storageRoot, threadId);
     if (runningMarker !== null) {
-      fail(`thread already executing in background (PID: ${runningMarker.pid})`);
+      fail(`thread ${threadId} is already being executed by PID ${runningMarker.pid}`);
     }
   }
 
@@ -1170,17 +1436,15 @@ export async function cmdThreadExec(
     return cmdThreadStepBackground(storageRoot, threadId, agentOverride, count, plog, workflowHash);
   }
 
-  // If we're the background worker, create marker before execution
-  let markerCreated = false;
-  if (backgroundWorker) {
-    await createMarker(storageRoot, {
-      thread: threadId,
-      workflow: workflowHash,
-      pid: process.pid,
-      startedAt: Date.now(),
-    });
-    markerCreated = true;
-  }
+  // Create running marker so `thread list` shows "running" during execution
+  // and concurrent `exec` on the same thread is rejected (see check above).
+  await createMarker(storageRoot, {
+    thread: threadId,
+    workflow: workflowHash,
+    pid: process.pid,
+    startedAt: Date.now(),
+    processStartTime: getProcessStartTime(process.pid),
+  });
 
   try {
     const results: StepOutput[] = [];
@@ -1193,10 +1457,7 @@ export async function cmdThreadExec(
     }
     return results;
   } finally {
-    // Cleanup marker if we created one
-    if (markerCreated) {
-      await deleteMarker(storageRoot, threadId);
-    }
+    await deleteMarker(storageRoot, threadId);
   }
 }
 
@@ -1264,6 +1525,7 @@ async function cmdThreadStepBackground(
       suspendMessage: null,
       done: false,
       background: true,
+      error: null,
     },
   ];
 }
@@ -1296,6 +1558,16 @@ async function resolveModeratorStepTarget(
   plog: ProcessLogger,
 ): Promise<StepOutput | AgentStepTarget> {
   const { lastRole, lastOutput } = resolveEvaluateArgs(uwf, chain);
+
+  // Intercept an already-suspended head before the moderator: a thread whose
+  // head step yielded `$status: "$SUSPEND"` stays suspended (idempotent re-exec).
+  const suspendReason = readSuspendReason(lastOutput);
+  if (suspendReason !== null) {
+    await ensureThreadSuspendMetadata(uwf.varStore, threadId, entry, lastRole, suspendReason);
+    plog.log(PL_MODERATOR, `moderator action=suspend suspendedRole=${lastRole}`, null);
+    return buildSuspendStepOutput(workflowHash, threadId, headHash, lastRole, suspendReason);
+  }
+
   const nextResult = evaluate(workflow.graph, lastRole, lastOutput);
   if (!nextResult.ok) {
     failStep(plog, `moderator evaluate failed: ${nextResult.error.message}`);
@@ -1303,32 +1575,10 @@ async function resolveModeratorStepTarget(
 
   plog.log(
     PL_MODERATOR,
-    `moderator ${
-      isSuspendResult(nextResult.value)
-        ? `action=suspend suspendedRole=${nextResult.value.suspendedRole}`
-        : `role=${nextResult.value.role}`
-    } prompt=${nextResult.value.prompt}`,
+    `moderator role=${nextResult.value.role} prompt=${nextResult.value.prompt}`,
     null,
   );
 
-  if (isSuspendResult(nextResult.value)) {
-    await ensureThreadSuspendMetadata(
-      uwf.varStore,
-      threadId,
-      entry,
-      nextResult.value.suspendedRole,
-      nextResult.value.prompt,
-    );
-    return buildStepOutputFromEvaluation(
-      workflowHash,
-      threadId,
-      headHash,
-      "suspended",
-      nextResult,
-      null,
-    );
-  }
-
   if (nextResult.value.role === END_ROLE) {
     plog.log(PL_THREAD_ARCHIVED, `thread archived head=${headHash}`, null);
     archiveThread(uwf, threadId, workflowHash, headHash);
@@ -1336,12 +1586,13 @@ async function resolveModeratorStepTarget(
       workflow: workflowHash,
       thread: threadId,
       head: headHash,
-      status: "completed",
+      status: "end",
       currentRole: null,
       suspendedRole: null,
       suspendMessage: null,
       done: true,
       background: null,
+      error: null,
     };
   }
 
@@ -1369,29 +1620,27 @@ async function finalizeAgentStep(
     uwfAfter,
     chainAfter,
   );
-  const afterResult = evaluate(workflow.graph, lastRoleAfter, lastOutputAfter);
-  if (!afterResult.ok) {
-    failStep(plog, `post-step moderator evaluate failed: ${afterResult.error.message}`);
-  }
 
-  if (isSuspendResult(afterResult.value)) {
+  // Intercept `$status: "$SUSPEND"` before the moderator (coroutine yield): the
+  // step is already in CAS and the head has advanced — mark the thread suspended
+  // and return without routing through the graph.
+  const suspendReason = readSuspendReason(lastOutputAfter);
+  if (suspendReason !== null) {
     setThread(
       uwfAfter.varStore,
       threadId,
       markThreadSuspended(
         getThread(uwfAfter.varStore, threadId) ?? createThreadIndexEntry(newHead),
-        afterResult.value.suspendedRole,
-        afterResult.value.prompt,
+        lastRoleAfter,
+        suspendReason,
       ),
     );
-    return buildStepOutputFromEvaluation(
-      workflowHash,
-      threadId,
-      newHead,
-      "suspended",
-      afterResult,
-      null,
-    );
+    return buildSuspendStepOutput(workflowHash, threadId, newHead, lastRoleAfter, suspendReason);
+  }
+
+  const afterResult = evaluate(workflow.graph, lastRoleAfter, lastOutputAfter);
+  if (!afterResult.ok) {
+    failStep(plog, `post-step moderator evaluate failed: ${afterResult.error.message}`);
   }
 
   const done = afterResult.value.role === END_ROLE;
@@ -1400,7 +1649,7 @@ async function finalizeAgentStep(
     archiveThread(uwfAfter, threadId, workflowHash, newHead);
   }
 
-  const status: ThreadStatus = done ? "completed" : "idle";
+  const status: ThreadStatus = done ? "end" : "idle";
   const currentRole = done ? null : afterResult.value.role;
 
   return {
@@ -1413,6 +1662,7 @@ async function finalizeAgentStep(
     suspendMessage: null,
     done,
     background: null,
+    error: null,
   };
 }
 
@@ -1476,6 +1726,31 @@ async function cmdThreadStepOnce(
     failStep(plog, `agent returned hash that is not a StepNode: ${newHead}`);
   }
 
+  // Recoverable failure: agent persisted a failed StepNode (e.g. frontmatter
+  // validation exhausted retries) but the engine MUST NOT advance head. The
+  // moderator graph is also untouched — the same role will be replayed on the
+  // next exec (until eventual success records `previousAttempts` linking the
+  // failed step hashes).
+  if (agentResult.isError === true) {
+    plog.log(
+      PL_AGENT_ERROR,
+      `agent reported recoverable failure stepHash=${newHead} message=${agentResult.errorMessage ?? ""}`,
+      null,
+    );
+    return {
+      workflow: workflowHash,
+      thread: threadId,
+      head: headHash,
+      status: "idle",
+      currentRole: role,
+      suspendedRole: null,
+      suspendMessage: null,
+      done: false,
+      background: null,
+      error: { stepHash: newHead, message: agentResult.errorMessage ?? "agent reported error" },
+    };
+  }
+
   return finalizeAgentStep(storageRoot, threadId, workflowHash, workflow, newHead, uwfAfter, plog);
 }
 
@@ -1526,7 +1801,9 @@ export type CancelOutput = {
 };
 
 /**
- * Stop background execution of a thread (but keep thread active)
+ * Stop background execution of a thread (but keep thread active).
+ * Validates process identity before sending signals to prevent killing
+ * unrelated processes when PIDs are recycled.
  */
 export async function cmdThreadStop(storageRoot: string, threadId: ThreadId): Promise<StopOutput> {
   const uwf = await createUwfStore(storageRoot);
@@ -1535,15 +1812,26 @@ export async function cmdThreadStop(storageRoot: string, threadId: ThreadId): Pr
     fail(`thread not active: ${threadId}`);
   }
 
-  // Check if thread is running in background and terminate it
-  const runningMarker = await isThreadRunning(storageRoot, threadId);
-  if (runningMarker === null) {
+  // Read the raw marker to check process identity
+  const marker = await readMarker(storageRoot, threadId);
+  if (marker === null) {
     process.stderr.write(`Warning: thread ${threadId} is not currently running\n`);
     return { thread: threadId, stopped: false };
   }
 
+  // Validate that the marker's PID still belongs to the same process
+  if (!isMarkerValid(marker)) {
+    // Stale marker — PID was recycled or process died. Do NOT send a signal.
+    process.stderr.write(
+      `Warning: thread ${threadId} was not actually running (stale marker cleaned up)\n`,
+    );
+    await deleteMarker(storageRoot, threadId);
+    return { thread: threadId, stopped: false };
+  }
+
+  // Process identity confirmed — safe to send SIGTERM
   try {
-    process.kill(runningMarker.pid, "SIGTERM");
+    process.kill(marker.pid, "SIGTERM");
   } catch {
     // Process may have already exited, ignore error
   }
@@ -1553,7 +1841,9 @@ export async function cmdThreadStop(storageRoot: string, threadId: ThreadId): Pr
 }
 
 /**
- * Cancel a thread (stop execution + move to history)
+ * Cancel a thread (stop execution + move to history).
+ * Validates process identity before sending signals to prevent killing
+ * unrelated processes when PIDs are recycled.
  */
 export async function cmdThreadCancel(
   storageRoot: string,
@@ -1565,14 +1855,18 @@ export async function cmdThreadCancel(
     fail(`thread not active: ${threadId}`);
   }
 
-  // Check if thread is running in background and terminate it
-  const runningMarker = await isThreadRunning(storageRoot, threadId);
-  if (runningMarker !== null) {
-    try {
-      process.kill(runningMarker.pid, "SIGTERM");
-    } catch {
-      // Process may have already exited, ignore error
+  // Read the raw marker and validate process identity before sending signals
+  const marker = await readMarker(storageRoot, threadId);
+  if (marker !== null) {
+    if (isMarkerValid(marker)) {
+      // Process identity confirmed — safe to send SIGTERM
+      try {
+        process.kill(marker.pid, "SIGTERM");
+      } catch {
+        // Process may have already exited, ignore error
+      }
     }
+    // Always delete the marker (stale or not) — cancellation proceeds
     await deleteMarker(storageRoot, threadId);
   }