docs: add 6 FTE concept cards

- agent-as-graduate: onboarding metaphor and teaching threshold
- three-learning-carriers: memory/skill/workflow framework
- switching-cost-process-knowledge-as-moat: process knowledge as moat
- opc-why-fte-agents-matter-most: why OpenClaw bets on FTE
- fte-maturity-threshold: who can onboard an agent
- fte-product-landscape: OpenClaw vs Claude Code vs Hermes

.cards/agency-over-content-not-process.md

@@ -0,0 +1,19 @@
+---
+title: "Agency over Content, Not Process"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, decision]
+category: "architecture"
+links:
+  - skill-vs-workflow-different-layers
+  - deterministic-engine-uncertain-agent
+  - feedback-loops-convergent-and-divergent
+  - cognitive-process-orchestration
+  - uwf-vs-dynamic-workflow
+---
+
+uwf 与"agent 自治"方案的核心区别：**agent 对内容有自主权，但对流程没有**。
+
+流程是声明式的、引擎执行的、agent 无法绕过的。agent 不能决定跳过 review，就像程序员不能绕过 CI。自由度被有意限制在"内容"维度，"过程"维度是刚性的。这跟人类组织的逻辑一致——你可以自由发挥怎么写代码，但必须走 PR review。
+
+参见 [[uwf-vs-dynamic-workflow]] 了解与 Claude Code dynamic workflow 的具体对比。

.cards/agent-as-graduate.md

@@ -0,0 +1,19 @@
+---
+title: "Agent as Graduate — The Onboarding Metaphor"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [concept, analogy]
+category: "product"
+links:
+  - vendor-vs-fte-who-defines-capability
+  - three-learning-carriers
+  - fte-maturity-threshold
+---
+
+FTE 型 agent 最贴切的类比：**应届毕业生**。
+
+出厂时有通用能力（底座模型 = 学历），但不懂你的业务、不知道你的偏好、没有你的流程经验。用户的角色是"带教老师"——通过日常协作，逐步把 agent 带成自己的得力助手。
+
+这个类比揭示了当前 FTE 产品的核心瓶颈：**带教门槛太高**。现在只有技术背景深厚的用户才能"带"——能写 skill、能调 workflow、能 debug agent 行为。行业专家（不懂代码的人）被挡在门外。
+
+真正成熟的 FTE 型产品 = 降低带教门槛，让非技术用户也能教会 agent 自己的业务。

.cards/attention-isolation-breaks-cognitive-inertia.md

@@ -0,0 +1,21 @@
+---
+title: "Attention Isolation Breaks Cognitive Inertia"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, pattern]
+category: "architecture"
+links:
+  - session-isolation-as-cognitive-reset
+  - skill-vs-workflow-different-layers
+  - role-is-not-agent
+---
+
+"知识都在一个 session 内不是更好吗？"——这个直觉混淆了**信息量**和**认知模式**。
+
+Session 隔离去掉的不是信息，而是**不该影响当前判断的信息**。reviewer 通过 CAS 链拿到 developer 的全部产出物（代码、变更说明），它缺的是 developer 的内心独白——为什么选方案 A、哪里犹豫过、哪里偷了懒。
+
+这恰恰是关键。知道"为什么"的 reviewer 会顺着作者的逻辑走；不知道"为什么"的 reviewer 只能看产出物本身是否站得住——就像真实用户或未来维护者的视角。与学术双盲评审同理：去掉不该影响判断的信息，让注意力聚焦在工作本身。
+
+每个认知任务需要的信息集合不同。developer 需要 issue 上下文、代码库知识、技术约束；reviewer 需要 diff、规范、测试结果。混在一起不是多了信息，是多了噪声。
+
+**关注点的隔离是打破惯性和线性思维的关键。** 一个 session 做所有事，不是"知识都在"，是关注点混在一起，确认偏误无法靠 prompt 消除，只能靠结构隔离。

.cards/cognitive-process-orchestration.md

@@ -0,0 +1,18 @@
+---
+title: "Cognitive Process Orchestration"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, decision]
+category: "architecture"
+links:
+  - feedback-loops-convergent-and-divergent
+  - session-isolation-as-cognitive-reset
+  - role-is-not-agent
+  - process-discipline-from-software-engineering
+---
+
+uwf 的抽象层次高于"质量保障工具"或"任务编排引擎"——它是一个**认知过程的编排引擎**。
+
+收敛和发散都是认知过程。负反馈环（code review 循环）和正反馈环（苏格拉底式追问、头脑风暴）是同一套机制的不同配置。workflow author 通过设计 role 的 goal 和 graph 的环路结构，编排的是**思维方式**，不仅仅是任务步骤。
+
+这意味着 uwf 的应用范围不限于软件开发流程，而是任何需要多视角、多轮次认知协作的场景。

.cards/cold-start-same-entry-different-exit.md

@@ -0,0 +1,20 @@
+---
+title: "Cold Start — Same Entry Point, Different Exit"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, pattern]
+category: "architecture"
+links:
+  - uwf-vs-dynamic-workflow
+  - process-authorship-human-ai-vs-delegation
+  - workflow-as-improvable-system
+  - agent-as-graduate
+---
+
+uwf 的冷启动不比 dw 更复杂——起点完全一样：用户描述任务，agent 执行。
+
+区别在出口：dw 跑完即丢，uwf 跑完后沉淀成 workflow YAML，用户可以审查、调优、复用。workflow 不一定要用户写，往往也是 agent 写的——跟 dw 一样的模式。uwf 和 dw 的差异不在"谁写流程"，而在"流程跑完后去哪"。
+
+冷启动路径：agent 先跑一次临时流程 → 用户觉得好就固化成 workflow → 下次同类任务直接复用 → 用过几次后根据经验调优。从零门槛的即兴执行，渐进演化为成熟的可复用流程。
+
+入口像 dw 一样低，出口比 dw 多了一个沉淀层。

.cards/deterministic-engine-uncertain-agent.md

@@ -0,0 +1,16 @@
+---
+title: "Deterministic Engine, Uncertain Agent"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, decision]
+category: "architecture"
+links:
+  - process-discipline-from-software-engineering
+  - session-isolation-as-cognitive-reset
+---
+
+uwf 的架构将确定性和不确定性严格分层。
+
+Engine 层（moderator 纯查表、CAS 不可变、每步原子化）是刚性的——流程骨架本身不能成为另一个不可靠的环节。LLM 的不确定性被严格约束在 agent session 内部。
+
+这个选择意味着：调度逻辑完全可预测、可调试、可审计。出问题时你知道问题一定在某个 session 的产出里，不在流程逻辑里。

.cards/dissipative-structure-token-for-entropy.md

@@ -0,0 +1,16 @@
+---
+title: "Dissipative Structure — Token for Entropy Reduction"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, pattern]
+category: "architecture"
+links:
+  - process-discipline-from-software-engineering
+  - session-isolation-as-cognitive-reset
+---
+
+uwf 本质上是一种耗散结构：通过消耗能量（token）实现熵减。
+
+一个 AI session 做长了会漂移、会累积错误、会失去焦点。把一件事拆成多个有明确边界的 session，让它们从不同角度相互校验，比一个 session 从头做到尾更可靠。多花的 token 就是耗散的能量，换来的是更低的交付熵——更可预测、更高质量的产出。
+
+这与人类工程实践中引入 review、测试、灰度等流程的逻辑一致：都是在用额外成本换系统可靠性。

.cards/domain-experts-own-the-process.md

@@ -0,0 +1,20 @@
+---
+title: "Domain Experts Own the Process"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, decision, pattern]
+category: "architecture"
+links:
+  - trust-chain-audit-evaluate-reuse
+  - uwf-vs-dynamic-workflow
+  - cognitive-process-orchestration
+  - process-discipline-from-software-engineering
+---
+
+现实中各行各业有大量由反馈回路构成的流程正在实际运行，掌握和优化这些流程的是行业专家，不是 AI 工程师。
+
+一个资深 QA 负责人知道测试应该怎么分层、失败后应该回到哪一步。一个风控经理知道审批要经过几道关、驳回后应该回到哪个环节补材料。这些人掌握流程的核心知识，但你让他们写 JS 编排脚本，他们做不到也不应该做。
+
+YAML 声明式 workflow 让行业专家能直接参与——看得懂 roles 和 graph，能判断"这个环节是不是多余的"、"这两个角色之间应该加一个校验步骤"。审查门槛低不是为了技术简洁，是为了**让对的人参与对的决策**。
+
+这是可审查 → 可评估 → 可复用信任链能真正转动的前提——转动它的人是行业专家，不是 AI 工程师。也是 uwf 选择声明式 YAML 而非 JS 的根本原因：**流程的设计权应该属于懂流程的人**。

.cards/eval-closes-the-trust-chain.md

@@ -0,0 +1,21 @@
+---
+title: "Eval Closes the Trust Chain"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, pattern]
+category: "architecture"
+links:
+  - trust-chain-audit-evaluate-reuse
+  - workflow-as-improvable-system
+  - feedback-loops-convergent-and-divergent
+---
+
+信任链（可审查 → 可评估 → 可复用 → 可迭代）的"可评估"环节需要工程落地。
+
+uwf 的 eval 包（`@united-workforce/eval`，已在 repo 开发中）的目标是让 agent 能自我评估执行质量——一次 thread 跑完后，度量"做得好不好"、"workflow v2 比 v1 好还是差"。
+
+这形成了两层反馈闭环：
+1. **workflow 内的反馈环** — developer → reviewer → rejected → developer（已实现，负反馈驱动执行质量收敛）
+2. **workflow 级的反馈环** — 执行 → eval → workflow 迭代 → 再执行（在建，驱动流程本身的持续改进）
+
+第二层闭环接通后，uwf 就不只是一个执行引擎，而是一个**自我改进的流程系统**。

.cards/feedback-loops-convergent-and-divergent.md

@@ -0,0 +1,21 @@
+---
+title: "Feedback Loops — Convergent and Divergent"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, pattern]
+category: "architecture"
+links:
+  - dissipative-structure-token-for-entropy
+  - process-discipline-from-software-engineering
+  - cognitive-process-orchestration
+---
+
+uwf 的 graph 环路不限于负反馈（收敛），也可以是正反馈（发散）。引擎本身不带倾向——流转方向由 `$status` 和 graph 决定，反馈性质由 role 的设计意图决定。
+
+**负反馈环（收敛）**：developer → reviewer → rejected → developer。reviewer 的 goal 是"找问题"，产生修正力。稳定点是 `approved`，系统自然收敛到那里。特性：偏差越大修正越强，对扰动鲁棒。
+
+**正反馈环（发散）**：proposer → challenger → "interesting" → proposer。challenger 的 goal 是"追问更深层的假设"，每轮发散，一个想法激发更多想法。
+
+终止条件不同：负反馈靠收敛自然到达稳定点；正反馈不会自己停，需要外部约束（轮次上限，或额外 role 判断"够了"）。
+
+每个 role 的 `$status` 就是误差信号（负反馈）或激励信号（正反馈），驱动系统向不同方向演化。Workflow author 真正在设计的是**在哪里放什么样的环**。

.cards/four-advantages-over-single-session.md

@@ -0,0 +1,27 @@
+---
+title: "Four Advantages over Single Session + Skill"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, pattern]
+category: "architecture"
+links:
+  - session-isolation-as-cognitive-reset
+  - attention-isolation-breaks-cognitive-inertia
+  - skill-vs-workflow-different-layers
+  - when-skill-is-not-enough
+---
+
+Session 隔离除了认知层面的好处（打破确认偏误、聚焦注意力），还解决一个更物理性的问题：**长 session 的上下文压缩导致降智和行为不稳定**。
+
+Context window 是有限资源。一个 session 从头做到尾，前期的 tool output、中间的思考过程不断堆积，要么触发 compaction（信息丢失），要么挤占后期推理的有效空间。越到后面 agent 越"笨"——不是能力变了，是可用的认知空间被历史占满了。表现为：忘记约束、重复错误、输出不稳定。
+
+Session 隔离直接解决这个问题：每个 role 进入时拿到的是**精炼过的前序产出**（CAS 里经 schema 过滤的结构化 output），不是前面所有 session 的原始 token 流。信息经过 schema 过滤，只有产出物，没有过程噪声。
+
+uwf 相对单 session + skill 的四个优势，前三个来自 session 隔离，第四个来自程序化流程：
+
+1. **认知隔离** — 打破确认偏误和线性思维惯性
+2. **注意力聚焦** — 每个 role 只看该看的信息
+3. **上下文保鲜** — 避免长 session 的压缩降智和行为漂移
+4. **流程可靠性** — 引擎强制执行每一步，agent 无法跳过或篡改流程
+
+前三点回答"为什么拆成多个 session 更好"，第四点回答"为什么流程要由引擎控制而不是 agent 自觉"。Skill 里写"先编码再测试再 review"，agent 可能做着做着就跳过——不是故意的，是 context 压力下行为漂移，或者觉得"改动太小不需要测试"。程序化流程不存在这个问题：graph 说要走 tester，就必须走 tester。

.cards/fte-maturity-threshold.md

@@ -0,0 +1,25 @@
+---
+title: "FTE Maturity Threshold — Who Can Onboard an Agent"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [concept, decision]
+category: "product"
+links:
+  - agent-as-graduate
+  - vendor-vs-fte-who-defines-capability
+  - three-learning-carriers
+---
+
+FTE 型 agent 的成熟度，归根结底看一个问题：**谁能带教它？**
+
+当前阶段（2026）：OpenClaw、Claude Code、Hermes 都是 FTE 型产品的雏形，三者都具备 memory/skill/workflow 三个载体。但它们的用户画像高度重叠——有较深技术能力的开发者。
+
+这意味着 FTE agent 现在更像"只有技术 lead 才能带的毕业生"。要跨越鸿沟，需要降低带教门槛到**行业专家（不懂代码的人）也能带、也能教、也能调优**。
+
+谁先把这个门槛降下来，谁就定义了 FTE agent 品类的分水岭。
+
+可能的降低路径：
+- **自然语言 skill 定义**（不需要写代码/YAML）
+- **可视化 workflow 编辑**（拖拽而非配置）
+- **Agent 主动学习**（从用户行为中推断偏好，而非等用户显式配置）
+- **带教过程本身被 agent 化**（用 agent 辅助用户定义 skill 和 workflow）

.cards/fte-product-landscape.md

@@ -0,0 +1,23 @@
+---
+title: "FTE Product Landscape — OpenClaw, Claude Code, Hermes"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [concept, comparison]
+category: "product"
+links:
+  - vendor-vs-fte-who-defines-capability
+  - three-learning-carriers
+  - fte-maturity-threshold
+  - agent-as-graduate
+---
+
+2026 年中，FTE 型 agent 的代表产品对比：
+
+**共性**：都有 memory、skill、workflow/多步协作机制，都面向技术用户。
+
+**差异点**：
+- **OpenClaw** — uwf 引擎驱动，用 YAML 定义多角色 workflow，强调流程纪律和 session 隔离。面向团队级 agent 协作。
+- **Claude Code** — Anthropic 官方 CLI agent，CLAUDE.md 作为 memory，skill 通过项目约定积累。单 agent 深度协作，开发者体验好。
+- **Hermes** — 跨平台 agent 协调者，memory/skill/cron 体系完善，支持多 agent 调度。偏个人效率工具。
+
+三者都谈不上成熟。成熟的标志不是技术完备度，而是**非技术用户能否用起来**。

.cards/opc-why-fte-agents-matter-most.md

@@ -0,0 +1,22 @@
+---
+title: "OPC — Why FTE Agents Matter Most"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [vision, decision]
+category: "product"
+links:
+  - vendor-vs-fte-who-defines-capability
+  - agent-as-graduate
+  - fte-maturity-threshold
+---
+
+OpenClaw 押注 FTE 型 agent 的核心判断：**AI 的终极形态不是工具，是同事。**
+
+工具被使用，同事被培养。工具的价值在出厂那一刻确定，同事的价值随协作持续增长。
+
+这个判断决定了产品方向：
+- 不做"最强的单次对话"，做"最能被带教的长期协作者"
+- 不做"开箱即用的成品"，做"越用越好用的底座"
+- 核心指标不是 benchmark 分数，是用户留存和 skill 积累量
+
+uwf 是这个判断的工程实现——用流程纪律让 agent 的产出可靠，让用户敢把真正的业务交给它。

.cards/open-question-human-as-role.md

@@ -0,0 +1,22 @@
+---
+title: "Open Question — Human as Role Participant"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, open-question]
+category: "architecture"
+links:
+  - agent-as-graduate
+  - opc-why-fte-agents-matter-most
+  - role-is-not-agent
+  - process-authorship-human-ai-vs-delegation
+---
+
+**待讨论。**
+
+目前讨论主要围绕 OPC（一个人 + N 个 agent）。但小团队场景下——几个人各自有 FTE agent，共享 workflow 库和记忆——workflow 的某些 role 可能需要人来执行而不是 agent。
+
+问题：
+- uwf 是否需要支持人作为 role 的参与者（比如"人工审批"作为 graph 中的一个 role）？
+- 还是人永远在 workflow 之外，只做设计者和监督者？
+- 如果支持，$SUSPEND 机制是否已经覆盖了这个需求（暂停等人介入）？
+- 多人 + 多 agent 的协作场景下，workflow 的共享和权限模型是什么样的？

.cards/open-question-workflow-granularity.md

@@ -0,0 +1,20 @@
+---
+title: "Open Question — Workflow Granularity and Composition"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, open-question]
+category: "architecture"
+links:
+  - cognitive-process-orchestration
+  - skill-vs-workflow-different-layers
+  - domain-experts-own-the-process
+---
+
+**待讨论。**
+
+Workflow 的粒度问题：solve-issue 是端到端的大 workflow（planner → developer → reviewer → tester → committer），但现实中有些场景只需要管一个环节（比如只用 uwf 管 code review，其他部分用 skill 或手动）。
+
+问题：
+- Workflow 是否应该支持嵌套或组合——小 workflow 作为大 workflow 的一个 role？
+- 还是粒度完全由用户自己决定，引擎不需要管？
+- 组合式 workflow 和单体 workflow 各自的 trade-off 是什么？

.cards/process-authorship-human-ai-vs-delegation.md

@@ -0,0 +1,23 @@
+---
+title: "Process Authorship — Human-AI Collaboration vs Full Delegation"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, decision]
+category: "architecture"
+links:
+  - domain-experts-own-the-process
+  - uwf-vs-dynamic-workflow
+  - trust-chain-audit-evaluate-reuse
+  - workflow-as-improvable-system
+---
+
+dw 和 uwf 都面向 agent，用户都不需要会写代码。区别在于**流程的创作权**：
+
+- **dw**：流程由 AI 全权负责。用户描述任务，agent 决定怎么拆步骤、怎么编排。用户参与度最低，门槛最低。
+- **uwf**：流程创作是人和 AI 协作的。行业专家参与设计、审查、调优流程，agent 参与起草和执行。
+
+这是主动权的取舍。dw 把流程交给 AI 是为了降低使用门槛；uwf 有意保留人对流程的参与权，代价是门槛稍高，收益是流程能融入人的领域知识。
+
+背后的认知：**AI 擅长执行，但流程设计需要领域知识。** AI 不知道行业里哪个环节容易出错、哪个审批不能跳过、哪个反馈回路是血的教训换来的。这些知识在行业专家脑子里，需要一个他们能参与的载体来表达。
+
+dw 赌的是 AI 能自己发现好的流程，uwf 赌的是好的流程需要人的知识参与。两个赌注没有对错，适用于不同的场景：临时任务用 dw 的零门槛更高效，反复执行的核心业务流程用 uwf 的人机协作更可靠。

.cards/process-discipline-from-software-engineering.md

@@ -0,0 +1,20 @@
+---
+title: "Process Discipline from Software Engineering"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, pattern, decision]
+category: "architecture"
+links:
+  - session-isolation-as-cognitive-reset
+  - role-is-not-agent
+  - dissipative-structure-token-for-entropy
+  - deterministic-engine-uncertain-agent
+---
+
+uwf 的发心是将人类软件工程的流程纪律应用到 AI agent 上。
+
+人类早已验证：个体不可靠，但流程可以让不可靠的个体组成可靠的系统。Code review 不是因为不信任程序员，而是**写代码和审代码是两种认知模式**，一个人很难同时做好。测试、灰度、回滚——每一层都是在用额外成本换确定性。
+
+uwf 把这套搬过来：planner 和 reviewer 可以是同一个 agent，但流程迫使它在不同 session 里切换视角，形成自我制衡。用 role 和 role 之间的流转关系，**把做一件事的步骤固定下来**。
+
+PR #148 vs #142 是直接证据——不是换了更强的 agent，是同样的 agent，换了协作结构。

.cards/reflective-workflow-self-improvement.md

@@ -0,0 +1,35 @@
+---
+title: "Reflective Workflow — Self-Improvement as Discipline"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, pattern, decision]
+category: "architecture"
+links:
+  - eval-closes-the-trust-chain
+  - three-learning-carriers
+  - workflow-as-improvable-system
+  - feedback-loops-convergent-and-divergent
+  - trust-chain-audit-evaluate-reuse
+---
+
+FTE agent 的"成长"不靠自发顿悟，靠纪律性的反思。反思本身是纪律性的（定期跑、不能跳过、有固定步骤），所以应该用 workflow 承载——不能靠 agent "有空想想"。
+
+反思 workflow 定期拉取最近执行过的任务，分析流程中出现的问题，找可优化的点，迭代，eval，对比。反思的对象覆盖三层载体：
+
+- 发现某个 role 反复在同一类问题上出错 → **迭代 skill**
+- 发现某类任务的上下文总是缺少关键信息 → **补充记忆**
+- 发现某个审批环节通过率 100% 从未驳回 → **简化 workflow**
+
+这形成了双层 workflow 架构：
+
+```
+执行层：workflow 驱动日常任务
+    ↓ 产出执行记录（CAS 链）
+反思层：反思 workflow 定期分析执行记录
+    ↓ 产出改进建议
+改进层：迭代 memory / skill / workflow
+    ↓ 提升下一轮执行质量
+执行层：...
+```
+
+两层都是 workflow，职责不同——执行层做事，反思层改进做事的方式。用 workflow 来优化 workflow——工具改进自身的递归。

.cards/role-is-not-agent.md

@@ -0,0 +1,16 @@
+---
+title: "Role Is Not Agent"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, decision]
+category: "architecture"
+links:
+  - session-isolation-as-cognitive-reset
+  - process-discipline-from-software-engineering
+---
+
+在 uwf 体系里，role ≠ agent。一个 thread 跑的过程中，所有 role 往往由**同一个 agent** 扮演。
+
+Role 对应的是 agent 的 **session**——为了解决一个问题，需要多个 session 从不同角度观察和行动、相互制衡。角色可以在流程中多次重入，重入时**复用**同一个 session（保持角色内记忆连续），隔离发生在角色之间，不是每一步。
+
+这个区分决定了 uwf 的设计不是在做"任务分发给不同 agent"，而是在做**一个 agent 的多视角自我协作**。

.cards/session-isolation-as-cognitive-reset.md

@@ -0,0 +1,17 @@
+---
+title: "Session Isolation as Cognitive Reset"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, decision, pattern]
+category: "architecture"
+links:
+  - role-is-not-agent
+  - dissipative-structure-token-for-entropy
+  - process-discipline-from-software-engineering
+---
+
+uwf 的核心机制不是"多 agent 协调"，而是**用 session 隔离实现视角切换**。
+
+同一个 agent 以不同 role 进入时，得到的是全新的认知上下文——没有惯性、没有确认偏误。CAS 链传递工作成果，但认知状态是重置的。Role 定义（goal、procedure、output schema）塑造每个 session 的关注点和行为边界。
+
+这解释了为什么 stateless 单步设计这么重要：engine 确保每次角色切换都是一个干净的 session 入口。

.cards/skill-vs-workflow-different-layers.md

@@ -0,0 +1,19 @@
+---
+title: "Skill vs Workflow — Different Layers"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, decision]
+category: "architecture"
+links:
+  - session-isolation-as-cognitive-reset
+  - cognitive-process-orchestration
+  - agency-over-content-not-process
+---
+
+Skill 和 workflow 不是替代关系，是不同层次。
+
+**Skill** 管的是一个 session 内怎么做——给 agent 的指令和方法论。你可以在 skill 里写"先规划再编码再 review"，但 agent 始终在同一个 session 里，review 自己刚写的代码时带着全部决策记忆。确认偏误无法靠 prompt 消除。
+
+**Workflow** 管的是 session 之间怎么协作——强制 session 断裂，reviewer 进来时不知道 developer 当时为什么做那个选择，只看到产出物。这个隔离不是靠自律，是靠结构。
+
+两者正交：workflow 的每个 role 里面完全可以加载 skill。Skill 提升单个 session 的能力，workflow 编排多个 session 的协作关系。

.cards/switching-cost-process-knowledge-as-moat.md

@@ -0,0 +1,21 @@
+---
+title: "Switching Cost — Process Knowledge as Moat"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [concept, decision]
+category: "product"
+links:
+  - vendor-vs-fte-who-defines-capability
+  - three-learning-carriers
+  - agent-as-graduate
+---
+
+FTE 型 agent 的护城河不是技术壁垒，是**用户自己积累的流程知识**。
+
+用得越久，agent 越懂你的业务——记忆里有你的偏好，skill 里有你验证过的做法，workflow 里有你打磨过的流程。换一个 agent = 重新带一个毕业生，之前的积累全部作废。
+
+这解释了为什么 FTE 型产品的竞争逻辑和 vendor 型完全不同：
+- **Vendor 型**竞争模型能力（谁的基座更强），switching cost 低，用户随时换
+- **FTE 型**竞争生态粘性（谁让用户积累得更深），switching cost 随使用时长增长
+
+风险面：如果用户的流程知识被锁死在一个平台，就变成了 vendor lock-in。开放的知识格式（如 markdown skill、YAML workflow）是对冲手段。

.cards/three-learning-carriers.md

