@united-workforce/cli 0.3.0 → 0.4.0

package/src/background/background.ts

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { RunningThreadItem, ThreadId } from "@united-workforce/protocol";
@@ -18,6 +19,42 @@ export function getMarkerPath(storageRoot: string, threadId: ThreadId): string {
   return join(getRunningDir(storageRoot), `${threadId}.json`);
 }
 
+/**
+ * Read the process start time from /proc/<pid>/stat (field 22, starttime).
+ * Returns the value in clock ticks since boot, or null on non-Linux systems
+ * or when the process does not exist.
+ */
+export function getProcessStartTime(pid: number): number | null {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    // /proc/<pid>/stat format: pid (comm) state ... field22_starttime ...
+    // The comm field can contain spaces and parentheses, so we find the last ')' first
+    const closeParenIdx = stat.lastIndexOf(")");
+    if (closeParenIdx === -1) {
+      return null;
+    }
+    // Fields after (comm) start at index 2 (state is field 3, index 2 in 0-based after split)
+    // starttime is field 22 (1-based), which is index 19 in the fields after ')'
+    const fieldsAfterComm = stat
+      .slice(closeParenIdx + 2)
+      .trim()
+      .split(" ");
+    // Field indices after comm (0-based): 0=state(3), 1=ppid(4), ..., 19=starttime(22)
+    const startTimeStr = fieldsAfterComm[19];
+    if (startTimeStr === undefined) {
+      return null;
+    }
+    const startTime = Number(startTimeStr);
+    if (Number.isNaN(startTime)) {
+      return null;
+    }
+    return startTime;
+  } catch {
+    // /proc not available (non-Linux) or process doesn't exist
+    return null;
+  }
+}
+
 /**
  * Check if a PID is still running.
  * Returns true if the process exists, false otherwise.
@@ -33,6 +70,39 @@ export function isPidAlive(pid: number): boolean {
   }
 }
 
+/**
+ * Validate that a running marker still refers to the same process.
+ * Checks both that the PID is alive AND that its start time matches.
+ * Returns false if:
+ *   - The PID is no longer alive
+ *   - The PID is alive but its start time doesn't match (PID was recycled)
+ * Returns true if:
+ *   - PID is alive AND start times match
+ *   - PID is alive AND marker has null processStartTime (backward compat / non-Linux)
+ */
+export function isMarkerValid(marker: RunningMarker): boolean {
+  if (!isPidAlive(marker.pid)) {
+    return false;
+  }
+
+  // If marker has no processStartTime (legacy marker or non-Linux at creation time),
+  // fall back to PID-alive-only check for backward compatibility
+  if (marker.processStartTime === null) {
+    return true;
+  }
+
+  // Verify process identity by comparing start times
+  const actualStartTime = getProcessStartTime(marker.pid);
+
+  // If we can't read the actual start time (non-Linux runtime), trust PID-alive check
+  if (actualStartTime === null) {
+    return true;
+  }
+
+  // Start times must match — if they differ, PID was recycled
+  return marker.processStartTime === actualStartTime;
+}
+
 /**
  * Create a marker file for a running thread.
  * Writes to a temp file in the same directory, then atomically renames.
@@ -63,6 +133,7 @@ export async function deleteMarker(storageRoot: string, threadId: ThreadId): Pro
 
 /**
  * Read a marker file. Returns null if file doesn't exist or is invalid.
+ * Handles legacy markers that lack processStartTime by defaulting to null.
  */
 export async function readMarker(
   storageRoot: string,
@@ -71,7 +142,15 @@ export async function readMarker(
   const markerPath = getMarkerPath(storageRoot, threadId);
   try {
     const content = await readFile(markerPath, "utf8");
-    const marker = JSON.parse(content) as RunningMarker;
+    const raw = JSON.parse(content) as Record<string, unknown>;
+    // Normalize legacy markers that lack processStartTime
+    const marker: RunningMarker = {
+      thread: raw.thread as ThreadId,
+      workflow: raw.workflow as string,
+      pid: raw.pid as number,
+      startedAt: raw.startedAt as number,
+      processStartTime: typeof raw.processStartTime === "number" ? raw.processStartTime : null,
+    };
     return marker;
   } catch {
     return null;
@@ -80,6 +159,8 @@ export async function readMarker(
 
 /**
  * List all running threads, filtering out stale markers.
+ * A marker is stale if the PID is dead or if the PID was recycled
+ * (processStartTime mismatch).
  */
 export async function listRunningThreads(storageRoot: string): Promise<RunningThreadItem[]> {
   const runningDir = getRunningDir(storageRoot);
@@ -107,8 +188,8 @@ export async function listRunningThreads(storageRoot: string): Promise<RunningTh
       continue;
     }
 
-    if (!isPidAlive(marker.pid)) {
-      // Stale marker - process no longer exists
+    if (!isMarkerValid(marker)) {
+      // Stale marker - process no longer exists or PID was recycled
       await deleteMarker(storageRoot, threadId);
       continue;
     }
@@ -126,7 +207,8 @@ export async function listRunningThreads(storageRoot: string): Promise<RunningTh
 
 /**
  * Check if a thread is currently executing in the background.
- * Returns the marker if running, null otherwise.
+ * Returns the marker if running (and process identity is verified), null otherwise.
+ * Automatically deletes stale markers (dead PID or recycled PID).
  */
 export async function isThreadRunning(
   storageRoot: string,
@@ -137,8 +219,8 @@ export async function isThreadRunning(
     return null;
   }
 
-  if (!isPidAlive(marker.pid)) {
-    // Stale marker
+  if (!isMarkerValid(marker)) {
+    // Stale marker — PID dead or recycled
     await deleteMarker(storageRoot, threadId);
     return null;
   }

package/src/background/index.ts

@@ -2,7 +2,9 @@ export {
   createMarker,
   deleteMarker,
   getMarkerPath,
+  getProcessStartTime,
   getRunningDir,
+  isMarkerValid,
   isPidAlive,
   isThreadRunning,
   listRunningThreads,

package/src/background/types.ts

@@ -6,4 +6,5 @@ export type RunningMarker = {
   workflow: CasRef;
   pid: number;
   startedAt: number;
+  processStartTime: number | null;
 };

package/src/cli.ts

@@ -11,12 +11,13 @@ import {
   cmdPromptUsage,
   cmdPromptWorkflowAuthoring,
 } from "./commands/prompt.js";
-import { cmdSetup, cmdSetupInteractive, resolvePresetBaseUrl } from "./commands/setup.js";
-import { cmdStepFork, cmdStepList, cmdStepRead, cmdStepShow } from "./commands/step.js";
+import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
+import { cmdStepAsk, cmdStepFork, cmdStepList, cmdStepRead, cmdStepShow } from "./commands/step.js";
 import {
   cmdThreadCancel,
   cmdThreadExec,
   cmdThreadList,
+  cmdThreadPoke,
   cmdThreadRead,
   cmdThreadResume,
   cmdThreadShow,
@@ -25,7 +26,12 @@ import {
   THREAD_READ_DEFAULT_QUOTA,
 } from "./commands/thread.js";
 import { parseTimeInput } from "./commands/thread-time-parser.js";
-import { cmdWorkflowAdd, cmdWorkflowList, cmdWorkflowShow } from "./commands/workflow.js";
+import {
+  cmdWorkflowAdd,
+  cmdWorkflowList,
+  cmdWorkflowShow,
+  cmdWorkflowValidate,
+} from "./commands/workflow.js";
 import { formatOutput, type OutputFormat } from "./format.js";
 import { resolveStorageRoot } from "./store.js";
 
@@ -72,6 +78,17 @@ workflow
     });
   });
 
+workflow
+  .command("validate")
+  .description("Validate a workflow YAML without registering it (CI-friendly)")
+  .argument("<file>", "Workflow YAML file")
+  .action((file: string) => {
+    runAction(async () => {
+      await cmdWorkflowValidate(file);
+      // silent on success — do not call writeOutput
+    });
+  });
+
 workflow
   .command("show")
   .description("Show a workflow by name or CAS hash")
@@ -79,7 +96,7 @@ workflow
   .action((id: string) => {
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
-      const result = await cmdWorkflowShow(storageRoot, id);
+      const result = await cmdWorkflowShow(storageRoot, id, process.cwd());
       writeOutput(result);
     });
   });
@@ -178,11 +195,18 @@ function parseStatusFilter(status: string | undefined): ThreadStatus[] | null {
   if (raw === "active") return ["idle", "running"];
 
   const parts = raw.split(",").map((s) => s.trim());
-  const validStatuses: ThreadStatus[] = ["idle", "running", "suspended", "completed", "cancelled"];
+  const validStatuses: ThreadStatus[] = [
+    "idle",
+    "running",
+    "suspended",
+    "end",
+    "cancelled",
+    "corrupt",
+  ];
   for (const part of parts) {
     if (!validStatuses.includes(part as ThreadStatus)) {
       process.stderr.write(
-        `Invalid status: ${part}. Must be one of: idle, running, suspended, completed, cancelled, active\n`,
+        `Invalid status: ${part}. Must be one of: idle, running, suspended, end, cancelled, active\n`,
       );
       process.exit(1);
     }
@@ -232,11 +256,12 @@ function parsePaginationOptions(
 
 thread
   .command("list")
-  .description("List threads")
+  .description("List threads (defaults to active: idle + running + corrupt)")
   .option(
     "--status <status>",
-    "Filter by status: idle, running, completed, cancelled, active (idle+running), or comma-separated values",
+    "Filter by status: idle, running, end, cancelled, active (idle+running), or comma-separated values",
   )
+  .option("--all", "Show all threads regardless of status (overrides default active-only filter)")
   .option("--after <date>", "Filter threads created after this date (ISO or relative like '7d')")
   .option("--before <date>", "Filter threads created before this date (ISO or relative like '7d')")
   .option("--skip <n>", "Skip first n threads")
@@ -244,6 +269,7 @@ thread
   .action(
     (opts: {
       status: string | undefined;
+      all: boolean | undefined;
       after: string | undefined;
       before: string | undefined;
       skip: string | undefined;
@@ -255,6 +281,7 @@ thread
         const nowMs = Date.now();
         const { afterMs, beforeMs } = parseTimeFilters(opts.after, opts.before, nowMs);
         const { skip, take } = parsePaginationOptions(opts.skip, opts.take);
+        const showAll = opts.all === true;
 
         const result = await cmdThreadList(
           storageRoot,
@@ -263,6 +290,7 @@ thread
           beforeMs,
           skip,
           take,
+          showAll,
         );
         writeOutput(result);
       });
@@ -290,6 +318,26 @@ thread
     });
   });
 
+thread
+  .command("poke")
+  .description("Re-run the head step's agent with a supplementary prompt (replaces head step)")
+  .argument("<thread-id>", "Thread ULID")
+  .requiredOption("-p, --prompt <text>", "Supplementary prompt for the agent")
+  .option("--agent <cmd>", "Override agent command (defaults to head step's agent)")
+  .action((threadId: string, opts: { prompt: string; agent: string | undefined }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const agentOverride = opts.agent ?? null;
+      const result = await cmdThreadPoke(
+        storageRoot,
+        threadId as ThreadId,
+        opts.prompt,
+        agentOverride,
+      );
+      writeOutput(result);
+    });
+  });
+
 thread
   .command("stop")
   .description("Stop background execution of a thread (keep thread active)")
@@ -369,6 +417,32 @@ step
     });
   });
 
