@united-workforce/cli 0.3.0 → 0.4.0

package/dist/commands/thread.js

@@ -1,16 +1,16 @@
 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 { validate } from "@ocas/core";
-import { createThreadIndexEntry, markThreadSuspended, updateThreadHead, } from "@united-workforce/protocol";
+import { createThreadIndexEntry, markThreadSuspended, SUSPEND_STATUS, updateThreadHead, } from "@united-workforce/protocol";
 import { createProcessLogger, extractUlidTimestamp, generateUlid, } from "@united-workforce/util";
 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 { completeThread, createUwfStore, getThread, loadActiveThreads, loadHistoryThreads, loadWorkflowRegistry, resolveWorkflowHash, setThread, } from "../store.js";
+import { evaluate } from "../moderator/index.js";
+import { completeThread, createUwfStore, findRegistryName, getThread, loadActiveThreads, loadHistoryThreads, loadWorkflowRegistry, resolveWorkflowHash, setThread, } from "../store.js";
 import { checkWorkflowFilenameConsistency, isCasRef, parseWorkflowPayload } from "../validate.js";
 import { validateWorkflow } from "../validate-semantic.js";
 import { collectOrderedSteps, expandOutput, fail, walkChain, } from "./shared.js";
@@ -18,56 +18,52 @@ import { materializeWorkflowPayload } from "./workflow.js";
 const END_ROLE = "$END";
 const START_ROLE = "$START";
 export const THREAD_READ_DEFAULT_QUOTA = 4000;
-function buildStepOutputFromEvaluation(workflowHash, threadId, head, status, evaluation, background) {
-    const done = status === "completed";
-    let currentRole = null;
-    let suspendedRole = null;
-    let suspendMessage = 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;
-        }
+/**
+ * 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) {
+    if (lastOutput[STATUS_KEY] !== SUSPEND_STATUS) {
+        return null;
     }
+    const reason = lastOutput.reason;
+    return typeof reason === "string" ? reason : "";
+}
+function buildSuspendStepOutput(workflowHash, threadId, head, suspendedRole, suspendMessage) {
     return {
         workflow: workflowHash,
         thread: threadId,
         head,
-        status,
-        currentRole,
+        status: "suspended",
+        currentRole: null,
         suspendedRole,
         suspendMessage,
-        done,
-        background,
+        done: false,
+        background: null,
+        error: null,
     };
 }
-function resolveSuspendFieldsFromGraph(uwf, head, workflowRef) {
+function resolveSuspendFieldsFromOutput(uwf, head) {
     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 };
 }
-function resolveSuspendFieldsForShow(entry, status, uwf, head, workflowRef) {
+function resolveSuspendFieldsForShow(entry, status, uwf, head) {
     if (status !== "suspended") {
         return { suspendedRole: null, suspendMessage: null };
     }
     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,
     };
 }
 async function ensureThreadSuspendMetadata(varStore, threadId, entry, suspendedRole, suspendMessage) {
@@ -78,16 +74,14 @@ async function ensureThreadSuspendMetadata(varStore, threadId, entry, suspendedR
     setThread(varStore, threadId, updated);
     return updated;
 }
-async function resolveActiveThreadStatus(storageRoot, threadId, uwf, head, workflowRef) {
+async function resolveActiveThreadStatus(storageRoot, threadId, uwf, head) {
     const runningMarker = await isThreadRunning(storageRoot, threadId);
     if (runningMarker !== null) {
         return "running";
     }
     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";
     }
     return "idle";
@@ -99,12 +93,15 @@ async function resolveActiveThreadStatus(storageRoot, threadId, uwf, head, workf
 function resolveCurrentRole(uwf, head, workflowRef) {
     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;
@@ -113,10 +110,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";
 function buildResumePrompt(graphPrompt, supplement) {
     if (supplement === null || supplement === "") {
         return graphPrompt;
@@ -147,18 +146,19 @@ async function workflowFileExists(dir, name, ext) {
     }
 }
 /**
- * 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, name) {
-    // 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;
@@ -167,15 +167,15 @@ async function findWorkflowInDir(dir, name) {
             /* not found */
         }
     }