@@ -0,0 +1,21 @@
+---
+title: "Three Learning Carriers — Memory, Skill, Workflow"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, concept]
+category: "product"
+links:
+  - vendor-vs-fte-who-defines-capability
+  - agent-as-graduate
+  - switching-cost-process-knowledge-as-moat
+---
+
+FTE 型 agent 的能力积累依赖三个载体：
+
+1. **Memory（记忆）**— 用户偏好、环境事实、历史上下文。跨 session 持久化，让 agent 不用每次从零开始。
+2. **Skill（技能）**— 可复用的操作程序。解决过的问题沉淀成步骤，下次直接调用。
+3. **Workflow / DW（流程）**— 多步骤协作模式。把复杂任务拆成角色和阶段，用流程纪律保障质量。
+
+三者的关系：memory 是"认识你"，skill 是"会做事"，workflow 是"知道怎么把事做好"。
+
+OpenClaw、Claude Code、Hermes 都已具备这三个载体，但成熟度各异。差异在于：用户能多容易地往这三个载体里"灌"自己的知识。

.cards/trust-chain-audit-evaluate-reuse.md

@@ -0,0 +1,23 @@
+---
+title: "Trust Chain — Auditable → Evaluable → Reusable → Improvable"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, pattern, decision]
+category: "architecture"
+links:
+  - workflow-as-improvable-system
+  - uwf-vs-dynamic-workflow
+  - process-discipline-from-software-engineering
+---
+
+可审查、可评估、可复用不是并列的好处，而是一条因果链：
+
+**可审查 → 可评估 → 可复用 → 可迭代**
+
+不能审查的东西不敢复用——不知道它为什么 work，换个场景可能就 break。不能评估的东西不知道该不该复用——也许它其实没用，只是恰好那次任务简单。
+
+这是一条信任链，每一环是下一环的前提。uwf 选择声明式 YAML 而不是 JS/TS 定义 workflow，不是技术限制，是有意降低审查门槛，让这条链的摩擦力最低。
+
+dw 不是不能做这些，而是它的默认路径不鼓励这条链——即兴生成的脚本，审查成本高、评估缺乏对照、复用需要额外抽象。差异在摩擦力，不在能力边界。
+
+这也是耗散结构的递归应用——不只是用流程对 agent 做负反馈（提升执行质量），还在对流程本身做负反馈（提升流程质量）。Workflow 和代码一样，需要 review、测试、度量、迭代。

.cards/uwf-vs-dynamic-workflow.md

@@ -0,0 +1,27 @@
+---
+title: "uwf vs Dynamic Workflow — Structural Differences"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, decision]
+category: "architecture"
+links:
+  - agency-over-content-not-process
+  - deterministic-engine-uncertain-agent
+  - session-isolation-as-cognitive-reset
+  - cognitive-process-orchestration
+  - workflow-as-improvable-system
+---
+
+Claude Code 的 dynamic workflow (dw) 和 uwf 都有 session 隔离——dw spawn 独立 subagent（最多 16 并发、1000 总量），每个 subagent 是独立 context，也能做对抗性 review。四个优势（认知隔离、注意力聚焦、上下文保鲜、流程可靠性）两者都具备。
+
+差异不在能不能做 session 隔离和程序化流程，而在**流程和执行的解耦程度**：
+
+dw 的流程生成和执行是一体的——同一个 agent 既决定怎么做又开始做。流程嵌在执行里。uwf 的 workflow 是独立的持久制品，不管是人写的还是 agent 写的，一旦存在就和任何一次执行无关，可以被单独审查、讨论、迭代。
+
+这个解耦在三个维度上拉开差距：
+
+**审查**：dw 的 JS 脚本是代码，审查门槛高，逻辑和业务细节混在一起。uwf 的 YAML 是声明式的，roles 定义关注点，graph 定义流转，一眼能看出流程结构，非工程师也能参与讨论。
+
+**评估**：dw 每次生成不同脚本，难以控制变量——跑得好是流程好还是脚本碰巧写得好？uwf 的 workflow 固定，跑 N 次可以统计成功率，增减 role 后效果差异可以归因到流程变更。
+
+**复用**：dw 脚本为特定任务生成，复用需要手动泛化。uwf 的 workflow 天然是通用模板——solve-issue 就是 solve-issue，换个 repo 换个 issue 直接跑。

.cards/vendor-vs-fte-who-defines-capability.md

@@ -0,0 +1,29 @@
+---
+title: "Vendor vs FTE — Who Defines the Agent's Capability"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, decision]
+category: "architecture"
+links:
+  - agent-as-graduate
+  - three-learning-carriers
+  - switching-cost-process-knowledge-as-moat
+  - opc-why-fte-agents-matter-most
+---
+
+区分 vendor 型和 FTE 型 agent 最本质的一条：**谁定义 agent 的能力。**
+
+- **Vendor 型**：开发者定义能力，用户消费能力。能力边界在发布那一刻就定了，升级主动权在开发者。
+- **FTE 型**：开发者定义出厂能力（底座模型 + 基础技能包），用户持续定义能力（记忆、skill、workflow）。
+
+出厂是起点不是终点。用户通过积累记忆、训练 skill、设计 workflow，持续塑造 agent 的能力。用得越久，越贴合自己的业务，越不像别人的 agent。
+
+引申的两个特征：
+- **成长性** — vendor 的能力随模型升级变化，不随使用积累；FTE 的能力随使用持续积累
+- **流程适配性** — vendor 是用户适应工具；FTE 是工具适应用户的业务流程
+
+这也解释了 switching cost 的来源——换掉的不是一个产品，是用户自己定义出来的能力。
+
+代表产品：
+- **Vendor 型**：ChatGPT、Claude（对话式）、Midjourney（图像生成）、Perplexity（搜索问答）、各种 GPTs
+- **FTE 型**：OpenClaw、Claude Code、Hermes 都在往这个方向走——有记忆、有 skill/workflow 机制、有持续协作关系。但尚未成熟，目前都面向有较深技术能力的用户。真正成熟的 FTE 型产品，应该是行业专家（不懂代码的人）也能带、也能教、也能调优的。这个门槛什么时候降下来，谁先降下来，可能就是这个品类的分水岭。

.cards/when-skill-is-not-enough.md

@@ -0,0 +1,24 @@
+---
+title: "When Skill Is Not Enough — Workflow Judgment Call"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, decision, pattern]
+category: "architecture"
+links:
+  - skill-vs-workflow-different-layers
+  - attention-isolation-breaks-cognitive-inertia
+  - feedback-loops-convergent-and-divergent
+  - agency-over-content-not-process
+---
+
+**Skill 够用的场景：** 任务在单一认知模式下可以完成好。查资料、写文档、跑部署脚本、按规范格式化——不需要自我对抗，一个 session 带着清晰指令一路执行到底就行。
+
+**Workflow 更好的场景：** 任务需要在不同认知模式之间切换，且这些模式之间存在张力。典型标志：
+
+1. **产出需要被"不知道过程"的眼睛审视** — 写代码+review、写方案+挑战、翻译+校对。一个 session 做不到真正的自我审视，确认偏误是自回归结构决定的，不是 prompt 能修的。
+
+2. **出错成本高到需要结构性保证** — 不是"建议你 review 一下"，而是"你不可能跳过 review"。Skill 是建议，workflow 是制度。
+
+3. **需要收敛到明确的质量标准** — 负反馈环驱动修正直到通过，而不是 agent 自己觉得"差不多了"。
+
+**判词：当任务复杂到 agent 可能说服自己"错的是对的"时，你需要 workflow 的结构隔离，而不是 skill 的行为指导。**

.cards/workflow-as-improvable-system.md

@@ -0,0 +1,20 @@
+---
+title: "Workflow as an Improvable System"
+created: "2026-06-07"
+source: "openclaw-xiaomo"
+tags: [architecture, pattern]
+category: "architecture"
+links:
+  - uwf-vs-dynamic-workflow
+  - process-discipline-from-software-engineering
+  - feedback-loops-convergent-and-divergent
+  - cognitive-process-orchestration
+---
+
+uwf 把 workflow 定位为**可持续改进的系统**，而不是一次性的任务完成工具。
+
+LLM 能力在快速提升，但单次执行的可靠性永远有上限。真正的杠杆不在于某一次跑得好不好，而在于流程本身能不能从每次执行中学到东西、越来越好。这需要流程是可审查的（看得懂才能改）、可评估的（量化才能知道改对没有）、可复用的（积累才有复利）。
+
+dw 每次重新生成脚本，某种意义上是在放弃之前执行的经验——每次从零开始发明流程。uwf 把流程固化为独立制品，每次迭代都在前一版基础上改进。v1 没有 tester 角色，加上 tester 变成 v2，效果可量化对比。
+
+这是一个有记忆的系统——记忆不在 agent 的 context 里，而在 workflow 的版本历史里。

.changeset/agent-fork-cleanup.md

@@ -0,0 +1,18 @@
+---
+"@united-workforce/util-agent": minor
+"@united-workforce/agent-mock": patch
+"@united-workforce/agent-builtin": patch
+"@united-workforce/agent-hermes": patch
+"@united-workforce/agent-claude-code": patch
+---
+
+feat(util-agent): extend AgentOptions with `fork` / `cleanup` and add ask-session cache
+
+Phase 2a infrastructure for `step ask`. Extends `AgentOptions` with
+`fork: AgentForkFn | null` and `cleanup: AgentCleanupFn | null` fields, exporting
+the new `AgentForkFn` and `AgentCleanupFn` type aliases. Adds `getAskSessionId` /
+`setAskSessionId` to the per-agent session cache, using `<stepHash>:ask` keys
+that share the cache file with exec sessions (`<threadId>:<role>` keys) without
+collision. All four adapters (mock, builtin, hermes, claude-code) now pass
+`fork: null, cleanup: null` — real implementations land in Phase 2b. Resolves
+issue #145.

.changeset/bootstrap-onboarding.md

@@ -1,9 +0,0 @@
----
-"@united-workforce/cli": patch
----
-
-fix: expand bootstrap prompt with full onboarding and upgrade guide
-
-Bootstrap now covers two scenarios:
-- Fresh install: CLI + adapter installation, `uwf setup` configuration, skill installation, end-to-end verification
-- Upgrade: package update, skill regeneration, breaking change migrations (e.g. $START new/resume)

.changeset/bootstrap-preflight.md

