@united-workforce/cli 0.5.0 → 0.6.0

package/src/commands/thread.ts

@@ -61,7 +61,13 @@ import {
 } from "../store.js";
 import { checkWorkflowFilenameConsistency, isCasRef, parseWorkflowPayload } from "../validate.js";
 import { validateWorkflow } from "../validate-semantic.js";
-import { getConfigPath, getNestedValue, loadConfig, parseDotPath } from "./config.js";
+import {
+  getConfigPath,
+  getNestedValue,
+  loadConfig,
+  loadWorkflowPaths,
+  parseDotPath,
+} from "./config.js";
 import {
   type ChainState,
   collectOrderedSteps,
@@ -168,6 +174,13 @@ async function resolveActiveThreadStatus(
     return "running";
   }
 
+  // Check the persisted entry status first — agent failure suspends the thread
+  // via markThreadSuspended() without producing a $SUSPEND output in CAS.
+  const entry = getThread(uwf.varStore, threadId);
+  if (entry !== null && entry.status === "suspended") {
+    return "suspended";
+  }
+
   const chain = walkChain(uwf, head);
   const { lastOutput } = resolveEvaluateArgs(uwf, chain);
   if (readSuspendReason(lastOutput) !== null) {
@@ -227,9 +240,20 @@ function buildResumePrompt(graphPrompt: string, supplement: string | null): stri
   return `${graphPrompt}\n\n${supplement}`;
 }
 
+/**
+ * Error thrown by failStep so that callers can catch it, persist
+ * thread state (e.g. suspend), and then re-throw / exit.
+ */
+class StepFailureError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StepFailureError";
+  }
+}
+
 function failStep(plog: ProcessLogger, message: string): never {
   plog.log(PL_STEP_ERROR, message, null);
-  fail(message);
+  throw new StepFailureError(message);
 }
 
 /**
@@ -346,6 +370,49 @@ async function findWorkflowInParents(startDir: string, name: string): Promise<st
   return null;
 }
 
+/**
+ * Search for a workflow by name directly in a directory (not inside .workflows/).
+ * Used for workflowPaths resolution — each path dir contains YAMLs at top level.
+ * Checks flat files (<name>.yaml/.yml) and folder layout (<name>/index.yaml/.yml).
+ */
+async function findWorkflowInPath(dir: string, name: string): Promise<string | null> {
+  // Check flat YAML files
+  for (const ext of [".yaml", ".yml"]) {
+    const result = await workflowFileExists(dir, name, ext);
+    if (result !== null) {
+      return result;
+    }
+  }
+  // Check folder-based layout (<name>/index.yaml)
+  for (const indexName of ["index.yaml", "index.yml"]) {
+    const candidate = resolvePath(dir, name, indexName);
+    try {
+      await access(candidate);
+      return candidate;
+    } catch {
+      /* not found */
+    }
+  }
+  return null;
+}
+
+/**
+ * Search workflowPaths directories for a workflow by name.
+ * Searches each directory in order; first match wins.
+ */
+async function findWorkflowInPaths(
+  dirs: ReadonlyArray<string>,
+  name: string,
+): Promise<string | null> {
+  for (const dir of dirs) {
+    const found = await findWorkflowInPath(dir, name);
+    if (found !== null) {
+      return found;
+    }
+  }
+  return null;
+}
+
 async function materializeLocalWorkflow(uwf: UwfStore, filePath: string): Promise<CasRef> {
   let text: string;
   try {
@@ -421,6 +488,13 @@ async function resolveWorkflowCasRef(
     return materializeLocalWorkflow(uwf, localPath);
   }
 
+  // Strategy 3.5: workflowPaths global directories
+  const workflowPaths = loadWorkflowPaths(uwf.storageRoot);
+  const pathsFile = await findWorkflowInPaths(workflowPaths, trimmed);
+  if (pathsFile !== null) {
+    return materializeLocalWorkflow(uwf, pathsFile);
+  }
+
   // Strategy 4: Global registry fallback
   const registry = loadWorkflowRegistry(uwf.varStore);
   const hash = resolveWorkflowHash(registry, trimmed);
@@ -1378,7 +1452,18 @@ export async function cmdThreadPoke(
   // 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);
+  let agentResult: AdapterOutput;
+  try {
+    agentResult = spawnAgent(plog, agent, threadId, role, prompt, effectiveCwd);
+  } catch (e) {
+    if (e instanceof StepFailureError) {
+      // Fatal agent failure in poke — persist suspended state before propagating
+      const uwfErr = await createUwfStore(storageRoot);
+      const errEntry = getThread(uwfErr.varStore, threadId) ?? entry;
+      setThread(uwfErr.varStore, threadId, markThreadSuspended(errEntry, role, e.message));
+    }
+    throw e;
+  }
   const agentStepHash = agentResult.stepHash as CasRef;
 
   plog.log(PL_AGENT_DONE, `agent returned head=${agentStepHash}`, null);
@@ -1507,6 +1592,95 @@ export async function cmdThreadExec(
   }
 }
 
+const JOIN_POLL_INTERVAL_MS = 1000;
+
+/**
+ * Block until a running thread finishes (marker disappears), then return the
+ * final thread state in the same `StepOutput[]` format that `cmdThreadExec`
+ * produces.
+ *
+ * - If the thread is currently running → poll until it stops, then return
+ *   its final state.
+ * - If the thread is not running → return its current state immediately.
+ *
+ * An optional `timeoutMs` aborts the wait with an error when exceeded.
+ */
+export async function cmdThreadJoin(
+  storageRoot: string,
+  threadId: ThreadId,
+  timeoutMs: number | null,
+): Promise<StepOutput[]> {
+  const uwf = await createUwfStore(storageRoot);
+  const entry = getThread(uwf.varStore, threadId);
+  if (entry === null) {
+    fail(`thread not found: ${threadId}`);
+  }
+
+  // Wait for running marker to disappear
+  const deadline = timeoutMs !== null ? Date.now() + timeoutMs : null;
+
+  while ((await isThreadRunning(storageRoot, threadId)) !== null) {
+    if (deadline !== null && Date.now() >= deadline) {
+      fail(`join timed out after ${timeoutMs}ms — thread ${threadId} is still running`);
+    }
+    await new Promise<void>((resolve) => {
+      setTimeout(resolve, JOIN_POLL_INTERVAL_MS);
+    });
+  }
+
+  // Thread is no longer running — read final state.
+  // Re-open the store to get the latest state written by the worker.
+  const freshUwf = await createUwfStore(storageRoot);
+  const freshEntry = getThread(freshUwf.varStore, threadId);
+  if (freshEntry === null) {
+    fail(`thread disappeared after join: ${threadId}`);
+  }
+
+  const activeHead = freshEntry.head;
+  const workflowHash = resolveWorkflowFromHead(freshUwf, activeHead);
+  if (workflowHash === null) {
+    fail(`failed to resolve workflow from head: ${activeHead}`);
+  }
+
+  // Build the StepOutput matching exec's format
+  if (freshEntry.status === "end" || freshEntry.status === "cancelled") {
+    return [
+      {
+        workflow: workflowHash,
+        thread: threadId,
+        head: activeHead,
+        status: freshEntry.status,
+        currentRole: null,
+        suspendedRole: null,
+        suspendMessage: null,
+        done: true,
+        background: null,
+        error: null,
+      },
+    ];
+  }
+
+  // Active thread — resolve detailed status
+  const status = await resolveActiveThreadStatus(storageRoot, threadId, freshUwf, activeHead);
+  const currentRole = resolveCurrentRole(freshUwf, activeHead, workflowHash);
+  const suspendFields = resolveSuspendFieldsForShow(freshEntry, status, freshUwf, activeHead);
+
+  return [
+    {
+      workflow: workflowHash,
+      thread: threadId,
+      head: activeHead,
+      status,
+      currentRole,
+      suspendedRole: suspendFields.suspendedRole,
+      suspendMessage: suspendFields.suspendMessage,
+      done: false,
+      background: null,
+      error: null,
+    },
+  ];
+}
+
 async function resolveActiveThreadWorkflowHash(
   storageRoot: string,
   threadId: ThreadId,
@@ -1761,6 +1935,51 @@ async function cmdThreadStepOnce(
   });
 
   loadDotenv({ path: getEnvPath(storageRoot) });
+
+  // Wrap agent execution in a try-catch: when the agent command crashes
+  // (non-zero exit, unparseable output, invalid CAS node, etc.), failStep throws
+  // StepFailureError. We catch it to persist suspended state before re-throwing
+  // so the CLI still exits non-zero.
+  try {
+    return await executeAndProcessAgentStep(
+      storageRoot,
+      threadId,
+      headHash,
+      workflowHash,
+      workflow,
+      role,
+      edgePrompt,
+      effectiveCwd,
+      agent,
+      plog,
+    );
+  } catch (e) {
+    if (e instanceof StepFailureError) {
+      // Fatal agent failure — persist suspended state before propagating
+      const uwfErr = await createUwfStore(storageRoot);
+      const errEntry = getThread(uwfErr.varStore, threadId) ?? createThreadIndexEntry(headHash);
+      setThread(uwfErr.varStore, threadId, markThreadSuspended(errEntry, role, e.message));
+    }
+    throw e;
+  }
+}
+
+/**
+ * Execute the agent command and process the result. Separated from cmdThreadStepOnce
+ * so that fatal failures (StepFailureError) can be caught and handled by the caller.
+ */
+async function executeAndProcessAgentStep(
+  storageRoot: string,
+  threadId: ThreadId,
+  headHash: CasRef,
+  workflowHash: CasRef,
+  workflow: WorkflowPayload,
+  role: string,
+  edgePrompt: string,
+  effectiveCwd: string,
+  agent: AgentConfig,
+  plog: ProcessLogger,
+): Promise<StepOutput> {
   const agentResult = spawnAgent(plog, agent, threadId, role, edgePrompt, effectiveCwd);
   const newHead = agentResult.stepHash as CasRef;
 
@@ -1778,22 +1997,28 @@ async function cmdThreadStepOnce(
   // next exec (until eventual success records `previousAttempts` linking the
   // failed step hashes).
   if (agentResult.isError === true) {
+    const errorMsg = agentResult.errorMessage ?? "agent reported error";
     plog.log(
       PL_AGENT_ERROR,
-      `agent reported recoverable failure stepHash=${newHead} message=${agentResult.errorMessage ?? ""}`,
+      `agent reported recoverable failure stepHash=${newHead} message=${errorMsg}`,
       null,
     );
+
+    // Persist suspended state so `thread list --status suspended` reflects the failure.
+    const priorEntry = getThread(uwfAfter.varStore, threadId) ?? createThreadIndexEntry(headHash);
+    setThread(uwfAfter.varStore, threadId, markThreadSuspended(priorEntry, role, errorMsg));
+
     return {
       workflow: workflowHash,
       thread: threadId,
       head: headHash,
-      status: "idle",
+      status: "suspended",
       currentRole: role,
-      suspendedRole: null,
-      suspendMessage: null,
+      suspendedRole: role,
+      suspendMessage: errorMsg,
       done: false,
       background: null,
-      error: { stepHash: newHead, message: agentResult.errorMessage ?? "agent reported error" },
+      error: { stepHash: newHead, message: errorMsg },
     };
   }
 

package/src/commands/workflow.ts

@@ -10,6 +10,7 @@ import { createIncludeTag } from "../include.js";
 import {
   createUwfStore,
   discoverProjectWorkflows,
+  discoverWorkflowPathsEntries,
   findRegistryName,
   loadWorkflowRegistry,
   resolveProjectWorkflowFile,
@@ -24,8 +25,9 @@ import {
   parseWorkflowPayload,
 } from "../validate.js";
 import { validateWorkflow } from "../validate-semantic.js";
+import { loadWorkflowPaths } from "./config.js";
 
-export type WorkflowOrigin = "local" | "global";
+export type WorkflowOrigin = "local" | "paths" | "global";
 
 export type WorkflowListEntry = {
   name: string;
@@ -160,6 +162,9 @@ export async function cmdWorkflowAdd(
   storageRoot: string,
   filePath: string,
 ): Promise<WorkflowAddOutput> {
+  process.stderr.write(
+    "warning: `uwf workflow add` is deprecated. Use workflowPaths in ~/.uwf/config.yaml instead. See issue #360.\n",
+  );
   let text: string;
   try {
     text = await readFile(filePath, "utf8");
@@ -295,6 +300,14 @@ async function resolveWorkflowCasRefForShow(
     return materializeLocalWorkflowForShow(uwf, localPath);
   }
 
+  // Strategy 3.5: workflowPaths global directories
+  const workflowPaths = loadWorkflowPaths(uwf.storageRoot);
+  const pathsEntries = await discoverWorkflowPathsEntries(workflowPaths);
+  const pathsFile = resolveProjectWorkflowFile(pathsEntries, trimmed);
+  if (pathsFile !== null) {
+    return materializeLocalWorkflowForShow(uwf, pathsFile);
+  }
+
   // Strategy 4: Global registry fallback
   const registry = loadWorkflowRegistry(uwf.varStore);
   const hash = resolveWorkflowHash(registry, trimmed);
@@ -344,18 +357,30 @@ export async function cmdWorkflowList(
 ): Promise<WorkflowListEntry[]> {
   const uwf = await createUwfStore(storageRoot);
   const localEntries = await discoverProjectWorkflows(projectRoot);
+  const workflowPaths = loadWorkflowPaths(storageRoot);
+  const pathsEntries = await discoverWorkflowPathsEntries(workflowPaths);
   const registry = loadWorkflowRegistry(uwf.varStore);
 
   const result: WorkflowListEntry[] = [];
-  const localNames = new Set<string>();
+  const seenNames = new Set<string>();
 
+  // Layer 1: local .workflows/ (highest priority)
   for (const entry of localEntries) {
-    localNames.add(entry.name);
+    seenNames.add(entry.name);
     result.push({ name: entry.name, hash: "(local)", origin: "local" });
   }
 
+  // Layer 2: workflowPaths directories
+  for (const entry of pathsEntries) {
+    if (!seenNames.has(entry.name)) {
+      seenNames.add(entry.name);
+      result.push({ name: entry.name, hash: "(paths)", origin: "paths" });
+    }
+  }
+
+  // Layer 3: global registry (lowest priority)
   for (const [name, hash] of Object.entries(registry)) {
-    if (!localNames.has(name)) {
+    if (!seenNames.has(name)) {
       result.push({ name, hash, origin: "global" });
     }
   }

package/src/output-mappers.ts

@@ -229,7 +229,8 @@ export function toWorkflowListPayload(entries: WorkflowListEntry[]): WorkflowLis
     items: entries.map((e) => ({
       name: e.name,
       hash: e.hash,
-      source: e.origin === "local" ? ".workflows" : "registry",
+      source:
+        e.origin === "local" ? ".workflows" : e.origin === "paths" ? "workflowPaths" : "registry",
       description: "",
     })),
   };

package/src/store.ts

@@ -56,7 +56,7 @@ async function findIndexWorkflow(
  * Scan a single directory for workflow entries (flat YAML files + folder/index.yaml).
  * Returns discovered entries. Returns empty array if directory does not exist.
  */
-async function scanWorkflowDir(dir: string): Promise<ProjectWorkflowEntry[]> {
+export async function scanWorkflowDir(dir: string): Promise<ProjectWorkflowEntry[]> {
   let dirents: Dirent[];
   try {
     dirents = await readdir(dir, { withFileTypes: true });
@@ -159,6 +159,30 @@ export function getDefaultStorageRoot(): string {
   return join(homedir(), ".uwf");
 }
 
+/**
+ * Discover workflows from workflowPaths directories.
+ * Each directory is scanned directly for YAML files (like scanWorkflowDir).
+ * Earlier dirs in the list take priority on name collisions.
+ */
+export async function discoverWorkflowPathsEntries(
+  dirs: ReadonlyArray<string>,
+): Promise<ProjectWorkflowEntry[]> {
+  const seen = new Set<string>();
+  const result: ProjectWorkflowEntry[] = [];
+
+  for (const dir of dirs) {
+    const entries = await scanWorkflowDir(dir);
+    for (const entry of entries) {
+      if (!seen.has(entry.name)) {
+        seen.add(entry.name);
+        result.push(entry);
+      }
+    }
+  }
+
+  return result;
+}
+
 /**
  * Resolve storage root.
  * Priority: `UWF_HOME` → default.

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 United Workforce
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.