-    // 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;
@@ -186,8 +186,21 @@ async function findWorkflowInDir(dir, name) {
     }
     return null;
 }
+/** Check if a directory contains a .git marker (directory or file). */
+async function hasGitMarker(dir) {
+    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.
  */
@@ -199,6 +212,10 @@ async function findWorkflowInParents(startDir, name) {
         if (found !== null) {
             return found;
         }
+        // Stop at .git boundary (repo root)
+        if (await hasGitMarker(currentDir)) {
+            break;
+        }
         // Stop at filesystem root
         if (currentDir === root) {
             break;
@@ -346,8 +363,8 @@ export async function cmdThreadShow(storageRoot, threadId) {
     if (workflow === null) {
         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,
@@ -359,13 +376,14 @@ export async function cmdThreadShow(storageRoot, threadId) {
             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"
         ? `Thread is suspended. Resume with: uwf thread resume ${threadId}`
         : null;
@@ -379,15 +397,25 @@ export async function cmdThreadShow(storageRoot, threadId) {
         suspendMessage: suspendFields.suspendMessage,
         done: false,
         background: null,
+        error: null,
         hint,
     };
 }
-async function threadListItemFromActive(storageRoot, uwf, threadId, head) {
+async function threadListItemFromActive(storageRoot, uwf, threadId, head, registry) {
     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: "",
+            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 {
         thread: threadId,
@@ -396,35 +424,67 @@ async function threadListItemFromActive(storageRoot, uwf, threadId, head) {
         status,
         currentRole: resolveCurrentRole(uwf, head, workflow),
         statusDisplay,
+        workflowName: findRegistryName(registry, workflow),
     };
 }
-async function collectActiveThreads(storageRoot, uwf, index) {
+async function collectActiveThreads(storageRoot, uwf, index, registry) {
     const items = [];
     for (const [threadId, entry] of Object.entries(index)) {
-        const item = await threadListItemFromActive(storageRoot, uwf, threadId, entry.head);
-        if (item !== null) {
-            items.push(item);
+        try {
+            const item = await threadListItemFromActive(storageRoot, uwf, 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,
+                workflow: "",
+                head: entry.head,
+                status: "corrupt",
+                currentRole: null,
+                statusDisplay: "corrupt",
+                workflowName: null,
+            });
         }
     }
     return items;
 }
-function collectCompletedThreads(uwf, activeIds) {
+function collectCompletedThreads(uwf, activeIds, registry) {
     const items = [];
     const history = loadHistoryThreads(uwf.varStore);
     const seen = new Set(); // Deduplication (issue #470)
     for (const [threadId, entry] of Object.entries(history)) {
         if (!activeIds.has(threadId) && !seen.has(threadId)) {
             seen.add(threadId);
-            const status = entry.status;
-            const workflow = resolveWorkflowFromHead(uwf, entry.head);
-            items.push({
-                thread: 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,
+                    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,
+                    workflow: "",
+                    head: entry.head,
+                    status: "corrupt",
+                    currentRole: null,
+                    statusDisplay: "corrupt",
+                    workflowName: null,
+                });
+            }
         }
     }
     return items;
@@ -455,23 +515,28 @@ function applyPagination(items, skip, take) {
     const takeCount = take ?? items.length;
     return items.slice(skipCount, skipCount + takeCount);
 }
-export async function cmdThreadList(storageRoot, statusFilter, afterMs, beforeMs, skip, take) {
+export async function cmdThreadList(storageRoot, statusFilter, afterMs, beforeMs, skip, take, showAll = false) {
     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 = 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");
+    const includeCompleted = 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
     items = applyTimeFilters(items, afterMs, beforeMs);
@@ -697,11 +762,9 @@ function resolveAgentConfig(config, workflow, role, agentOverride) {
     }
     return agentConfig;
 }
-function spawnAgent(plog, agent, threadId, role, edgePrompt, cwd) {
-    const argv = [...agent.args, "--thread", threadId, "--role", role, "--prompt", edgePrompt];
-    let stdout;
+function executeAgentCommand(agent, argv, cwd, plog) {
     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
@@ -721,14 +784,17 @@ function spawnAgent(plog, agent, threadId, role, edgePrompt, cwd) {
         const detail = stderr.trim() !== "" ? `: ${stderr.trim()}` : "";
         failStep(plog, `agent command failed (${agent.command})${detail}`);
     }
+}
+function parseAgentOutput(stdout, plog) {
     const line = stdout.trim().split("\n").pop()?.trim() ?? "";
-    let parsed;
     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, line, plog) {
     const obj = parsed;
     if (typeof obj !== "object" ||
         obj === null ||
@@ -736,10 +802,33 @@ function spawnAgent(plog, agent, threadId, role, edgePrompt, cwd) {
         !isCasRef(obj.stepHash)) {
         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;
 }
+function spawnAgent(plog, agent, threadId, role, edgePrompt, cwd) {
+    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, threadId, _workflow, _head) {
-    completeThread(uwf.varStore, threadId, "completed");
+    completeThread(uwf.varStore, threadId, "end");
 }
 export async function cmdThreadResume(storageRoot, threadId, supplement, agentOverride) {
     const runningMarker = await isThreadRunning(storageRoot, threadId);
@@ -754,15 +843,15 @@ export async function cmdThreadResume(storageRoot, threadId, supplement, agentOv
     const headHash = entry.head;
     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;
-    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})`);
     }
     const plog = createProcessLogger({
@@ -770,7 +859,7 @@ export async function cmdThreadResume(storageRoot, threadId, supplement, agentOv
         context: { thread: threadId, workflow: workflowHash },
     });
     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}`);
         }
@@ -784,27 +873,136 @@ export async function cmdThreadResume(storageRoot, threadId, supplement, agentOv
             prompt: resumePrompt,
         });
     }
-    // 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", completedAt: null };
     setThread(uwf.varStore, threadId, updatedEntry);
     plog.log(PL_THREAD_RESUME, `resume completed role=${startRole} supplement=${supplement !== null}`, null);
     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, uwf, threadId) {
+    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 };
+}
+/**
+ * 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, workflow, replacedHash) {
+    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, threadId, prompt, agentOverride) {
+    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;
+    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;
+    // Rewrite the new step so that its `prev` points to the OLD head's prev (replace semantics).
+    const replacedPayload = {
+        ...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) {
     if (count < 1 || !Number.isInteger(count)) {
@@ -813,11 +1011,12 @@ export function validateCount(count) {
 }
 export async function cmdThreadExec(storageRoot, threadId, agentOverride, count, background, backgroundWorker) {
     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}`);
         }
     }
     const workflowHash = await resolveActiveThreadWorkflowHash(storageRoot, threadId);
@@ -829,17 +1028,15 @@ export async function cmdThreadExec(storageRoot, threadId, agentOverride, count,
         // Spawn background process
         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 = [];
         for (let i = 0; i < count; i++) {
@@ -852,10 +1049,7 @@ export async function cmdThreadExec(storageRoot, threadId, agentOverride, count,
         return results;
     }
     finally {
-        // Cleanup marker if we created one
-        if (markerCreated) {
-            await deleteMarker(storageRoot, threadId);
-        }
+        await deleteMarker(storageRoot, threadId);
     }
 }
 async function resolveActiveThreadWorkflowHash(storageRoot, threadId) {
@@ -903,6 +1097,7 @@ async function cmdThreadStepBackground(storageRoot, threadId, agentOverride, cou
             suspendMessage: null,
             done: false,
             background: true,
+            error: null,
         },
     ];
 }
@@ -917,17 +1112,19 @@ function resolveResumeStepTarget(resume, chain, threadCwd, plog) {
 }
 async function resolveModeratorStepTarget(_storageRoot, threadId, entry, headHash, workflowHash, workflow, uwf, chain, threadCwd, plog) {
     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}`);
     }
-    plog.log(PL_MODERATOR, `moderator ${isSuspendResult(nextResult.value)
-        ? `action=suspend suspendedRole=${nextResult.value.suspendedRole}`
-        : `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);
-    }
+    plog.log(PL_MODERATOR, `moderator role=${nextResult.value.role} prompt=${nextResult.value.prompt}`, null);
     if (nextResult.value.role === END_ROLE) {
         plog.log(PL_THREAD_ARCHIVED, `thread archived head=${headHash}`, null);
         archiveThread(uwf, threadId, workflowHash, headHash);
@@ -935,12 +1132,13 @@ async function resolveModeratorStepTarget(_storageRoot, threadId, entry, headHas
             workflow: workflowHash,
             thread: threadId,
             head: headHash,
-            status: "completed",
+            status: "end",
             currentRole: null,
             suspendedRole: null,
             suspendMessage: null,
             done: true,
             background: null,
+            error: null,
         };
     }
     return {
@@ -954,20 +1152,24 @@ async function finalizeAgentStep(_storageRoot, threadId, workflowHash, workflow,
     setThread(uwfAfter.varStore, threadId, updateThreadHead(priorEntry, newHead));
     const chainAfter = walkChain(uwfAfter, newHead);
     const { lastRole: lastRoleAfter, lastOutput: lastOutputAfter } = resolveEvaluateArgs(uwfAfter, chainAfter);
+    // 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), lastRoleAfter, suspendReason));
+        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}`);
     }
-    if (isSuspendResult(afterResult.value)) {
-        setThread(uwfAfter.varStore, threadId, markThreadSuspended(getThread(uwfAfter.varStore, threadId) ?? createThreadIndexEntry(newHead), afterResult.value.suspendedRole, afterResult.value.prompt));
-        return buildStepOutputFromEvaluation(workflowHash, threadId, newHead, "suspended", afterResult, null);
-    }
     const done = afterResult.value.role === END_ROLE;
     if (done) {
         plog.log(PL_THREAD_ARCHIVED, `thread archived head=${newHead}`, null);
         archiveThread(uwfAfter, threadId, workflowHash, newHead);
     }
-    const status = done ? "completed" : "idle";
+    const status = done ? "end" : "idle";
     const currentRole = done ? null : afterResult.value.role;
     return {
         workflow: workflowHash,
@@ -979,6 +1181,7 @@ async function finalizeAgentStep(_storageRoot, threadId, workflowHash, workflow,
         suspendMessage: null,
         done,
         background: null,
+        error: null,
     };
 }
 async function cmdThreadStepOnce(storageRoot, threadId, agentOverride, plog, resume = null) {
@@ -1013,6 +1216,26 @@ async function cmdThreadStepOnce(storageRoot, threadId, agentOverride, plog, res
     if (newNode === null || newNode.type !== uwfAfter.schemas.stepNode) {
         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);
 }
 async function resolveHeadHash(storageRoot, threadId) {
@@ -1043,7 +1266,9 @@ export async function cmdThreadRead(storageRoot, threadId, quota = THREAD_READ_D
     });
 }
 /**
- * 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, threadId) {
     const uwf = await createUwfStore(storageRoot);
@@ -1051,14 +1276,22 @@ export async function cmdThreadStop(storageRoot, threadId) {
     if (entry === null) {
         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
@@ -1067,7 +1300,9 @@ export async function cmdThreadStop(storageRoot, threadId) {
     return { thread: threadId, stopped: true };
 }
 /**
- * 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, threadId) {
     const uwf = await createUwfStore(storageRoot);
@@ -1075,15 +1310,19 @@ export async function cmdThreadCancel(storageRoot, threadId) {
     if (entry === null) {
         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);
     }
     completeThread(uwf.varStore, threadId, "cancelled");