fix(thread-read): remove ### Output section and deduplicate ### Prompt globally

LLM sometimes emits plain text (e.g. 'Now I'll write the tests...')
without calling tools, which the loop treated as final output. Now
the loop detects this and injects a user message nudging the LLM
to either continue using tools or output frontmatter with ---.

.workflows/solve-issue.yaml

@@ -41,7 +41,8 @@ roles:
       Before starting any work, ensure a clean worktree:
       1. `git checkout main && git pull` to get the latest code
       2. `git checkout -b fix/<issue-number>-<short-description>` to create a fresh branch
-         - If bounced back from reviewer or tester, reuse the existing branch instead
+         - If bounced back from reviewer or tester, reuse the existing branch and rebase onto latest main:
+           `git checkout main && git pull && git checkout <branch> && git rebase main`
 
       Then implement TDD:
       3. Read the test spec from CAS: `uwf cas get <plan hash>` (find the hash from the latest planner step's frontmatter.plan)

package.json

@@ -9,7 +9,7 @@
     "check": "bunx tsc --build && biome check . && bash scripts/lint-log-tags.sh",
     "typecheck": "bunx tsc --build",
     "format": "biome format --write .",
-    "test": "bun run --filter '*' test",
+    "test": "bun run --filter './packages/*' test",
     "changeset": "bunx changeset",
     "version": "bunx changeset version",
     "release": "bun run build && bun test && node scripts/publish-all.mjs"

packages/cli-workflow/src/__tests__/thread.test.ts

@@ -266,12 +266,7 @@ describe("cmdThreadRead ### Content section", () => {
 
     expect(markdown).toContain("### Content");
     expect(markdown).toContain("The assistant response text");
-
-    const contentIdx = markdown.indexOf("### Content");
-    const outputIdx = markdown.indexOf("### Output");
-    expect(contentIdx).toBeGreaterThanOrEqual(0);
-    expect(outputIdx).toBeGreaterThanOrEqual(0);
-    expect(contentIdx).toBeLessThan(outputIdx);
+    expect(markdown).not.toContain("### Output");
   });
 
   test("omits ### Content when detail has no matching assistant turns", async () => {
@@ -314,7 +309,7 @@ describe("cmdThreadRead ### Content section", () => {
     const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
 
     expect(markdown).not.toContain("### Content");
-    expect(markdown).toContain("### Output");
+    expect(markdown).not.toContain("### Output");
   });
 });
 
@@ -392,3 +387,87 @@ describe("cmdThreadStepDetails", () => {
     await expect(cmdThreadStepDetails(tmpDir, "nonexistenth0" as CasRef)).rejects.toThrow();
   });
 });