+step
+  .command("ask")
+  .description(
+    "Ask a follow-up question to a historical step's agent (read-only; no thread mutation)",
+  )
+  .argument("<step-hash>", "CAS hash of the StepNode to query")
+  .requiredOption("-p, --prompt <text>", "Question to ask the step's agent")
+  .option("--agent <cmd>", "Override agent command (defaults to the step's recorded agent)")
+  .option(
+    "--no-fork",
+    "Skip session-fork; spawn the agent in a fresh ask session and inject the step's detail ref for context",
+  )
+  .action(
+    (stepHash: string, opts: { prompt: string; agent: string | undefined; fork: boolean }) => {
+      const storageRoot = resolveStorageRoot();
+      runAction(async () => {
+        const stdout = await cmdStepAsk(storageRoot, stepHash as CasRef, {
+          prompt: opts.prompt,
+          agentOverride: opts.agent ?? null,
+          fork: opts.fork,
+        });
+        process.stdout.write(stdout.endsWith("\n") ? stdout : `${stdout}\n`);
+      });
+    },
+  );
+
 step
   .command("read")
   .description("Read a step's turns as human-readable markdown")
@@ -542,46 +616,22 @@ prompt
 
 program
   .command("setup")
-  .description("Configure provider, model, and agent. Run without options for interactive wizard.")
-  .option("--provider <name>", "Provider name")
-  .option("--base-url <url>", "OpenAI-compatible API base URL")
-  .option("--api-key <key>", "API key")
-  .option("--model <name>", "Default model name")
+  .description(
+    "Configure the default agent. Run without --agent for interactive wizard.\n" +
+      "LLM provider/model configuration lives in <storage>/config.yaml under providers and models.",
+  )
   .option("--agent <name>", "Default agent adapter (e.g. hermes → uwf-hermes)")