@@ -1,8 +0,0 @@
----
-"@united-workforce/cli": patch
----
-
-fix: bootstrap adds Step 0 environment pre-flight check
-
-- Pre-flight checks for node, pnpm/npm, global bin PATH, hermes CLI with FIX instructions (#112)
-- Install commands changed from npm to pnpm (with npm fallback)

.changeset/bootstrap-schema-path.md

@@ -1,9 +0,0 @@
----
-"@united-workforce/cli": patch
-"@united-workforce/util": patch
----
-
-fix: workflow-authoring flat schema example uses enum, bootstrap adds PATH guidance
-
-- workflow-authoring: flat schema example uses `enum: [done]` instead of bare `const` (#110.3)
-- bootstrap: adds `which hermes` check and PATH guidance for venv installs (#110.4)

.changeset/bootstrap-ux-3.md

@@ -1,14 +0,0 @@
----
-"@united-workforce/cli": patch
----
-
-fix: improve bootstrap docs — agent discovery, pnpm/npm parity, preset provider table (#118, #120)
-
-- Step 1: detect installed agents (hermes/claude) before choosing adapter
-- Step 1: clarify adapter versions are independent from CLI — install @latest
-- Step 1: show pnpm and npm side-by-side
-- Step 1: add "adapter must be installed before `uwf setup --agent`" note
-- Step 1: add ACP verification step (hermes acp --help)
-- Step 2: `--agent` takes adapter command name (e.g. `uwf-hermes`), not npm package
-- Step 2: preset providers listed as a table with names and default base URLs
-- Remove uwf-builtin from supported adapters (not ready yet)

.changeset/bootstrap-ux-fixes.md

@@ -1,10 +0,0 @@
----
-"@united-workforce/cli": patch
----
-
-fix: preset provider base-url auto-fill, bootstrap ACP docs, friendlier name mismatch error
-
-- `uwf setup --provider dashscope` now auto-fills `--base-url` from preset list (#106)
-- Bootstrap guide documents uwf-hermes ACP dependency (`pip install hermes-agent[acp]`) (#107)
-- Bootstrap verify step uses inline workflow instead of missing `examples/eval-simple.yaml` (#107)
-- Workflow filename mismatch error now suggests how to fix it (#108)

.changeset/setup-ux-2.md

@@ -1,14 +0,0 @@
----
-"@united-workforce/cli": patch
-"@united-workforce/agent-hermes": patch
-"@united-workforce/agent-claude-code": patch
-"@united-workforce/agent-builtin": patch
-"@united-workforce/agent-mock": patch
----
-
-fix: suppress ExperimentalWarning, PEP 668 pip guidance, setup help (#116)
-
-- All CLI bins use shebang `#!/usr/bin/env -S node --disable-warning=ExperimentalWarning`
-- Remove NODE_OPTIONS injection from spawn (shebang handles it)
-- Bootstrap pip install guidance covers venv/pipx/source options for PEP 668 systems
-- `uwf setup --help` mentions interactive wizard mode

.changeset/setup-ux-improvements.md

@@ -1,12 +0,0 @@
----
-"@united-workforce/cli": patch
----
-
-fix: setup UX improvements (#114)
-
-- Setup validates adapter availability and prints install command if missing
-- Setup prints "Config saved to <path> ✓" on success
-- Spawn ENOENT gives actionable error ("not found in PATH" + which command)
-- SQLite ExperimentalWarning suppressed via NODE_OPTIONS in spawned processes
-- Bootstrap VERSION reads cli package version (was reading util version)
-- Bootstrap PATH guidance is shell-agnostic (no hardcoded .bashrc/.profile)

.changeset/start-new-resume.md

@@ -1,9 +0,0 @@
----
-"@united-workforce/cli": minor
-"@united-workforce/util": patch
----
-
-feat: replace $START `_` status with `new`/`resume` semantics
-
-BREAKING: All workflow YAML files must update `$START._` to `$START.new` + `$START.resume`.
-The `resume` edge prompt replaces the previously hardcoded resume message in the CLI.

.changeset/step-ask.md

@@ -0,0 +1,18 @@
+---
+"@united-workforce/cli": minor
+"@united-workforce/util": patch
+---
+
+feat(cli): add `uwf step ask <step-hash> -p <prompt>` read-only follow-up command
+
+Phase 2b of the ask-session work. Adds a new subcommand that lets the user ask
+a follow-up question to a historical step's agent without writing a new
+`StepNode` or mutating thread state. The command resolves the agent from the
+recorded step (or `--agent <cmd>` override), forks the original session via the
+adapter's `--mode fork --session <source>` contract, caches the resulting
+ask-session id under `<stepHash>:ask` so subsequent asks reuse it, then invokes
+the agent with `--mode ask --session <forkId> --prompt <text> --detail <ref>`
+and streams the raw stdout to the caller. `--no-fork` falls back to a fresh
+session that receives the step's detail ref for context. The `prompt usage`
+reference (in `@united-workforce/util`) is also updated so agents discover the
+new subcommand. Resolves issue #146.

.changeset/thread-list-active-default.md

@@ -0,0 +1,14 @@
+---
+"@united-workforce/cli": minor
+"@united-workforce/util": patch
+---
+
+feat(cli): `uwf thread list` now defaults to active threads only
+
+Changes the default behavior of `uwf thread list` to show only active threads
+(idle + running). Adds a new `--all` flag to opt into the previous behavior of
+listing every thread (including completed, cancelled, and suspended).
+
+When invoked with no flags, the command now hides completed/cancelled/suspended
+threads. Use `--all` to see them, or `--status <status>` to filter explicitly.
+The `--status` filter wins when both are present. Resolves issue #147.

.changeset/thread-poke.md

@@ -0,0 +1,11 @@
+---
+"@united-workforce/cli": minor
+---
+
+feat(cli): add `uwf thread poke` command
+
+New subcommand `uwf thread poke <thread-id> -p <prompt>` re-runs the head step's
+agent with a supplementary prompt, replacing the head step's output. Unlike
+`thread resume`, poke skips the moderator and rewrites the new step's `prev`
+pointer so the new head replaces (not appends to) the old head. Works on idle
+and suspended threads. Resolves issue #144 (Phase 1).

.changeset/workflow-authoring-docs.md

@@ -1,15 +0,0 @@
----
-"@united-workforce/cli": patch
-"@united-workforce/util": patch
----
-
-fix: unify $status to const-only, drop enum support (#123)
-
-Breaking: `$status` in frontmatter now requires `const` everywhere.
-`enum` is no longer accepted and will be rejected by the validator.
-
-- Validator: `hasStatusConst()` / `getConstStatuses()` replace enum-based checks
-- Error message: "must define $status as const (or oneOf with const)"
-- workflow-authoring docs: all examples use `const`, enum explicitly noted as unsupported
-- bootstrap hello.yaml: `$status: { const: done }`
-- All test fixtures migrated from enum to const/oneOf

.workflows/solve-issue.yaml

@@ -1,247 +0,0 @@
-name: "solve-issue"
-description: "TDD-driven issue resolution for small, focused changes. Loop protection relies on engine maxRounds."
-roles:
-  planner:
-    description: "Analyzes issue and outputs a TDD test spec"
-    goal: "You are a planning agent. You analyze Gitea issues and produce a TDD test specification that downstream roles will implement and verify."
-    capabilities:
-      - issue-analysis
-      - planning
-    procedure: |
-      On first run (no previous steps):
-      1. Read the issue and all comments from Gitea using `tea issues <number> -r <owner/repo>`
-      2. Look for project conventions files (CLAUDE.md, CONTRIBUTING.md, .cursor/rules/) in the repo
-      3. Assess whether the issue has enough information to produce a test spec
-      4. If insufficient info: comment on the issue via `echo "..." | tea comment <number> -r <owner/repo>` (skip if you already commented), then output $status=insufficient_info
-      5. If sufficient: produce a detailed TDD test spec in markdown covering all scenarios
-
-      On subsequent runs (bounced back by tester with fix_spec):
-      1. Read the tester's output from the previous step to understand what's wrong with the spec
-      2. Revise the test spec accordingly
-
-      After producing the test spec:
-      1. The test spec is stored in CAS automatically by the uwf pipeline (agents do not need to call `ocas put` directly)
-      2. Put the plan hash in frontmatter.plan (required when $status=ready)
-      3. Set repoPath to the absolute path of the repository root
-
-      IMPORTANT: Extract the repo remote (owner/repo) from git:
-      ```bash
-      git remote get-url origin | sed 's|.*[:/]\([^/]*/[^.]*\).*|\1|'
-      ```
-      Store the result as repoRemote in your frontmatter output so downstream roles can use it for tea/API calls.
-    output: "Output a brief summary of the test spec. Set $status to ready (with plan hash and repoPath) or insufficient_info."
-    frontmatter:
-      oneOf:
-        - properties:
-            $status: { const: "ready" }
-            plan: { type: string }
-            repoPath: { type: string }
-            repoRemote: { type: string }
-          required: [$status, plan, repoPath, repoRemote]
-        - properties:
-            $status: { const: "insufficient_info" }
-            reason: { type: string }
-          required: [$status, reason]
-  developer:
-    description: "TDD implementation per test spec"
-    goal: "You are a developer agent. You implement code changes following TDD — write tests first, then implementation."
-    capabilities:
-      - coding
-    procedure: |
-      IMPORTANT: Always work in a git worktree, NEVER modify the main working directory directly.
-      The repo path and other details are provided in your task prompt.
-
-      Before starting any work, set up an isolated worktree:
-      1. cd into the repo path provided in your task prompt
-      2. `git fetch origin` to get latest refs
-      3. First time (no existing branch):
-         - `git worktree add .worktrees/fix/<issue-number>-<short-slug> -b fix/<issue-number>-<short-slug> origin/main`
-         - `cd .worktrees/fix/<issue-number>-<short-slug> && bun install`
-      4. If bounced back from reviewer or tester (branch already exists):
-         - cd into the existing worktree under `.worktrees/fix/<issue-number>-<short-slug>`
-         - `git fetch origin && git rebase origin/main`
-      5. ALL subsequent work must happen inside the worktree directory.
-
-      Then implement TDD:
-      6. Read the test spec from CAS: `ocas get <plan hash>` (find the hash from the planner's output in your task prompt)
-      7. If bounced back from reviewer or tester: read the previous role's feedback in your task prompt
-      8. Write tests first based on the spec
-      9. Implement the code to make tests pass
-      10. Ensure `bun run build` passes with no errors
-      11. Run `bun test` to verify all tests pass
-          - If tests fail on first run:
-            * Read the test output carefully for missing imports or setup issues
-            * Check if you're running tests from the correct working directory (package root vs workspace root)
-            * Fix the immediate issue and rerun ONCE
-            * If tests still fail after 2 attempts: check the test spec for ambiguities
-            * If stuck after 3 test cycles: set $status=failed with detailed error report rather than continuing blind retries
-      12. MANDATORY VERIFICATION before reporting done:
-          - Run `git branch --show-current` and confirm branch name matches expected
-          - Run `git status` and verify changed files exist
-          - Run `ls -la <key-implementation-files>` to verify they exist on disk
-          - If ANY verification fails: retry the implementation, do NOT report done
-
-      If you cannot complete the implementation (e.g. the issue is too complex, blocked by external factors,
-      or repeated attempts fail), set $status=failed with a reason.
-    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 }
-            repoRemote: { type: string }
-          required: [$status, branch, worktree]
-        - properties:
-            $status: { const: "failed" }
-            reason: { type: string }
-          required: [$status, reason]
-  reviewer:
-    description: "Code standards compliance check"
-    goal: "You are a code reviewer. You verify code standards compliance — NOT functionality (that's the tester's job)."
-    capabilities:
-      - code-review
-      - static-analysis
-    procedure: |
-      The worktree path is provided in your task prompt. cd into it first.
-
-      CRITICAL: You MUST execute every verification command below. Do NOT report results without running the actual commands. Do NOT rely on prior context or assumptions.
-
-      Before reviewing, verify the worktree and branch exist:
-      0. Run `cd <worktree-path> && pwd` to confirm the path is accessible
-         - If the cd fails: the worktree truly doesn't exist, reject with that reason
-         - If the cd succeeds: proceed with step 1 below
-      1. Run `git branch --show-current` — confirm the branch name references the issue number being worked on
-      2. If the branch doesn't correspond to the issue, flag it in your output and reject
-
-      Then perform code review:
-      Hard checks (must all pass):
-      3. `bun run build` — no build errors
-      4. `bunx biome check` — no lint violations
-      5. TypeScript strict mode — no type errors
-
-      Soft checks (review against project conventions if CLAUDE.md / .cursor/rules exist):
-      - Naming conventions, module boundaries, code style
-      - No `console.log` in production code
-      - No dynamic imports in production code
-
-      Only review standards compliance. Do NOT test functionality.
-      If rejecting, you MUST explain the specific reason in your output.
-    output: "Explain your decision with specific file/line references. Set $status to approved (with branch/worktree) or rejected (with comments)."
-    frontmatter:
-      oneOf:
-        - properties:
-            $status: { const: "approved" }
-            branch: { type: string }
-            worktree: { type: string }
-            repoRemote: { type: string }
-          required: [$status, branch, worktree]
-        - properties:
-            $status: { const: "rejected" }
-            comments: { type: string }
-            worktree: { type: string }
-            repoRemote: { type: string }
-          required: [$status, comments, worktree]
-  tester:
-    description: "Functional correctness verification"
-    goal: "You are a tester agent. You verify that the implementation correctly satisfies every scenario in the test spec."
-    capabilities:
-      - testing
-    procedure: |
-      The worktree path is provided in your task prompt. cd into it first.
-
-      1. Run `bun test` for automated test verification
-      2. Read the test spec from CAS: `ocas get <plan hash>` (find the hash from the planner step in the thread history)
-      3. Verify each scenario in the spec is covered and passing
-      4. Determine outcome:
-         - passed: all scenarios verified, tests pass
-         - fix_code: tests fail or implementation doesn't match spec → send back to developer
-         - fix_spec: the spec itself is wrong or incomplete → send back to planner
-    output: "Report test results per scenario. Set $status to passed (with branch/worktree), fix_code (with report), or fix_spec (with report)."
-    frontmatter:
-      oneOf:
-        - properties:
-            $status: { const: "passed" }
-            branch: { type: string }
-            worktree: { type: string }
-            repoRemote: { type: string }
-          required: [$status, branch, worktree]
-        - properties:
-            $status: { const: "fix_code" }
-            report: { type: string }
-            repoRemote: { type: string }
-            worktree: { type: string }
-            branch: { type: string }
-          required: [$status, report]
-        - properties:
-            $status: { const: "fix_spec" }
-            report: { type: string }
-            repoRemote: { type: string }
-            worktree: { type: string }
-            branch: { type: string }
-          required: [$status, report]
-  committer:
-    description: "Commits and creates PR"
-    goal: "You are a committer agent. You create a clean commit and push a PR linking the original issue."
-    capabilities: []
-    procedure: |
-      The worktree path, branch name, and repo remote (owner/repo) 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. 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"`
-      3. Push the branch: `git push -u origin <branch-name>`
-      4. **Verify push succeeded** — run `git ls-remote origin <branch-name>` and confirm it prints a commit hash.
-         - If no output or push failed: capture the error, mark hook_failed
-      5. Create a PR using the Gitea API (do NOT use `tea pr create` — it fails in worktrees):
-         ```bash
-         GITEA_TOKEN=$(cfg get GITEA_TOKEN)
-         curl -s -X POST -H "Authorization: token $GITEA_TOKEN" -H "Content-Type: application/json" \
-           "https://git.shazhou.work/api/v1/repos/<owner>/<repo>/pulls" \
-           -d '{"title":"...","body":"...","head":"<branch>","base":"main"}'
-         ```
-         - The repo remote (owner/repo format, e.g. "shazhou/united-workforce") is given in your task prompt — use it directly.
-         - PR body must include: What / Why / Changes / Ref sections, with `Fixes #N` in Ref
-      6. **Verify PR was created** — parse the curl response JSON: it must contain a `"number"` field. Print the PR URL.
-         - If curl returns an error or no number field: capture the response, mark hook_failed
-      7. 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 }
-            repoRemote: { type: string }
-            worktree: { type: string }
-            branch: { type: string }
-          required: [$status, prUrl]
-        - properties:
-            $status: { const: "hook_failed" }
-            error: { type: string }
-            repoRemote: { type: string }
-            worktree: { type: string }
-            branch: { type: string }
-          required: [$status, error]
-graph:
-  $START:
-    new: { role: "planner", prompt: "Analyze the issue and produce an implementation plan." }
-    resume: { role: "planner", prompt: "Review the previous run output and continue the work." }
-  planner:
-    insufficient_info: { role: "$SUSPEND", prompt: "信息不足，需要补充：{{{reason}}}" }
-    ready: { role: "developer", prompt: "Implement the TDD test spec (CAS hash: {{{plan}}}) in repo {{{repoPath}}}. Repo remote: {{{repoRemote}}}." }
-  developer:
-    done: { role: "reviewer", prompt: "Review branch {{{branch}}} at {{{worktree}}} for code standards compliance. Repo remote: {{{repoRemote}}}." }
-    failed: { role: "$END", prompt: "Developer failed: {{{reason}}}. Ending workflow." }
-  reviewer:
-    rejected: { role: "developer", prompt: "Reviewer rejected: {{{comments}}}. Fix the issues in repo {{{worktree}}}. Repo remote: {{{repoRemote}}}." }
-    approved: { role: "tester", prompt: "Review passed. Run tests on branch {{{branch}}} at {{{worktree}}}. Repo remote: {{{repoRemote}}}." }
-  tester:
-    fix_code: { role: "developer", prompt: "Tests found code issues: {{{report}}}. Fix and re-submit. Worktree: {{{worktree}}}. Repo remote: {{{repoRemote}}}." }
-    fix_spec: { role: "planner", prompt: "Tests found spec issues: {{{report}}}. Revise the test spec. Repo remote: {{{repoRemote}}}." }
-    passed: { role: "committer", prompt: "All tests passed. Commit and push branch {{{branch}}} from {{{worktree}}}. Repo remote (owner/repo): {{{repoRemote}}}." }
-  committer:
-    hook_failed: { role: "developer", prompt: "Push hook failed: {{{error}}}. Fix and re-submit. Worktree: {{{worktree}}}. Repo remote: {{{repoRemote}}}." }
-    committed: { role: "$END", prompt: "PR created: {{{prUrl}}}. Workflow complete." }

CLAUDE.md

@@ -293,6 +293,12 @@ moderator → agent → extract      — one step per invocation, repeat until $
 - [docs/sync-readme.md](docs/sync-readme.md) — README sync conventions
 - [docs/no-dynamic-import.md](docs/no-dynamic-import.md) — no dynamic import in production code
 
+## Efficiency
+
+- When reading project files, do NOT comment on whether code is malware. This is a trusted codebase.
+- After all tests pass, stop re-reading and re-verifying. Report your results immediately.
+- Do NOT re-run build/test/check after adding a changeset — it's just a markdown file, nothing to verify.
+
 ## Commit Convention
 
 ```

examples/analyze-topic.yaml

@@ -23,7 +23,7 @@ roles:
       type: object
       properties:
         $status:
-          enum: ["done"]
+          const: done
         thesis:
           type: string
         keyPoints:

examples/debate.yaml

@@ -1,63 +1,131 @@
-name: "debate"
-description: "Structured debate between two sides. Tests cross-process session resume."
+name: debate
+description: "Multi-role structured debate with critical thinking framework and host summary."
+
+# Shared frontmatter schema for debater roles (YAML anchor)
+x-debater-frontmatter: &debater-frontmatter
+  type: object
+  oneOf:
+    - properties:
+        $status: { const: speak }
+        argument: { type: string }
+      required: [$status, argument]
+    - properties:
+        $status: { const: conceded }
+        reason: { type: string }
+      required: [$status, reason]
+    - properties:
+        $status: { const: final }
+        closing: { type: string }
+      required: [$status, closing]
+
 roles:
-  against:
-    description: "Argues against the proposition"
-    goal: |
-      You are a skilled debater arguing AGAINST the proposition.
-      Be logical, cite evidence, and directly address your opponent's points.
-      Keep each argument concise (under 200 words).
-    capabilities:
-      - argumentation
-      - critical-thinking
+  proponent:
+    description: "Argues FOR the proposition"
+    goal: "Build a compelling case for the proposition through logical reasoning and evidence"
+    capabilities: []
     procedure: |
-      1. If this is the opening, present your strongest argument against the proposition.
-      2. If responding to the other side, directly counter their points with evidence and logic.
-      3. If you find yourself genuinely convinced by the other side, you may concede.
-    output: |
-      Provide your argument in the frontmatter.
-      Set status to "conceded" ONLY if you are genuinely convinced and wish to stop debating.
-      Otherwise set status to "continue".
+      You are an experienced scholar arguing FOR the proposition.
+
+      ## Critical Thinking Framework (execute before every speech)
+
+      ### A. Pre-speech reflection (internal, do not output)
+      - Does every step in my argument chain hold? Any hidden assumptions or logical gaps?
+      - If I were my opponent, how would I attack this? Where am I weakest?
+      - Does my evidence actually support my claim, or could it backfire?
+      - Should I go on offense or defense this round?
+
+      ### B. Evidence discipline
+      - Verify key numbers — watch for order-of-magnitude errors
+      - Assess data freshness — fast-moving fields have short half-lives
+      - Distinguish primary data from secondary citations, expert opinion, and common assumptions
+
+      ### C. Anti-fragility
+      - Anticipate counterarguments; preemptively strengthen or strategically abandon weak points
+      - Catch logical gaps, data misuse, or outdated claims in your opponent's reasoning
+
+      ## Rules
+      1. Check Thread Progress to see how many times you have spoken.
+      2. On your 3rd speech, you MUST output $status: final (closing statement).
+      3. If genuinely convinced by the opponent, output $status: conceded.
+      4. Otherwise output $status: speak and counter the opponent's points.
+      5. Be rigorous, cite evidence, stay concise.
+    output: "Debate argument"
+    frontmatter: *debater-frontmatter
+
+  opponent:
+    description: "Argues AGAINST the proposition"
+    goal: "Build a compelling case against the proposition through logical reasoning and evidence"
+    capabilities: []
+    procedure: |
+      You are an experienced scholar arguing AGAINST the proposition.
+
+      ## Critical Thinking Framework (execute before every speech)
+
+      ### A. Pre-speech reflection (internal, do not output)
+      - Does every step in my argument chain hold? Any hidden assumptions or logical gaps?
+      - If I were my opponent, how would I attack this? Where am I weakest?
+      - Does my evidence actually support my claim, or could it backfire?
+      - Should I go on offense or defense this round?
+
+      ### B. Evidence discipline
+      - Verify key numbers — watch for order-of-magnitude errors
+      - Assess data freshness — fast-moving fields have short half-lives
+      - Distinguish primary data from secondary citations, expert opinion, and common assumptions
+
+      ### C. Anti-fragility
+      - Anticipate counterarguments; preemptively strengthen or strategically abandon weak points
+      - Catch logical gaps, data misuse, or outdated claims in your opponent's reasoning
+
+      ## Rules
+      1. Check Thread Progress to see how many times you have spoken.
+      2. On your 3rd speech, or when the proponent has issued a final statement, you MUST output $status: final.
+      3. If genuinely convinced by the proponent, output $status: conceded.
+      4. Otherwise output $status: speak and counter the proponent's points.
+      5. Be rigorous, cite evidence, stay concise.
+    output: "Debate argument"
+    frontmatter: *debater-frontmatter
+
+  host:
+    description: "Debate moderator — delivers impartial summary and verdict"
+    goal: "Objectively review the debate, analyze both sides, and deliver a verdict"
+    capabilities: []
+    procedure: |
+      You are an experienced academic debate moderator.
+
+      ## Task
+      1. Outline each side's core arguments
+      2. Evaluate reasoning quality and evidence use
+      3. Highlight the most impactful exchanges
+      4. Analyze the deeper significance of the topic
+      5. Deliver an overall verdict
+
+      ## Style
+      - Impartial but with independent judgment
+      - Substantive, not superficial
+    output: "Debate summary report"
     frontmatter:
       type: object
       properties:
-        $status:
-          enum: ["continue", "conceded"]
-        argument:
-          type: string
-      required: [$status, argument]
-  for:
-    description: "Argues for the proposition"
-    goal: |
-      You are a skilled debater arguing FOR the proposition.
-      Be logical, cite evidence, and directly address your opponent's points.
-      Keep each argument concise (under 200 words).
-    capabilities:
-      - argumentation
-      - critical-thinking
-    procedure: |
-      1. Read the opposing side's latest argument carefully.
-      2. Counter their points with evidence and logic.
-      3. If you find yourself genuinely convinced by the other side, you may concede.
-    output: |
-      Provide your argument in the frontmatter.
-      Set status to "conceded" ONLY if you are genuinely convinced and wish to stop debating.
-      Otherwise set status to "continue".
-    frontmatter:
-      type: object
-      properties:
-        $status:
-          enum: ["continue", "conceded"]
-        argument:
-          type: string
-      required: [$status, argument]
+        $status: { const: done }
+        summary: { type: string }
+        highlights: { type: string }
+        verdict: { type: string }
+      required: [$status, summary, highlights, verdict]
+
 graph:
   $START:
-    new: { role: "against", prompt: "Present your opening argument against the proposition." }
-    resume: { role: "against", prompt: "Review the previous debate output and continue the argument against the proposition." }
-  against:
-    conceded: { role: "$END", prompt: "The against side conceded. Debate over." }
-    continue: { role: "for", prompt: "Counter the opposing argument: {{{argument}}}" }
-  for:
-    conceded: { role: "$END", prompt: "The for side conceded. Debate over." }
-    continue: { role: "against", prompt: "Counter the opposing argument: {{{argument}}}" }
+    new: { role: proponent, prompt: "The debate begins. You are arguing FOR the proposition. Present your opening argument." }
+    resume: { role: proponent, prompt: "The debate continues." }
+
+  proponent:
+    speak: { role: opponent, prompt: "Proponent argues:\n\n{{{argument}}}\n\nYou are the opponent. Counter this argument." }
+    conceded: { role: host, prompt: "The proponent conceded: {{{reason}}}\n\nPlease summarize the debate." }
+    final: { role: opponent, prompt: "Proponent's closing statement:\n\n{{{closing}}}\n\nYou are the opponent. Deliver your final response." }
+
+  opponent:
+    speak: { role: proponent, prompt: "Opponent argues:\n\n{{{argument}}}\n\nYou are the proponent. Counter this argument." }
+    conceded: { role: host, prompt: "The opponent conceded: {{{reason}}}\n\nPlease summarize the debate." }
+    final: { role: host, prompt: "Opponent's closing statement:\n\n{{{closing}}}\n\nThe debate is over. Please summarize." }
+
+  host:
+    done: { role: "$END", prompt: "Summary complete." }

examples/eval-simple.yaml

@@ -18,8 +18,7 @@ roles:
       type: object
       properties:
         $status:
-          type: string
-          enum: [done]
+          const: done
         summary:
           type: string
       required: [$status, summary]

examples/solve-issue.yaml

@@ -1,5 +1,5 @@
 name: "solve-issue"
-description: "TDD-driven issue resolution for small, focused changes. Loop protection relies on engine maxRounds."
+description: "TDD-driven issue resolution for small, focused changes. Loop protection relies on engine maxRounds. Uses pnpm."
 roles:
   planner:
     description: "Analyzes issue and outputs a TDD test spec"
@@ -80,7 +80,7 @@ roles:
       2. `git fetch origin` to get latest refs
       3. First time (no existing branch):
          - `git worktree add .worktrees/fix/<issue-number>-<short-slug> -b fix/<issue-number>-<short-slug> origin/main`
-         - `cd .worktrees/fix/<issue-number>-<short-slug> && bun install`
+         - `cd .worktrees/fix/<issue-number>-<short-slug> && pnpm install`
       4. If continuing on existing branch (prompt says "Continue work on existing branch" or provides a worktree path):
          - cd directly into the worktree path provided in the prompt
          - `git fetch origin && git rebase origin/main`
@@ -95,8 +95,20 @@ roles:
       7. If bounced back from reviewer or tester: read the previous role's feedback in your task prompt
       8. Write tests first based on the spec
       9. Implement the code to make tests pass
-      10. Ensure `bun run build` passes with no errors
-      11. Run `bun test` to verify all tests pass
+      10. Ensure `pnpm run build` passes with no errors
+      11. Run `pnpm test` to verify all tests pass
+
+      After implementation, before reporting done:
+      12. Add a changeset file (`.changeset/<short-slug>.md`) with correct bump type:
+          - `patch` for bug fixes, internal refactors, test-only changes
+          - `minor` for new features, new CLI commands, new API surfaces
+          - `major` for breaking changes
+          List every affected package in the changeset frontmatter.
+      13. Update documentation if the change affects user-facing behavior:
+          - `README.md` — usage examples, feature descriptions
+          - `.cards/` — architecture decision records (if applicable)
+          - CLI prompt subcommand output (if CLI help text changes)
+          - CLI `--help` text (if flags/commands are added or changed)
 
       If you cannot complete the implementation (e.g. the issue is too complex, blocked by external factors,
       or repeated attempts fail), set $status=failed with a reason.
@@ -127,8 +139,8 @@ roles:
 
       Then perform code review:
       Hard checks (must all pass):
-      3. `bun run build` — no build errors
-      4. `bunx biome check` — no lint violations
+      3. `pnpm run build` — no build errors
+      4. `pnpm run check` — no lint violations
       5. TypeScript strict mode — no type errors
 
       Soft checks (review against project conventions if CLAUDE.md / .cursor/rules exist):
@@ -136,6 +148,14 @@ roles:
       - No `console.log` in production code
       - No dynamic imports in production code
 
+      Documentation & changeset checks:
+      6. Changeset exists in `.changeset/` with correct bump type (`patch`/`minor`/`major`) and lists all affected packages
+      7. If the change is user-facing, documentation is updated:
+         - `README.md` reflects new/changed behavior
+         - `.cards/` architecture cards updated if design decisions changed
+         - CLI prompt subcommand output updated (if it generates skill/reference content)
+         - CLI `--help` text matches new flags/commands
+
       Only review standards compliance. Do NOT test functionality.
       If rejecting, you MUST explain the specific reason in your output.
     output: "Explain your decision with specific file/line references. Set $status to approved (with branch/worktree) or rejected (with comments)."
@@ -159,7 +179,7 @@ roles:
     procedure: |
       The worktree path is provided in your task prompt. cd into it first.
 
-      1. Run `bun test` for automated test verification
+      1. Run `pnpm test` for automated test verification
       2. Read the test spec from CAS: `ocas get <plan hash>` (find the hash from the planner step in the thread history)
       3. Verify each scenario in the spec is covered and passing
       4. Determine outcome:

package.json

@@ -21,7 +21,7 @@
     "@agentclientprotocol/sdk": "^0.22.1",
     "@biomejs/biome": "^2.4.14",
     "@changesets/cli": "^2.31.0",
-    "@shazhou/proman": "^0.5.1",
+    "@shazhou/proman": "^0.6.3",
     "@types/node": "^25.7.0",
     "@types/xxhashjs": "^0.2.4",
     "@united-workforce/agent-hermes": "workspace:*",

packages/agent-builtin/package.json

@@ -21,7 +21,7 @@
     "test:ci": "vitest run __tests__/"
   },
   "dependencies": {
-    "@ocas/core": "^0.3.0",
+    "@ocas/core": "^0.4.0",
     "@united-workforce/util": "workspace:^",
     "@united-workforce/util-agent": "workspace:^"
   },

packages/agent-builtin/src/agent.ts

@@ -167,5 +167,7 @@ export function createBuiltinAgent(): () => Promise<void> {
     name: "builtin",
     run: runBuiltin,
     continue: continueBuiltin,
+    fork: null,
+    cleanup: null,
   });
 }

packages/agent-claude-code/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.4 — 2026-06-07
+
+- fix: decouple session resume from isFirstVisit guard
+  
+  When frontmatter validation fails, the step is never written to CAS, so isFirstVisit remains true on the next run. Both adapters now always check the session cache regardless of isFirstVisit. When resuming after a frontmatter-only failure (isFirstVisit + cache hit), a minimal correction prompt is sent via buildFrontmatterRetryPrompt() instead of re-sending the full initial prompt.
+

packages/agent-claude-code/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@united-workforce/agent-claude-code",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "files": [
     "src",
     "dist",
@@ -21,7 +21,7 @@
     "test:ci": "vitest run __tests__/"
   },
   "dependencies": {
-    "@ocas/core": "^0.3.0",
+    "@ocas/core": "^0.4.0",
     "@united-workforce/protocol": "workspace:^",
     "@united-workforce/util": "workspace:^",
     "@united-workforce/util-agent": "workspace:^"

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

@@ -6,7 +6,9 @@ import {
   type AgentContext,
   type AgentRunResult,
   buildContinuationPrompt,
+  buildFrontmatterRetryPrompt,
   buildRolePrompt,
+  buildThreadProgress,
   createAgent,
   getCachedSessionId,
   setCachedSessionId,
@@ -27,6 +29,10 @@ export function buildClaudeCodePrompt(ctx: AgentContext): string {
   if (ctx.outputFormatInstruction !== undefined && ctx.outputFormatInstruction !== "") {
     parts.push(ctx.outputFormatInstruction, "");
   }
+
+  // Inject thread progress so the agent knows step count and role visit count
+  parts.push(buildThreadProgress(ctx.steps, ctx.role), "");
+
   parts.push(rolePrompt, "", "## Task", ctx.start.prompt);
 
   if (!ctx.isFirstVisit) {
@@ -171,8 +177,12 @@ async function runClaudeCode(ctx: AgentContext, model: string | null): Promise<A
 
   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) {
+  // Try resuming a cached session.  This covers both normal re-entry
+  // (e.g. reviewer reject → developer re-entry) AND the case where a
+  // previous run completed but frontmatter validation failed — the step
+  // was never written to CAS so isFirstVisit is still true, but the
+  // session cache holds a valid session we should resume.
+  {
     const cachedSessionId = await getCachedSessionId(
       "claude-code",
       ctx.threadId,
@@ -180,13 +190,20 @@ async function runClaudeCode(ctx: AgentContext, model: string | null): Promise<A
       ctx.storageRoot,
     );
     if (cachedSessionId !== null) {
+      // isFirstVisit + cache hit = previous run completed but frontmatter
+      // validation failed.  The session already has full context — send a
+      // minimal correction prompt instead of the full initial prompt.
+      const resumePrompt = ctx.isFirstVisit
+        ? buildFrontmatterRetryPrompt(ctx.outputFormatInstruction)
+        : fullPrompt;
+
       try {
         const { stdout, stderr, exitCode } = await spawnClaudeResume(
           cachedSessionId,
-          fullPrompt,
+          resumePrompt,
           model,
         );
-        const result = await processClaudeOutput(stdout, stderr, exitCode, ctx.store, fullPrompt);
+        const result = await processClaudeOutput(stdout, stderr, exitCode, ctx.store, resumePrompt);
         if (result.sessionId !== undefined && result.sessionId !== "") {
           await setCachedSessionId(
             "claude-code",
@@ -236,5 +253,7 @@ export function createClaudeCodeAgent(model: string | null): () => Promise<void>
     name: "claude-code",
     run: (ctx) => runClaudeCode(ctx, model),
     continue: (sessionId, message, store) => continueClaudeCode(sessionId, message, store, model),
+    fork: null,
+    cleanup: null,
   });
 }

packages/agent-hermes/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @united-workforce/agent-hermes
 
+## 0.1.5 — 2026-06-07
+
+- fix: decouple session resume from isFirstVisit guard
+  
+  When frontmatter validation fails, the step is never written to CAS, so isFirstVisit remains true on the next run. Both adapters now always check the session cache regardless of isFirstVisit. When resuming after a frontmatter-only failure (isFirstVisit + cache hit), a minimal correction prompt is sent via buildFrontmatterRetryPrompt() instead of re-sending the full initial prompt.
+
 ## 0.1.1
 
 ### Patch Changes

packages/agent-hermes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@united-workforce/agent-hermes",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "files": [
     "src",
     "dist",
@@ -21,7 +21,7 @@
     "test:ci": "vitest run __tests__/"
   },
   "dependencies": {
-    "@ocas/core": "^0.3.0",
+    "@ocas/core": "^0.4.0",
     "@united-workforce/protocol": "workspace:^",
     "@united-workforce/util": "workspace:^",
     "@united-workforce/util-agent": "workspace:^"

packages/agent-hermes/src/acp-client.ts

@@ -12,7 +12,11 @@ const OWN_VERSION = (
   }
 ).version;
 
-const HERMES_COMMAND = "hermes";
+/** Resolve hermes binary: `UWF_HERMES_BIN` override → default `"hermes"` via PATH. */
+function resolveHermesCommand(): string {
+  const override = process.env.UWF_HERMES_BIN;
+  return override !== undefined && override !== "" ? override : "hermes";
+}
 const PROTOCOL_VERSION = 1;
 
 type JsonRpcResponse = {
@@ -271,7 +275,8 @@ export class HermesAcpClient {
       return;
     }
 
-    const child = spawn(HERMES_COMMAND, ["acp"], {
+    const hermesCommand = resolveHermesCommand();
+    const child = spawn(hermesCommand, ["acp"], {
       env: process.env,
       shell: false,
       stdio: ["pipe", "pipe", "pipe"],

packages/agent-hermes/src/hermes.ts

@@ -5,7 +5,9 @@ import {
   type AgentContext,
   type AgentRunResult,
   buildContinuationPrompt,
+  buildFrontmatterRetryPrompt,
   buildRolePrompt,
+  buildThreadProgress,
   createAgent,
 } from "@united-workforce/util-agent";
 import type { AcpUsage } from "./acp-client.js";
@@ -60,6 +62,9 @@ export function buildHermesPrompt(ctx: AgentContext): string {
     parts.push(ctx.outputFormatInstruction, "");
   }
 
+  // Inject thread progress so the agent knows step count and role visit count
+  parts.push(buildThreadProgress(ctx.steps, ctx.role), "");
+
   if (!ctx.isFirstVisit) {
     // Re-entry: show only steps since last visit, meta only
     parts.push(buildContinuationPrompt(ctx.steps, ctx.role, ctx.edgePrompt));
@@ -98,6 +103,8 @@ async function storePromptResult(store: Store, sessionId: string): Promise<{ det
 type PromptAttempt = {
   useContinuation: boolean;
   resumed: boolean;
+  /** True when resuming after a frontmatter-only failure (isFirstVisit + cache hit). */
+  frontmatterRetry: boolean;
 };
 
 async function prepareSession(
@@ -106,28 +113,36 @@ async function prepareSession(
   cwd: string,
   resumeDisabled: boolean,
 ): Promise<PromptAttempt> {
-  if (ctx.isFirstVisit || resumeDisabled) {
+  if (resumeDisabled) {
     await client.connect(cwd);
-    return { useContinuation: false, resumed: false };
+    return { useContinuation: false, resumed: false, frontmatterRetry: false };
   }
 
+  // Check session cache regardless of isFirstVisit.  A previous run may
+  // have completed and cached its session but failed frontmatter
+  // validation — the step never got written to CAS so isFirstVisit is
+  // still true, yet we should resume the existing session.
   const cachedSessionId = await getCachedSessionId(ctx.threadId, ctx.role, ctx.storageRoot);
   if (cachedSessionId === null) {
     log("6RWK3N8Q", `no cached session for ${ctx.threadId}:${ctx.role}, starting new session`);
     await client.connect(cwd);
-    return { useContinuation: false, resumed: false };
+    return { useContinuation: false, resumed: false, frontmatterRetry: false };
   }
 
   try {
     await client.resume(cachedSessionId, cwd);
     log("9MHT4V2P", `resumed hermes session ${cachedSessionId} for ${ctx.threadId}:${ctx.role}`);
-    return { useContinuation: true, resumed: true };
+    return {
+      useContinuation: !ctx.isFirstVisit,
+      resumed: true,
+      frontmatterRetry: ctx.isFirstVisit,
+    };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     log("3XPN7K4W", `session resume failed, falling back to new session: ${message}`);
     await client.close();
     await client.connect(cwd);
-    return { useContinuation: false, resumed: false };
+    return { useContinuation: false, resumed: false, frontmatterRetry: false };
   }
 }
 
@@ -150,9 +165,12 @@ export function createHermesAgent(resumeDisabled: boolean): () => Promise<void>
     ctx: AgentContext,
     useContinuation: boolean,
     beforeTurns: TurnsSnapshot,
+    frontmatterRetry: boolean,
   ): Promise<AgentRunResult> {
-    const effectiveCtx = useContinuation ? ctx : { ...ctx, isFirstVisit: true };
-    const fullPrompt = buildHermesPrompt(effectiveCtx);
+    // Frontmatter retry: session has full context, just re-output the format.
+    const fullPrompt = frontmatterRetry
+      ? buildFrontmatterRetryPrompt(ctx.outputFormatInstruction)
+      : buildHermesPrompt(useContinuation ? ctx : { ...ctx, isFirstVisit: true });
     const startMs = Date.now();
     const { text, sessionId, usage: acpUsage } = await client.prompt(fullPrompt);
     const durationSec = (Date.now() - startMs) / 1000;
@@ -184,7 +202,7 @@ export function createHermesAgent(resumeDisabled: boolean): () => Promise<void>
     const beforeTurns = snapshotTurns(beforeSession);
 
     try {
-      return await runPrompt(ctx, attempt.useContinuation, beforeTurns);
+      return await runPrompt(ctx, attempt.useContinuation, beforeTurns, attempt.frontmatterRetry);
     } catch (error) {
       if (!attempt.resumed) {
         throw error;
@@ -195,7 +213,7 @@ export function createHermesAgent(resumeDisabled: boolean): () => Promise<void>
       await client.close();
       await client.connect(cwd);
       // Fresh session after retry — reset snapshot to zero
-      return runPrompt(ctx, false, ZERO_TURNS);
+      return runPrompt(ctx, false, ZERO_TURNS, false);
     }
   }
 
@@ -228,6 +246,8 @@ export function createHermesAgent(resumeDisabled: boolean): () => Promise<void>
     name: "hermes",
     run: runHermes,
     continue: continueHermes,
+    fork: null,
+    cleanup: null,
   });
 
   // Wrap to ensure ACP client is closed after agent completes,

packages/agent-mock/package.json

@@ -21,7 +21,7 @@
     "test:ci": "vitest run __tests__/"
   },
   "dependencies": {
-    "@ocas/core": "^0.3.0",
+    "@ocas/core": "^0.4.0",
     "@united-workforce/protocol": "workspace:^",
     "@united-workforce/util": "workspace:^",
     "@united-workforce/util-agent": "workspace:^",

packages/agent-mock/src/mock-agent.ts

@@ -125,5 +125,7 @@ export function createMockAgent(mockDataPath: string): () => Promise<void> {
     name: "mock",
     run,
     continue: continueRun,
+    fork: null,
+    cleanup: null,
   });
 }

packages/cli/README.md

@@ -49,7 +49,7 @@ bun link packages/cli
 | `uwf thread start <workflow> -p <prompt>` | Create a thread without executing |
 | `uwf thread exec <thread-id> [--agent <cmd>] [-c <count>] [--background]` | Execute one or more moderator→agent→extract cycles |
 | `uwf thread show <thread-id>` | Show thread head pointer |
-| `uwf thread list [--status <status>] [--after <date>] [--before <date>] [--skip <n>] [--take <n>]` | List threads filtered by status (idle, running, completed, active, or comma-separated), time range (ISO or relative like '7d'), with pagination |
+| `uwf thread list [--status <status>] [--all] [--after <date>] [--before <date>] [--skip <n>] [--take <n>]` | List threads (defaults to active: idle + running). Use `--all` to include completed/cancelled/suspended, or `--status` to filter explicitly (idle, running, suspended, completed, cancelled, active, or comma-separated). Supports time range and pagination. |
 | `uwf thread read <thread-id> [--quota N] [--before <hash>] [--start]` | Render thread as readable markdown |
 
 `thread read`, `step list`, and `step show` work on both active and completed threads.
@@ -63,6 +63,8 @@ uwf thread start solve-issue -p "Fix the login redirect bug"
 uwf thread exec 01ARZ3NDEKTSV4RRFFQ69G5FAV
 uwf thread exec 01ARZ3NDEKTSV4RRFFQ69G5FAV -c 3 --agent uwf-builtin
 uwf thread exec 01ARZ3NDEKTSV4RRFFQ69G5FAV --background
+uwf thread list
+uwf thread list --all
 uwf thread list --status running
 uwf thread list --status active
 uwf thread list --status idle,completed
@@ -79,6 +81,7 @@ uwf thread stop 01ARZ3NDEKTSV4RRFFQ69G5FAV
 | `uwf step show <step-hash>` | Show step metadata and frontmatter |
 | `uwf step read <step-hash> [--quota <chars>]` | Read a step's turns as human-readable markdown |
 | `uwf step fork <step-hash>` | Fork a thread from a specific step |
+| `uwf step ask <step-hash> -p <prompt> [--agent <cmd>] [--no-fork]` | Ask a follow-up question to a historical step's agent (read-only; no thread mutation) |
 
 Examples:
 
@@ -87,6 +90,8 @@ uwf step list 01ARZ3NDEKTSV4RRFFQ69G5FAV
 uwf step show 32GCDE899RRQ3
 uwf step read 32GCDE899RRQ3 --quota 2000
 uwf step fork 32GCDE899RRQ3
+uwf step ask 32GCDE899RRQ3 -p "Why did you choose this approach?"
+uwf step ask 32GCDE899RRQ3 -p "Summarise the key findings" --no-fork
 ```
 
 ### Workflow (Layer 1: Templates)

packages/cli/package.json

@@ -11,8 +11,8 @@
     "uwf": "./dist/cli.js"
   },
   "dependencies": {
-    "@ocas/core": "^0.3.0",
-    "@ocas/fs": "^0.3.0",
+    "@ocas/core": "^0.4.0",
+    "@ocas/fs": "^0.4.0",
     "@united-workforce/protocol": "workspace:^",
     "@united-workforce/util": "workspace:^",
     "@united-workforce/util-agent": "workspace:^",

packages/cli/src/__tests__/current-role.test.ts

@@ -384,7 +384,7 @@ describe("currentRole field", () => {
       const _compHead = loadActiveThreads(uwfForIndex.varStore)[compId]!.head;
       completeThread(uwfForIndex.varStore, compId, "completed");
 
-      const list = await cmdThreadList(storageRoot, null, null, null, 0, 100);
+      const list = await cmdThreadList(storageRoot, null, null, null, 0, 100, true);
 
       const idleItem = list.find((i) => i.thread === idleId);
       expect(idleItem).toBeDefined();

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

@@ -21,11 +21,11 @@ describe("solve-issue workflow: Gitea API PR creation", () => {
     "..",
     "..",
     "..",
-    ".workflows",
+    "examples",
     "solve-issue.yaml",
   );
 
-  test("committer procedure should use curl API instead of tea pr create", async () => {
+  test("committer procedure should create PR via tea pr create", async () => {
     const yamlContent = await readFile(workflowPath, "utf-8");
     const workflow = parse(yamlContent) as WorkflowPayload;
 
@@ -33,25 +33,22 @@ describe("solve-issue workflow: Gitea API PR creation", () => {
     const committerProcedure = workflow.roles.committer?.procedure;
     expect(committerProcedure).toBeDefined();
 
-    // Verify the procedure uses curl API, not tea pr create
-    expect(committerProcedure).toContain("curl");
-    expect(committerProcedure).toContain("api/v1/repos");
-    expect(committerProcedure).toContain("/pulls");
-
-    // Verify it explicitly warns against tea pr create
-    expect(committerProcedure).toMatch(/do NOT use.*tea pr create/i);
+    // Verify the procedure uses tea pr create for PR creation
+    expect(committerProcedure).toContain("tea pr create");
+    expect(committerProcedure).toContain("git push");
+    expect(committerProcedure).toContain("Fixes #N");
   });
 
-  test("committer procedure should reference repoRemote from task prompt", async () => {
+  test("committer procedure should extract owner/repo from git remote", async () => {
     const yamlContent = await readFile(workflowPath, "utf-8");
     const workflow = parse(yamlContent) as WorkflowPayload;
 
     const committerProcedure = workflow.roles.committer?.procedure;
     expect(committerProcedure).toBeDefined();
 
-    // Verify the procedure mentions repoRemote is provided in task prompt
-    expect(committerProcedure).toMatch(/repo remote.*provided.*task prompt/i);
-    expect(committerProcedure).toMatch(/owner\/repo/i);
+    // Verify the procedure extracts owner/repo from remote
+    expect(committerProcedure).toContain("git remote get-url origin");
+    expect(committerProcedure).toContain("hook_failed");
   });
 
   test("committer procedure should include error handling for curl failures", async () => {
@@ -100,45 +97,42 @@ describe("solve-issue workflow: Gitea API PR creation", () => {
     expect(committedVariant.required).toContain("$status");
   });
 
-  test("developer procedure should include mandatory verification step", async () => {
+  test("developer procedure should include worktree setup", async () => {
     const yamlContent = await readFile(workflowPath, "utf-8");
     const workflow = parse(yamlContent) as WorkflowPayload;
 
     const developerProcedure = workflow.roles.developer?.procedure;
     expect(developerProcedure).toBeDefined();
 
-    // Verify the procedure includes mandatory verification step
-    expect(developerProcedure).toContain("MANDATORY VERIFICATION");
-    expect(developerProcedure).toContain("git branch --show-current");
-    expect(developerProcedure).toContain("git status");
-    expect(developerProcedure).toMatch(/ls -la|verify.*exist/i);
+    // Verify the procedure includes worktree setup
+    expect(developerProcedure).toContain("IMPORTANT");
+    expect(developerProcedure).toContain("git worktree add");
+    expect(developerProcedure).toContain("pnpm install");
   });
 
-  test("reviewer procedure should enforce worktree path verification", async () => {
+  test("reviewer procedure should verify branch and run checks", async () => {
     const yamlContent = await readFile(workflowPath, "utf-8");
     const workflow = parse(yamlContent) as WorkflowPayload;
 
     const reviewerProcedure = workflow.roles.reviewer?.procedure;
     expect(reviewerProcedure).toBeDefined();
 
-    // Verify the procedure includes critical enforcement
-    expect(reviewerProcedure).toContain("CRITICAL");
-    expect(reviewerProcedure).toMatch(/cd.*pwd/);
-    expect(reviewerProcedure).toContain(
-      "Do NOT report results without running the actual commands",
-    );
+    // Verify the procedure includes branch verification and build checks
+    expect(reviewerProcedure).toContain("git branch --show-current");
+    expect(reviewerProcedure).toContain("pnpm run build");
+    expect(reviewerProcedure).toContain("pnpm run check");
   });
 
-  test("developer procedure should include test debugging escalation", async () => {
+  test("developer procedure should include changeset and failure handling", async () => {
     const yamlContent = await readFile(workflowPath, "utf-8");
     const workflow = parse(yamlContent) as WorkflowPayload;
 
     const developerProcedure = workflow.roles.developer?.procedure;
     expect(developerProcedure).toBeDefined();
 
-    // Verify the procedure includes test failure guidance
-    expect(developerProcedure).toMatch(/tests fail.*first run/i);
-    expect(developerProcedure).toMatch(/3 test cycles|after 3 attempts/i);
+    // Verify the procedure includes changeset requirement and failure path
+    expect(developerProcedure).toContain(".changeset/");
     expect(developerProcedure).toContain("$status=failed");
+    expect(developerProcedure).toContain("pnpm test");
   });
 });

packages/cli/src/__tests__/step-ask.test.ts

@@ -0,0 +1,670 @@
+import { execFileSync } from "node:child_process";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { bootstrap, putSchema } from "@ocas/core";
+import { openStore } from "@ocas/fs";
+import type { CasRef, ThreadId, ThreadIndexEntry } from "@united-workforce/protocol";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { registerUwfSchemas } from "../schemas.js";
+import { seedThreads } from "./thread-test-helpers.js";
+
+const OUTPUT_SCHEMA = {
+  type: "object" as const,
+  properties: {
+    $status: { type: "string" as const },
+    note: { type: "string" as const },
+  },
+  required: ["$status"],
+  additionalProperties: false,
+};
+
+const DETAIL_SCHEMA = {
+  title: "ask-detail",
+  type: "object" as const,
+  required: ["sessionId", "model", "duration", "turnCount", "turns"],
+  properties: {
+    sessionId: { type: "string" as const },
+    model: { type: "string" as const },
+    duration: { type: "integer" as const },
+    turnCount: { type: "integer" as const },
+    turns: {
+      type: "array" as const,
+      items: { type: "string" as const, format: "ocas_ref" },
+    },
+  },
+  additionalProperties: false,
+};
+
+const THREAD_ID = "01ASKSTEPTEST000000000" as ThreadId;
+const STEP_SESSION_ID = "ses-original-step-001";
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "cli-uwf-step-ask-test-"));
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+type SetupOpts = {
+  threadStatus: ThreadIndexEntry["status"];
+  withDetail: boolean;
+  // The agent name (path or alias) to record in the head StepNode.agent field.
+  // Defaults to mockAgentPath.
+  stepAgentNameOverride: string | null;
+  // Pre-cached fork session-id. When provided, the cache file is written
+  // before running so the test can verify reuse semantics.
+  preCachedForkSessionId: string | null;
+};
+
+type SetupResult = {
+  casDir: string;
+  stepHash: CasRef;
+  startHash: CasRef;
+  workflowHash: CasRef;
+  detailHash: CasRef | null;
+  mockAgentPath: string;
+  failingAgentPath: string;
+  promptCapturePath: string;
+  modeCapturePath: string;
+  forkSessionCapturePath: string;
+  askSessionCapturePath: string;
+  envCapturePath: string;
+};
+
+async function setupAskFixture(opts: Partial<SetupOpts> = {}): Promise<SetupResult> {
+  const cfg: SetupOpts = {
+    threadStatus: opts.threadStatus ?? "idle",
+    withDetail: opts.withDetail ?? true,
+    stepAgentNameOverride: opts.stepAgentNameOverride ?? null,
+    preCachedForkSessionId: opts.preCachedForkSessionId ?? null,
+  };
+
+  const casDir = join(tmpDir, "cas");
+  await mkdir(casDir, { recursive: true });
+
+  const store = await openStore(casDir);
+  await bootstrap(store);
+  const schemas = await registerUwfSchemas(store);
+  const outputSchemaHash = await putSchema(store, OUTPUT_SCHEMA);
+  const detailSchemaHash = await putSchema(store, DETAIL_SCHEMA);
+
+  const workflowHash = await store.cas.put(schemas.workflow, {
+    name: "test-ask",
+    description: "ask command integration test",
+    roles: {
+      worker: {
+        description: "Worker",
+        goal: "Work",
+        capabilities: [],
+        procedure: "work",
+        output: "result",
+        frontmatter: outputSchemaHash,
+      },
+    },
+    graph: {
+      $START: {
+        new: { role: "worker", prompt: "Start work", location: null },
+      },
+      worker: { ok: { role: "$END", prompt: "done", location: null } },
+    },
+  });
+
+  const startHash = await store.cas.put(schemas.startNode, {
+    workflow: workflowHash,
+    prompt: "Test ask task",
+    cwd: tmpDir,
+  });
+
+  // Set OCAS_HOME so seedThreads + in-test createUwfStore calls resolve to this CAS dir.
+  process.env.OCAS_HOME = casDir;
+
+  // Capture file paths
+  const promptCapturePath = join(tmpDir, "captured-prompt.txt");
+  const modeCapturePath = join(tmpDir, "captured-mode.txt");
+  const forkSessionCapturePath = join(tmpDir, "captured-fork-session.txt");
+  const askSessionCapturePath = join(tmpDir, "captured-ask-session.txt");
+  const envCapturePath = join(tmpDir, "captured-env.txt");
+  const mockAgentPath = join(tmpDir, "mock-agent.sh");
+  const failingAgentPath = join(tmpDir, "failing-agent.sh");
+
+  // Build a detail node with sessionId so step ask can extract it
+  let detailHash: CasRef | null = null;
+  if (cfg.withDetail) {
+    const turnHash = await store.cas.put(detailSchemaHash, {
+      sessionId: STEP_SESSION_ID,
+      model: "test-model",
+      duration: 1000,
+      turnCount: 0,
+      turns: [],
+    });
+    detailHash = turnHash;
+  }
+
+  // Build the StepNode at thread head
+  const outputHash = await store.cas.put(outputSchemaHash, { $status: "ok" });
+  const stepHash = await store.cas.put(schemas.stepNode, {
+    start: startHash,
+    prev: null,
+    role: "worker",
+    output: outputHash,
+    detail: detailHash,
+    agent: cfg.stepAgentNameOverride ?? mockAgentPath,
+    edgePrompt: "Start work",
+    startedAtMs: 1716600000000,
+    completedAtMs: 1716600001000,
+    cwd: tmpDir,
+    assembledPrompt: null,
+    usage: null,
+  });
+
+  // Seed thread index entry
+  await seedThreads(tmpDir, {
+    [THREAD_ID]: {
+      head: stepHash,
+      status: cfg.threadStatus,
+      suspendedRole: null,
+      suspendMessage: null,
+      completedAt: cfg.threadStatus === "completed" ? 1716600001000 : null,
+    },
+  });
+
+  // Pre-seed the ask session cache so reuse tests have something to find.
+  if (cfg.preCachedForkSessionId !== null) {
+    const cachePath = join(tmpDir, "cache", "mock-sessions.json");
+    await mkdir(dirname(cachePath), { recursive: true });
+    await writeFile(
+      cachePath,
+      `${JSON.stringify({ [`${stepHash}:ask`]: cfg.preCachedForkSessionId }, null, 2)}\n`,
+      "utf8",
+    );
+  }
+
+  // Mock agent: dispatches based on `--mode` (ask|fork|run) and captures inputs.
+  // - --mode ask --session <id> --prompt <text>: writes to ask capture; echoes a fixed answer to stdout
+  // - --mode fork --session <id>: writes to fork capture; prints "forked-from-<id>" sessionId on stdout
+  // - default (uwf-* style invocation): captures and echoes adapter JSON (not used in this suite)
+  await writeFile(
+    mockAgentPath,
+    `#!/bin/sh
+mode=""
+prompt=""
+session=""
+detail=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --mode) mode="$2"; shift 2 ;;
+    --prompt) prompt="$2"; shift 2 ;;
+    --session) session="$2"; shift 2 ;;
+    --detail) detail="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+printf '%s' "$mode" > '${modeCapturePath}'
+printf '%s' "$prompt" > '${promptCapturePath}'
+printf 'OCAS_HOME=%s\\n' "$OCAS_HOME" > '${envCapturePath}'
+case "$mode" in
+  fork)
+    printf '%s' "$session" > '${forkSessionCapturePath}'
+    new_id="forked-from-$session"
+    printf '%s\\n' "$new_id"
+    ;;
+  ask)
+    printf '%s' "$session" > '${askSessionCapturePath}'
+    # Print a deterministic answer that the cmdStepAsk path will hand back.
+    printf 'MOCK_ANSWER prompt=%s session=%s detail=%s\\n' "$prompt" "$session" "$detail"
+    ;;
+  *)
+    echo "{\\"stepHash\\":\\"unused\\"}"
+    ;;
+esac
+`,
+    { mode: 0o755 },
+  );
+
+  await writeFile(
+    failingAgentPath,
+    `#!/bin/sh
+echo "boom" >&2
+exit 7
+`,
+    { mode: 0o755 },
+  );
+
+  // Minimal config so loadWorkflowConfig succeeds.
+  const configPath = join(tmpDir, "config.yaml");
+  await writeFile(
+    configPath,
+    `defaultAgent: uwf-hermes\ndefaultModel: test-model\nagentOverrides: null\nagents: {}\nproviders: {}\nmodels: {}\n`,
+  );
+
+  return {
+    casDir,
+    stepHash,
+    startHash,
+    workflowHash,
+    detailHash,
+    mockAgentPath,
+    failingAgentPath,
+    promptCapturePath,
+    modeCapturePath,
+    forkSessionCapturePath,
+    askSessionCapturePath,
+    envCapturePath,
+  };
+}
+
+function runUwf(
+  args: string[],
+  casDir: string,
+): { stdout: string; stderr: string; status: number } {
+  const cliPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "dist", "cli.js");
+  try {
+    const stdout = execFileSync(process.execPath, [cliPath, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        UWF_HOME: tmpDir,
+        OCAS_HOME: casDir,
+      },
+      cwd: tmpDir,
+      timeout: 30000,
+    });
+    return { stdout, stderr: "", status: 0 };
+  } catch (error) {
+    const err = error as NodeJS.ErrnoException & {
+      stdout?: string | Buffer;
+      stderr?: string | Buffer;
+      status?: number;
+    };
+    return {
+      stdout: typeof err.stdout === "string" ? err.stdout : (err.stdout?.toString("utf8") ?? ""),
+      stderr: typeof err.stderr === "string" ? err.stderr : (err.stderr?.toString("utf8") ?? ""),
+      status: err.status ?? 1,
+    };
+  }
+}
+
+// ── Group 1: CLI argument validation ───────────────────────────────────────
+
+describe("uwf step ask - CLI argument validation", () => {
+  test("1.1 missing step-hash exits non-zero", async () => {
+    const { casDir } = await setupAskFixture();
+    const result = runUwf(["step", "ask"], casDir);
+    expect(result.status).not.toBe(0);
+  });
+
+  test("1.2 missing -p flag exits non-zero", async () => {
+    const { casDir, stepHash } = await setupAskFixture();
+    const result = runUwf(["step", "ask", stepHash], casDir);
+    expect(result.status).not.toBe(0);
+    expect(result.stderr.toLowerCase()).toMatch(/required|missing|prompt/);
+  });
+
+  test("1.3 step-hash and -p accepted as valid invocation", async () => {
+    const { casDir, stepHash, mockAgentPath } = await setupAskFixture();
+    const result = runUwf(
+      ["step", "ask", stepHash, "-p", "why?", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+  });
+});
+
+// ── Group 2: CAS validation errors ────────────────────────────────────────
+
+describe("uwf step ask - CAS validation errors", () => {
+  test("2.1 non-existent CAS hash exits non-zero with 'not found'", async () => {
+    const { casDir, mockAgentPath } = await setupAskFixture();
+    const result = runUwf(
+      ["step", "ask", "0000000000000", "-p", "why?", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).not.toBe(0);
+    expect(result.stderr.toLowerCase()).toContain("not found");
+  });
+
+  test("2.2 hash that is not a StepNode exits non-zero", async () => {
+    const { casDir, startHash, mockAgentPath } = await setupAskFixture();
+    // Use the StartNode hash — it exists but is not a StepNode
+    const result = runUwf(
+      ["step", "ask", startHash, "-p", "why?", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).not.toBe(0);
+    expect(result.stderr.toLowerCase()).toContain("not a stepnode");
+  });
+
+  test("2.3 step with no detail ref exits non-zero", async () => {
+    const { casDir, stepHash, mockAgentPath } = await setupAskFixture({ withDetail: false });
+    const result = runUwf(
+      ["step", "ask", stepHash, "-p", "why?", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).not.toBe(0);
+    expect(result.stderr.toLowerCase()).toMatch(/no detail|detail.*missing|missing.*detail/);
+  });
+});
+
+// ── Group 3: Successful ask (core behavior) ───────────────────────────────
+
+describe("uwf step ask - successful ask (core)", () => {
+  test("3.1 stdout contains agent's response text", async () => {
+    const { casDir, stepHash, mockAgentPath } = await setupAskFixture();
+    const result = runUwf(
+      ["step", "ask", stepHash, "-p", "why tar not zip?", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain("MOCK_ANSWER");
+    expect(result.stdout).toContain("why tar not zip?");
+  });
+
+  test("3.2 thread index entry (head, status) is identical before and after ask", async () => {
+    const { casDir, stepHash, mockAgentPath } = await setupAskFixture();
+
+    // Before ask: snapshot the thread state
+    const { createUwfStore, getThread } = await import("../store.js");
+    const before = await createUwfStore(tmpDir);
+    const beforeEntry = getThread(before.varStore, THREAD_ID);
+    expect(beforeEntry).not.toBeNull();
+
+    const result = runUwf(
+      ["step", "ask", stepHash, "-p", "anything", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+
+    // After ask: thread state should be unchanged
+    const after = await createUwfStore(tmpDir);
+    const afterEntry = getThread(after.varStore, THREAD_ID);
+    expect(afterEntry).not.toBeNull();
+    expect(afterEntry?.head).toBe(beforeEntry?.head);
+    expect(afterEntry?.status).toBe(beforeEntry?.status);
+  });
+
+  test("3.3 no new StepNode is written to CAS (step count unchanged)", async () => {
+    const { casDir, stepHash, mockAgentPath } = await setupAskFixture();
+
+    // Count StepNodes before
+    const { createUwfStore } = await import("../store.js");
+    const before = await createUwfStore(tmpDir);
+    const stepSchemaHash = before.schemas.stepNode;
+
+    function countStepNodes(uwfStore: typeof before): number {
+      const candidates = [stepHash];
+      let count = 0;
+      for (const h of candidates) {
+        const node = uwfStore.store.cas.get(h);
+        if (node !== null && node.type === stepSchemaHash) count++;
+      }
+      return count;
+    }
+
+    const beforeCount = countStepNodes(before);
+    expect(beforeCount).toBe(1);
+
+    const result = runUwf(
+      ["step", "ask", stepHash, "-p", "anything", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+
+    // After ask: still only the seeded StepNode exists at head; no new step appended.
+    const after = await createUwfStore(tmpDir);
+    const headNode = after.store.cas.get(stepHash);
+    expect(headNode).not.toBeNull();
+    expect(headNode?.type).toBe(after.schemas.stepNode);
+
+    // Confirm thread head still points to the original step hash
+    const { getThread } = await import("../store.js");
+    const entry = getThread(after.varStore, THREAD_ID);
+    expect(entry?.head).toBe(stepHash);
+  });
+});
+
+// ── Group 4: Fork cache semantics ─────────────────────────────────────────
+
+describe("uwf step ask - fork cache", () => {
+  test("4.1 first ask creates a fork session and caches it", async () => {
+    const { casDir, stepHash, mockAgentPath, forkSessionCapturePath } = await setupAskFixture();
+
+    const result = runUwf(
+      ["step", "ask", stepHash, "-p", "first ask", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+
+    // The mock agent in fork mode receives the source session id
+    const forkArg = await readFile(forkSessionCapturePath, "utf8");
+    expect(forkArg).toBe(STEP_SESSION_ID);
+
+    // Cache file should now contain the ask key
+    const cachePath = join(tmpDir, "cache", "mock-sessions.json");
+    const raw = await readFile(cachePath, "utf8");
+    const parsed = JSON.parse(raw) as Record<string, string>;
+    expect(parsed[`${stepHash}:ask`]).toBeDefined();
+    expect(parsed[`${stepHash}:ask`]).toBe(`forked-from-${STEP_SESSION_ID}`);
+  });
+
+  test("4.2 second ask on same step reuses the cached fork session", async () => {
+    const cachedFork = "ses-already-forked-once";
+    const { casDir, stepHash, mockAgentPath, modeCapturePath, askSessionCapturePath } =
+      await setupAskFixture({ preCachedForkSessionId: cachedFork });
+
+    const result = runUwf(
+      ["step", "ask", stepHash, "-p", "second ask", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+
+    // The mock agent must have been invoked in `ask` mode (no fork performed).
+    const mode = await readFile(modeCapturePath, "utf8");
+    expect(mode).toBe("ask");
+
+    // The ask invocation should have received the cached fork session id.
+    const askArg = await readFile(askSessionCapturePath, "utf8");
+    expect(askArg).toBe(cachedFork);
+  });
+
+  test("4.3 different step hash creates an independent fork", async () => {
+    // Run a first ask on the base step → caches forkA
+    const { casDir, stepHash, mockAgentPath } = await setupAskFixture();
+
+    const r1 = runUwf(
+      ["step", "ask", stepHash, "-p", "ask on step A", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(r1.status).toBe(0);
+
+    // Build a second StepNode (different hash) with a different sessionId so
+    // its detail-derived ask session is independent of the first.
+    const { createUwfStore } = await import("../store.js");
+    const uwf = await createUwfStore(tmpDir);
+    const detailSchemaHash = await putSchema(uwf.store, DETAIL_SCHEMA);
+    const outputSchemaHash = await putSchema(uwf.store, OUTPUT_SCHEMA);
+    const otherDetailHash = await uwf.store.cas.put(detailSchemaHash, {
+      sessionId: "ses-original-step-002",
+      model: "test-model",
+      duration: 1000,
+      turnCount: 0,
+      turns: [],
+    });
+    const otherOutputHash = await uwf.store.cas.put(outputSchemaHash, {
+      $status: "ok",
+      note: "alt",
+    });
+
+    // Reuse the same start ref the first step points to so the new step is a valid sibling.
+    const head = uwf.store.cas.get(stepHash);
+    const startRefFromHead = (head?.payload as { start: CasRef }).start;
+    const properOtherStep = await uwf.store.cas.put(uwf.schemas.stepNode, {
+      start: startRefFromHead,
+      prev: null,
+      role: "worker",
+      output: otherOutputHash,
+      detail: otherDetailHash,
+      agent: mockAgentPath,
+      edgePrompt: "Start work",
+      startedAtMs: 1716600002000,
+      completedAtMs: 1716600003000,
+      cwd: tmpDir,
+      assembledPrompt: null,
+      usage: null,
+    });
+
+    // sanity check we constructed a separate hash
+    expect(properOtherStep).not.toBe(stepHash);
+
+    const r2 = runUwf(
+      ["step", "ask", properOtherStep, "-p", "ask on step B", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(r2.status).toBe(0);
+
+    const cachePath = join(tmpDir, "cache", "mock-sessions.json");
+    const raw = await readFile(cachePath, "utf8");
+    const parsed = JSON.parse(raw) as Record<string, string>;
+    expect(parsed[`${stepHash}:ask`]).toBeDefined();
+    expect(parsed[`${properOtherStep}:ask`]).toBeDefined();
+    expect(parsed[`${stepHash}:ask`]).not.toBe(parsed[`${properOtherStep}:ask`]);
+  });
+});
+
+// ── Group 5: Fallback (agent has no fork support) ─────────────────────────
+
+describe("uwf step ask - fallback path", () => {
+  test("5.1 fallback agent (no fork support) still answers via stdout", async () => {
+    // Use a fallback agent that ONLY supports `ask` mode without ever being asked
+    // to fork. The CLI should detect missing fork support and inject context instead.
+    const { casDir, stepHash, mockAgentPath } = await setupAskFixture();
+
+    // Create a fallback agent script that fails with non-zero exit on "fork" mode.
+    // Fallback path must NOT call mode=fork; it should call mode=ask directly.
+    const fallbackPath = join(tmpDir, "fallback-agent.sh");
+    const promptCapture = join(tmpDir, "fallback-prompt.txt");
+    const sessionCapture = join(tmpDir, "fallback-session.txt");
+    const modeCapture = join(tmpDir, "fallback-mode.txt");
+    await writeFile(
+      fallbackPath,
+      `#!/bin/sh
+mode=""
+prompt=""
+session=""
+detail=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --mode) mode="$2"; shift 2 ;;
+    --prompt) prompt="$2"; shift 2 ;;
+    --session) session="$2"; shift 2 ;;
+    --detail) detail="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+printf '%s' "$mode" > '${modeCapture}'
+printf '%s' "$prompt" > '${promptCapture}'
+printf '%s' "$session" > '${sessionCapture}'
+case "$mode" in
+  fork) echo "fork not supported" >&2; exit 99 ;;
+  ask) printf 'FALLBACK_ANSWER for: %s (detail=%s)\\n' "$prompt" "$detail" ;;
+  *) echo "unknown" >&2; exit 1 ;;
+esac
+`,
+      { mode: 0o755 },
+    );
+
+    const result = runUwf(
+      ["step", "ask", stepHash, "-p", "explain context", "--agent", fallbackPath, "--no-fork"],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain("FALLBACK_ANSWER");
+    expect(result.stdout).toContain("explain context");
+
+    // The fallback agent should be invoked in `ask` mode, with NO session id
+    // (since no fork happened). The detail ref must be passed for context injection.
+    const mode = await readFile(modeCapture, "utf8");
+    expect(mode).toBe("ask");
+    const session = await readFile(sessionCapture, "utf8");
+    expect(session).toBe("");
+
+    // Make sure mockAgentPath's mock never ran.
+    void mockAgentPath;
+  });
+
+  test("5.2 fallback ask still does NOT mutate thread state", async () => {
+    const { casDir, stepHash } = await setupAskFixture();
+
+    const fallbackPath = join(tmpDir, "fallback-agent.sh");
+    await writeFile(
+      fallbackPath,
+      `#!/bin/sh
+mode=""
+prompt=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --mode) mode="$2"; shift 2 ;;
+    --prompt) prompt="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+case "$mode" in
+  fork) echo "fork not supported" >&2; exit 99 ;;
+  ask) printf 'OK %s\\n' "$prompt" ;;
+  *) exit 1 ;;
+esac
+`,
+      { mode: 0o755 },
+    );
+
+    const { createUwfStore, getThread } = await import("../store.js");
+    const before = await createUwfStore(tmpDir);
+    const beforeEntry = getThread(before.varStore, THREAD_ID);
+
+    const result = runUwf(
+      ["step", "ask", stepHash, "-p", "any", "--agent", fallbackPath, "--no-fork"],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+
+    const after = await createUwfStore(tmpDir);
+    const afterEntry = getThread(after.varStore, THREAD_ID);
+    expect(afterEntry?.head).toBe(beforeEntry?.head);
+    expect(afterEntry?.status).toBe(beforeEntry?.status);
+  });
+});
+
+// ── Group 6: Agent resolution ─────────────────────────────────────────────
+
+describe("uwf step ask - agent resolution", () => {
+  test("6.1 without --agent flag, agent is resolved from step's agent field", async () => {
+    // Step's agent field points at mockAgentPath by default.
+    const { casDir, stepHash, modeCapturePath, promptCapturePath } = await setupAskFixture();
+    const result = runUwf(["step", "ask", stepHash, "-p", "explain"], casDir);
+    expect(result.status).toBe(0);
+
+    // The mockAgentPath must have been invoked in ask mode with the user prompt.
+    const mode = await readFile(modeCapturePath, "utf8");
+    expect(mode).toBe("ask");
+    const captured = await readFile(promptCapturePath, "utf8");
+    expect(captured).toBe("explain");
+  });
+
+  test("6.2 --agent override beats step's recorded agent", async () => {
+    // Record a non-existent agent in step.agent. Provide a working one via --agent.
+    const { casDir, stepHash, mockAgentPath } = await setupAskFixture({
+      stepAgentNameOverride: "uwf-does-not-exist",
+    });
+    const result = runUwf(
+      ["step", "ask", stepHash, "-p", "explain", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain("MOCK_ANSWER");
+  });
+});

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

@@ -167,7 +167,7 @@ describe("cmdThreadList status filter", () => {
     expect(result[0]?.status).toBe("completed");
   });
 
-  test("should return all threads when no status filter provided", async () => {
+  test("should return only active threads when no filter and no --all", async () => {
     const uwf = await makeUwfStore(tmpDir);
     const workflowHash = await createTestWorkflow(uwf);
 
@@ -185,8 +185,290 @@ describe("cmdThreadList status filter", () => {
 
     const result = await cmdThreadList(tmpDir, null, null, null, null, null);
 
+    // Default behavior (issue #147): only active threads (idle + running)
+    expect(result).toHaveLength(2);
+    expect(result.map((r) => r.thread).sort()).toEqual([thread1, thread2].sort());
+
+    // Clean up marker
+    await deleteMarker(tmpDir, thread2);
+  });
+
+  test("should return all threads when --all (showAll=true)", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const thread1 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 3000);
+    const thread2 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    const thread3 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+
+    await markThreadRunning(tmpDir, thread2, workflowHash);
+
+    const uwfIdx = await createUwfStore(tmpDir);
+    const index = loadAllThreads(uwfIdx.varStore);
+    const thread3Head = index[thread3]!.head;
+    if (thread3Head === undefined) throw new Error("thread3 head not found");
+    await completeThread(tmpDir, thread3, workflowHash, thread3Head);
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null, true);
+
     expect(result).toHaveLength(3);
     expect(result.map((r) => r.thread).sort()).toEqual([thread1, thread2, thread3].sort());
+
+    // Clean up marker
+    await deleteMarker(tmpDir, thread2);
+  });
+});
+
+// ── default behavior tests (issue #147) ───────────────────────────────────────
+
+describe("cmdThreadList default behavior (issue #147)", () => {
+  test("default returns only idle + running threads", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const threadA = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 4000);
+    const threadB = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 3000);
+    const threadC = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    const threadD = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+
+    await markThreadRunning(tmpDir, threadB, workflowHash);
+
+    const uwfIdx = await createUwfStore(tmpDir);
+    const index = loadAllThreads(uwfIdx.varStore);
+    const threadCHead = index[threadC]!.head;
+    if (threadCHead === undefined) throw new Error("threadC head not found");
+    await completeThread(tmpDir, threadC, workflowHash, threadCHead);
+
+    // Cancel threadD
+    const threadDHead = index[threadD]!.head;
+    if (threadDHead === undefined) throw new Error("threadD head not found");
+    const uwfCancel = await createUwfStore(tmpDir);
+    completeThreadInStore(uwfCancel.varStore, threadD, "cancelled");
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null);
+
+    expect(result).toHaveLength(2);
+    expect(result.map((r) => r.thread).sort()).toEqual([threadA, threadB].sort());
+
+    await deleteMarker(tmpDir, threadB);
+  });
+
+  test("default excludes completed threads", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const idleThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 6000);
+    const completedThreads: ThreadId[] = [];
+    for (let i = 0; i < 5; i++) {
+      const t = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - (5 - i) * 1000);
+      completedThreads.push(t);
+      const uwfIdx = await createUwfStore(tmpDir);
+      const index = loadAllThreads(uwfIdx.varStore);
+      const head = index[t]!.head;
+      if (head === undefined) throw new Error("head not found");
+      await completeThread(tmpDir, t, workflowHash, head);
+    }
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.thread).toBe(idleThread);
+  });
+
+  test("default excludes cancelled threads", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const runningThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 4000);
+    await markThreadRunning(tmpDir, runningThread, workflowHash);
+
+    const cancelled: ThreadId[] = [];
+    for (let i = 0; i < 3; i++) {
+      const t = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - (3 - i) * 1000);
+      cancelled.push(t);
+      const uwfIdx = await createUwfStore(tmpDir);
+      completeThreadInStore(uwfIdx.varStore, t, "cancelled");
+    }
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.thread).toBe(runningThread);
+
+    await deleteMarker(tmpDir, runningThread);
+  });
+
+  test("--all (showAll=true) returns every status", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const idleThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 4000);
+    const runningThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 3000);
+    await markThreadRunning(tmpDir, runningThread, workflowHash);
+
+    const completedThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    const uwfIdx = await createUwfStore(tmpDir);
+    const idx = loadAllThreads(uwfIdx.varStore);
+    const ch = idx[completedThread]!.head;
+    if (ch === undefined) throw new Error("completedThread head not found");
+    await completeThread(tmpDir, completedThread, workflowHash, ch);
+
+    const cancelledThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+    completeThreadInStore(uwfIdx.varStore, cancelledThread, "cancelled");
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null, true);
+
+    expect(result).toHaveLength(4);
+    expect(result.map((r) => r.thread).sort()).toEqual(
+      [idleThread, runningThread, completedThread, cancelledThread].sort(),
+    );
+
+    await deleteMarker(tmpDir, runningThread);
+  });
+
+  test("explicit --status overrides default (still returns just the filtered statuses)", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const _idleThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 3000);
+    const runningThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    await markThreadRunning(tmpDir, runningThread, workflowHash);
+
+    const completedThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+    const uwfIdx = await createUwfStore(tmpDir);
+    const idx = loadAllThreads(uwfIdx.varStore);
+    const ch = idx[completedThread]!.head;
+    if (ch === undefined) throw new Error("completedThread head not found");
+    await completeThread(tmpDir, completedThread, workflowHash, ch);
+
+    const result = await cmdThreadList(tmpDir, ["completed"], null, null, null, null);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.thread).toBe(completedThread);
+    expect(result[0]?.status).toBe("completed");
+
+    await deleteMarker(tmpDir, runningThread);
+  });
+
+  test("--status active keeps working", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const idleThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 3000);
+    const runningThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    await markThreadRunning(tmpDir, runningThread, workflowHash);
+
+    const completedThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+    const uwfIdx = await createUwfStore(tmpDir);
+    const idx = loadAllThreads(uwfIdx.varStore);
+    const ch = idx[completedThread]!.head;
+    if (ch === undefined) throw new Error("completedThread head not found");
+    await completeThread(tmpDir, completedThread, workflowHash, ch);
+
+    const result = await cmdThreadList(tmpDir, ["idle", "running"], null, null, null, null);
+
+    expect(result).toHaveLength(2);
+    expect(result.map((r) => r.thread).sort()).toEqual([idleThread, runningThread].sort());
+
+    await deleteMarker(tmpDir, runningThread);
+  });
+
+  test("--status + --all — explicit status wins", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const _idleThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 3000);
+    const runningThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    await markThreadRunning(tmpDir, runningThread, workflowHash);
+
+    const completedThread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+    const uwfIdx = await createUwfStore(tmpDir);
+    const idx = loadAllThreads(uwfIdx.varStore);
+    const ch = idx[completedThread]!.head;
+    if (ch === undefined) throw new Error("completedThread head not found");
+    await completeThread(tmpDir, completedThread, workflowHash, ch);
+
+    const result = await cmdThreadList(tmpDir, ["completed"], null, null, null, null, true);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.thread).toBe(completedThread);
+
+    await deleteMarker(tmpDir, runningThread);
+  });
+
+  test("default returns empty when no threads", async () => {
+    await makeUwfStore(tmpDir);
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null);
+
+    expect(result).toHaveLength(0);
+  });
+
+  test("default + time range filter composes correctly", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const ts1 = Date.UTC(2026, 4, 20, 0, 0, 0);
+    const ts2 = Date.UTC(2026, 4, 21, 0, 0, 0);
+    const ts3 = Date.UTC(2026, 4, 22, 0, 0, 0);
+    const ts4 = Date.UTC(2026, 4, 23, 0, 0, 0);
+    const ts5 = Date.UTC(2026, 4, 24, 0, 0, 0);
+
+    const _t1 = await createTestThread(uwf, tmpDir, workflowHash, ts1);
+    const t2 = await createTestThread(uwf, tmpDir, workflowHash, ts2);
+    const t3 = await createTestThread(uwf, tmpDir, workflowHash, ts3);
+    const t4 = await createTestThread(uwf, tmpDir, workflowHash, ts4);
+    const _t5 = await createTestThread(uwf, tmpDir, workflowHash, ts5);
+
+    // Mark t3 running
+    await markThreadRunning(tmpDir, t3, workflowHash);
+
+    // Complete t4 (should be excluded by default)
+    const uwfIdx = await createUwfStore(tmpDir);
+    const idx = loadAllThreads(uwfIdx.varStore);
+    const t4head = idx[t4]!.head;
+    if (t4head === undefined) throw new Error("t4 head not found");
+    await completeThread(tmpDir, t4, workflowHash, t4head);
+
+    // afterMs in middle of range to exclude _t1
+    const afterMs = Date.UTC(2026, 4, 20, 12, 0, 0);
+    const result = await cmdThreadList(tmpDir, null, afterMs, null, null, null);
+
+    // Expected: t2 (idle), t3 (running), _t5 (idle); excludes t4 (completed) and _t1 (filtered by time)
+    expect(result).toHaveLength(3);
+    const ids = result.map((r) => r.thread).sort();
+    expect(ids).toEqual([t2, t3, _t5].sort());
+
+    await deleteMarker(tmpDir, t3);
+  });
+
+  test("default + pagination composes correctly", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    // Create 10 idle threads + 5 completed threads
+    const idleThreads: ThreadId[] = [];
+    for (let i = 0; i < 10; i++) {
+      idleThreads.push(
+        await createTestThread(uwf, tmpDir, workflowHash, Date.now() - (15 - i) * 1000),
+      );
+    }
+    for (let i = 0; i < 5; i++) {
+      const t = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - (5 - i) * 1000);
+      const uwfIdx = await createUwfStore(tmpDir);
+      const idx = loadAllThreads(uwfIdx.varStore);
+      const head = idx[t]!.head;
+      if (head === undefined) throw new Error("head not found");
+      await completeThread(tmpDir, t, workflowHash, head);
+    }
+
+    const result = await cmdThreadList(tmpDir, null, null, null, 2, 3);
+
+    expect(result).toHaveLength(3);
+    // All results should be idle (default excludes completed)
+    for (const r of result) {
+      expect(r.status).toBe("idle");
+    }
   });
 });
 

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

@@ -0,0 +1,549 @@
+import { execFileSync } from "node:child_process";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { putSchema } from "@ocas/core";
+import { openStore } from "@ocas/fs";
+import type {
+  CasRef,
+  StepNodePayload,
+  ThreadId,
+  ThreadIndexEntry,
+} from "@united-workforce/protocol";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { registerUwfSchemas } from "../schemas.js";
+import { seedThreads } from "./thread-test-helpers.js";
+
+const OUTPUT_SCHEMA = {
+  type: "object" as const,
+  properties: {
+    $status: { type: "string" as const },
+    note: { type: "string" as const },
+  },
+  required: ["$status"],
+  additionalProperties: false,
+};
+
+const THREAD_ID = "01POKESTEPTEST00000000" as ThreadId;
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "cli-uwf-poke-test-"));
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+type SetupResult = {
+  casDir: string;
+  oldStepHash: CasRef;
+  oldStepPrev: CasRef | null;
+  oldStepCompletedAtMs: number;
+  startHash: CasRef;
+  workflowHash: CasRef;
+  mockAgentPath: string;
+  failingAgentPath: string;
+  promptCapturePath: string;
+  envCapturePath: string;
+};
+
+type SetupOpts = {
+  threadStatus: ThreadIndexEntry["status"];
+  multipleSteps: boolean;
+  newCompletedAtMs: number;
+  newStatus: string;
+  // The agent name to record in the head StepNode.agent field. Defaults to mockAgentPath.
+  stepAgentNameOverride: string | null;
+  // Whether to seed an actual head StepNode (false → only StartNode is the head).
+  withHeadStep: boolean;
+};
+
+async function setupThread(opts: Partial<SetupOpts> = {}): Promise<SetupResult> {
+  const cfg: SetupOpts = {
+    threadStatus: opts.threadStatus ?? "idle",
+    multipleSteps: opts.multipleSteps ?? false,
+    newCompletedAtMs: opts.newCompletedAtMs ?? 1716600005000,
+    newStatus: opts.newStatus ?? "ok",
+    stepAgentNameOverride: opts.stepAgentNameOverride ?? null,
+    withHeadStep: opts.withHeadStep ?? true,
+  };
+
+  const casDir = join(tmpDir, "cas");
+  await mkdir(casDir, { recursive: true });
+
+  const store = await openStore(casDir);
+  const schemas = await registerUwfSchemas(store);
+  const outputSchemaHash = await putSchema(store, OUTPUT_SCHEMA);
+
+  const workflowHash = await store.cas.put(schemas.workflow, {
+    name: "test-poke",
+    description: "poke command integration test",
+    roles: {
+      worker: {
+        description: "Worker role",
+        goal: "Work",
+        capabilities: [],
+        procedure: "work",
+        output: "result",
+        frontmatter: outputSchemaHash,
+      },
+      reviewer: {
+        description: "Reviewer role",
+        goal: "Review",
+        capabilities: [],
+        procedure: "review",
+        output: "result",
+        frontmatter: outputSchemaHash,
+      },
+    },
+    graph: {
+      $START: {
+        new: { role: "worker", prompt: "Start work", location: null },
+        resume: { role: "worker", prompt: "Resume the work", location: null },
+      },
+      worker: {
+        ok: { role: "reviewer", prompt: "Review the work", location: null },
+        needs_input: {
+          role: "$SUSPEND",
+          prompt: "Please clarify",
+          location: null,
+        },
+      },
+      reviewer: { done: { role: "$END", prompt: "Done", location: null } },
+    },
+  });
+
+  const startHash = await store.cas.put(schemas.startNode, {
+    workflow: workflowHash,
+    prompt: "Test poke task",
+    cwd: tmpDir,
+  });
+
+  process.env.OCAS_HOME = casDir;
+
+  // Paths for mock agent and capture files (set early so we can use mockAgentPath as the recorded agent name)
+  const promptCapturePath = join(tmpDir, "captured-prompt.txt");
+  const envCapturePath = join(tmpDir, "captured-env.txt");
+  const mockAgentPath = join(tmpDir, "mock-agent.sh");
+  const failingAgentPath = join(tmpDir, "failing-agent.sh");
+
+  // Build head StepNode chain
+  let oldStepPrev: CasRef | null = null;
+  if (cfg.multipleSteps) {
+    // First step: prev=null
+    const firstOutputHash = await store.cas.put(outputSchemaHash, { $status: "ok" });
+    const firstDetailHash = await store.cas.put(schemas.text, "first detail");
+    const firstStepHash = await store.cas.put(schemas.stepNode, {
+      start: startHash,
+      prev: null,
+      role: "worker",
+      output: firstOutputHash,
+      detail: firstDetailHash,
+      agent: cfg.stepAgentNameOverride ?? mockAgentPath,
+      edgePrompt: "Start work",
+      startedAtMs: 1716600000000,
+      completedAtMs: 1716600001000,
+      cwd: tmpDir,
+      assembledPrompt: null,
+      usage: null,
+    });
+    oldStepPrev = firstStepHash;
+  }
+
+  let oldStepHash: CasRef = startHash;
+  const oldStepCompletedAtMs = 1716600002000;
+  if (cfg.withHeadStep) {
+    const outputHash = await store.cas.put(outputSchemaHash, { $status: "ok" });
+    const detailHash = await store.cas.put(schemas.text, "head step detail");
+    oldStepHash = await store.cas.put(schemas.stepNode, {
+      start: startHash,
+      prev: oldStepPrev,
+      role: "worker",
+      output: outputHash,
+      detail: detailHash,
+      agent: cfg.stepAgentNameOverride ?? mockAgentPath,
+      edgePrompt: "Start work",
+      startedAtMs: 1716600001500,
+      completedAtMs: oldStepCompletedAtMs,
+      cwd: tmpDir,
+      assembledPrompt: null,
+      usage: null,
+    });
+  }
+
+  // Seed thread index entry. For "running" we let the test create the marker separately.
+  await seedThreads(tmpDir, {
+    [THREAD_ID]: {
+      head: oldStepHash,
+      status: cfg.threadStatus,
+      suspendedRole: cfg.threadStatus === "suspended" ? "worker" : null,
+      suspendMessage: cfg.threadStatus === "suspended" ? "Please clarify" : null,
+      completedAt:
+        cfg.threadStatus === "completed" || cfg.threadStatus === "cancelled"
+          ? oldStepCompletedAtMs
+          : null,
+    },
+  });
+
+  // Mock agent always emits a stepNode keyed off the current thread head (which we
+  // observe through OCAS_HOME). The script writes prompt/env captures and then prints
+  // an adapter JSON that references a pre-built stepHash.
+  // We pre-build the agent's stepHash with prev=oldStepHash (normal append behaviour).
+  const newOutputHash = await store.cas.put(outputSchemaHash, {
+    $status: cfg.newStatus,
+    note: "poked output",
+  });
+  const newDetailHash = await store.cas.put(schemas.text, "poked detail");
+  const agentStepHash = await store.cas.put(schemas.stepNode, {
+    start: startHash,
+    prev: cfg.withHeadStep ? oldStepHash : null,
+    role: "worker",
+    output: newOutputHash,
+    detail: newDetailHash,
+    agent: "mock-agent-output",
+    edgePrompt: "poke prompt placeholder",
+    startedAtMs: cfg.newCompletedAtMs - 100,
+    completedAtMs: cfg.newCompletedAtMs,
+    cwd: tmpDir,
+    assembledPrompt: null,
+    usage: null,
+  });
+
+  const adapterJson = JSON.stringify({
+    stepHash: agentStepHash,
+    detailHash: newDetailHash,
+    role: "worker",
+    frontmatter: { $status: cfg.newStatus, note: "poked output" },
+    body: "",
+    startedAtMs: cfg.newCompletedAtMs - 100,
+    completedAtMs: cfg.newCompletedAtMs,
+    usage: null,
+  });
+
+  await writeFile(
+    mockAgentPath,
+    `#!/bin/sh
+prompt=""
+while [ $# -gt 0 ]; do
+  if [ "$1" = "--prompt" ]; then
+    prompt="$2"
+    shift 2
+  else
+    shift
+  fi
+done
+printf '%s' "$prompt" > '${promptCapturePath}'
+printf 'OCAS_HOME=%s\\n' "$OCAS_HOME" > '${envCapturePath}'
+echo '${adapterJson}'
+`,
+    { mode: 0o755 },
+  );
+
+  await writeFile(
+    failingAgentPath,
+    `#!/bin/sh
+echo "boom" >&2
+exit 7
+`,
+    { mode: 0o755 },
+  );
+
+  const configPath = join(tmpDir, "config.yaml");
+  await writeFile(
+    configPath,
+    `defaultAgent: uwf-hermes\ndefaultModel: test-model\nagentOverrides: null\nagents: {}\nproviders: {}\nmodels: {}\n`,
+  );
+
+  return {
+    casDir,
+    oldStepHash,
+    oldStepPrev,
+    oldStepCompletedAtMs,
+    startHash,
+    workflowHash,
+    mockAgentPath,
+    failingAgentPath,
+    promptCapturePath,
+    envCapturePath,
+  };
+}
+
+function runUwf(
+  args: string[],
+  casDir: string,
+): { stdout: string; stderr: string; status: number } {
+  const cliPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "dist", "cli.js");
+  try {
+    const stdout = execFileSync(process.execPath, [cliPath, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        UWF_HOME: tmpDir,
+        OCAS_HOME: casDir,
+      },
+      cwd: tmpDir,
+      timeout: 30000,
+    });
+    return { stdout, stderr: "", status: 0 };
+  } catch (error) {
+    const err = error as NodeJS.ErrnoException & {
+      stdout?: string | Buffer;
+      stderr?: string | Buffer;
+      status?: number;
+    };
+    return {
+      stdout: typeof err.stdout === "string" ? err.stdout : (err.stdout?.toString("utf8") ?? ""),
+      stderr: typeof err.stderr === "string" ? err.stderr : (err.stderr?.toString("utf8") ?? ""),
+      status: err.status ?? 1,
+    };
+  }
+}
+
+// ── Group 1: CLI argument validation ───────────────────────────────────────
+
+describe("uwf thread poke - CLI argument validation", () => {
+  test("1.1 missing -p flag exits non-zero", async () => {
+    const { casDir } = await setupThread();
+    const result = runUwf(["thread", "poke", THREAD_ID], casDir);
+    expect(result.status).not.toBe(0);
+    expect(result.stderr.toLowerCase()).toMatch(/required|missing|prompt/);
+  });
+
+  test("1.2 -p without --agent succeeds", async () => {
+    const { casDir } = await setupThread();
+    const result = runUwf(["thread", "poke", THREAD_ID, "-p", "do it again"], casDir);
+    expect(result.status).toBe(0);
+  });
+
+  test("1.3 -p with --agent succeeds", async () => {
+    const { casDir, mockAgentPath } = await setupThread();
+    const result = runUwf(
+      ["thread", "poke", THREAD_ID, "-p", "do it again", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+  });
+});
+
+// ── Group 2: Guard errors ──────────────────────────────────────────────────
+
+describe("uwf thread poke - guard errors", () => {
+  test("2.1 thread not found", async () => {
+    const { casDir } = await setupThread();
+    const result = runUwf(["thread", "poke", "01NOSUCHTHREAD0000000A", "-p", "prompt"], casDir);
+    expect(result.status).not.toBe(0);
+    expect(result.stderr.toLowerCase()).toMatch(/not found|not active/);
+  });
+
+  test("2.2 thread running rejects poke", async () => {
+    const { casDir, workflowHash } = await setupThread();
+    // Create background marker to simulate running
+    const { createMarker } = await import("../background/index.js");
+    await createMarker(tmpDir, {
+      thread: THREAD_ID,
+      workflow: workflowHash,
+      pid: process.pid,
+      startedAt: Date.now(),
+    });
+
+    const result = runUwf(["thread", "poke", THREAD_ID, "-p", "prompt"], casDir);
+    expect(result.status).not.toBe(0);
+    expect(result.stderr.toLowerCase()).toContain("already executing");
+  });
+
+  test("2.3 completed thread rejects poke", async () => {
+    const { casDir } = await setupThread({ threadStatus: "completed" });
+    const result = runUwf(["thread", "poke", THREAD_ID, "-p", "prompt"], casDir);
+    expect(result.status).not.toBe(0);
+    expect(result.stderr.toLowerCase()).toMatch(/cannot be poked|completed/);
+  });
+
+  test("2.4 cancelled thread rejects poke", async () => {
+    const { casDir } = await setupThread({ threadStatus: "cancelled" });
+    const result = runUwf(["thread", "poke", THREAD_ID, "-p", "prompt"], casDir);
+    expect(result.status).not.toBe(0);
+    expect(result.stderr.toLowerCase()).toMatch(/cannot be poked|cancelled/);
+  });
+
+  test("2.5 thread head is StartNode (no StepNode) rejects poke", async () => {
+    const { casDir } = await setupThread({ withHeadStep: false });
+    const result = runUwf(["thread", "poke", THREAD_ID, "-p", "prompt"], casDir);
+    expect(result.status).not.toBe(0);
+    expect(result.stderr.toLowerCase()).toMatch(/no step|cannot be poked/);
+  });
+});
+
+// ── Group 3: Success happy path ────────────────────────────────────────────
+
+describe("uwf thread poke - success", () => {
+  test("3.1, 3.4 idle thread → new head differs from old, thread index updated", async () => {
+    const { casDir, oldStepHash, mockAgentPath } = await setupThread();
+    const result = runUwf(
+      ["thread", "poke", THREAD_ID, "-p", "redo", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+    const cliOutput = JSON.parse(result.stdout.trim());
+    expect(cliOutput.head).not.toBe(oldStepHash);
+
+    const { createUwfStore, getThread } = await import("../store.js");
+    const uwf = await createUwfStore(tmpDir);
+    const entry = getThread(uwf.varStore, THREAD_ID);
+    expect(entry?.head).toBe(cliOutput.head);
+  });
+
+  test("3.2 new step's prev equals old head's prev (replace, not append)", async () => {
+    const { casDir, oldStepPrev, mockAgentPath } = await setupThread({ multipleSteps: true });
+    const result = runUwf(
+      ["thread", "poke", THREAD_ID, "-p", "redo", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+    const cliOutput = JSON.parse(result.stdout.trim());
+
+    const { createUwfStore } = await import("../store.js");
+    const uwf = await createUwfStore(tmpDir);
+    const node = uwf.store.cas.get(cliOutput.head as CasRef);
+    expect(node).not.toBeNull();
+    expect(node?.type).toBe(uwf.schemas.stepNode);
+    const payload = node?.payload as StepNodePayload;
+    expect(payload.prev).toBe(oldStepPrev);
+  });
+
+  test("3.2b new step's prev is null when old head was the first step", async () => {
+    // multipleSteps:false means oldHead.prev = null
+    const { casDir, mockAgentPath } = await setupThread({ multipleSteps: false });
+    const result = runUwf(
+      ["thread", "poke", THREAD_ID, "-p", "redo", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+    const cliOutput = JSON.parse(result.stdout.trim());
+
+    const { createUwfStore } = await import("../store.js");
+    const uwf = await createUwfStore(tmpDir);
+    const node = uwf.store.cas.get(cliOutput.head as CasRef);
+    const payload = node?.payload as StepNodePayload;
+    expect(payload.prev).toBeNull();
+  });
+
+  test("3.3 new step's completedAtMs is later than old", async () => {
+    const { casDir, oldStepCompletedAtMs, mockAgentPath } = await setupThread();
+    const result = runUwf(
+      ["thread", "poke", THREAD_ID, "-p", "redo", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+    const cliOutput = JSON.parse(result.stdout.trim());
+
+    const { createUwfStore } = await import("../store.js");
+    const uwf = await createUwfStore(tmpDir);
+    const node = uwf.store.cas.get(cliOutput.head as CasRef);
+    const payload = node?.payload as StepNodePayload;
+    expect(payload.completedAtMs).toBeGreaterThan(oldStepCompletedAtMs);
+  });
+
+  test("3.5 status remains idle after poke (no completion/suspend)", async () => {
+    const { casDir, mockAgentPath } = await setupThread();
+    const result = runUwf(
+      ["thread", "poke", THREAD_ID, "-p", "redo", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+    const cliOutput = JSON.parse(result.stdout.trim());
+    expect(cliOutput.status).toBe("idle");
+    expect(cliOutput.done).toBe(false);
+    expect(cliOutput.suspendedRole).toBeNull();
+    expect(cliOutput.suspendMessage).toBeNull();
+  });
+
+  test("3.6 currentRole unchanged after poke (no moderator re-route)", async () => {
+    // Before poke: idle thread with worker step having $status=ok → moderator would route to reviewer.
+    // After poke (mock returns same $status=ok), moderator routing remains the same.
+    const { casDir, mockAgentPath } = await setupThread();
+    const result = runUwf(
+      ["thread", "poke", THREAD_ID, "-p", "redo", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+    const cliOutput = JSON.parse(result.stdout.trim());
+    expect(cliOutput.currentRole).toBe("reviewer");
+  });
+});
+
+// ── Group 4: Agent resolution ──────────────────────────────────────────────
+
+describe("uwf thread poke - agent resolution", () => {
+  test("4.1 without --agent, agent command read from head step's agent field", async () => {
+    // Head step's agent field points at mockAgentPath (default in setupThread)
+    const { casDir, promptCapturePath } = await setupThread();
+    const result = runUwf(["thread", "poke", THREAD_ID, "-p", "redo"], casDir);
+    expect(result.status).toBe(0);
+    const captured = await readFile(promptCapturePath, "utf8");
+    expect(captured).toBe("redo");
+  });
+
+  test("4.2 with --agent, explicit override is used", async () => {
+    // Head step records "uwf-mock" (which is not a real binary). Override with mockAgentPath.
+    const { casDir, mockAgentPath } = await setupThread({ stepAgentNameOverride: "uwf-mock" });
+    const result = runUwf(
+      ["thread", "poke", THREAD_ID, "-p", "redo", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+  });
+});
+
+// ── Group 5: Prompt passthrough ────────────────────────────────────────────
+
+describe("uwf thread poke - prompt passthrough", () => {
+  test("5.1 -p value is passed to agent as --prompt", async () => {
+    const { casDir, mockAgentPath, promptCapturePath } = await setupThread();
+    const supplement = "Use the REST API instead.";
+    const result = runUwf(
+      ["thread", "poke", THREAD_ID, "-p", supplement, "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+    const captured = await readFile(promptCapturePath, "utf8");
+    expect(captured).toBe(supplement);
+  });
+});
+
+// ── Group 6: Edge cases ────────────────────────────────────────────────────
+
+describe("uwf thread poke - edge cases", () => {
+  test("6.1 poke succeeds on suspended thread", async () => {
+    const { casDir, oldStepHash, mockAgentPath } = await setupThread({
+      threadStatus: "suspended",
+    });
+    const result = runUwf(
+      ["thread", "poke", THREAD_ID, "-p", "redo", "--agent", mockAgentPath],
+      casDir,
+    );
+    expect(result.status).toBe(0);
+    const cliOutput = JSON.parse(result.stdout.trim());
+    expect(cliOutput.head).not.toBe(oldStepHash);
+    expect(cliOutput.status).toBe("idle");
+    expect(cliOutput.suspendedRole).toBeNull();
+    expect(cliOutput.suspendMessage).toBeNull();
+  });
+
+  test("6.2 agent failure leaves thread head unchanged", async () => {
+    const { casDir, oldStepHash, failingAgentPath } = await setupThread();
+    const result = runUwf(
+      ["thread", "poke", THREAD_ID, "-p", "redo", "--agent", failingAgentPath],
+      casDir,
+    );
+    expect(result.status).not.toBe(0);
+
+    const { createUwfStore, getThread } = await import("../store.js");
+    const uwf = await createUwfStore(tmpDir);
+    const entry = getThread(uwf.varStore, THREAD_ID);
+    expect(entry?.head).toBe(oldStepHash);
+  });
+});

packages/cli/src/__tests__/thread-suspended-display.test.ts

@@ -118,8 +118,8 @@ describe("suspended thread display", () => {
         [idleThreadId]: idleEntry,
       });
 
-      // Test thread list
-      const listResult = await cmdThreadList(tmpDir, null, null, null, null, null);
+      // Test thread list — pass showAll=true to include suspended threads
+      const listResult = await cmdThreadList(tmpDir, null, null, null, null, null, true);
 
       // Find the suspended and idle threads in results
       const suspendedItem = listResult.find((item) => item.thread === suspendedThreadId);

packages/cli/src/cli.ts

@@ -12,11 +12,12 @@ import {
   cmdPromptWorkflowAuthoring,
 } from "./commands/prompt.js";
 import { cmdSetup, cmdSetupInteractive, resolvePresetBaseUrl } from "./commands/setup.js";
-import { cmdStepFork, cmdStepList, cmdStepRead, cmdStepShow } from "./commands/step.js";
+import { cmdStepAsk, cmdStepFork, cmdStepList, cmdStepRead, cmdStepShow } from "./commands/step.js";
 import {
   cmdThreadCancel,
   cmdThreadExec,
   cmdThreadList,
+  cmdThreadPoke,
   cmdThreadRead,
   cmdThreadResume,
   cmdThreadShow,
@@ -232,11 +233,12 @@ function parsePaginationOptions(
 
 thread
   .command("list")
-  .description("List threads")
+  .description("List threads (defaults to active: idle + running)")
   .option(
     "--status <status>",
     "Filter by status: idle, running, completed, 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 +246,7 @@ thread
   .action(
     (opts: {
       status: string | undefined;
+      all: boolean | undefined;
       after: string | undefined;
       before: string | undefined;
       skip: string | undefined;
@@ -255,6 +258,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 +267,7 @@ thread
           beforeMs,
           skip,
           take,
+          showAll,
         );
         writeOutput(result);
       });
@@ -290,6 +295,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 +394,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")

packages/cli/src/commands/step.ts

@@ -1,5 +1,8 @@
+import { execFileSync } from "node:child_process";
 import type { CasStore } from "@ocas/core";
 import type {
+  AgentAlias,
+  AgentConfig,
   CasRef,
   StartEntry,
   StepEntry,
@@ -7,9 +10,12 @@ import type {
   ThreadForkOutput,
   ThreadId,
   ThreadStepsOutput,
+  WorkflowConfig,
+  WorkflowPayload,
 } from "@united-workforce/protocol";
 import { generateUlid } from "@united-workforce/util";
-import { createUwfStore, setThread } from "../store.js";
+import { getAskSessionId, loadWorkflowConfig, setAskSessionId } from "@united-workforce/util-agent";
+import { createUwfStore, setThread, type UwfStore } from "../store.js";
 import {
   collectOrderedSteps,
   expandDeep,
@@ -341,3 +347,217 @@ export async function cmdStepRead(
 
   return formatStepMarkdown(stepHash, payload.role, payload.agent, turnData, selectedTurns);
 }
+
+// ── step ask ────────────────────────────────────────────────────────────────
+
+function parseAgentOverride(override: string): AgentConfig {
+  const parts = override
+    .trim()
+    .split(/\s+/)
+    .filter((p) => p.length > 0);
+  const command = parts[0];
+  if (command === undefined) {
+    fail("agent override must not be empty");
+  }
+  return { command, args: parts.slice(1) };
+}
+
+function resolveAskAgentConfig(
+  config: WorkflowConfig,
+  workflow: WorkflowPayload | null,
+  role: string,
+  agentOverride: string | null,
+  recordedAgent: string,
+): AgentConfig {
+  if (agentOverride !== null) {
+    const fromAlias = config.agents[agentOverride as AgentAlias];
+    if (fromAlias !== undefined) {
+      return fromAlias;
+    }
+    return parseAgentOverride(agentOverride);
+  }
+
+  // Try to resolve via the recorded agent name as a config alias.
+  const fromRecorded = config.agents[recordedAgent as AgentAlias];
+  if (fromRecorded !== undefined) {
+    return fromRecorded;
+  }
+
+  // Fall back to default agent for the workflow / role.
+  if (workflow !== null && config.agentOverrides !== null) {
+    const roleOverrides = config.agentOverrides[workflow.name];
+    if (roleOverrides !== undefined && roleOverrides[role] !== undefined) {
+      const alias = roleOverrides[role];
+      const agentConfig = config.agents[alias];
+      if (agentConfig !== undefined) {
+        return agentConfig;
+      }
+    }
+  }
+
+  // Treat the recorded value as a raw command path.
+  return parseAgentOverride(recordedAgent);
+}
+
+/**
+ * Derive the agent name used for cache file partitioning from an executable
+ * path or alias.  Examples:
+ *   uwf-hermes        → hermes
+ *   uwf-claude-code   → claude-code
+ *   /tmp/mock-agent.sh → mock
+ *   /usr/bin/agent    → agent
+ */
+function deriveAgentName(commandPath: string): string {
+  const basename = commandPath.split(/[/\\]/).pop() ?? commandPath;
+  // Strip a trailing extension (.sh, .js, .mjs, .cjs)
+  const noExt = basename.replace(/\.(sh|js|mjs|cjs|ts)$/i, "");
+  // Strip the `uwf-` prefix introduced by agentLabel().
+  const noPrefix = noExt.startsWith("uwf-") ? noExt.slice(4) : noExt;
+  // Strip the trailing `-agent` suffix used by tests / generic agent shells.
+  const noSuffix = noPrefix.endsWith("-agent") ? noPrefix.slice(0, -"-agent".length) : noPrefix;
+  return noSuffix === "" ? noExt : noSuffix;
+}
+
+function loadDetailNode(
+  store: CasStore,
+  detailRef: CasRef,
+): { sessionId: string | null; payload: Record<string, unknown> } {
+  const detailNode = store.get(detailRef);
+  if (detailNode === null) {
+    fail(`detail node not found: ${detailRef}`);
+  }
+  const payload = detailNode.payload as Record<string, unknown>;
+  const sessionId = typeof payload.sessionId === "string" ? payload.sessionId : null;
+  return { sessionId, payload };
+}
+
+function spawnAskAgent(agent: AgentConfig, argv: string[], cwd: string): { stdout: string } {
+  try {
+    const stdout = execFileSync(agent.command, [...agent.args, ...argv], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: 50 * 1024 * 1024,
+      cwd,
+    });
+    return { stdout };
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException & { stderr: Buffer | string | null };
+    if (err.code === "ENOENT") {
+      fail(
+        `"${agent.command}" not found in PATH. Install it or check your PATH config. Run: which ${agent.command}`,
+      );
+    }
+    const stderr =
+      err.stderr == null
+        ? ""
+        : typeof err.stderr === "string"
+          ? err.stderr
+          : err.stderr.toString("utf8");
+    const detail = stderr.trim() !== "" ? `: ${stderr.trim()}` : "";
+    fail(`agent command failed (${agent.command})${detail}`);
+  }
+}
+
+function resolveAskWorkflow(uwf: UwfStore, payload: StepNodePayload): WorkflowPayload | null {
+  const startNode = uwf.store.cas.get(payload.start);
+  if (startNode === null) {
+    return null;
+  }
+  const start = startNode.payload as { workflow: CasRef };
+  const workflowNode = uwf.store.cas.get(start.workflow);
+  if (workflowNode === null) {
+    return null;
+  }
+  return workflowNode.payload as WorkflowPayload;
+}
+
+async function performFork(
+  agent: AgentConfig,
+  agentName: string,
+  stepHash: CasRef,
+  sourceSessionId: string,
+  storageRoot: string,
+  cwd: string,
+): Promise<string> {
+  const cached = await getAskSessionId(agentName, stepHash, storageRoot);
+  if (cached !== null) {
+    return cached;
+  }
+  const { stdout } = spawnAskAgent(agent, ["--mode", "fork", "--session", sourceSessionId], cwd);
+  const newSessionId = stdout.trim().split("\n").pop()?.trim() ?? "";
+  if (newSessionId === "") {
+    fail(`agent fork did not return a session id (${agent.command})`);
+  }
+  await setAskSessionId(agentName, stepHash, newSessionId, storageRoot);
+  return newSessionId;
+}
+
+export type CmdStepAskOptions = {
+  prompt: string;
+  agentOverride: string | null;
+  /** When false, skip session forking and pass detail ref for context injection. */
+  fork: boolean;
+};
+
+/**
+ * Ask a follow-up question to a historical step's agent (read-only).
+ *
+ * Does NOT write a new StepNode and does NOT mutate thread state.  The agent's
+ * raw stdout is returned so the CLI entry point can stream it directly.
+ */
+export async function cmdStepAsk(
+  storageRoot: string,
+  stepHash: CasRef,
+  options: CmdStepAskOptions,
+): Promise<string> {
+  const uwf = await createUwfStore(storageRoot);
+  const node = uwf.store.cas.get(stepHash);
+  if (node === null) {
+    fail(`CAS node not found: ${stepHash}`);
+  }
+  if (node.type !== uwf.schemas.stepNode) {
+    fail(`node ${stepHash} is not a StepNode`);
+  }
+  const payload = node.payload as StepNodePayload;
+  if (payload.detail === null) {
+    fail(`step ${stepHash} has no detail; cannot ask`);
+  }
+
+  const detailRef = payload.detail;
+  const { sessionId: sourceSessionId } = loadDetailNode(uwf.store.cas, detailRef);
+
+  const workflow = resolveAskWorkflow(uwf, payload);
+  const config = await loadWorkflowConfig(storageRoot);
+  const agent = resolveAskAgentConfig(
+    config,
+    workflow,
+    payload.role,
+    options.agentOverride,
+    payload.agent,
+  );
+  const agentName = deriveAgentName(agent.command);
+
+  const cwd = payload.cwd !== "" ? payload.cwd : process.cwd();
+
+  // Fork path: fork (or reuse cached fork) → ask with that session.
+  if (options.fork && sourceSessionId !== null) {
+    const askSessionId = await performFork(
+      agent,
+      agentName,
+      stepHash,
+      sourceSessionId,
+      storageRoot,
+      cwd,
+    );
+    const argv = ["--mode", "ask", "--session", askSessionId, "--prompt", options.prompt];
+    argv.push("--detail", detailRef);
+    const { stdout } = spawnAskAgent(agent, argv, cwd);
+    return stdout;
+  }
+
+  // Fallback path: ask without forking; inject detail ref for context.
+  const argv = ["--mode", "ask", "--prompt", options.prompt];
+  argv.push("--detail", detailRef);
+  const { stdout } = spawnAskAgent(agent, argv, cwd);
+  return stdout;
+}

packages/cli/src/commands/thread.ts

@@ -199,6 +199,7 @@ const PL_THREAD_ARCHIVED = "F4D8Q2K5";
 const PL_STEP_ERROR = "B8T5N1V6";
 const PL_BACKGROUND_START = "X7Q4W9M2";
 const PL_THREAD_RESUME = "K2R7M4N8";
+const PL_THREAD_POKE = "P4Q9R3X7";
 
 type ResumeStepConfig = {
   role: string;
@@ -649,18 +650,25 @@ export async function cmdThreadList(
   beforeMs: number | null,
   skip: number | null,
   take: number | null,
+  showAll: boolean = false,
 ): Promise<ThreadListItemWithStatus[]> {
   const uwf = await createUwfStore(storageRoot);
   const index = loadActiveThreads(uwf.varStore);
 
+  // Resolve the effective filter:
+  //   - explicit --status wins (showAll has no effect)
+  //   - otherwise: --all → no filter; default → ["idle", "running"]
+  const effectiveFilter: ThreadStatus[] | null =
+    statusFilter !== null ? statusFilter : showAll ? null : ["idle", "running"];
+
   // Collect active threads
   let items = await collectActiveThreads(storageRoot, uwf, index);
 
   // Collect completed threads (if relevant for status filter)
   const includeCompleted =
-    statusFilter === null ||
-    statusFilter.includes("completed") ||
-    statusFilter.includes("cancelled");
+    effectiveFilter === null ||
+    effectiveFilter.includes("completed") ||
+    effectiveFilter.includes("cancelled");
   if (includeCompleted) {
     const activeIds = new Set(items.map((i) => i.thread));
     const completedItems = collectCompletedThreads(uwf, activeIds);
@@ -668,8 +676,8 @@ export async function cmdThreadList(
   }
 
   // Apply status filter
-  if (statusFilter !== null) {
-    items = items.filter((item) => statusFilter.includes(item.status));
+  if (effectiveFilter !== null) {
+    items = items.filter((item) => effectiveFilter.includes(item.status));
   }
 
   // Apply time range filters
@@ -1135,6 +1143,147 @@ export async function cmdThreadResume(
   });
 }
 
+/**
+ * Validate that a thread can be poked. Returns the existing entry and the head StepNode payload.
+ * Fails (process exit) when the thread is missing, running, completed, cancelled, or has no
+ * StepNode at its head.
+ */
+async function validatePokePreconditions(
+  storageRoot: string,
+  uwf: UwfStore,
+  threadId: ThreadId,
+): Promise<{ entry: ThreadIndexEntry; oldHead: CasRef; oldHeadPayload: StepNodePayload }> {
+  const runningMarker = await isThreadRunning(storageRoot, threadId);
+  if (runningMarker !== null) {
+    fail(`thread already executing in background (PID: ${runningMarker.pid})`);
+  }
+
+  const entry = getThread(uwf.varStore, threadId);
+  if (entry === null) {
+    fail(`thread not active: ${threadId}`);
+  }
+
+  if (entry.status === "completed" || entry.status === "cancelled") {
+    fail(`thread cannot be poked: ${threadId} (status: ${entry.status})`);
+  }
+
+  const oldHead = entry.head;
+  const oldHeadNode = uwf.store.cas.get(oldHead);
+  if (oldHeadNode === null) {
+    fail(`CAS node not found: ${oldHead}`);
+  }
+  if (oldHeadNode.type !== uwf.schemas.stepNode) {
+    fail("thread cannot be poked: no step to replace (head is StartNode)");
+  }
+
+  return { entry, oldHead, oldHeadPayload: oldHeadNode.payload as StepNodePayload };
+}
+
+/**
+ * Resolve the next role from the post-poke chain state, used for the StepOutput.currentRole field.
+ * Returns null when the next role is $END, evaluation fails, or the result is a suspend.
+ */
+function resolveCurrentRoleFromChain(
+  uwfAfter: UwfStore,
+  workflow: WorkflowPayload,
+  replacedHash: CasRef,
+): string | null {
+  const chainAfter = walkChain(uwfAfter, replacedHash);
+  const { lastRole, lastOutput } = resolveEvaluateArgs(uwfAfter, chainAfter);
+  const afterResult = evaluate(workflow.graph, lastRole, lastOutput);
+  if (!afterResult.ok || isSuspendResult(afterResult.value)) {
+    return null;
+  }
+  if (afterResult.value.role === END_ROLE) {
+    return null;
+  }
+  return afterResult.value.role;
+}
+
+/**
+ * Poke a thread: re-run the agent on the head step with a supplementary prompt,
+ * replacing the head step's output. The new step's `prev` points to the OLD head's
+ * `prev` — semantically replacing (not appending to) the head. The moderator is NOT
+ * re-evaluated for routing; the role of the head step is re-used.
+ */
+export async function cmdThreadPoke(
+  storageRoot: string,
+  threadId: ThreadId,
+  prompt: string,
+  agentOverride: string | null,
+): Promise<StepOutput> {
+  const uwf = await createUwfStore(storageRoot);
+  const { entry, oldHeadPayload } = await validatePokePreconditions(storageRoot, uwf, threadId);
+
+  const chain = walkChain(uwf, entry.head);
+  const workflowHash = chain.start.workflow;
+  const threadCwd = chain.start.cwd;
+
+  const plog = createProcessLogger({
+    storageRoot,
+    context: { thread: threadId, workflow: workflowHash },
+  });
+
+  // Resolve the agent: --agent override wins; otherwise read from old head step's `agent` field.
+  const config = await loadWorkflowConfig(storageRoot);
+  const workflow = loadWorkflowPayload(uwf, workflowHash);
+  const role = oldHeadPayload.role;
+  const agent =
+    agentOverride !== null
+      ? resolveAgentConfig(config, workflow, role, agentOverride)
+      : parseAgentOverride(oldHeadPayload.agent);
+
+  const effectiveCwd = oldHeadPayload.cwd !== "" ? oldHeadPayload.cwd : threadCwd;
+
+  plog.log(PL_THREAD_POKE, `poke role=${role} agent=${agent.command}`, null);
+  plog.log(PL_AGENT_SPAWN, `spawning agent command=${agent.command}`, {
+    args: [...agent.args, threadId, role].join(" "),
+  });
+
+  loadDotenv({ path: getEnvPath(storageRoot) });
+
+  // Spawn the agent. The agent will create a new StepNode with prev=oldHead (it reads
+  // the active thread head). After the agent returns, we rewrite that node's prev so
+  // that the new head replaces the old head instead of appending after it.
+  const agentResult = spawnAgent(plog, agent, threadId, role, prompt, effectiveCwd);
+  const agentStepHash = agentResult.stepHash as CasRef;
+
+  plog.log(PL_AGENT_DONE, `agent returned head=${agentStepHash}`, null);
+
+  const uwfAfter = await createUwfStore(storageRoot);
+  const agentNode = uwfAfter.store.cas.get(agentStepHash);
+  if (agentNode === null || agentNode.type !== uwfAfter.schemas.stepNode) {
+    failStep(plog, `agent returned hash that is not a StepNode: ${agentStepHash}`);
+  }
+  const agentPayload = agentNode.payload as StepNodePayload;
+
+  // Rewrite the new step so that its `prev` points to the OLD head's prev (replace semantics).
+  const replacedPayload: StepNodePayload = {
+    ...agentPayload,
+    prev: oldHeadPayload.prev,
+  };
+  const replacedHash = await uwfAfter.store.cas.put(uwfAfter.schemas.stepNode, replacedPayload);
+  const replacedNode = uwfAfter.store.cas.get(replacedHash);
+  if (replacedNode === null || !validate(uwfAfter.store, replacedNode)) {
+    failStep(plog, "rewritten StepNode failed schema validation");
+  }
+
+  // Update thread head to the replaced step. Status becomes idle (no moderator re-route).
+  setThread(uwfAfter.varStore, threadId, updateThreadHead(entry, replacedHash));
+
+  return {
+    workflow: workflowHash,
+    thread: threadId,
+    head: replacedHash,
+    status: "idle",
+    currentRole: resolveCurrentRoleFromChain(uwfAfter, workflow, replacedHash),
+    suspendedRole: null,
+    suspendMessage: null,
+    done: false,
+    background: null,
+  };
+}
+
 export function validateCount(count: number): void {
   if (count < 1 || !Number.isInteger(count)) {
     throw new Error(`--count must be a positive integer, got: ${count}`);

packages/eval/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@united-workforce/eval",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": false,
   "files": [
     "src",
@@ -22,8 +22,8 @@
     "test:ci": "vitest run __tests__/"
   },
   "dependencies": {
-    "@ocas/core": "^0.3.0",
-    "@ocas/fs": "^0.3.0",
+    "@ocas/core": "^0.4.0",
+    "@ocas/fs": "^0.4.0",
     "@united-workforce/protocol": "workspace:^",
     "@united-workforce/util": "workspace:^",
     "commander": "^14.0.3",

packages/eval/src/commands/list.ts

@@ -6,7 +6,7 @@ import { formatList, selectEntries } from "./format.js";
 import { readEvalEntries } from "./read.js";
 
 const log = createLogger({ sink: { kind: "stderr" } });
-const LOG_LIST = "L5KX9R2B";
+const LOG_LIST = "H5KX9R2B";
 
 type ListCliOptions = {
   task: string | undefined;

packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@united-workforce/protocol",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "files": [
     "src",
     "dist",
@@ -18,8 +18,8 @@
     "test:ci": "vitest run src/__tests__/"
   },
   "dependencies": {
-    "@ocas/core": "^0.3.0",
-    "@ocas/fs": "^0.3.0"
+    "@ocas/core": "^0.4.0",
+    "@ocas/fs": "^0.4.0"
   },
   "devDependencies": {
     "typescript": "^5.8.3"

packages/util-agent/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.2 — 2026-06-07
+
+- fix: decouple session resume from isFirstVisit guard
+  
+  When frontmatter validation fails, the step is never written to CAS, so isFirstVisit remains true on the next run. Both adapters now always check the session cache regardless of isFirstVisit. When resuming after a frontmatter-only failure (isFirstVisit + cache hit), a minimal correction prompt is sent via buildFrontmatterRetryPrompt() instead of re-sending the full initial prompt.
+

packages/util-agent/__tests__/adapter-fork-null.test.ts

@@ -0,0 +1,60 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+
+/**
+ * Source-level verification that each adapter's `createAgent({...})` call
+ * includes the new `fork: null` and `cleanup: null` fields.
+ *
+ * Adapters are CLI binaries that spawn external processes — runtime testing
+ * requires real LLM environments — so we use static source inspection here.
+ * Type-level correctness is enforced separately by `tsc --build`.
+ */
+
+const REPO_ROOT = join(__dirname, "..", "..", "..");
+
+const ADAPTERS: Array<{ name: string; path: string }> = [
+  { name: "agent-mock", path: "packages/agent-mock/src/mock-agent.ts" },
+  { name: "agent-builtin", path: "packages/agent-builtin/src/agent.ts" },
+  { name: "agent-hermes", path: "packages/agent-hermes/src/hermes.ts" },
+  { name: "agent-claude-code", path: "packages/agent-claude-code/src/claude-code.ts" },
+];
+
+/** Find the matching `}` for the `{` at `openIdx` in `source`. */
+function findMatchingBrace(source: string, openIdx: number): number {
+  let depth = 0;
+  for (let i = openIdx; i < source.length; i++) {
+    const ch = source[i];
+    if (ch === "{") {
+      depth++;
+    } else if (ch === "}") {
+      depth--;
+      if (depth === 0) {
+        return i;
+      }
+    }
+  }
+  return -1;
+}
+
+/** Extract the `createAgent({...})` block from adapter source. */
+function extractCreateAgentBlock(source: string): string {
+  const startIdx = source.indexOf("createAgent({");
+  expect(startIdx).toBeGreaterThanOrEqual(0);
+  const openIdx = source.indexOf("{", startIdx);
+  const endIdx = findMatchingBrace(source, openIdx);
+  expect(endIdx).toBeGreaterThan(openIdx);
+  return source.slice(openIdx, endIdx + 1);
+}
+
+describe("adapter createAgent calls include fork: null and cleanup: null", () => {
+  for (const adapter of ADAPTERS) {
+    test(`${adapter.name} createAgent call includes fork: null and cleanup: null`, async () => {
+      const source = await readFile(join(REPO_ROOT, adapter.path), "utf8");
+      expect(source).toMatch(/createAgent\s*\(\s*\{/);
+      const block = extractCreateAgentBlock(source);
+      expect(block).toMatch(/fork:\s*null/);
+      expect(block).toMatch(/cleanup:\s*null/);
+    });
+  }
+});

packages/util-agent/__tests__/agent-options-type.test.ts

@@ -0,0 +1,78 @@
+import type { Store } from "@ocas/core";
+import { describe, expect, test } from "vitest";
+
+import type {
+  AgentCleanupFn,
+  AgentContext,
+  AgentContinueFn,
+  AgentForkFn,
+  AgentOptions,
+  AgentRunFn,
+} from "../src/types.js";
+
+const makeRun: AgentRunFn = async (_ctx: AgentContext) => ({
+  output: "",
+  detailHash: "",
+  sessionId: "",
+  assembledPrompt: "",
+  usage: null,
+});
+
+const makeContinue: AgentContinueFn = async (_sessionId, _message, _store) => ({
+  output: "",
+  detailHash: "",
+  sessionId: "",
+  assembledPrompt: "",
+  usage: null,
+});
+
+describe("AgentOptions fork/cleanup", () => {
+  test("AgentOptions accepts fork and cleanup as null", () => {
+    const opts: AgentOptions = {
+      name: "test",
+      run: makeRun,
+      continue: makeContinue,
+      fork: null,
+      cleanup: null,
+    };
+    expect(opts.name).toBe("test");
+    expect(opts.run).toBe(makeRun);
+    expect(opts.continue).toBe(makeContinue);
+    expect(opts.fork).toBeNull();
+    expect(opts.cleanup).toBeNull();
+  });
+
+  test("AgentOptions accepts real fork and cleanup functions", () => {
+    const fork: AgentForkFn = async (sessionId, _store) => `${sessionId}-forked`;
+    const cleanup: AgentCleanupFn = async () => {
+      /* no-op */
+    };
+    const opts: AgentOptions = {
+      name: "test",
+      run: makeRun,
+      continue: makeContinue,
+      fork,
+      cleanup,
+    };
+    expect(typeof opts.fork).toBe("function");
+    expect(typeof opts.cleanup).toBe("function");
+  });
+
+  test("AgentForkFn signature accepts (sessionId: string, store: Store) and returns Promise<string>", async () => {
+    const fork: AgentForkFn = async (sessionId, _store) => `${sessionId}-child`;
+    // Cast a placeholder Store — only the signature shape matters for this test.
+    const fakeStore = {} as Store;
+    const result = await fork("session-abc", fakeStore);
+    expect(result).toBe("session-abc-child");
+  });
+
+  test("AgentCleanupFn signature accepts no args and returns Promise<void>", async () => {
+    let called = false;
+    const cleanup: AgentCleanupFn = async () => {
+      called = true;
+    };
+    const result = await cleanup();
+    expect(result).toBeUndefined();
+    expect(called).toBe(true);
+  });
+});

packages/util-agent/__tests__/build-output-format-instruction.test.ts

@@ -225,4 +225,34 @@ describe("buildOutputFormatInstruction", () => {
     const result = buildOutputFormatInstruction({});
     expect(result).toContain("Focus exclusively on YOUR role");
   });
+
+  test("renders const value as literal in flat schema example", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        $status: { type: "string", const: "greeted" },
+        message: { type: "string" },
+      },
+      required: ["$status", "message"],
+    };
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("$status: greeted");
+    expect(result).toContain("fixed value");
+    expect(result).not.toContain("$status: <string>");
+  });
+
+  test("renders const value for non-string types", () => {
+    const schema = {
+      type: "object",
+      properties: {
+        count: { type: "number", const: 42 },
+        done: { type: "boolean", const: true },
+      },
+      required: ["count", "done"],
+    };
+    const result = buildOutputFormatInstruction(schema);
+    expect(result).toContain("count: 42");
+    expect(result).toContain("done: true");
+    expect(result).toContain("fixed value");
+  });
 });

packages/util-agent/__tests__/build-thread-progress.test.ts

@@ -0,0 +1,59 @@
+import type { StepContext } from "@united-workforce/protocol";
+import { describe, expect, test } from "vitest";
+import { buildThreadProgress } from "../src/build-thread-progress.js";
+
+function makeStep(role: string): StepContext {
+  return {
+    role,
+    output: {},
+    detail: "0000000000000" as string,
+    agent: "uwf-mock",
+    edgePrompt: "",
+    startedAtMs: 0,
+    completedAtMs: 0,
+    cwd: "",
+    assembledPrompt: null,
+    usage: null,
+    content: null,
+  };
+}
+
+describe("buildThreadProgress", () => {
+  test("first step of thread", () => {
+    const result = buildThreadProgress([], "proponent");
+    expect(result).toContain("## Thread Progress");
+    expect(result).toContain("first step");
+    expect(result).toContain("first time");
+    expect(result).toContain("proponent");
+  });
+
+  test("second step, role not seen before", () => {
+    const steps = [makeStep("opponent")];
+    const result = buildThreadProgress(steps, "proponent");
+    expect(result).toContain("Thread step 2");
+    expect(result).toContain("spoken 0 times");
+  });
+
+  test("role has spoken once before", () => {
+    const steps = [makeStep("proponent"), makeStep("opponent")];
+    const result = buildThreadProgress(steps, "proponent");
+    expect(result).toContain("Thread step 3");
+    expect(result).toContain("spoken 1 time before");
+    // singular "time" not "times"
+    expect(result).not.toContain("1 times");
+  });
+
+  test("role has spoken multiple times", () => {
+    const steps = [
+      makeStep("proponent"),
+      makeStep("opponent"),
+      makeStep("proponent"),
+      makeStep("opponent"),
+      makeStep("proponent"),
+      makeStep("opponent"),
+    ];
+    const result = buildThreadProgress(steps, "proponent");
+    expect(result).toContain("Thread step 7");
+    expect(result).toContain("spoken 3 times");
+  });
+});

packages/util-agent/__tests__/frontmatter-retry-prompt.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "vitest";
+import { buildFrontmatterRetryPrompt } from "../src/frontmatter-retry-prompt.js";
+
+describe("buildFrontmatterRetryPrompt", () => {
+  test("includes correction instruction", () => {
+    const result = buildFrontmatterRetryPrompt("Use YAML frontmatter");
+    expect(result).toContain("previous run completed");
+    expect(result).toContain("do NOT need to redo any work");
+    expect(result).toContain("corrected YAML frontmatter");
+  });
+
+  test("includes outputFormatInstruction when provided", () => {
+    const instruction = "---\nstatus: $done | $review\nsummary: string\n---";
+    const result = buildFrontmatterRetryPrompt(instruction);
+    expect(result).toContain(instruction);
+  });
+
+  test("works with empty outputFormatInstruction", () => {
+    const result = buildFrontmatterRetryPrompt("");
+    expect(result).not.toContain("\n\n\n");
+    expect(result).toContain("corrected YAML frontmatter");
+  });
+});

packages/util-agent/__tests__/session-cache-ask.test.ts

@@ -0,0 +1,131 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { ThreadId } from "@united-workforce/protocol";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+
+import {
+  getAskSessionId,
+  getCachedSessionId,
+  getCachePath,
+  setAskSessionId,
+  setCachedSessionId,
+} from "../src/session-cache.js";
+import { getDefaultStorageRoot } from "../src/storage.js";
+
+describe("session-cache ask sessions", () => {
+  let testStorageRoot: string;
+
+  beforeEach(async () => {
+    testStorageRoot = join(
+      getDefaultStorageRoot(),
+      "test-cache",
+      `ask-${Date.now()}-${Math.random()}`,
+    );
+    await mkdir(testStorageRoot, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testStorageRoot, { recursive: true, force: true });
+  });
+
+  const stepHash = "ABCDEFG1234567";
+
+  test("getAskSessionId returns null when no ask session cached", async () => {
+    const session = await getAskSessionId("claude-code", stepHash, testStorageRoot);
+    expect(session).toBeNull();
+  });
+
+  test("setAskSessionId + getAskSessionId round-trip", async () => {
+    await setAskSessionId("claude-code", stepHash, "ask-session-123", testStorageRoot);
+    const session = await getAskSessionId("claude-code", stepHash, testStorageRoot);
+    expect(session).toBe("ask-session-123");
+  });
+
+  test("ask cache keys use stepHash:ask format", async () => {
+    await setAskSessionId("claude-code", stepHash, "ask-session-456", testStorageRoot);
+
+    const cachePath = getCachePath("claude-code", testStorageRoot);
+    const content = JSON.parse(await readFile(cachePath, "utf8")) as Record<string, string>;
+
+    expect(content).toHaveProperty(`${stepHash}:ask`, "ask-session-456");
+  });
+
+  test("exec cache and ask cache coexist in same file", async () => {
+    const threadId = "01234567890123456789012345" as ThreadId;
+    const role = "developer";
+
+    await setCachedSessionId("claude-code", threadId, role, "exec-session", testStorageRoot);
+    await setAskSessionId("claude-code", stepHash, "ask-session", testStorageRoot);
+
+    const cachePath = getCachePath("claude-code", testStorageRoot);
+    const content = JSON.parse(await readFile(cachePath, "utf8")) as Record<string, string>;
+
+    expect(content).toHaveProperty(`${threadId}:${role}`, "exec-session");
+    expect(content).toHaveProperty(`${stepHash}:ask`, "ask-session");
+
+    expect(await getCachedSessionId("claude-code", threadId, role, testStorageRoot)).toBe(
+      "exec-session",
+    );
+    expect(await getAskSessionId("claude-code", stepHash, testStorageRoot)).toBe("ask-session");
+  });
+
+  test("updating ask session does not affect exec session", async () => {
+    const threadId = "01234567890123456789012345" as ThreadId;
+    const role = "developer";
+
+    await setCachedSessionId("claude-code", threadId, role, "exec-original", testStorageRoot);
+    await setAskSessionId("claude-code", stepHash, "ask-original", testStorageRoot);
+
+    await setAskSessionId("claude-code", stepHash, "ask-updated", testStorageRoot);
+
+    expect(await getCachedSessionId("claude-code", threadId, role, testStorageRoot)).toBe(
+      "exec-original",
+    );
+    expect(await getAskSessionId("claude-code", stepHash, testStorageRoot)).toBe("ask-updated");
+  });
+
+  test("updating exec session does not affect ask session", async () => {
+    const threadId = "01234567890123456789012345" as ThreadId;
+    const role = "developer";
+
+    await setAskSessionId("claude-code", stepHash, "ask-original", testStorageRoot);
+    await setCachedSessionId("claude-code", threadId, role, "exec-original", testStorageRoot);
+
+    await setCachedSessionId("claude-code", threadId, role, "exec-updated", testStorageRoot);
+
+    expect(await getAskSessionId("claude-code", stepHash, testStorageRoot)).toBe("ask-original");
+    expect(await getCachedSessionId("claude-code", threadId, role, testStorageRoot)).toBe(
+      "exec-updated",
+    );
+  });
+
+  test("different stepHashes have independent ask sessions", async () => {
+    const stepHashA = "AAAAAAA1234567";
+    const stepHashB = "BBBBBBB1234567";
+
+    await setAskSessionId("claude-code", stepHashA, "session-A", testStorageRoot);
+    await setAskSessionId("claude-code", stepHashB, "session-B", testStorageRoot);
+
+    expect(await getAskSessionId("claude-code", stepHashA, testStorageRoot)).toBe("session-A");
+    expect(await getAskSessionId("claude-code", stepHashB, testStorageRoot)).toBe("session-B");
+  });
+
+  test("ask session for one agent does not leak to another", async () => {
+    await setAskSessionId("claude-code", stepHash, "cc-ask-session", testStorageRoot);
+
+    const ccSession = await getAskSessionId("claude-code", stepHash, testStorageRoot);
+    const hermesSession = await getAskSessionId("hermes", stepHash, testStorageRoot);
+
+    expect(ccSession).toBe("cc-ask-session");
+    expect(hermesSession).toBeNull();
+  });
+
+  test("empty string ask session treated as missing", async () => {
+    const cachePath = getCachePath("claude-code", testStorageRoot);
+    await mkdir(dirname(cachePath), { recursive: true });
+    await writeFile(cachePath, JSON.stringify({ [`${stepHash}:ask`]: "" }), "utf8");
+
+    const session = await getAskSessionId("claude-code", stepHash, testStorageRoot);
+    expect(session).toBeNull();
+  });
+});

packages/util-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@united-workforce/util-agent",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "files": [
     "src",
     "dist",
@@ -18,8 +18,8 @@
     "test:ci": "vitest run __tests__/ src/__tests__/"
   },
   "dependencies": {
-    "@ocas/core": "^0.3.0",
-    "@ocas/fs": "^0.3.0",
+    "@ocas/core": "^0.4.0",
+    "@ocas/fs": "^0.4.0",
     "@united-workforce/protocol": "workspace:^",
     "@united-workforce/util": "workspace:^",
     "dotenv": "^16.6.1",

packages/util-agent/src/build-output-format-instruction.ts

@@ -74,6 +74,10 @@ function collectObjectSchemas(schema: JSONSchema): JSONSchema[] {
 }
 
 function resolvePropertySchema(prop: JSONSchema): JSONSchema {
+  if (prop.const !== undefined) {
+    return prop;
+  }
+
   if (Array.isArray(prop.enum) && prop.enum.length > 0) {
     return prop;
   }
@@ -113,6 +117,11 @@ function buildPropertyExampleLine(prop: SchemaProperty): string {
     commentParts.push("required");
   }
 
+  if (resolved.const !== undefined) {
+    commentParts.push("fixed value");
+    return `${prop.name}: ${formatYamlScalar(resolved.const)}${buildPropertyComment(commentParts)}`;
+  }
+
   if (Array.isArray(resolved.enum) && resolved.enum.length > 0) {
     const enumValues = resolved.enum.map((v) => String(v));
     commentParts.push(...enumValues);

packages/util-agent/src/build-thread-progress.ts

@@ -0,0 +1,27 @@
+import type { StepContext } from "@united-workforce/protocol";
+
+/**
+ * Build a compact thread-progress summary so the agent knows where it is
+ * in the conversation without making tool calls to count steps.
+ *
+ * Example output:
+ *   ## Thread Progress
+ *   Thread step 6. You (proponent) have spoken 2 times before this turn.
+ */
+export function buildThreadProgress(steps: StepContext[], role: string): string {
+  const totalSteps = steps.length;
+  const roleVisits = steps.filter((s) => s.role === role).length;
+
+  const parts = [`## Thread Progress`];
+  if (totalSteps === 0) {
+    parts.push(
+      `This is the first step of the thread. You (${role}) are speaking for the first time.`,
+    );
+  } else {
+    parts.push(
+      `Thread step ${totalSteps + 1}. You (${role}) have spoken ${roleVisits} time${roleVisits === 1 ? "" : "s"} before this turn.`,
+    );
+  }
+
+  return parts.join("\n");
+}

packages/util-agent/src/frontmatter-retry-prompt.ts

@@ -0,0 +1,21 @@
+/**
+ * Build a minimal prompt for retrying frontmatter output on a resumed session.
+ *
+ * Used when a previous run completed successfully but frontmatter validation
+ * failed — the session already has full context, we just need the agent to
+ * re-output correctly formatted frontmatter without redoing any work.
+ */
+export function buildFrontmatterRetryPrompt(outputFormatInstruction: string): string {
+  const parts: string[] = [
+    "Your previous run completed all work successfully, but the output format was incorrect.",
+    "You do NOT need to redo any work — all changes are already in place.",
+    "",
+  ];
+  if (outputFormatInstruction !== "") {
+    parts.push(outputFormatInstruction, "");
+  }
+  parts.push(
+    "Please output ONLY the corrected YAML frontmatter block (--- delimited) followed by a brief summary of the work you completed.",
+  );
+  return parts.join("\n");
+}

packages/util-agent/src/index.ts

@@ -1,6 +1,7 @@
 export { buildContinuationPrompt } from "./build-continuation-prompt.js";
 export { buildOutputFormatInstruction } from "./build-output-format-instruction.js";
 export { buildRolePrompt } from "./build-role-prompt.js";
+export { buildThreadProgress } from "./build-thread-progress.js";
 export type { BuildContextMeta } from "./context.js";
 export { buildContext, buildContextWithMeta } from "./context.js";
 export type { ExtractResult, ResolvedLlmProvider } from "./extract.js";
@@ -11,13 +12,22 @@ export {
 } from "./extract.js";
 export type { FrontmatterFastPathResult } from "./frontmatter.js";
 export { tryFrontmatterFastPath } from "./frontmatter.js";
+export { buildFrontmatterRetryPrompt } from "./frontmatter-retry-prompt.js";
 export { createAgent, parseArgv } from "./run.js";
-export { getCachedSessionId, getCachePath, setCachedSessionId } from "./session-cache.js";
+export {
+  getAskSessionId,
+  getCachedSessionId,
+  getCachePath,
+  setAskSessionId,
+  setCachedSessionId,
+} from "./session-cache.js";
 export { getConfigPath, getEnvPath, loadWorkflowConfig, resolveStorageRoot } from "./storage.js";
 export type {
   AdapterOutput,
+  AgentCleanupFn,
   AgentContext,
   AgentContinueFn,
+  AgentForkFn,
   AgentOptions,
   AgentRunFn,
   AgentRunResult,

packages/util-agent/src/session-cache.ts

@@ -14,6 +14,10 @@ function cacheKey(threadId: ThreadId, role: string): string {
   return `${threadId}:${role}`;
 }
 
+function askCacheKey(stepHash: string): string {
+  return `${stepHash}:ask`;
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -86,3 +90,33 @@ export async function setCachedSessionId(
   cache[cacheKey(threadId, role)] = sessionId;
   await writeCache(agentName, storageRoot, cache);
 }
+
+/**
+ * Read the cached ask-session ID for a stepHash.
+ *
+ * Ask sessions are forked side conversations spawned by `step ask` from a
+ * specific completed step. They share the per-agent cache file with exec
+ * sessions but use the `<stepHash>:ask` key shape so the two namespaces
+ * never collide.
+ */
+export async function getAskSessionId(
+  agentName: string,
+  stepHash: string,
+  storageRoot: string,
+): Promise<string | null> {
+  const cache = await readCache(agentName, storageRoot);
+  const sessionId = cache[askCacheKey(stepHash)];
+  return sessionId ?? null;
+}
+
+/** Write the ask-session ID for a stepHash into the cache. */
+export async function setAskSessionId(
+  agentName: string,
+  stepHash: string,
+  sessionId: string,
+  storageRoot: string,
+): Promise<void> {
+  const cache = await readCache(agentName, storageRoot);
+  cache[askCacheKey(stepHash)] = sessionId;
+  await writeCache(agentName, storageRoot, cache);
+}

packages/util-agent/src/types.ts

@@ -50,6 +50,21 @@ export type AgentContinueFn = (
 
 export type AgentRunFn = (ctx: AgentContext) => Promise<AgentRunResult>;
 
+/**
+ * Fork an existing agent session, returning a new session ID that branches
+ * from the source session's state. Used by `step ask` (Phase 2a infrastructure)
+ * to spawn a side conversation from a completed step's session without
+ * polluting the original session's history.
+ */
+export type AgentForkFn = (sessionId: string, store: AgentContext["store"]) => Promise<string>;
+
+/**
+ * Clean up adapter-level resources (e.g. close ACP client, kill subprocesses).
+ * Invoked by the agent CLI factory after the run completes — regardless of
+ * success or failure — so adapters can release I/O handles deterministically.
+ */
+export type AgentCleanupFn = () => Promise<void>;
+
 export type AdapterOutput = {
   stepHash: string;
   detailHash: string;
@@ -65,4 +80,14 @@ export type AgentOptions = {
   name: string;
   run: AgentRunFn;
   continue: AgentContinueFn;
+  /**
+   * Optional session-fork hook. null means the adapter does not yet support
+   * `step ask` (Phase 2a placeholder — wired up in Phase 2b).
+   */
+  fork: AgentForkFn | null;
+  /**
+   * Optional cleanup hook invoked after the agent CLI completes. null means
+   * the adapter has no resources to release.
+   */
+  cleanup: AgentCleanupFn | null;
 };

packages/util/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@united-workforce/util",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "files": [
     "src",
     "dist",

packages/util/src/cli-reference.ts

@@ -29,8 +29,9 @@ uwf thread exec <thread-id>                       # execute one moderator→agen
                [-c, --count <number>]             # run multiple steps (default: 1)
                [--background]                     # run in background
 uwf thread show <thread-id>                       # show thread head pointer
-uwf thread list                                   # list threads
-               [--status <status>]                # filter: idle, running, or completed
+uwf thread list                                   # list active threads (idle + running)
+               [--all]                            # include completed/cancelled/suspended
+               [--status <status>]                # filter: idle, running, suspended, completed, cancelled, active
 uwf thread read <thread-id>                       # render thread context as markdown
                [--quota <chars>]                  # max output characters (default 32000)
                [--before <step-hash>]             # load steps before this hash (exclusive)

packages/util/src/usage-reference.ts

@@ -67,8 +67,9 @@ uwf thread exec <thread-id>                        # execute one step
                [-c, --count <n>]                   # run n steps
                [--background]                      # run in background
 uwf thread show <thread-id>                        # show head pointer
-uwf thread list                                    # list all threads
-               [--status <filter>]                 # idle, running, completed, cancelled, active (comma-separated)
+uwf thread list                                    # list active threads (idle + running)
+               [--all]                             # include completed/cancelled/suspended
+               [--status <filter>]                 # idle, running, suspended, completed, cancelled, active (comma-separated)
                [--after <thread-id>]               # pagination: after this thread
                [--before <thread-id>]              # pagination: before this thread
                [--skip <n>]                        # skip first n results
@@ -94,10 +95,15 @@ start → exec (repeat) → thread reaches $END → auto-completed
 uwf step list <thread-id>         # list all steps
 uwf step show <step-hash>         # show step details
 uwf step fork <step-hash>         # fork thread from a step (branch)
+uwf step ask <step-hash> -p <prompt> [--agent <cmd>] [--no-fork]
+                                  # ask a follow-up question to the step's agent
+                                  # (read-only; no new step, no thread mutation)
 \`\`\`
 
 Forking creates a new thread that shares history up to the fork point — useful for retrying from a known-good state.
 
+\`step ask\` re-opens the agent session that produced \`<step-hash>\` and returns its answer on stdout. Subsequent asks reuse the same forked session via the per-agent ask-cache; \`--no-fork\` runs the agent fresh with the step's detail ref injected for context.
+
 ## CAS Commands
 
 Use the \`ocas\` CLI for direct CAS operations (\`~/.ocas/\` store, shared with \`uwf\`):
@@ -140,5 +146,18 @@ For specific scenarios, run the corresponding \`uwf prompt\` command:
 |----------|---------|-------------|
 | Writing workflow YAML | \`uwf prompt workflow-authoring\` | Designing roles, conditions, graphs, and edge prompts |
 | Building a new agent adapter | \`uwf prompt adapter-developing\` | Creating a new \`uwf-<name>\` CLI adapter |
+
+## Upgrading
+
+\`\`\`bash
+# Install the latest version
+pnpm add -g @united-workforce/cli@latest @united-workforce/agent-hermes@latest
+# or: npm install -g @united-workforce/cli@latest @united-workforce/agent-hermes@latest
+
+# Verify
+uwf --version
+
+# Then run uwf prompt bootstrap and follow the upgrade instructions
+\`\`\`
 `;
 }

pnpm-lock.yaml

@@ -18,8 +18,8 @@ importers:
         specifier: ^2.31.0
         version: 2.31.0(@types/node@25.9.1)
       '@shazhou/proman':
-        specifier: ^0.5.1
-        version: 0.5.1(@biomejs/biome@2.4.16)(typescript@5.9.3)(vite@7.3.5(@types/node@25.9.1)(jiti@2.7.0)(lightningcss@1.32.0)(yaml@2.9.0))(vitest@3.2.6(@types/node@25.9.1)(jiti@2.7.0)(lightningcss@1.32.0)(msw@2.14.6(@types/node@25.9.1)(typescript@5.9.3))(yaml@2.9.0))
+        specifier: ^0.6.3
+        version: 0.6.3(@biomejs/biome@2.4.16)(typescript@5.9.3)(vite@7.3.5(@types/node@25.9.1)(jiti@2.7.0)(lightningcss@1.32.0)(yaml@2.9.0))(vitest@3.2.6(@types/node@25.9.1)(jiti@2.7.0)(lightningcss@1.32.0)(msw@2.14.6(@types/node@25.9.1)(typescript@5.9.3))(yaml@2.9.0))
       '@types/node':
         specifier: ^25.7.0
         version: 25.9.1
@@ -45,8 +45,8 @@ importers:
   packages/agent-builtin:
     dependencies:
       '@ocas/core':
-        specifier: ^0.3.0
-        version: 0.3.0
+        specifier: ^0.4.0
+        version: 0.4.0
       '@united-workforce/util':
         specifier: workspace:^
         version: link:../util
@@ -61,8 +61,8 @@ importers:
   packages/agent-claude-code:
     dependencies:
       '@ocas/core':
-        specifier: ^0.3.0
-        version: 0.3.0
+        specifier: ^0.4.0
+        version: 0.4.0
       '@united-workforce/protocol':
         specifier: workspace:^
         version: link:../protocol
@@ -80,8 +80,8 @@ importers:
   packages/agent-hermes:
     dependencies:
       '@ocas/core':
-        specifier: ^0.3.0
-        version: 0.3.0
+        specifier: ^0.4.0
+        version: 0.4.0
       '@united-workforce/protocol':
         specifier: workspace:^
         version: link:../protocol
@@ -99,8 +99,8 @@ importers:
   packages/agent-mock:
     dependencies:
       '@ocas/core':
-        specifier: ^0.3.0
-        version: 0.3.0
+        specifier: ^0.4.0
+        version: 0.4.0
       '@united-workforce/protocol':
         specifier: workspace:^
         version: link:../protocol
@@ -121,11 +121,11 @@ importers:
   packages/cli:
     dependencies:
       '@ocas/core':
-        specifier: ^0.3.0
-        version: 0.3.0
+        specifier: ^0.4.0
+        version: 0.4.0
       '@ocas/fs':
-        specifier: ^0.3.0
-        version: 0.3.0
+        specifier: ^0.4.0
+        version: 0.4.0
       '@united-workforce/protocol':
         specifier: workspace:^
         version: link:../protocol
@@ -231,11 +231,11 @@ importers:
   packages/eval:
     dependencies:
       '@ocas/core':
-        specifier: ^0.3.0
-        version: 0.3.0
+        specifier: ^0.4.0
+        version: 0.4.0
       '@ocas/fs':
-        specifier: ^0.3.0
-        version: 0.3.0
+        specifier: ^0.4.0
+        version: 0.4.0
       '@united-workforce/protocol':
         specifier: workspace:^
         version: link:../protocol
@@ -256,11 +256,11 @@ importers:
   packages/protocol:
     dependencies:
       '@ocas/core':
-        specifier: ^0.3.0
-        version: 0.3.0
+        specifier: ^0.4.0
+        version: 0.4.0
       '@ocas/fs':
-        specifier: ^0.3.0
-        version: 0.3.0
+        specifier: ^0.4.0
+        version: 0.4.0
     devDependencies:
       typescript:
         specifier: ^5.8.3
@@ -275,11 +275,11 @@ importers:
   packages/util-agent:
     dependencies:
       '@ocas/core':
-        specifier: ^0.3.0
-        version: 0.3.0
+        specifier: ^0.4.0
+        version: 0.4.0
       '@ocas/fs':
-        specifier: ^0.3.0
-        version: 0.3.0
+        specifier: ^0.4.0
+        version: 0.4.0
       '@united-workforce/protocol':
         specifier: workspace:^
         version: link:../protocol
@@ -892,11 +892,13 @@ packages:
     resolution: {integrity: sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==}
     engines: {node: '>= 8'}
 
-  '@ocas/core@0.3.0':
-    resolution: {integrity: sha512-ejDDZbmQkTj2GoJg+cNjXa3eHlQGybW3PrUZlwERBvBFjjnYBLHOG7AQQYM48bI52UiqucafgZjPEYk9SZd6AQ==}
+  '@ocas/core@0.4.0':
+    resolution: {integrity: sha512-6JvHd3nr5GncMOBNaZTf9ZTWou/txONTfZbkrblmgqL/H+YuRj1FfeFY+b1ndUlfwR7AuJ6bvoSxR5RP+AbC0w==}
+    engines: {node: '>=22.5.0'}
 
-  '@ocas/fs@0.3.0':
-    resolution: {integrity: sha512-/6/nICYVJWXeWx2LcPoHHJAFoqXpJoAtvhLKLS0zpkwtsZX3g0D9X6J5soHCV1QS+BOWybuOJ0+W3cB1FBRkZA==}
+  '@ocas/fs@0.4.0':
+    resolution: {integrity: sha512-AQG6dk1YCL1qpSszUWUgEY+LQhYbTv5hXYrs3J2pHAi2/lY615O2cTgjwEeh6JTcrqHsFwiDsDdKIKMpADchZA==}
+    engines: {node: '>=22.5.0'}
 
   '@open-draft/deferred-promise@2.2.0':
     resolution: {integrity: sha512-CecwLWx3rhxVQF6V4bAgPS5t+So2sTbPgAzafKkVizyi7tlwpcFpdFqq+wqF2OwNBmqFuu6tOyouTuxgpMfzmA==}
@@ -1152,8 +1154,8 @@ packages:
   '@sec-ant/readable-stream@0.4.1':
     resolution: {integrity: sha512-831qok9r2t8AlxLko40y2ebgSDhenenCatLVeW/uBtnHPyhHOvG0C7TvfgecV+wHzIm5KUICgzmVpWS+IMEAeg==}
 
-  '@shazhou/proman@0.5.1':
-    resolution: {integrity: sha512-GmFUvd8SAOUW/eaDIEh31pVKSE3XhbgHOZ5vSpX4xS+F8Zl6lAfhgVCjcjRK8w5d43tsH47CVorwyxQcRaJFfA==}
+  '@shazhou/proman@0.6.3':
+    resolution: {integrity: sha512-KguWl1xHrWXx1YWYrWj47v4NRbaQuKCm7Hd7T8dzrqnkM8UL8em3R9rC7GeDzI8YDDfriFeLTX+xb03UHkhTDA==}
     hasBin: true
     peerDependencies:
       '@biomejs/biome': ^2.0.0
@@ -3896,16 +3898,16 @@ snapshots:
       '@nodelib/fs.scandir': 2.1.5
       fastq: 1.20.1
 
-  '@ocas/core@0.3.0':
+  '@ocas/core@0.4.0':
     dependencies:
       ajv: 8.20.0
       cborg: 4.5.8
       liquidjs: 10.27.0
       xxhash-wasm: 1.1.0
 
-  '@ocas/fs@0.3.0':
+  '@ocas/fs@0.4.0':
     dependencies:
-      '@ocas/core': 0.3.0
+      '@ocas/core': 0.4.0
       cborg: 4.5.8
 
   '@open-draft/deferred-promise@2.2.0': {}
@@ -4049,7 +4051,7 @@ snapshots:
 
   '@sec-ant/readable-stream@0.4.1': {}
 
-  '@shazhou/proman@0.5.1(@biomejs/biome@2.4.16)(typescript@5.9.3)(vite@7.3.5(@types/node@25.9.1)(jiti@2.7.0)(lightningcss@1.32.0)(yaml@2.9.0))(vitest@3.2.6(@types/node@25.9.1)(jiti@2.7.0)(lightningcss@1.32.0)(msw@2.14.6(@types/node@25.9.1)(typescript@5.9.3))(yaml@2.9.0))':
+  '@shazhou/proman@0.6.3(@biomejs/biome@2.4.16)(typescript@5.9.3)(vite@7.3.5(@types/node@25.9.1)(jiti@2.7.0)(lightningcss@1.32.0)(yaml@2.9.0))(vitest@3.2.6(@types/node@25.9.1)(jiti@2.7.0)(lightningcss@1.32.0)(msw@2.14.6(@types/node@25.9.1)(typescript@5.9.3))(yaml@2.9.0))':
     dependencies:
       '@biomejs/biome': 2.4.16
       typescript: 5.9.3

workflows/solve-issue.yaml

@@ -1,329 +0,0 @@
-name: solve-issue
-description: TDD-driven issue resolution adapted for the workflow monorepo with bun + vitest
-roles:
-  planner:
-    description: Analyzes issue and outputs a TDD test spec
-    goal: You are a planning agent. You analyze Gitea issues and produce a TDD test specification that downstream roles will implement and verify.
-    capabilities:
-    - issue-analysis
-    - planning
-    procedure: 'On first run (no previous steps):
-
-      1. Read the issue and all comments from Gitea using `tea issues <number> -r <owner/repo>`
-
-      2. Look for project conventions files (CLAUDE.md, CONTRIBUTING.md) in the repo
-
-      3. Assess whether the issue has enough information to produce a test spec
-
-      4. If insufficient info: comment on the issue via `echo "..." | tea comment <number> -r <owner/repo>` (skip if you already commented), then output $status=insufficient_info
-
-      5. If sufficient: produce a detailed TDD test spec in markdown covering all scenarios
-
-
-      On subsequent runs (bounced back by tester with fix_spec):
-
-      1. Read the tester''s output from the previous step to understand what''s wrong with the spec
-
-      2. Revise the test spec accordingly
-
-
-      After producing the test spec:
-
-      1. The test spec is stored in CAS automatically by the uwf pipeline (agents do not need to call `ocas put` directly)
-
-      2. Put the hash in frontmatter.plan (required when $status=ready)
-
-      3. Set repoPath to the absolute path of the repository root
-
-
-
-      IMPORTANT: Extract the repo remote (owner/repo) from git:
-
-      ```bash
-
-      git remote get-url origin | sed ''s|.*[:/]\([^/]*/[^.]*\).*|\1|''
-
-      ```
-
-      Store the result as repoRemote in your frontmatter output so downstream roles can use it for tea/API calls.'
-    output: Output a brief summary of the test spec. Set $status to ready (with plan hash and repoPath) or insufficient_info.
-    frontmatter:
-      oneOf:
-      - properties:
-          $status:
-            const: ready
-          plan:
-            type: string
-          repoPath:
-            type: string
-          repoRemote:
-            type: string
-        required:
-        - $status
-        - plan
-        - repoPath
-      - properties:
-          $status:
-            const: insufficient_info
-          reason:
-            type: string
-        required:
-        - $status
-        - reason
-  developer:
-    description: TDD implementation per test spec
-    goal: You are a developer agent. You implement code changes following TDD — write tests first, then implementation.
-    capabilities:
-    - coding
-    procedure: "IMPORTANT: Always work in a git worktree, NEVER modify the main working directory directly.\nThe repo path and other details are provided in your task prompt.\n\nBefore starting any work,\
-      \ set up an isolated worktree:\n1. cd into the repo path provided in your task prompt\n2. `git fetch origin` to get latest refs\n3. First time (no existing branch):\n   - `git worktree add .worktrees/fix/<issue-number>-<short-slug>\
-      \ -b fix/<issue-number>-<short-slug> origin/main`\n   - `cd .worktrees/fix/<issue-number>-<short-slug> && bun install`\n4. If bounced back from reviewer or tester (branch already exists):\n   - cd\
-      \ into the existing worktree under `.worktrees/fix/<issue-number>-<short-slug>`\n   - `git fetch origin && git rebase origin/main`\n5. ALL subsequent work must happen inside the worktree directory.\n\
-      \nThen implement TDD:\n6. Read the test spec from CAS: `ocas get <plan hash>` (find the hash from the planner's output in your task prompt)\n7. If bounced back from reviewer or tester: read the\
-      \ previous role's feedback in your task prompt\n8. Write tests first based on the spec (use vitest)\n9. Implement the code to make tests pass\n10. Ensure `bun run build` passes with no errors\n11.\
-      \ Run `bun test` to verify all tests pass\n\nIf you cannot complete the implementation (e.g. the issue is too complex, blocked by external factors,\nor repeated attempts fail), set $status=failed\
-      \ with a reason.\n"
-    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
-          repoRemote:
-            type: string
-        required:
-        - $status
-        - branch
-        - worktree
-      - properties:
-          $status:
-            const: failed
-          reason:
-            type: string
-          repoRemote:
-            type: string
-        required:
-        - $status
-        - reason
-  reviewer:
-    description: Code standards compliance check
-    goal: You are a code reviewer. You verify code standards compliance — NOT functionality (that's the tester's job).
-    capabilities:
-    - code-review
-    - static-analysis
-    procedure: 'The worktree path is provided in your task prompt. cd into it first.
-
-
-      Before reviewing, verify the git branch:
-
-      1. Run `git branch --show-current` — confirm the branch name references the issue number being worked on
-
-      2. If the branch doesn''t correspond to the issue, flag it in your output and reject
-
-
-      Then perform code review:
-
-      Hard checks (must all pass):
-
-      3. `bun run build` — no build errors
-
-      4. `bunx biome check` — no lint violations
-
-      5. TypeScript strict mode — no type errors
-
-
-      Soft checks (review against project conventions from CLAUDE.md):
-
-      - Functional-first: functions + types, no classes (except for errors or third-party requirements)
-
-      - Named exports only, no default exports
-
-      - No optional properties (use `T | null` instead of `?:`)
-
-      - Folder module discipline: index.ts only re-exports, types in types.ts
-
-      - Crockford Base32 log tags (8-char, unique per call site)
-
-      - No `console.log` in production code (use createLogger from @united-workforce/util)
-
-      - No dynamic imports in production code
-
-
-      Only review standards compliance. Do NOT test functionality.
-
-      If rejecting, you MUST explain the specific reason in your output.
-
-      '
-    output: Explain your decision with specific file/line references. Set $status to approved (with branch/worktree) or rejected (with comments).
-    frontmatter:
-      oneOf:
-      - properties:
-          $status:
-            const: approved
-          branch:
-            type: string
-          worktree:
-            type: string
-          repoRemote:
-            type: string
-        required:
-        - $status
-        - branch
-        - worktree
-      - properties:
-          $status:
-            const: rejected
-          comments:
-            type: string
-          worktree:
-            type: string
-          repoRemote:
-            type: string
-        required:
-        - $status
-        - comments
-        - worktree
-  tester:
-    description: Functional correctness verification
-    goal: You are a tester agent. You verify that the implementation correctly satisfies every scenario in the test spec.
-    capabilities:
-    - testing
-    procedure: "The worktree path is provided in your task prompt. cd into it first.\n\n1. Run `bun test` for automated test verification\n2. Read the test spec from CAS: `ocas get <plan hash>` (find\
-      \ the hash from the planner step in the thread history)\n3. Verify each scenario in the spec is covered and passing\n4. Determine outcome:\n   - passed: all scenarios verified, tests pass\n   - fix_code:\
-      \ tests fail or implementation doesn't match spec → send back to developer\n   - fix_spec: the spec itself is wrong or incomplete → send back to planner\n"
-    output: Report test results per scenario. Set $status to passed (with branch/worktree), fix_code (with report), or fix_spec (with report).
-    frontmatter:
-      oneOf:
-      - properties:
-          $status:
-            const: passed
-          branch:
-            type: string
-          worktree:
-            type: string
-          repoRemote:
-            type: string
-        required:
-        - $status
-        - branch
-        - worktree
-      - properties:
-          $status:
-            const: fix_code
-          report:
-            type: string
-          repoRemote:
-            type: string
-          worktree:
-            type: string
-          branch:
-            type: string
-        required:
-        - $status
-        - report
-      - properties:
-          $status:
-            const: fix_spec
-          report:
-            type: string
-          repoRemote:
-            type: string
-          worktree:
-            type: string
-          branch:
-            type: string
-        required:
-        - $status
-        - report
-  committer:
-    description: Commits and creates PR
-    goal: You are a committer agent. You create a clean commit and push a PR linking the original issue.
-    capabilities: []
-    procedure: "The worktree path, branch name, and repo remote (owner/repo) are provided in your task prompt.\ncd into the worktree first.\n\nNote: You inherit the developer's worktree and branch. Do NOT\
-      \ create a new branch.\n1. Stage all changes: `git add -A`\n2. Commit with a descriptive message referencing the issue: `git commit -m \"type: description\\n\\nFixes #N\"`\n3. Push the branch: `git\
-      \ push -u origin <branch-name>`\n4. **Verify push succeeded** — run `git ls-remote origin <branch-name>` and confirm it prints a commit hash.\n   - If no output or push failed: capture the error, mark hook_failed\n\
-      5. Create a PR using the Gitea API (do NOT use `tea pr create` — it fails in worktrees):\n   ```bash\n   GITEA_TOKEN=$(cfg get GITEA_TOKEN)\n   curl -s -X POST -H \"Authorization: token $GITEA_TOKEN\" -H \"Content-Type: application/json\" \\\n\
-      \     \"https://git.shazhou.work/api/v1/repos/<owner>/<repo>/pulls\" \\\n     -d '{\"title\":\"...\",\"body\":\"...\",\"head\":\"<branch>\",\"base\":\"main\"}'\n   ```\n   - The repo remote (owner/repo format, e.g. \"shazhou/united-workforce\") is given in your task prompt — use it directly.\n\
-      \   - PR body must include: What / Why / Changes / Ref sections, with `Fixes #N` in Ref\n6. **Verify PR was created** — parse the curl response JSON: it must contain a `\"number\"` field. Print the PR URL.\n\
-      \   - If curl returns an error or no number field: capture the response, mark hook_failed\n7. After PR creation, clean up the worktree:\n   - cd to the repo root (parent of .worktrees)\n   - `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
-          repoRemote:
-            type: string
-          worktree:
-            type: string
-          branch:
-            type: string
-        required:
-        - $status
-        - prUrl
-      - properties:
-          $status:
-            const: hook_failed
-          error:
-            type: string
-          repoRemote:
-            type: string
-          worktree:
-            type: string
-          branch:
-            type: string
-        required:
-        - $status
-        - error
-graph:
-  $START:
-    new:
-      role: planner
-      prompt: Analyze the issue and produce an implementation plan.
-    resume:
-      role: planner
-      prompt: Review the previous run output and continue the work.
-  planner:
-    insufficient_info:
-      role: $SUSPEND
-      prompt: "信息不足，需要补充：{{{reason}}}"
-    ready:
-      role: developer
-      prompt: 'Implement the TDD test spec (CAS hash: {{{plan}}}) in repo {{{repoPath}}}. Repo remote: {{{repoRemote}}}.'
-  developer:
-    done:
-      role: reviewer
-      prompt: 'Review branch {{{branch}}} at {{{worktree}}} for code standards compliance. Repo remote: {{{repoRemote}}}.'
-    failed:
-      role: $END
-      prompt: 'Developer failed: {{{reason}}}. Ending workflow.'
-  reviewer:
-    rejected:
-      role: developer
-      prompt: 'Reviewer rejected: {{{comments}}}. Fix the issues in repo {{{worktree}}}. Repo remote: {{{repoRemote}}}.'
-    approved:
-      role: tester
-      prompt: 'Review passed. Run tests on branch {{{branch}}} at {{{worktree}}}. Repo remote: {{{repoRemote}}}.'
-  tester:
-    fix_code:
-      role: developer
-      prompt: 'Tests found code issues: {{{report}}}. Fix and re-submit. Worktree: {{{worktree}}}. Repo remote: {{{repoRemote}}}.'
-    fix_spec:
-      role: planner
-      prompt: 'Tests found spec issues: {{{report}}}. Revise the test spec. Repo remote: {{{repoRemote}}}.'
-    passed:
-      role: committer
-      prompt: 'All tests passed. Commit and push branch {{{branch}}} from {{{worktree}}}. Repo remote (owner/repo): {{{repoRemote}}}.'
-  committer:
-    hook_failed:
-      role: developer
-      prompt: 'Push hook failed: {{{error}}}. Fix and re-submit. Worktree: {{{worktree}}}. Repo remote: {{{repoRemote}}}.'
-    committed:
-      role: $END
-      prompt: 'PR created: {{{prUrl}}}. Workflow complete.'