docs: update all documentation to reflect apiKey refactoring (#528)

Update all documentation files that contained outdated apiKeyEnv
references to use the new apiKey approach.

## Changes

- docs/architecture.md: Update config example to use apiKey field
- docs/wf-stateless-design.md: Update config examples and type
  definitions to use apiKey instead of apiKeyEnv
- docs/builtin-agent-research.md: Update ProviderConfig type
  definition and code examples

All documentation now consistent with the code implementation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.gitignore

@@ -12,4 +12,4 @@ packages/workflow-template-develop/develop.esm.js
 .DS_Store
 *.py
 .claude
-tmp
+tmp.worktrees/

.workflows/retrospect-workflow.yaml

@@ -1,220 +0,0 @@
-name: "retrospect-workflow"
-description: "Post-execution retrospective: analyze a completed thread, find inefficiencies, and improve the workflow definition."
-roles:
-  analyst:
-    description: "Scans thread execution for anomalies and produces a findings report"
-    goal: "You are a workflow execution analyst. You review completed thread data to find inefficiencies, wasted effort, and procedure gaps."
-    capabilities:
-      - data-analysis
-    procedure: |
-      You receive a completed thread ID in your task prompt.
-
-      Phase 0 — Validation (must pass before any analysis):
-      1. Run `uwf step list <thread-id>` to get thread metadata including the workflow hash
-      2. Run `uwf workflow show <workflow-hash>` to get the workflow name
-      3. Verify the workflow exists locally: check `.workflows/<name>.yaml` in the current repo
-         - If NOT found: output $status=wrong_project with the workflow name. Do NOT proceed.
-      4. Compare the thread's workflow hash against the current registered version:
-         - Run `uwf workflow show <name>` to get the current hash
-         - If hashes differ: the thread ran on an older version. Note this — you will need to diff versions after analysis.
-
-      Phase 1 — Overview scan:
-      5. From the step list, compute a health signal for each step:
-         - Duration: flag if >2x the median of other steps
-         - Output tokens: flag if >2x the median
-         - Status flow: flag non-happy-path transitions (rejected, fix_code, fix_spec, hook_failed)
-         - Step count: flag if the same role appears more than expected (indicates loops)
-      6. If no anomalies found AND versions match: output $status=clean
-      7. If no anomalies found BUT versions differ:
-         - Diff the two workflow versions to check if any procedure changes are relevant
-         - If the current version already addresses potential concerns: output $status=clean with a note
-         - Otherwise: proceed to Phase 2
-
-      Phase 2 — Targeted deep-dive (only for flagged steps):
-      8. For each flagged step, run `uwf step show <hash>` to get the detail with turns
-      9. Analyze the turn sequence for:
-         - Repeated tool calls with the same or similar input (blind retries)
-         - Tool errors followed by no strategy change (same approach retried)
-         - Unnecessary exploration (reading files or running commands unrelated to the task)
-         - Hallucinated commands or flags (commands that don't exist or wrong syntax)
-         - Excessive turns before reaching the goal
-      10. For each finding, record:
-          - Which role and step hash
-          - What happened (specific turn indices and commands)
-          - Root cause hypothesis (procedure gap, missing pitfall, unclear instruction)
-          - Suggested fix (what to add/change in the procedure)
-      11. If versions differ: compare findings against the version diff.
-          Mark any finding that is already fixed in the current version as "resolved_in_current".
-          Only report findings that are NOT yet addressed.
-
-      Output a structured findings report. Set $status=clean if nothing actionable, $status=findings if unresolved issues exist, or $status=wrong_project if the workflow doesn't belong here.
-    output: "A findings report with per-issue root cause and suggested procedure fixes. Set $status to clean or findings (with report hash)."
-    frontmatter:
-      oneOf:
-        - properties:
-            $status: { const: "clean" }
-            summary: { type: string }
-          required: [$status, summary]
-        - properties:
-            $status: { const: "findings" }
-            report: { type: string }
-            targetWorkflow: { type: string }
-          required: [$status, report, targetWorkflow]
-        - properties:
-            $status: { const: "wrong_project" }
-            workflowName: { type: string }
-          required: [$status, workflowName]
-  proposer:
-    description: "Translates findings into concrete workflow edits"
-    goal: "You are a workflow improvement proposer. You read the analyst's findings and produce specific, minimal edits to the workflow YAML."
-    capabilities:
-      - planning
-    procedure: |
-      1. Read the analyst's findings report from your task prompt
-      2. Locate the target workflow YAML:
-         - Workflow definitions live in the WORKFLOW ENGINE repo (where `uwf` is developed), NOT in the repo that was analyzed.
-         - Find it via: `uwf workflow show <targetWorkflow> --format yaml` to read the current definition
-         - The physical file is `.workflows/<targetWorkflow>.yaml` in the workflow engine repo
-         - Use `git rev-parse --show-toplevel` in the current directory to find the workflow engine repo root
-      3. Read the current workflow YAML to understand existing procedures
-      4. For each finding, draft a minimal edit:
-         - Prefer adding a pitfall note or clarifying instruction over restructuring
-         - If a procedure step is ambiguous, make it explicit
-         - If a tool usage pattern is wrong, add a "Do NOT" or "IMPORTANT" note
-         - Keep edits surgical — don't rewrite procedures that work fine
-      5. Check if existing tests need updating (search for test files referencing the workflow)
-      6. Produce a change plan as CAS text node via `uwf cas put-text "<plan>"`
-
-      The plan should list each edit with:
-      - File path
-      - What to change (old text → new text, or addition)
-      - Why (linked to which finding)
-      - Any test updates needed
-    output: "A change plan stored in CAS. Set $status to ready (with plan hash and repoPath) or no_action (if findings don't warrant changes)."
-    frontmatter:
-      oneOf:
-        - properties:
-            $status: { const: "ready" }
-            plan: { type: string }
-            repoPath: { type: string }
-          required: [$status, plan, repoPath]
-        - properties:
-            $status: { const: "no_action" }
-            reason: { type: string }
-          required: [$status, reason]
-  developer:
-    description: "Applies the proposed workflow edits"
-    goal: "You are a developer agent. You apply workflow YAML edits and update related tests."
-    capabilities:
-      - coding
-    procedure: |
-      IMPORTANT: Always work in a git worktree, NEVER modify the main working directory directly.
-      The workflow definitions live in THIS repo (the workflow engine), not the repo that was analyzed.
-
-      Before starting any work, set up an isolated worktree:
-      1. Use `git rev-parse --show-toplevel` to find the repo root (do NOT use repoPath from proposer — that's the analyzed repo)
-      2. `git fetch origin` to get latest refs
-      3. `git worktree add .worktrees/retrospect/<short-slug> -b retrospect/<short-slug> origin/main`
-      4. `cd .worktrees/retrospect/<short-slug> && bun install`
-      5. ALL subsequent work must happen inside the worktree directory.
-
-      Then apply changes:
-      6. Read the change plan from CAS: `uwf cas get <plan hash>`
-      7. Apply each edit from the plan to the workflow YAML
-      8. Update or add tests as specified in the plan
-      9. Run `bun run build` and `bun test` to verify
-      10. Run `bun run check` for lint
-      11. Commit with message: `improve: <workflow-name> — <brief summary>`
-    output: "List all files changed and provide a summary. Set $status to done (with branch/worktree), or failed (with reason)."
-    frontmatter:
-      oneOf:
-        - properties:
-            $status: { const: "done" }
-            branch: { type: string }
-            worktree: { type: string }
-          required: [$status, branch, worktree]
-        - properties:
-            $status: { const: "failed" }
-            reason: { type: string }
-          required: [$status, reason]
-  reviewer:
-    description: "Reviews the workflow edits for correctness"
-    goal: "You are a reviewer. You verify that workflow edits are minimal, correct, and actually address the findings."
-    capabilities:
-      - code-review
-    procedure: |
-      The worktree path is provided in your task prompt. cd into it first.
-
-      Review criteria:
-      1. Each edit must trace back to a specific finding — no drive-by changes
-      2. Edits should be minimal — don't rewrite working procedures
-      3. New pitfall notes or instructions must be clear and actionable
-      4. Tests must be updated if assertions changed
-      5. `bun run build` and `bun test` must pass
-      6. `bunx biome check` must pass
-
-      IMPORTANT: `tea pr create` must run from the MAIN repo directory (not a worktree), because tea cannot detect the repo from worktree `.git` files.
-    output: "Explain your decision. Set $status to approved (with branch/worktree) or rejected (with comments)."
-    frontmatter:
-      oneOf:
-        - properties:
-            $status: { const: "approved" }
-            branch: { type: string }
-            worktree: { type: string }
-          required: [$status, branch, worktree]
-        - properties:
-            $status: { const: "rejected" }
-            comments: { type: string }
-            worktree: { type: string }
-          required: [$status, comments, worktree]
-  committer:
-    description: "Commits and creates PR"
-    goal: "You are a committer agent. You create a clean commit and push a PR."
-    capabilities: []
-    procedure: |
-      The worktree path, branch name, and repo info are provided in your task prompt.
-      cd into the worktree first.
-
-      Note: You inherit the developer's worktree and branch. Do NOT create a new branch.
-      1. Stage all changes: `git add -A`
-      2. Commit with a descriptive message: `git commit -m "improve: <workflow> — <summary>"`
-      3. Push the branch: `git push -u origin <branch-name>`
-         - If push hook fails: capture the error log in your output, mark hook_failed
-      4. On push success: create a PR via `tea pr create --title "..." --description "..."`
-         - IMPORTANT: `tea pr create` must run from the MAIN repo directory (not a worktree), because tea cannot detect the repo from worktree `.git` files. cd to the repo root first.
-         - Do NOT pass `--repo` — let tea auto-detect from the main repo's git remote.
-         - PR description must include: What / Why / Findings / Changes sections
-         - On tea failure: capture stderr/stdout, include PR details for manual creation, mark hook_failed
-      5. After PR creation, clean up the worktree:
-         - cd to the repo root (parent of .worktrees)
-         - `git worktree remove <worktree-path>`
-    output: "Include PR URL on success or error log on failure. Set $status to committed (with prUrl) or hook_failed (with error)."
-    frontmatter:
-      oneOf:
-        - properties:
-            $status: { const: "committed" }
-            prUrl: { type: string }
-          required: [$status, prUrl]
-        - properties:
-            $status: { const: "hook_failed" }
-            error: { type: string }
-          required: [$status, error]
-graph:
-  $START:
-    _: { role: "analyst", prompt: "Analyze completed thread {{{threadId}}} for execution anomalies." }
-  analyst:
-    clean: { role: "$END", prompt: "No issues found. Thread executed cleanly." }
-    findings: { role: "proposer", prompt: "Findings report: {{{report}}}. Target workflow: {{{targetWorkflow}}}. Propose minimal edits." }
-    wrong_project: { role: "$END", prompt: "Thread uses workflow '{{{workflowName}}}' which does not exist in this project. Run retrospect from the correct repo." }
-  proposer:
-    no_action: { role: "$END", prompt: "No actionable changes needed: {{{reason}}}." }
-    ready: { role: "developer", prompt: "Apply the change plan (CAS hash: {{{plan}}}) to the workflow definitions in this repo." }
-  developer:
-    done: { role: "reviewer", prompt: "Review workflow edits on branch {{{branch}}} at {{{worktree}}}." }
-    failed: { role: "$END", prompt: "Developer failed: {{{reason}}}. Ending workflow." }
-  reviewer:
-    rejected: { role: "developer", prompt: "Reviewer rejected: {{{comments}}}. Fix the issues in {{{worktree}}}." }
-    approved: { role: "committer", prompt: "Approved. Commit and push branch {{{branch}}} from {{{worktree}}}." }
-  committer:
-    hook_failed: { role: "developer", prompt: "Push hook failed: {{{error}}}. Fix and re-submit." }
-    committed: { role: "$END", prompt: "PR created: {{{prUrl}}}. Workflow improved." }

.workflows/solve-issue.yaml

@@ -155,13 +155,12 @@ roles:
       cd into the worktree first.
 
       Note: You inherit the developer's worktree and branch. Do NOT create a new branch.
-      1. Check `git status` — if working tree is clean and branch is ahead of origin, skip to step 3 (push).
-      2. If there are unstaged/uncommitted changes: `git add -A` then `git commit -m "type: description\n\nFixes #N"`
+      1. Stage all changes: `git add -A`
+      2. Commit with a descriptive message referencing the issue: `git commit -m "type: description\n\nFixes #N"`
       3. Push the branch: `git push -u origin <branch-name>`
          - If push hook fails: capture the error log in your output, mark hook_failed
-      4. On push success: create a PR via `tea pr create --title "..." --description "..."`
-         - IMPORTANT: `tea pr create` must run from the MAIN repo directory (not a worktree), because tea cannot detect the repo from worktree `.git` files. cd to the repo root first.
-         - Do NOT pass `--repo` — let tea auto-detect from the main repo's git remote.
+      4. On push success: create a PR via `tea pr create --repo <owner/repo> --title "..." --description "..."`
+         - Extract owner/repo from: `git remote get-url origin | sed 's/.*[:/]\([^/]*\/[^.]*\).*/\1/'`
          - PR description must include: What / Why / Changes / Ref sections, with `Fixes #N` in Ref
          - On tea failure: capture stderr/stdout, include PR details for manual creation, mark hook_failed
       5. After PR creation, clean up the worktree:

docs/architecture.md

@@ -391,7 +391,7 @@ Everything else is immutable CAS content.
 providers:
   openrouter:
     baseUrl: "https://openrouter.ai/api/v1"
-    apiKeyEnv: "OPENROUTER_API_KEY"
+    apiKey: "sk-..."
 
 models:
   sonnet:

docs/builtin-agent-research.md

@@ -402,7 +402,7 @@ workflow 怎么配置和使用 model？
 ```136:160:packages/workflow-protocol/src/types.ts
 export type ProviderConfig = {
   baseUrl: string;
-  apiKeyEnv: string;
+  apiKey: string;
 };
 
 export type ModelConfig = {
@@ -429,7 +429,7 @@ export type WorkflowConfig = {
 export function resolveModel(config: WorkflowConfig, alias: ModelAlias): ResolvedLlmProvider {
   const modelEntry = config.models[alias];
   const providerEntry = config.providers[modelEntry.provider];
-  const apiKey = process.env[providerEntry.apiKeyEnv];
+  const apiKey = providerEntry.apiKey;
   return { baseUrl: providerEntry.baseUrl, apiKey, model: modelEntry.name };
 }
 ```

docs/wf-stateless-design.md

@@ -280,13 +280,13 @@ threads.yaml: { "01J7K9M2XNPQR5VWBCDF8G3H4T": "8FWKR3TN5V1QA" }
 providers:
   openai:
     baseUrl: "https://api.openai.com/v1"
-    apiKeyEnv: "OPENAI_API_KEY"
+    apiKey: "sk-..."
   anthropic:
     baseUrl: "https://api.anthropic.com/v1"
-    apiKeyEnv: "ANTHROPIC_API_KEY"
+    apiKey: "sk-ant-..."
   openrouter:
     baseUrl: "https://openrouter.ai/api/v1"
-    apiKeyEnv: "OPENROUTER_API_KEY"
+    apiKey: "sk-or-..."
 
 models:
   sonnet:
@@ -465,7 +465,7 @@ type Scenario = string;              // e.g. "extract"
 
 type ProviderConfig = {
   baseUrl: string;
-  apiKeyEnv: string;                 // env var name to read API key from
+  apiKey: string;                    // API key stored directly
 };
 
 type ModelConfig = {

packages/cli-workflow/README.md

@@ -119,7 +119,7 @@ uwf setup --provider openai --base-url https://api.openai.com/v1 \
   --api-key sk-... --model gpt-4o --agent hermes
 ```
 
-Config: `~/.uncaged/workflow/config.yaml`. API keys: `~/.uncaged/workflow/.env`.
+Config: `~/.uncaged/workflow/config.yaml` (includes API keys).
 
 ### Skill
 

packages/cli-workflow/package.json

@@ -8,7 +8,7 @@
   ],
   "type": "module",
   "bin": {
-    "uwf": "./src/cli.ts"
+    "uwf": "./dist/cli.js"
   },
   "dependencies": {
     "@uncaged/json-cas": "^0.5.3",

packages/cli-workflow/src/__tests__/resolve-head-hash.test.ts

@@ -40,6 +40,7 @@ describe("resolveHeadHash", () => {
       workflow: workflowHash,
       head: headHash,
       completedAt: Date.now(),
+      reason: null,
     });
 
     const result = await resolveHeadHash(tmpDir, threadId);
@@ -64,6 +65,7 @@ describe("resolveHeadHash", () => {
       workflow: workflowHash,
       head: historicalHash,
       completedAt: Date.now(),
+      reason: null,
     });
 
     const result = await resolveHeadHash(tmpDir, threadId);
@@ -87,18 +89,21 @@ describe("resolveHeadHash", () => {
       workflow: workflowHash,
       head: hash1,
       completedAt: Date.now() - 2000,
+      reason: null,
     });
     await appendThreadHistory(tmpDir, {
       thread: threadId2,
       workflow: workflowHash,
       head: hash2,
       completedAt: Date.now() - 1000,
+      reason: null,
     });
     await appendThreadHistory(tmpDir, {
       thread: threadId3,
       workflow: workflowHash,
       head: hash3,
       completedAt: Date.now(),
+      reason: null,
     });
 
     const result = await resolveHeadHash(tmpDir, threadId2);

packages/cli-workflow/src/__tests__/setup-validate.test.ts

@@ -129,9 +129,8 @@ describe("cmdSetup with validation", () => {
     const result = await cmdSetup(setupArgs());
 
     expect(result.validation).toEqual({ ok: true, value: undefined });
-    // Config files should still be written
+    // Config file should still be written
     expect(result.configPath).toBeTruthy();
-    expect(result.envPath).toBeTruthy();
   });
 
   test("includes validation failure — config still saved", async () => {
@@ -143,8 +142,7 @@ describe("cmdSetup with validation", () => {
 
     expect(result.validation).toBeDefined();
     expect((result.validation as { ok: boolean }).ok).toBe(false);
-    // Config files should still be written despite validation failure
+    // Config file should still be written despite validation failure
     expect(result.configPath).toBeTruthy();
-    expect(result.envPath).toBeTruthy();
   });
 });

packages/cli-workflow/src/__tests__/solve-issue-tea-worktree.test.ts

@@ -24,7 +24,7 @@ describe("solve-issue workflow: tea pr create worktree fix", () => {
     "solve-issue.yaml",
   );
 
-  test("committer procedure should require running tea pr create from main repo directory", async () => {
+  test("committer procedure should include --repo flag in tea pr create command", async () => {
     const yamlContent = await readFile(workflowPath, "utf-8");
     const workflow = parse(yamlContent) as WorkflowPayload;
 
@@ -32,12 +32,19 @@ describe("solve-issue workflow: tea pr create worktree fix", () => {
     const committerProcedure = workflow.roles.committer?.procedure;
     expect(committerProcedure).toBeDefined();
 
-    // Verify the procedure includes tea pr create
+    // Verify the procedure includes tea pr create with --repo flag
     expect(committerProcedure).toContain("tea pr create");
+    expect(committerProcedure).toContain("--repo");
 
-    // Verify the procedure warns about running from main repo dir (not worktree)
-    expect(committerProcedure).toMatch(/main repo directory/i);
-    expect(committerProcedure).toMatch(/not a worktree/i);
+    // Verify the --repo flag appears before or together with tea pr create
+    // This ensures the command is: tea pr create --repo <owner/repo> ...
+    const teaPrCreateMatch = committerProcedure?.match(/tea pr create[^\n]*/);
+    expect(teaPrCreateMatch).not.toBeNull();
+
+    if (teaPrCreateMatch) {
+      const teaCommandLine = teaPrCreateMatch[0];
+      expect(teaCommandLine).toContain("--repo");
+    }
   });
 
   test("committer procedure should mention repo extraction from git remote", async () => {

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

@@ -0,0 +1,85 @@
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CasRef, ThreadId } from "@uncaged/workflow-protocol";
+import { describe, expect, test } from "vitest";
+import { appendThreadHistory, loadThreadHistory } from "../store.js";
+
+describe("thread cancel status", () => {
+  test("cancelled history entry has reason 'cancelled'", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "uwf-cancel-test-"));
+    const threadId = "01JTEST000000000000CANCEL1" as ThreadId;
+
+    await appendThreadHistory(tmpDir, {
+      thread: threadId,
+      workflow: "test-workflow",
+      head: "test-head-hash" as CasRef,
+      completedAt: Date.now(),
+      reason: "cancelled",
+    });
+
+    const history = await loadThreadHistory(tmpDir);
+    expect(history).toHaveLength(1);
+    expect(history[0]?.reason).toBe("cancelled");
+  });
+
+  test("completed history entry has reason 'completed'", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "uwf-cancel-test-"));
+    const threadId = "01JTEST000000000000CANCEL2" as ThreadId;
+
+    await appendThreadHistory(tmpDir, {
+      thread: threadId,
+      workflow: "test-workflow",
+      head: "test-head-hash" as CasRef,
+      completedAt: Date.now(),
+      reason: "completed",
+    });
+
+    const history = await loadThreadHistory(tmpDir);
+    expect(history).toHaveLength(1);
+    expect(history[0]?.reason).toBe("completed");
+  });
+
+  test("legacy history entry without reason parses as null", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "uwf-cancel-test-"));
+    const threadId = "01JTEST000000000000CANCEL3" as ThreadId;
+
+    // Simulate legacy entry without reason field
+    await appendThreadHistory(tmpDir, {
+      thread: threadId,
+      workflow: "test-workflow",
+      head: "test-head-hash" as CasRef,
+      completedAt: Date.now(),
+      reason: null,
+    });
+
+    const history = await loadThreadHistory(tmpDir);
+    expect(history).toHaveLength(1);
+    expect(history[0]?.reason).toBeNull();
+  });
+
+  test("mixed completed and cancelled entries preserve distinct reasons", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "uwf-cancel-test-"));
+
+    await appendThreadHistory(tmpDir, {
+      thread: "01JTEST000000000000CANCEL4" as ThreadId,
+      workflow: "test-workflow",
+      head: "head1" as CasRef,
+      completedAt: Date.now(),
+      reason: "completed",
+    });
+
+    await appendThreadHistory(tmpDir, {
+      thread: "01JTEST000000000000CANCEL5" as ThreadId,
+      workflow: "test-workflow",
+      head: "head2" as CasRef,
+      completedAt: Date.now(),
+      reason: "cancelled",
+    });
+
+    const history = await loadThreadHistory(tmpDir);
+    expect(history).toHaveLength(2);
+    expect(history[0]?.reason).toBe("completed");
+    expect(history[1]?.reason).toBe("cancelled");
+  });
+});

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

@@ -74,6 +74,7 @@ async function completeThread(
     workflow: workflowHash,
     head: headHash,
     completedAt: Date.now(),
+    reason: null,
   });
 }
 

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

@@ -758,6 +758,7 @@ describe("cmdStepList with completed threads", () => {
       workflow: workflowHash,
       head: step2Hash,
       completedAt: Date.now(),
+      reason: null,
     });
 
     const result = await cmdStepList(tmpDir, threadId);
@@ -886,6 +887,7 @@ describe("cmdStepShow with completed threads", () => {
       workflow: workflowHash,
       head: stepHash,
       completedAt: Date.now(),
+      reason: null,
     });
 
     const result = await cmdStepShow(tmpDir, stepHash);
@@ -949,6 +951,7 @@ describe("cmdThreadRead with completed threads", () => {
       workflow: workflowHash,
       head: stepHash,
       completedAt: Date.now(),
+      reason: null,
     });
 
     const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
@@ -1011,6 +1014,7 @@ describe("cmdThreadRead with completed threads", () => {
       workflow: workflowHash,
       head: step3Hash,
       completedAt: Date.now(),
+      reason: null,
     });
 
     const markdown = await cmdThreadRead(

packages/cli-workflow/src/cli.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node
 
 import type { CasRef, ThreadId } from "@uncaged/workflow-protocol";
 import { Command } from "commander";
@@ -181,11 +181,11 @@ 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", "completed"];
+  const validStatuses: ThreadStatus[] = ["idle", "running", "completed", "cancelled"];
   for (const part of parts) {
     if (!validStatuses.includes(part as ThreadStatus)) {
       process.stderr.write(
-        `Invalid status: ${part}. Must be one of: idle, running, completed, active\n`,
+        `Invalid status: ${part}. Must be one of: idle, running, completed, cancelled, active\n`,
       );
       process.exit(1);
     }
@@ -238,7 +238,7 @@ thread
   .description("List threads")
   .option(
     "--status <status>",
-    "Filter by status: idle, running, completed, active (idle+running), or comma-separated values",
+    "Filter by status: idle, running, completed, cancelled, active (idle+running), or comma-separated values",
   )
   .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')")

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

@@ -85,10 +85,6 @@ function getConfigPath(root: string): string {
   return join(root, "config.yaml");
 }
 
-function getEnvPath(root: string): string {
-  return join(root, ".env");
-}
-
 /**
  * Load existing config.yaml or return empty structure.
  */
@@ -106,37 +102,6 @@ function loadExistingConfig(configPath: string): Record<string, unknown> {
   return {};
 }
 
-/**
- * Load existing .env as key=value map.
- */
-function loadEnvFile(envPath: string): Record<string, string> {
-  const env: Record<string, string> = {};
-  try {
-    if (existsSync(envPath)) {
-      for (const line of readFileSync(envPath, "utf8").split("\n")) {
-        const trimmed = line.trim();
-        if (trimmed === "" || trimmed.startsWith("#")) continue;
-        const eq = trimmed.indexOf("=");
-        if (eq > 0) {
-          env[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
-        }
-      }
-    }
-  } catch {
-    // ignore
-  }
-  return env;
-}
-
-function saveEnvFile(envPath: string, env: Record<string, string>): void {
-  const lines = Object.entries(env).map(([k, v]) => `${k}=${v}`);
-  writeFileSync(envPath, `${lines.join("\n")}\n`, "utf8");
-}
-
-function apiKeyEnvName(providerName: string): string {
-  return `${providerName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`;
-}
-
 // ──────────────────────────────────────────────────────────────────────────────
 // Extracted helpers — _discoverAgents
 // ──────────────────────────────────────────────────────────────────────────────
@@ -397,8 +362,7 @@ function mergeConfig(existing: Record<string, unknown>, args: SetupArgs): Record
       : {}
   ) as Record<string, unknown>;
 
-  const envName = apiKeyEnvName(args.provider);
-  providers[args.provider] = { baseUrl: args.baseUrl, apiKeyEnv: envName };
+  providers[args.provider] = { baseUrl: args.baseUrl, apiKey: args.apiKey };
 
   const models = (
     typeof existing.models === "object" && existing.models !== null
@@ -437,25 +401,17 @@ export async function cmdSetup(args: SetupArgs): Promise<Record<string, unknown>
   mkdirSync(storageRoot, { recursive: true });
 
   const configPath = getConfigPath(storageRoot);
-  const envPath = getEnvPath(storageRoot);
 
   const existing = loadExistingConfig(configPath);
   const merged = mergeConfig(existing, args);
 
   writeFileSync(configPath, stringify(merged, { indent: 2 }), "utf8");
 
-  // Write API key to .env
-  const envName = apiKeyEnvName(args.provider);
-  const envData = loadEnvFile(envPath);
-  envData[envName] = args.apiKey;
-  saveEnvFile(envPath, envData);
-
   // Validate model connectivity
   const validation = await validateModel(args.baseUrl, args.apiKey, args.model);
 
   return {
     configPath,
-    envPath,
     provider: args.provider,
     model: args.model,
     defaultAgent: merged.defaultAgent,

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

@@ -331,7 +331,7 @@ export async function cmdThreadShow(storageRoot: string, threadId: ThreadId): Pr
   fail(`thread not found: ${threadId}`);
 }
 
-export type ThreadStatus = "idle" | "running" | "completed";
+export type ThreadStatus = "idle" | "running" | "completed" | "cancelled";
 
 export type ThreadListItemWithStatus = ThreadListItem & {
   status: ThreadStatus;
@@ -389,7 +389,7 @@ async function collectCompletedThreads(
         thread: entry.thread,
         workflow: entry.workflow,
         head: entry.head,
-        status: "completed",
+        status: entry.reason === "cancelled" ? "cancelled" : "completed",
       });
     }
   }
@@ -444,7 +444,10 @@ export async function cmdThreadList(
   let items = await collectActiveThreads(storageRoot, uwf, index);
 
   // Collect completed threads (if relevant for status filter)
-  const includeCompleted = statusFilter === null || statusFilter.includes("completed");
+  const includeCompleted =
+    statusFilter === null ||
+    statusFilter.includes("completed") ||
+    statusFilter.includes("cancelled");
   if (includeCompleted) {
     const activeIds = new Set(items.map((i) => i.thread));
     const completedItems = await collectCompletedThreads(storageRoot, activeIds);
@@ -811,6 +814,7 @@ async function archiveThread(
     workflow,
     head,
     completedAt: Date.now(),
+    reason: "completed",
   });
 }
 
@@ -1147,6 +1151,7 @@ export async function cmdThreadCancel(
     workflow,
     head,
     completedAt: Date.now(),
+    reason: "cancelled",
   };
   await appendThreadHistory(storageRoot, historyEntry);
 

packages/cli-workflow/src/store.ts

@@ -88,6 +88,7 @@ export function getHistoryPath(storageRoot: string): string {
 
 export type ThreadHistoryLine = ThreadListItem & {
   completedAt: number;
+  reason: "completed" | "cancelled" | null;
 };
 
 export type UwfStore = {
@@ -228,7 +229,15 @@ export async function loadThreadHistory(storageRoot: string): Promise<ThreadHist
         typeof head === "string" &&
         typeof completedAt === "number"
       ) {
-        lines.push({ thread: thread as ThreadId, workflow, head, completedAt });
+        const reason = rec.reason;
+        const parsedReason = reason === "completed" || reason === "cancelled" ? reason : null;
+        lines.push({
+          thread: thread as ThreadId,
+          workflow,
+          head,
+          completedAt,
+          reason: parsedReason,
+        });
       }
     }
     return lines;

packages/workflow-protocol/README.md

@@ -100,7 +100,7 @@ type ProviderAlias = string;
 type ModelAlias = string;
 type AgentAlias = string;
 
-type ProviderConfig = { baseUrl: string; apiKeyEnv: string };
+type ProviderConfig = { baseUrl: string; apiKey: string };
 type ModelConfig = {
   provider: ProviderAlias;
   name: string;

packages/workflow-protocol/src/types.ts

@@ -151,7 +151,7 @@ export type Scenario = string;
 
 export type ProviderConfig = {
   baseUrl: string;
-  apiKeyEnv: string;
+  apiKey: string;
 };
 
 export type ModelConfig = {

packages/workflow-util-agent/src/extract.ts

@@ -1,8 +1,7 @@
 import { getSchema, validate } from "@uncaged/json-cas";
 
 import type { CasRef, ModelAlias, WorkflowConfig } from "@uncaged/workflow-protocol";
-import { config as loadDotenv } from "dotenv";
-import { createAgentStore, getEnvPath, resolveStorageRoot } from "./storage.js";
+import { createAgentStore, resolveStorageRoot } from "./storage.js";
 
 export type ResolvedLlmProvider = {
   baseUrl: string;
@@ -38,9 +37,9 @@ export function resolveModel(config: WorkflowConfig, alias: ModelAlias): Resolve
   if (providerEntry === undefined) {
     throw new Error(`unknown provider "${modelEntry.provider}" for model "${alias}"`);
   }
-  const apiKey = process.env[providerEntry.apiKeyEnv];
+  const apiKey = providerEntry.apiKey;
   if (apiKey === undefined || apiKey === "") {
-    throw new Error(`missing API key env var: ${providerEntry.apiKeyEnv}`);
+    throw new Error(`missing API key for provider: ${modelEntry.provider}`);
   }
   return {
     baseUrl: providerEntry.baseUrl,
@@ -130,7 +129,7 @@ export type ExtractResult = {
 
 /**
  * Call an OpenAI-compatible LLM to extract structured output matching outputSchema.
- * Loads config.yaml and .env from the workflow storage root.
+ * Loads config.yaml from the workflow storage root.
  */
 export async function extract(
   rawOutput: string,
@@ -138,7 +137,6 @@ export async function extract(
   config: WorkflowConfig,
 ): Promise<ExtractResult> {
   const storageRoot = resolveStorageRoot();
-  loadDotenv({ path: getEnvPath(storageRoot) });
 
   const { store } = await createAgentStore(storageRoot);
   const schema = getSchema(store, outputSchema);

packages/workflow-util-agent/src/storage.ts

@@ -84,11 +84,11 @@ function normalizeProviders(raw: unknown): Record<ProviderAlias, ProviderConfig>
       throw new Error(`config.providers.${name} must be a mapping`);
     }
     const baseUrl = entry.baseUrl;
-    const apiKeyEnv = entry.apiKeyEnv;
-    if (typeof baseUrl !== "string" || typeof apiKeyEnv !== "string") {
-      throw new Error(`config.providers.${name} requires baseUrl and apiKeyEnv`);
+    const apiKey = entry.apiKey;
+    if (typeof baseUrl !== "string" || typeof apiKey !== "string") {
+      throw new Error(`config.providers.${name} requires baseUrl and apiKey`);
     }
-    providers[name] = { baseUrl, apiKeyEnv };
+    providers[name] = { baseUrl, apiKey };
   }
   return providers;
 }