-  .action(
-    (opts: {
-      provider?: string;
-      baseUrl?: string;
-      apiKey?: string;
-      model?: string;
-      agent?: string;
-    }) => {
-      const storageRoot = resolveStorageRoot();
-      runAction(async () => {
-        // Resolve preset base-url when provider is known but --base-url is omitted
-        const resolvedBaseUrl =
-          opts.baseUrl ??
-          (opts.provider !== undefined ? resolvePresetBaseUrl(opts.provider) : null);
-        if (opts.provider && resolvedBaseUrl && opts.apiKey && opts.model) {
-          const result = await cmdSetup({
-            provider: opts.provider,
-            baseUrl: resolvedBaseUrl,
-            apiKey: opts.apiKey,
-            model: opts.model,
-            agent: opts.agent ?? undefined,
-            storageRoot,
-          });
-          writeOutput(result);
-        } else if (!opts.provider && !opts.baseUrl && !opts.apiKey && !opts.model) {
-          await cmdSetupInteractive(storageRoot);
-        } else {
-          throw new Error(
-            "Non-interactive setup requires: --provider, --api-key, --model (--base-url is optional for preset providers)",
-          );
-        }
-      });
-    },
-  );
+  .action((opts: { agent?: string }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      if (opts.agent !== undefined && opts.agent !== "") {
+        const result = await cmdSetup({ agent: opts.agent, storageRoot });
+        writeOutput(result);
+      } else {
+        await cmdSetupInteractive(storageRoot);
+      }
+    });
+  });
 
 const log = program.command("log").description("Process-level debug logs");
 