+
+// ── cmdThreadRead: ### Prompt deduplication ───────────────────────────────────
+
+describe("cmdThreadRead ### Prompt deduplication", () => {
+  async function makeThreadWithRoles(uwf: UwfStore, roles: string[]): Promise<string> {
+    const roleMap: Record<string, unknown> = {};
+    for (const r of [...new Set(roles)]) {
+      roleMap[r] = {
+        description: r,
+        goal: `Goal for ${r}`,
+        capabilities: [],
+        procedure: "Do stuff.",
+        output: "Output.",
+        meta: "placeholder00" as CasRef,
+      };
+    }
+    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
+      name: "dedup-wf",
+      description: "desc",
+      roles: roleMap,
+      conditions: {},
+      graph: {},
+    });
+    const startHash = await uwf.store.put(uwf.schemas.startNode, {
+      workflow: workflowHash,
+      prompt: "Start",
+    });
+    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
+      name: "out",
+      description: "",
+      roles: {},
+      conditions: {},
+      graph: {},
+    });
+
+    let prev: string | null = null;
+    let stepHash = "";
+    for (const role of roles) {
+      stepHash = await uwf.store.put(uwf.schemas.stepNode, {
+        start: startHash,
+        prev: prev as CasRef | null,
+        role,
+        output: outputHash,
+        detail: null,
+        agent: "uwf-test",
+      });
+      prev = stepHash;
+    }
+    return stepHash;
+  }
+
+  test("same consecutive role shows ### Prompt once", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const headHash = await makeThreadWithRoles(uwf, ["writer", "writer"]);
+    const threadId = "01JTEST0000000000000003" as ThreadId;
+    await saveThreadsIndex(tmpDir, { [threadId]: headHash });
+
+    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
+    const count = (markdown.match(/### Prompt/g) ?? []).length;
+    expect(count).toBe(1);
+  });
+
+  test("different consecutive roles each show ### Prompt", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const headHash = await makeThreadWithRoles(uwf, ["planner", "coder"]);
+    const threadId = "01JTEST0000000000000004" as ThreadId;
+    await saveThreadsIndex(tmpDir, { [threadId]: headHash });
+
+    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
+    const count = (markdown.match(/### Prompt/g) ?? []).length;
+    expect(count).toBe(2);
+  });
+
+  test("non-consecutive same role shows ### Prompt twice", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const headHash = await makeThreadWithRoles(uwf, ["roleA", "roleB", "roleA"]);
+    const threadId = "01JTEST0000000000000005" as ThreadId;
+    await saveThreadsIndex(tmpDir, { [threadId]: headHash });
+
+    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
+    const count = (markdown.match(/### Prompt/g) ?? []).length;
+    expect(count).toBe(2);
+  });
+});

packages/cli-workflow/src/__tests__/workflow-resolution.test.ts

@@ -0,0 +1,367 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createFsStore } from "@uncaged/json-cas-fs";
+import type { CasRef, WorkflowPayload } from "@uncaged/workflow-protocol";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { stringify } from "yaml";
+import { cmdThreadStart } from "../commands/thread.js";
+import { registerUwfSchemas } from "../schemas.js";
+import type { UwfStore } from "../store.js";
+import { loadWorkflowRegistry, saveWorkflowRegistry } from "../store.js";
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+async function makeUwfStore(storageRoot: string): Promise<UwfStore> {
+  const casDir = join(storageRoot, "cas");
+  await mkdir(casDir, { recursive: true });
+  const store = createFsStore(casDir);
+  const schemas = await registerUwfSchemas(store);
+  return { storageRoot, store, schemas };
+}
+
+async function storeWorkflow(uwf: UwfStore, name: string): Promise<CasRef> {
+  const payload: WorkflowPayload = {
+    name,
+    description: "Test workflow",
+    roles: {},
+    conditions: {},
+    graph: {},
+  };
+  return await uwf.store.put(uwf.schemas.workflow, payload);
+}
+
+async function createWorkflowYaml(name: string, version: string | null = null): Promise<string> {
+  const payload: WorkflowPayload = {
+    name,
+    description: version !== null ? `Test workflow (${version})` : "Test workflow",
+    roles: {},
+    conditions: {},
+    graph: {},
+  };
+  const yaml = stringify(payload);
+  return yaml;
+}
+
+// ── fixture ───────────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+let storageRoot: string;
+let projectRoot: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "cli-uwf-wf-resolve-test-"));
+  storageRoot = join(tmpDir, "storage");
+  projectRoot = join(tmpDir, "project");
+  await mkdir(storageRoot, { recursive: true });
+  await mkdir(projectRoot, { recursive: true });
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+// ── Strategy 1: CAS Hash Resolution ───────────────────────────────────────────
+
+describe("Strategy 1: CAS Hash Resolution", () => {
+  test("should resolve valid 13-char Crockford Base32 hash", async () => {
+    const uwf = await makeUwfStore(storageRoot);
+    const hash = await storeWorkflow(uwf, "test-workflow");
+
+    const result = await cmdThreadStart(storageRoot, hash, "test prompt", projectRoot);
+
+    expect(result.workflow).toBe(hash);
+    expect(result.thread).toMatch(/^[0-9A-HJKMNP-TV-Z]{26}$/);
+  });
+
+  test("should fail on invalid hash format (non-Crockford characters)", async () => {
+    await makeUwfStore(storageRoot);
+
+    await expect(
+      cmdThreadStart(storageRoot, "123456789ABCD", "prompt", projectRoot),
+    ).rejects.toThrow();
+  });
+
+  test("should fail on valid-format hash not present in CAS", async () => {
+    await makeUwfStore(storageRoot);
+    const fakeHash = "0000000000000"; // valid format, doesn't exist
+
+    await expect(cmdThreadStart(storageRoot, fakeHash, "prompt", projectRoot)).rejects.toThrow();
+  });
+
+  test("should reject 40-char hex hash (legacy format not supported)", async () => {
+    await makeUwfStore(storageRoot);
+    const hexHash = "a".repeat(40);
+
+    await expect(cmdThreadStart(storageRoot, hexHash, "prompt", projectRoot)).rejects.toThrow();
+  });
+});
+
+// ── Strategy 2: File Path Resolution ──────────────────────────────────────────
+
+describe("Strategy 2: File Path Resolution", () => {
+  test("should load workflow from absolute file path", async () => {
+    await makeUwfStore(storageRoot);
+    const yamlPath = join(tmpDir, "test-workflow.yaml");
+    await writeFile(yamlPath, await createWorkflowYaml("test-workflow"));
+
+    const result = await cmdThreadStart(storageRoot, yamlPath, "prompt", projectRoot);
+
+    expect(result.workflow).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+    const uwf = await makeUwfStore(storageRoot);
+    const node = uwf.store.get(result.workflow);
+    expect(node).not.toBeNull();
+    if (node !== null) {
+      expect((node.payload as WorkflowPayload).name).toBe("test-workflow");
+    }
+  });
+
+  test("should load workflow from relative file path", async () => {
+    await makeUwfStore(storageRoot);
+    const yamlPath = "test-workflow.yaml";
+    await writeFile(join(projectRoot, yamlPath), await createWorkflowYaml("test-workflow"));
+
+    const result = await cmdThreadStart(storageRoot, yamlPath, "prompt", projectRoot);
+
+    expect(result.workflow).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+
+  test("should fail when file path does not exist", async () => {
+    await makeUwfStore(storageRoot);
+
+    await expect(
+      cmdThreadStart(storageRoot, "./nonexistent.yaml", "prompt", projectRoot),
+    ).rejects.toThrow();
+  });
+
+  test("should fail on invalid YAML syntax in file", async () => {
+    await makeUwfStore(storageRoot);
+    const yamlPath = join(tmpDir, "bad-syntax.yaml");
+    await writeFile(yamlPath, "invalid: yaml: : :");
+
+    await expect(cmdThreadStart(storageRoot, yamlPath, "prompt", projectRoot)).rejects.toThrow();
+  });
+
+  test("should fail on valid YAML with invalid WorkflowPayload shape", async () => {
+    await makeUwfStore(storageRoot);
+    const yamlPath = join(tmpDir, "invalid-workflow.yaml");
+    await writeFile(yamlPath, "name: test\n# missing roles, conditions, and graph");
+
+    await expect(cmdThreadStart(storageRoot, yamlPath, "prompt", projectRoot)).rejects.toThrow();
+  });
+
+  test("should enforce filename matches workflow name", async () => {
+    await makeUwfStore(storageRoot);
+    const yamlPath = join(tmpDir, "solve-issue.yaml");
+    await writeFile(yamlPath, await createWorkflowYaml("wrong-name"));
+
+    await expect(cmdThreadStart(storageRoot, yamlPath, "prompt", projectRoot)).rejects.toThrow();
+  });
+});
+
+// ── Strategy 3: Local Discovery (Parent Traversal) ────────────────────────────
+
+describe("Strategy 3: Local Discovery", () => {
+  test("should find workflow in current directory .workflow/", async () => {
+    await makeUwfStore(storageRoot);
+    const workflowDir = join(projectRoot, ".workflow");
+    await mkdir(workflowDir, { recursive: true });
+    await writeFile(join(workflowDir, "solve-issue.yaml"), await createWorkflowYaml("solve-issue"));
+
+    const result = await cmdThreadStart(storageRoot, "solve-issue", "prompt", projectRoot);
+
+    expect(result.workflow).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+    const uwf = await makeUwfStore(storageRoot);
+    const node = uwf.store.get(result.workflow);
+    expect(node).not.toBeNull();
+    if (node !== null) {
+      expect((node.payload as WorkflowPayload).name).toBe("solve-issue");
+    }
+  });
+
+  test("should find workflow in parent directory .workflow/", async () => {
+    await makeUwfStore(storageRoot);
+    const workflowDir = join(projectRoot, ".workflow");
+    await mkdir(workflowDir, { recursive: true });
+    await writeFile(join(workflowDir, "solve-issue.yaml"), await createWorkflowYaml("solve-issue"));
+
+    const subdir = join(projectRoot, "packages", "cli-workflow", "src");
+    await mkdir(subdir, { recursive: true });
+
+    const result = await cmdThreadStart(storageRoot, "solve-issue", "prompt", subdir);
+
+    expect(result.workflow).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+
+  test("should stop at filesystem root when traversing", async () => {
+    await makeUwfStore(storageRoot);
+    const deepPath = join(tmpDir, "deep", "path", "that", "does", "not", "have", "workflow");
+    await mkdir(deepPath, { recursive: true });
+
+    await expect(cmdThreadStart(storageRoot, "nonexistent", "prompt", deepPath)).rejects.toThrow();
+  });
+
+  test("should prefer .workflow/ over .workflows/ directory", async () => {
+    await makeUwfStore(storageRoot);
+    const workflowDir = join(projectRoot, ".workflow");
+    const workflowsDir = join(projectRoot, ".workflows");
+    await mkdir(workflowDir, { recursive: true });
+    await mkdir(workflowsDir, { recursive: true });
+
+    await writeFile(
+      join(workflowDir, "solve-issue.yaml"),
+      await createWorkflowYaml("solve-issue", "1"),
+    );
+    await writeFile(
+      join(workflowsDir, "solve-issue.yaml"),
+      await createWorkflowYaml("solve-issue", "2"),
+    );
+
+    const result = await cmdThreadStart(storageRoot, "solve-issue", "prompt", projectRoot);
+
+    const uwf = await makeUwfStore(storageRoot);
+    const node = uwf.store.get(result.workflow);
+    expect(node).not.toBeNull();
+    if (node !== null) {
+      expect((node.payload as WorkflowPayload).description).toBe("Test workflow (1)");
+    }
+  });
+
+  test("should support .yml extension in local discovery", async () => {
+    await makeUwfStore(storageRoot);
+    const workflowDir = join(projectRoot, ".workflow");
+    await mkdir(workflowDir, { recursive: true });
+    await writeFile(join(workflowDir, "solve-issue.yml"), await createWorkflowYaml("solve-issue"));
+
+    const result = await cmdThreadStart(storageRoot, "solve-issue", "prompt", projectRoot);
+
+    expect(result.workflow).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+});
+
+// ── Strategy 4: Global Registry Fallback ──────────────────────────────────────
+
+describe("Strategy 4: Global Registry Resolution", () => {
+  test("should resolve workflow from global registry when not found locally", async () => {
+    const uwf = await makeUwfStore(storageRoot);
+    const hash = await storeWorkflow(uwf, "deploy-pipeline");
+    const registry = await loadWorkflowRegistry(storageRoot);
+    registry["deploy-pipeline"] = hash;
+    await saveWorkflowRegistry(storageRoot, registry);
+
+    const isolatedRoot = join(tmpDir, "isolated");
+    await mkdir(isolatedRoot, { recursive: true });
+
+    const result = await cmdThreadStart(storageRoot, "deploy-pipeline", "prompt", isolatedRoot);
+
+    expect(result.workflow).toBe(hash);
+  });
+
+  test("should fail when workflow not found in any strategy", async () => {
+    await makeUwfStore(storageRoot);
+
+    await expect(cmdThreadStart(storageRoot, "nonexistent", "prompt", tmpDir)).rejects.toThrow();
+  });
+});
+
+// ── Strategy Priority Order ───────────────────────────────────────────────────
+
+describe("Resolution Priority", () => {
+  test("should use explicit file path over local discovery", async () => {
+    await makeUwfStore(storageRoot);
+
+    // Setup: Create workflow in .workflow/ AND as explicit file
+    const workflowDir = join(projectRoot, ".workflow");
+    await mkdir(workflowDir, { recursive: true });
+    await writeFile(
+      join(workflowDir, "solve-issue.yaml"),
+      await createWorkflowYaml("solve-issue", "discovery"),
+    );
+
+    const explicitPath = join(projectRoot, "custom-solve-issue.yaml");
+    await writeFile(explicitPath, await createWorkflowYaml("custom-solve-issue", "explicit"));
+
+    // Execute with explicit path
+    const result = await cmdThreadStart(storageRoot, explicitPath, "prompt", projectRoot);
+
+    const uwf = await makeUwfStore(storageRoot);
+    const node = uwf.store.get(result.workflow);
+    expect(node).not.toBeNull();
+    if (node !== null) {
+      expect((node.payload as WorkflowPayload).description).toBe("Test workflow (explicit)");
+    }
+  });
+
+  test("should use local discovery over global registry", async () => {
+    const uwf = await makeUwfStore(storageRoot);
+
+    // Setup: Register globally
+    const globalHash = await storeWorkflow(uwf, "solve-issue");
+    const registry = await loadWorkflowRegistry(storageRoot);
+    registry["solve-issue"] = globalHash;
+    await saveWorkflowRegistry(storageRoot, registry);
+
+    // Setup: Create local .workflow/
+    const workflowDir = join(projectRoot, ".workflow");
+    await mkdir(workflowDir, { recursive: true });
+    const localYaml = await createWorkflowYaml("solve-issue", "local");
+    await writeFile(join(workflowDir, "solve-issue.yaml"), localYaml);
+
+    const result = await cmdThreadStart(storageRoot, "solve-issue", "prompt", projectRoot);
+
+    const uwf2 = await makeUwfStore(storageRoot);
+    const node = uwf2.store.get(result.workflow);
+    expect(node).not.toBeNull();
+    if (node !== null) {
+      expect((node.payload as WorkflowPayload).description).toBe("Test workflow (local)");
+    }
+  });
+});
+
+// ── Edge Cases ────────────────────────────────────────────────────────────────
+
+describe("Edge Cases", () => {
+  test("should treat '13-char-string.yaml' as file path, not CAS hash", async () => {
+    await makeUwfStore(storageRoot);
+    const fileName = "0123456789ABC.yaml"; // 13 chars + .yaml
+    await writeFile(join(projectRoot, fileName), await createWorkflowYaml("0123456789ABC"));
+
+    const result = await cmdThreadStart(storageRoot, fileName, "prompt", projectRoot);
+
+    expect(result.workflow).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+
+  test("should handle workflow names containing slashes as file paths", async () => {
+    await makeUwfStore(storageRoot);
+    const filePath = "subdir/solve-issue.yaml";
+    const fullPath = join(projectRoot, filePath);
+    await mkdir(join(projectRoot, "subdir"), { recursive: true });
+    await writeFile(fullPath, await createWorkflowYaml("solve-issue"));
+
+    const result = await cmdThreadStart(storageRoot, filePath, "prompt", projectRoot);
+
+    expect(result.workflow).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+
+  test("should handle absolute paths correctly", async () => {
+    await makeUwfStore(storageRoot);
+    const absPath = join(tmpDir, "abs-workflow.yaml");
+    await writeFile(absPath, await createWorkflowYaml("abs-workflow"));
+
+    const result = await cmdThreadStart(storageRoot, absPath, "prompt", projectRoot);
+
+    expect(result.workflow).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+
+  test("should fail on empty workflow ID", async () => {
+    await makeUwfStore(storageRoot);
+
+    await expect(cmdThreadStart(storageRoot, "", "prompt", projectRoot)).rejects.toThrow();
+  });
+
+  test("should fail on whitespace-only workflow ID", async () => {
+    await makeUwfStore(storageRoot);
+
+    await expect(cmdThreadStart(storageRoot, "   ", "prompt", projectRoot)).rejects.toThrow();
+  });
+});

packages/cli-workflow/src/commands/setup.ts

@@ -137,6 +137,75 @@ function apiKeyEnvName(providerName: string): string {
   return `${providerName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`;
 }
 
+/**
+ * Discover uwf-* agent binaries in PATH.
+ * Returns sorted list of binary names (e.g., ["uwf-hermes", "uwf-claude-code"]).
+ */
+async function _discoverAgents(): Promise<string[]> {
+  try {
+    // Use which -a to find all uwf-* binaries in PATH
+    const proc = Bun.spawn(["which", "-a", "uwf-hermes", "uwf-claude-code", "uwf-cursor"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const text = await new Response(proc.stdout).text();
+    await proc.exited;
+
+    if (proc.exitCode !== 0) {
+      // Try alternative approach: search PATH directories manually
+      const pathEnv = process.env.PATH || "";
+      const pathDirs = pathEnv.split(":").filter((d) => d.length > 0);
+      const agents = new Set<string>();
+
+      for (const dir of pathDirs) {
+        try {
+          if (!existsSync(dir)) continue;
+          const { readdirSync, statSync } = await import("node:fs");
+          const entries = readdirSync(dir);
+
+          for (const entry of entries) {
+            if (!entry.startsWith("uwf-") || entry === "uwf") continue;
+            const fullPath = join(dir, entry);
+            try {
+              const stat = statSync(fullPath);
+              // Check if executable (owner, group, or other has execute bit)
+              if (stat.isFile() && (stat.mode & 0o111) !== 0) {
+                agents.add(entry);
+              }
+            } catch {
+              // Skip if can't stat
+            }
+          }
+        } catch {
+          // Skip inaccessible directories
+        }
+      }
+
+      return Array.from(agents).sort();
+    }
+
+    // Parse which output - each line is a path to a binary
+    const paths = text
+      .trim()
+      .split("\n")
+      .filter((line) => line.length > 0);
+    const agents = new Set<string>();
+
+    for (const path of paths) {
+      const basename = path.split("/").pop();
+      if (basename?.startsWith("uwf-") && basename !== "uwf") {
+        agents.add(basename);
+      }
+    }
+
+    return Array.from(agents).sort();
+  } catch {
+    // If all fails, return empty array
+    return [];
+  }
+}
+
 /**
  * Merge setup args into config.yaml structure. Non-destructive — preserves existing entries.
  */

packages/cli-workflow/src/commands/thread.ts

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
-import { readFile } from "node:fs/promises";
+import { access, readFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve as resolvePath } from "node:path";
 import type { Store as CasStore, JSONSchema } from "@uncaged/json-cas";
 import { getSchema, validate } from "@uncaged/json-cas";
 import { getEnvPath, loadWorkflowConfig } from "@uncaged/workflow-agent-kit";
@@ -30,12 +31,10 @@ import { parse, stringify } from "yaml";
 import {
   appendThreadHistory,
   createUwfStore,
-  discoverProjectWorkflows,
   findThreadInHistory,
   loadThreadHistory,
   loadThreadsIndex,
   loadWorkflowRegistry,
-  resolveProjectWorkflowFile,
   resolveWorkflowHash,
   saveThreadsIndex,
   type ThreadHistoryLine,
@@ -82,6 +81,83 @@ function fail(message: string): never {
   process.exit(1);
 }
 
+/**
+ * Check if a string looks like a file path (contains path separators or has .yaml/.yml extension).
+ */
+function isFilePath(input: string): boolean {
+  return (
+    input.includes("/") || input.includes("\\") || input.endsWith(".yaml") || input.endsWith(".yml")
+  );
+}
+
+/**
+ * Check if a workflow file exists at the given path.
+ */
+async function workflowFileExists(dir: string, name: string, ext: string): Promise<string | null> {
+  const candidate = resolvePath(dir, `${name}${ext}`);
+  try {
+    await access(candidate);
+    return candidate;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Search for a workflow file in a given directory (checks both .workflow/ and .workflows/).
+ */
+async function findWorkflowInDir(dir: string, name: string): Promise<string | null> {
+  // Check .workflow/ directory first (preferred)
+  for (const ext of [".yaml", ".yml"]) {
+    const result = await workflowFileExists(resolvePath(dir, ".workflow"), name, ext);
+    if (result !== null) {
+      return result;
+    }
+  }
+
+  // Check .workflows/ directory as fallback (legacy)
+  for (const ext of [".yaml", ".yml"]) {
+    const result = await workflowFileExists(resolvePath(dir, ".workflows"), name, ext);
+    if (result !== null) {
+      return result;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Traverse parent directories looking for `.workflow/<name>.yaml` or `.workflow/<name>.yml`.
+ * Returns the absolute path if found, otherwise null.
+ * Stops at filesystem root or .git directory.
+ */
+async function findWorkflowInParents(startDir: string, name: string): Promise<string | null> {
+  let currentDir = resolvePath(startDir);
+  const root = resolvePath("/");
+
+  while (true) {
+    const found = await findWorkflowInDir(currentDir, name);
+    if (found !== null) {
+      return found;
+    }
+
+    // Stop at filesystem root
+    if (currentDir === root) {
+      break;
+    }
+
+    // Move to parent directory
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      // Reached filesystem root
+      break;
+    }
+    currentDir = parentDir;
+  }
+
+  return null;
+}
+
 async function materializeLocalWorkflow(uwf: UwfStore, filePath: string): Promise<CasRef> {
   let text: string;
   try {
@@ -123,18 +199,41 @@ async function resolveWorkflowCasRef(
   workflowId: string,
   projectRoot: string,
 ): Promise<CasRef> {
-  // Project-local resolution: check .workflows/<workflowId>.yaml first
-  const localEntries = await discoverProjectWorkflows(projectRoot);
-  const localFile = resolveProjectWorkflowFile(localEntries, workflowId);
-  if (localFile !== null) {
-    return materializeLocalWorkflow(uwf, localFile);
+  // Validate input
+  const trimmed = workflowId.trim();
+  if (trimmed === "") {
+    fail("workflow ID cannot be empty");
   }
 
-  // Global registry fallback
+  // Strategy 1: Direct CAS hash
+  if (isCasRef(trimmed)) {
+    const node = uwf.store.get(trimmed);
+    if (node === null) {
+      fail(`CAS node not found: ${trimmed}`);
+    }
+    if (node.type !== uwf.schemas.workflow) {
+      fail(`node ${trimmed} is not a Workflow (type ${node.type})`);
+    }
+    return trimmed;
+  }
+
+  // Strategy 2: Explicit file path (relative or absolute)
+  if (isFilePath(trimmed)) {
+    const absolutePath = isAbsolute(trimmed) ? trimmed : resolvePath(projectRoot, trimmed);
+    return materializeLocalWorkflow(uwf, absolutePath);
+  }
+
+  // Strategy 3: Local discovery (parent directory traversal)
+  const localPath = await findWorkflowInParents(projectRoot, trimmed);
+  if (localPath !== null) {
+    return materializeLocalWorkflow(uwf, localPath);
+  }
+
+  // Strategy 4: Global registry fallback
   const registry = await loadWorkflowRegistry(storageRoot);
-  const hash = resolveWorkflowHash(registry, workflowId);
+  const hash = resolveWorkflowHash(registry, trimmed);
   if (!isCasRef(hash)) {
-    fail(`workflow not found: ${workflowId}`);
+    fail(`workflow not found: ${trimmed}`);
   }
   const node = uwf.store.get(hash);
   if (node === null) {
@@ -440,7 +539,7 @@ function collectOrderedSteps(
 }
 
 function formatYaml(value: unknown): string {
-  return stringify(value).trimEnd();
+  return stringify(value, { aliasDuplicateObjects: false }).trimEnd();
 }
 
 function formatCompactStep(index: number, item: OrderedStepItem, outputYaml: string): string {
@@ -556,11 +655,11 @@ function formatThreadReadMarkdown(options: {
 
   // Step blocks
   const startIndex = candidates.length - selected.length;
+  const shownPromptRoles = new Set<string>();
   for (let i = 0; i < selected.length; i++) {
     const item = selected[i];
     if (item === undefined) continue;
     const stepNum = startIndex + i + 1;
-    const outputYaml = formatYaml(expandOutput(uwf, item.payload.output));
     const ts = new Date(item.timestamp)
       .toISOString()
       .replace("T", " ")
@@ -570,9 +669,10 @@ function formatThreadReadMarkdown(options: {
       `**Agent:** ${item.payload.agent} | **Time:** ${ts}`,
     ];
     const roleDef = workflow.roles[item.payload.role];
-    if (roleDef) {
+    if (roleDef && !shownPromptRoles.has(item.payload.role)) {
       const prompt = roleDef.goal;
       stepLines.push("", "### Prompt", "", prompt);
+      shownPromptRoles.add(item.payload.role);
     }
     if (item.payload.detail) {
       const content = extractLastAssistantContent(uwf, item.payload.detail);
@@ -580,7 +680,6 @@ function formatThreadReadMarkdown(options: {
         stepLines.push("", "### Content", "", content);
       }
     }
-    stepLines.push("", "### Output", "", "```yaml", outputYaml, "```");
     parts.push(stepLines.join("\n"));
   }
 

packages/cli-workflow/src/format.ts

@@ -7,6 +7,6 @@ export function formatOutput(data: unknown, format: OutputFormat): string {
     case "json":
       return JSON.stringify(data);
     case "yaml":
-      return stringify(data).trimEnd();
+      return stringify(data, { aliasDuplicateObjects: false }).trimEnd();
   }
 }

packages/workflow-agent-builtin/src/agent.ts

@@ -13,10 +13,28 @@ import { storeBuiltinDetail } from "./detail.js";
 import type { ChatMessage } from "./llm/index.js";
 import { BUILTIN_CONTINUE_MAX_TURNS, BUILTIN_MAX_TURNS, runBuiltinLoop } from "./loop.js";
 import { buildBuiltinMessages } from "./prompt.js";
-import { initSessionDir, removeSession } from "./session.js";
+import { initSessionDir } from "./session.js";
 
 const log = createLogger({ sink: { kind: "stderr" } });
 
+const FRONTMATTER_FENCE = "---";
+
+/**
+ * Strip any text before the first `---` fence.
+ * LLMs sometimes emit preamble text before the frontmatter block.
+ */
+function stripPreamble(text: string): string {
+  if (text.startsWith(FRONTMATTER_FENCE)) {
+    return text;
+  }
+  const idx = text.indexOf(`\n${FRONTMATTER_FENCE}\n`);
+  if (idx !== -1) {
+    log("6GWRP3QX", `stripped ${idx + 1} chars of preamble before frontmatter`);
+    return text.slice(idx + 1);
+  }
+  return text;
+}
+
 type SessionRecord = {
   sessionId: string;
   model: string;
@@ -48,6 +66,7 @@ async function runBuiltinWithMessages(
   session: SessionRecord,
   store: Store,
   maxTurns: number,
+  noTools: boolean,
 ): Promise<AgentRunResult> {
   const loopResult = await runBuiltinLoop({
     provider,
@@ -56,13 +75,13 @@ async function runBuiltinWithMessages(
     maxTurns,
     storageRoot,
     sessionId: session.sessionId,
+    noTools,
   });
 
   session.messages = loopResult.messages;
 
   if (loopResult.turnCount === 0) {
     log("5RWTK9NB", "no turns produced, returning empty output");
-    await removeSession(storageRoot, session.sessionId);
     return { output: "", detailHash: "", sessionId: session.sessionId };
   }
 
@@ -75,10 +94,7 @@ async function runBuiltinWithMessages(
     session.startedAtMs,
   );
 
-  // Clean up session jsonl
-  await removeSession(storageRoot, session.sessionId);
-
-  return { output: loopResult.finalText, detailHash, sessionId: session.sessionId };
+  return { output: stripPreamble(loopResult.finalText), detailHash, sessionId: session.sessionId };
 }
 
 async function runBuiltin(ctx: AgentContext): Promise<AgentRunResult> {
@@ -105,6 +121,7 @@ async function runBuiltin(ctx: AgentContext): Promise<AgentRunResult> {
     session,
     ctx.store,
     BUILTIN_MAX_TURNS,
+    false,
   );
 }
 
@@ -127,6 +144,7 @@ async function continueBuiltin(
     session,
     store,
     BUILTIN_CONTINUE_MAX_TURNS,
+    true,
   );
 }
 

packages/workflow-agent-builtin/src/llm/llm.ts

@@ -96,8 +96,17 @@ function serializeMessage(message: ChatMessage): Record<string, unknown> {
 export async function chatCompletionWithTools(
   provider: ResolvedLlmProvider,
   messages: ChatMessage[],
-  tools: OpenAiToolDefinition[],
+  tools: OpenAiToolDefinition[] | null,
 ): Promise<LlmAssistantResponse> {
+  const body: Record<string, unknown> = {
+    model: provider.model,
+    messages: messages.map(serializeMessage),
+  };
+  if (tools !== null && tools.length > 0) {
+    body.tools = tools;
+    body.tool_choice = "auto";
+  }
+
   let response: Response;
   try {
     response = await fetch(chatUrl(provider.baseUrl), {
@@ -106,12 +115,7 @@ export async function chatCompletionWithTools(
         Authorization: `Bearer ${provider.apiKey}`,
         "Content-Type": "application/json",
       },
-      body: JSON.stringify({
-        model: provider.model,
-        messages: messages.map(serializeMessage),
-        tools,
-        tool_choice: "auto",
-      }),
+      body: JSON.stringify(body),
     });
   } catch (cause) {
     const message = cause instanceof Error ? cause.message : String(cause);

packages/workflow-agent-builtin/src/loop.ts

@@ -23,6 +23,8 @@ export type RunBuiltinLoopOptions = {
   maxTurns: number;
   storageRoot: string;
   sessionId: string;
+  /** When true, do not provide tools — force LLM to emit text only. */
+  noTools: boolean;
 };
 
 export type RunBuiltinLoopResult = {
@@ -73,13 +75,17 @@ export async function runBuiltinLoop(
   options: RunBuiltinLoopOptions,
 ): Promise<RunBuiltinLoopResult> {
   const messages = [...options.messages];
-  const openAiTools = builtinToolsToOpenAi(getBuiltinTools());
+  const openAiTools = options.noTools ? [] : builtinToolsToOpenAi(getBuiltinTools());
   let finalText = "";
   let turnCount = 0;
 
   for (let turn = 0; turn < options.maxTurns; turn++) {
     log("8K2M4N7P", `builtin loop turn ${turn + 1}/${options.maxTurns}`);
-    const response = await chatCompletionWithTools(options.provider, messages, openAiTools);
+    const response = await chatCompletionWithTools(
+      options.provider,
+      messages,
+      openAiTools.length > 0 ? openAiTools : null,
+    );
 
     const assistantMessage: ChatMessage = {
       role: "assistant",
@@ -89,14 +95,27 @@ export async function runBuiltinLoop(
     messages.push(assistantMessage);
 
     if (response.toolCalls === null || response.toolCalls.length === 0) {
-      finalText = response.content ?? "";
+      const text = response.content ?? "";
       await appendTurn(options.storageRoot, options.sessionId, {
         role: "assistant",
-        content: response.content ?? "",
+        content: text,
         toolCalls: null,
         reasoning: null,
       });
       turnCount += 1;
+
+      // If tools are available but LLM stopped calling them without producing
+      // frontmatter, nudge it to continue working or output frontmatter.
+      if (!options.noTools && !text.trimStart().startsWith("---") && turn < options.maxTurns - 1) {
+        log("7FXQM2KN", "text-only turn without frontmatter, nudging LLM to continue");
+        const nudge =
+          "You stopped calling tools but your response does not start with the required `---` YAML frontmatter. " +
+          "Either continue using tools to complete your work, or output your final response starting with `---`.";
+        messages.push({ role: "user", content: nudge });
+        continue;
+      }
+
+      finalText = text;
       break;
     }
 

packages/workflow-agent-builtin/src/prompt.ts

@@ -59,6 +59,21 @@ export function buildBuiltinMessages(ctx: AgentContext): ChatMessage[] {
   }
   systemParts.push(rolePrompt);
 
+  systemParts.push(
+    "",
+    "## Workflow",
+    "",
+    `Your working directory is: ${process.cwd()}`,
+    "",
+    "You have tools available (read_file, write_file, run_command). " +
+      "Use them to complete your task — read files, run commands, make changes as needed. " +
+      "Your task is described in the user message below — do NOT use uwf or workflow CLI commands to discover your task. " +
+      "When you are done, output your final response with the YAML frontmatter block as specified above. " +
+      "Do NOT output the frontmatter until you have completed all necessary work. " +
+      "CRITICAL: Your final output MUST start with the `---` fence on the very first line — " +
+      "no preamble text, no explanation before it. The parser requires `---` at position 0.",
+  );
+
   const messages: ChatMessage[] = [{ role: "system", content: systemParts.join("\n") }];
 
   const roleVisitIndices: number[] = [];

packages/workflow-agent-claude-code/src/claude-code.ts

@@ -49,6 +49,7 @@ export function buildClaudeCodePrompt(ctx: AgentContext): string {
   if (historyBlock !== "") {
     parts.push("", historyBlock);
   }
+  parts.push("", "## Current Instruction", "", ctx.edgePrompt);
   return parts.join("\n");
 }
 
@@ -132,6 +133,8 @@ async function processClaudeOutput(stdout: string, store: Store): Promise<AgentR
 async function runClaudeCode(ctx: AgentContext): Promise<AgentRunResult> {
   const fullPrompt = buildClaudeCodePrompt(ctx);
 
+  log("K7R2M4N8", `prompt for role=${ctx.role} (length=${fullPrompt.length}):\n${fullPrompt}`);
+
   // Try resuming a cached session for re-entry scenarios (e.g. reviewer reject → developer re-entry).
   if (!ctx.isFirstVisit) {
     const cachedSessionId = await getCachedSessionId(ctx.threadId, ctx.role);