package/src/commands/config.ts

@@ -3,20 +3,14 @@ import { join } from "node:path";
 import { parse, stringify } from "yaml";
 
 /**
- * Valid configuration key schema
+ * Valid configuration key schema. Engine config is LLM-free — providers,
+ * models, defaultModel, and modelOverrides are no longer accepted here.
+ * Each adapter owns its own LLM configuration.
  */
 const VALID_CONFIG_KEYS: Record<
   string,
   { nested: boolean; knownFields?: string[]; minDepth?: number }
 > = {
-  providers: {
-    nested: true,
-    knownFields: ["baseUrl", "apiKey"],
-  },
-  models: {
-    nested: true,
-    knownFields: ["provider", "name"],
-  },
   agents: {
     nested: true,
     knownFields: ["command", "args"],
@@ -26,14 +20,7 @@ const VALID_CONFIG_KEYS: Record<
     // agentOverrides.<workflowName>.<roleName> = agentAlias (string value)
     // No knownFields — workflow/role names are user-defined
   },
-  modelOverrides: {
-    nested: true,
-    minDepth: 2,
-    // modelOverrides.<scenario> = modelAlias (string value)
-    // No knownFields — scenarios are user-defined
-  },
   defaultAgent: { nested: false },
-  defaultModel: { nested: false },
 };
 
 /**
@@ -175,27 +162,12 @@ export function setNestedValue(obj: Record<string, unknown>, path: string[], val
 }
 
 /**
- * Deep clone and mask all apiKey values in providers section
+ * Deep clone the config. Engine config is LLM-free, so there are no apiKey
+ * fields to mask — this function is preserved as a defensive deep-clone
+ * boundary used by `cmdConfigList`.
  */
 export function maskApiKeys(config: Record<string, unknown>): Record<string, unknown> {
-  // Deep clone
-  const cloned = JSON.parse(JSON.stringify(config)) as Record<string, unknown>;
-
-  // Mask apiKey values in providers
-  if (cloned.providers && typeof cloned.providers === "object") {
-    const providers = cloned.providers as Record<string, unknown>;
-    for (const providerName of Object.keys(providers)) {
-      const provider = providers[providerName];
-      if (provider && typeof provider === "object") {
-        const providerObj = provider as Record<string, unknown>;
-        if ("apiKey" in providerObj) {
-          providerObj.apiKey = "***MASKED***";
-        }
-      }
-    }
-  }
-
-  return cloned;
+  return JSON.parse(JSON.stringify(config)) as Record<string, unknown>;
 }
 
 /**

package/src/commands/prompt.ts

@@ -241,7 +241,17 @@ uwf thread exec <thread-id>
 uwf thread show <thread-id>
 \`\`\`
 
-If the thread reaches \`$END\` with status \`completed\`, the setup is working.
+If the thread reaches \`$END\` with status \`end\`, the setup is working.
+
+To verify suspend/resume and poke:
+
+\`\`\`bash
+# After a role yields with $status: "$SUSPEND", resume the suspended thread:
+uwf thread resume <thread-id> -p "Additional context for the agent"
+
+# Re-run the head step's agent with a supplementary prompt (replaces head step):
+uwf thread poke <thread-id> -p "Try again with this hint"
+\`\`\`
 
 ## Scenario B: Upgrade from Previous Version
 
@@ -297,7 +307,7 @@ Check the changelog for breaking changes. Known migrations:
     resume: { role: planner, prompt: "Review previous run and continue." }
   \`\`\`
 
-Update all \`.workflow/\` and \`.workflows/\` YAML files in your projects. \`uwf workflow add\` will reject files with the old \`_\` syntax.
+Update all \`.workflows/\` and \`.workflow/\` YAML files in your projects. \`uwf workflow add\` will reject files with the old \`_\` syntax.
 
 - **v0.2.1**: \`$status: { enum: [value] }\` → \`$status: { const: "value" }\`. The validator no longer accepts \`enum\` for \`$status\`. Update all workflow YAML files:
   \`\`\`yaml
@@ -310,6 +320,9 @@ Update all \`.workflow/\` and \`.workflows/\` YAML files in your projects. \`uwf
   # For multi-exit, use oneOf with const (unchanged)
   \`\`\`
 
+- **v0.4.0**: Thread status \`completed\` → \`end\`. Update scripts that filter \`--status completed\` to use \`--status end\`. Legacy on-disk \`status: completed\` is normalized to \`end\` on read.
+- **v0.4.0**: \`$SUSPEND\` is now an engine-level coroutine yield, not a graph target. Workflows that routed to \`role: "$SUSPEND"\` must emit \`$status: "$SUSPEND"\` with a \`reason\` from the role output instead. The thread becomes \`suspended\`; continue with \`uwf thread resume\`.
+
 ### Step 4 — Verify
 
 \`\`\`bash