pi-claude-supervisor 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented here.
 
+## [0.5.0](https://github.com/btnalit/pi-claude-supervisor/compare/v0.4.1...v0.5.0) (2026-09-14)
+
+
+### Features
+
+* add acceptance review repair loop ([fe29c78](https://github.com/btnalit/pi-claude-supervisor/commit/fe29c78a228494768aa52b03ee1bf1545b079119))
+
+## [Unreleased]
+
+### Added
+
+- Structured task specifications with Goal, scope, constraints, forbidden actions and multiple argv-based acceptance checks.
+- Independent read-only Reviewer results with bounded findings and automatic repair rounds.
+- JSONL malformed-record handling and duplicate result/permission suppression fixtures.
+- Active JSONL request shutdown coverage and deterministic acceptance/review tests.
+
 ## [0.4.1](https://github.com/btnalit/pi-claude-supervisor/compare/v0.4.0...v0.4.1) (2026-09-14)
 
 

package/README.cn.md

@@ -51,6 +51,7 @@ Claude CLI `2.1.270` 运行，跨版本兼容性不在本轮范围内。
 ```text
 /supervise capabilities
 /supervise start inspect the current repository
+/supervise start --spec ./task.json
 /supervise poll
 /supervise sessions
 /supervise recover <task-id>
@@ -61,6 +62,21 @@ Claude CLI `2.1.270` 运行，跨版本兼容性不在本轮范围内。
 /supervise resume-auto <task-id>
 ```
 
+`--spec` 接受 JSON 文件；验收命令始终使用 argv 执行，不经过 shell。例如：
+
+```json
+{
+  "goal": "实现请求的修改",
+  "scope": ["src/"],
+  "constraints": ["保持公共 API 兼容"],
+  "forbidden": ["不要发布构建产物"],
+  "acceptance": [
+    { "id": "tests", "name": "tests", "command": "npm", "args": ["test"], "required": true }
+  ],
+  "maxRepairRounds": 3
+}
+```
+
 人工升级通知的 generic JSON 格式为：
 
 ```json
@@ -84,6 +100,12 @@ Claude CLI `2.1.270` 运行，跨版本兼容性不在本轮范围内。
 再根据任务和仓库证据自动回答；无法确定时才升级人工。如需微信内闭环，需要另建带签名验证、
 一次性 action token 和重放保护的入站 callback 服务。
 
+近期自动化目标是先稳定完成“多命令验收—独立只读 Reviewer—结构化修复轮次—再次验收”闭环。
+任务可通过 API 或 JSON spec 提供 `goal`、`scope`、`constraints`、`forbidden` 和多个
+`acceptance` 命令；旧的纯文本任务继续使用默认 `git diff --check`。Reviewer 只能使用
+`read`、`grep`、`find`、`ls`，不会修改工作树或批准权限。当前稳定性验证固定针对 Claude Code
+`2.1.270`，暂不把多版本兼容、sandbox、低权限和网络隔离作为本阶段门禁。
+
 ### tmux/PTY 交互模式
 
 如果希望在可见的 Claude Code 终端中工作，可显式启用 tmux transport：

package/README.md

@@ -57,6 +57,7 @@ export PI_CLAUDE_SUPERVISOR_WORKER=claude
 ```text
 /supervise capabilities
 /supervise start inspect the current repository and report what should be changed
+/supervise start --spec ./task.json
 /supervise sessions
 /supervise recover <task-id>
 /supervise poll
@@ -68,6 +69,22 @@ export PI_CLAUDE_SUPERVISOR_WORKER=claude
 /supervise verify
 ```
 
+`--spec` accepts a JSON file; checks are always executed with argv (never through
+a shell), for example:
+
+```json
+{
+  "goal": "Implement the requested change",
+  "scope": ["src/"],
+  "constraints": ["Keep the public API compatible"],
+  "forbidden": ["Do not publish artifacts"],
+  "acceptance": [
+    { "id": "tests", "name": "tests", "command": "npm", "args": ["test"], "required": true }
+  ],
+  "maxRepairRounds": 3
+}
+```
+
 The default MVP writes the task to the worker's stdin as plain process-pipe
 text. After running the transport spike for the target CLI, JSONL framing can
 be selected explicitly:
@@ -88,6 +105,14 @@ remaining lifecycle, signal and recovery checks. Host permissions and network
 access follow explicit caller authorization and host policy; there is no
 automatic merge, deploy, release or publish.
 
+The near-term automation milestone adds a structured acceptance pipeline:
+multiple argv-based checks, an independent read-only Reviewer, bounded structured
+findings and repair rounds. Legacy text tasks keep the default `git diff --check`.
+The Reviewer only has `read`, `grep`, `find` and `ls`; it cannot edit files or grant
+permissions. Stability evidence is pinned to Claude Code `2.1.270`; CLI
+multi-version compatibility, sandboxing, low-privilege execution and network
+isolation are not part of this milestone.
+
 Automatic mode persists the Pi Decision Worker session under the configured state
 directory. After an unclean Pi restart, `/supervise sessions` lists recoverable
 tasks; `/supervise recover <task-id>` explicitly restores the Decision Worker

package/docs/architecture.md

@@ -181,6 +181,29 @@ human operator; it does not attempt a second LLM fallback. Alert delivery is
 kept independent from event-log persistence so an audit write failure cannot
 suppress the alert.
 
+## Acceptance, review and repair loop
+
+A task may provide a structured `TaskSpec` with `goal`, `scope`, `constraints`,
+`forbidden` and an ordered list of required or optional acceptance checks. A
+legacy plain-text task is normalized to a goal with the default `git diff
+--check` acceptance check. The verifier runs every configured check with argv,
+bounded output and the same deterministic command policy; a Worker completion
+claim never substitutes for these results.
+
+When automatic supervision is enabled, a successful check set is passed to a
+fresh read-only Reviewer session. The Reviewer receives the task specification, repository status/diff evidence,
+check results and bounded Worker completion evidence, but not the Decision Worker
+conversation or control channel. It can inspect only `read`, `grep`, `find` and `ls`, and must return
+`pass`, `revise` or `human` with bounded structured findings. Invalid Reviewer
+output or a Reviewer API failure is a human-required condition.
+
+A `revise` result produces an audited repair round and sends a bounded corrective
+instruction to a still-live JSONL/tmux Worker. Checks and review then run again.
+The repair budget defaults to three rounds; repeated findings and P0/P1 findings
+stop automation and escalate. A non-persistent Worker that has already exited
+cannot be silently recreated for repair; it remains failed/recoverable rather
+than replaying the original task.
+
 ## Deliberate non-goals
 
 - automatic merge/deploy/release;
@@ -192,4 +215,7 @@ suppress the alert.
 - shell command interpolation;
 - automatic network denial or a fake domain allowlist. Network access follows
   Claude's own permission model and the command policy; suspicious download-to-
-  shell patterns require human review rather than blanket network rejection.
+  shell patterns require human review rather than blanket network rejection;
+- Claude CLI multi-version compatibility in the current stability milestone;
+- OS sandbox, low-privilege execution and network isolation in the current
+  lifecycle milestone.

package/docs/engineering-plan.md

@@ -916,3 +916,66 @@ PTY 和 headless JSONL 只能选择一个作为 MVP 的主 transport，禁止两
 ## 附录 B：一句话版本
 
 > 先用最小、可审计、可接管的 Supervisor 闭环证明可靠性，再逐步开放 LLM 判断和自动化权限；不要从“自动化最多”开始，而要从“边界最清楚、证据最可靠”开始。
+
+## 20. 近期落地与剩余门禁：稳定的自动验收闭环
+
+本轮已落地 TaskSpec、多命令验收、独立只读 Reviewer、结构化 repair round、重复 finding/P0/P1 人工升级、JSONL 去重和确定性 replay fixture。剩余门禁是固定 CLI 的重复运行统计，而不是继续扩大安全边界。近期目标从“扩大安全边界”调整为先证明单一已验证 Claude CLI 版本上的真实功能稳定性。当前只验证固定的 Claude Code `2.1.270`，不把多版本兼容作为本阶段任务。OS sandbox、低权限用户、网络 allowlist、SBOM 和更深的供应链加固后置，不作为本阶段门禁；现有 no-shell、Policy Gate、人工接管和独立验收边界继续保留。
+
+### 20.1 Goal / Evidence / Sign-off 模型
+
+任务规格统一为：
+
+```yaml
+ goal: 实现用户邀请接口
+ scope:
+   - 新增接口
+   - 添加权限校验
+ constraints:
+   - 不修改核心数据库模型
+ forbidden:
+   - 不执行生产部署
+ acceptance:
+   - id: tests
+     command: npm
+     args: [test]
+   - id: typecheck
+     command: npm
+     args: [run, typecheck]
+   - id: diff-check
+     command: git
+     args: [diff, --check]
+ maxRepairRounds: 3
+```
+
+兼容旧任务时，普通任务文本作为 `goal`，默认验收仍为 `git diff --check`。所有验收命令使用 argv 和确定性 Policy Gate，不经过 shell。
+
+验收流程固定为：
+
+```text
+Worker result
+  → 多命令 acceptance checks
+  → 独立只读 Reviewer
+      ├── pass   → completed
+      ├── revise → 结构化修复指令 → Worker → 重新验收
+      └── human  → 人工接管
+```
+
+Reviewer 必须使用独立 Pi session，只允许 `read`、`grep`、`find`、`ls`，输出结构化 verdict 和 findings；不能修改工作树或直接批准权限。默认最多三轮修复；相同 finding 重复出现或出现 P0/P1 问题时升级人工。
+
+### 20.2 JSONL 稳定性证据
+
+只对 Claude Code `2.1.270` 建立证据，覆盖：
+
+- JSONL 跨 chunk 拆分、单 chunk 多记录和 malformed 行；malformed 行不能触发完成事件；
+- 重复 result、重复 permission request、重复 Supervisor idempotency key 不产生重复动作；
+- active request 期间的 SIGTERM、SIGINT、stop 和 Pi shutdown；
+- 普通完成、低风险 Bash allow、`AskUserQuestion` deny-to-text、多轮、验收失败修复和恢复回放。
+
+真实 Claude Spike 不进入普通 CI；确定性 fake Worker/replay fixture 进入 CI。自动模式继续保持显式 opt-in，直到以下门禁通过：普通任务连续十次成功，权限和问题转文本场景各至少五次成功，无重复动作、无错误 complete、无未清理 Worker，且关键事件可以完整回放。
+
+### 20.3 明确不属于本阶段
+
+- Claude CLI 多版本兼容；
+- OS sandbox、低权限执行和网络隔离；
+- 自动 merge、deploy、release、publish；
+- 多 Worker 在同一工作树协作。

package/docs/testing.md

@@ -49,9 +49,9 @@ non-sensitive prompt, and prints protocol metadata rather than raw model output.
 It must not be added to the normal CI gate because authentication is an owner
 controlled prerequisite.
 
-The historical fixtures validate one prompt, multiple turns, session resume,
-permission allow/deny and SIGTERM/SIGINT behavior with Claude Code 2.1.268.
-The current release validation uses Claude Code 2.1.270 at
+The transport fixtures validate one prompt, multiple turns, session resume,
+permission allow/deny and SIGTERM/SIGINT behavior. The current release validation
+uses Claude Code 2.1.270 at
 `/home/yancao/.local/share/mise/installs/claude/2.1.270/claude`, including real
 owned tmux turns, pause/resume, and restart re-adoption.
 The adapter regression suite also verifies event subscription, parsed
@@ -59,6 +59,11 @@ The adapter regression suite also verifies event subscription, parsed
 The automation spike additionally exercises a real Pi SDK Decision Worker with
 Claude: ordinary completion, harmless Bash permission approval, and an
 `AskUserQuestion` denial-to-text fallback followed by automatic verification.
+A local pinned-CLI run completed all three scenarios with `state=completed`,
+`verified=true`, and zero human interventions. Provider/model latency can still
+cause a later run to fail closed as human-required after the bounded Decision
+Worker or Reviewer timeout; this is evidence for the manual spike only, not a CI
+guarantee.
 The extension persists each automatic Decision Worker session as Pi JSONL plus a
 0600 task mapping. Recovery is explicit and safe: after an unclean Pi restart,
 `/supervise sessions` shows the task as `recoverable`, and `/supervise recover
@@ -144,3 +149,43 @@ not eliminate the post-spawn attachment window. `SIGSTOP` and `SIGKILL` of the P
 verify and document the resulting orphan behavior.
 Default behavior must be fail-closed and leave no orphaned worker process within
 the managed process group.
+
+## Near-term automation acceptance gate
+
+The next implementation milestone focuses on real stability for the pinned
+Claude Code `2.1.270` CLI. It does not add a multi-version matrix or wait for
+OS sandbox, low-privilege or network-isolation work.
+
+### Acceptance and Reviewer fixtures
+
+Deterministic tests must cover:
+
+- legacy text tasks normalized to a Goal with the default `git diff --check`;
+- multiple required/optional checks with bounded output, timeout and exit-code evidence;
+- independent read-only Reviewer pass/revise/human results;
+- invalid Reviewer JSON and Reviewer API failure escalating to human;
+- repair rounds, repeated finding detection, P0/P1 escalation and repair-budget exhaustion;
+- completion being impossible without passing all required checks and review.
+
+Reviewer sessions use only `read`, `grep`, `find` and `ls`; they must not modify
+the worktree or send Worker input. Decision Worker and Reviewer model calls are
+bounded; timeout or API failure escalates instead of auto-completing. Review reports
+are persisted as bounded event payloads and are not treated as permission grants.
+
+### JSONL protocol and replay fixtures
+
+The adapter/replay matrix must cover:
+
+- JSON split across stdout chunks and multiple records in one chunk;
+- malformed JSON between valid records without a false completion event;
+- duplicate result and permission records without duplicate actions;
+- duplicate Supervisor idempotency keys without duplicate input;
+- stop, SIGTERM, SIGINT and Pi shutdown while a JSONL request is active;
+- ordinary completion, low-risk permission allow, AskUserQuestion deny-to-text,
+  multi-turn, verifier failure/repair, takeover and explicit recovery.
+
+Real Claude tests remain authenticated manual Spikes and are pinned to
+`2.1.270`; they are not part of normal CI. Normal CI runs deterministic fake
+Worker and replay fixtures. Stability evidence should include ten consecutive
+ordinary automatic runs and at least five runs each for permission and question
+handling, with no duplicate action, false completion or unreaped Worker.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-claude-supervisor",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "A policy-gated Pi supervisor for observing and verifying Claude Code workers.",
   "license": "MIT",
   "publishConfig": {

package/src/acceptance.ts

@@ -0,0 +1,84 @@
+import type { AcceptanceCheck, TaskSpec } from "./types.ts";
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_MAX_REPAIR_ROUNDS = 3;
+
+/** Normalize legacy plain-text tasks into the structured acceptance model. */
+export function normalizeTaskSpec(value: unknown, fallbackGoal: string): TaskSpec {
+  if (value !== undefined && (!value || typeof value !== "object" || Array.isArray(value))) {
+    throw new Error("task spec must be a JSON object");
+  }
+  const source = (value ?? {}) as Record<string, unknown>;
+  const goal = typeof source.goal === "string" && source.goal.trim() ? source.goal.trim() : fallbackGoal.trim();
+  if (!goal) throw new Error("task goal must not be empty");
+  return {
+    goal,
+    scope: stringList(source.scope, "scope"),
+    constraints: stringList(source.constraints, "constraints"),
+    forbidden: stringList(source.forbidden, "forbidden"),
+    acceptance: normalizeChecks(source.acceptance),
+    maxRepairRounds: normalizeRepairRounds(source.maxRepairRounds),
+  };
+}
+
+export function defaultAcceptanceChecks(): AcceptanceCheck[] {
+  return [{
+    id: "diff-check",
+    name: "git diff check",
+    command: "git",
+    args: ["diff", "--check"],
+    required: true,
+    timeoutMs: DEFAULT_TIMEOUT_MS,
+  }];
+}
+
+function normalizeChecks(value: unknown): AcceptanceCheck[] {
+  if (value === undefined) return defaultAcceptanceChecks();
+  if (!Array.isArray(value)) throw new Error("task spec acceptance must be an array");
+  if (value.length === 0) return defaultAcceptanceChecks();
+  const checks = value.map((item, index) => normalizeCheck(item, index));
+  const ids = new Set<string>();
+  for (const check of checks) {
+    if (ids.has(check.id)) throw new Error(`duplicate acceptance check id: ${check.id}`);
+    ids.add(check.id);
+  }
+  return checks;
+}
+
+function normalizeCheck(value: unknown, index: number): AcceptanceCheck {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`acceptance[${index}] must be an object`);
+  const source = value as Record<string, unknown>;
+  const id = typeof source.id === "string" && /^[A-Za-z0-9._-]+$/u.test(source.id.trim())
+    ? source.id.trim()
+    : `check-${index + 1}`;
+  const name = typeof source.name === "string" && source.name.trim() ? source.name.trim() : id;
+  const command = typeof source.command === "string" ? source.command.trim() : "";
+  if (!command) throw new Error(`acceptance[${index}] command must not be empty`);
+  const args = source.args === undefined
+    ? []
+    : Array.isArray(source.args) && source.args.every((arg) => typeof arg === "string")
+      ? source.args.map((arg) => arg)
+      : undefined;
+  if (!args) throw new Error(`acceptance[${index}] args must be an array of strings`);
+  const timeoutValue = source.timeoutMs;
+  const timeoutMs = timeoutValue === undefined ? DEFAULT_TIMEOUT_MS : timeoutValue;
+  if (typeof timeoutMs !== "number" || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60 * 60_000) {
+    throw new Error(`acceptance[${index}] timeoutMs must be between 1 and 3600000`);
+  }
+  if (typeof source.required !== "undefined" && typeof source.required !== "boolean") {
+    throw new Error(`acceptance[${index}] required must be boolean`);
+  }
+  return { id, name, command, args, required: source.required !== false, timeoutMs };
+}
+
+function stringList(value: unknown, field: string): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw new Error(`task spec ${field} must be an array of strings`);
+  return value.map((item) => item.trim()).filter(Boolean);
+}
+
+function normalizeRepairRounds(value: unknown): number {
+  if (value === undefined) return DEFAULT_MAX_REPAIR_ROUNDS;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > 10) throw new Error("maxRepairRounds must be between 0 and 10");
+  return value;
+}

package/src/decision-session-store.ts

@@ -1,11 +1,14 @@
 import { chmod, lstat, mkdir, readdir, readFile, rename, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { redactSensitive } from "./redaction.ts";
+import { normalizeTaskSpec } from "./acceptance.ts";
+import type { TaskSpec } from "./types.ts";
 
 export interface DecisionSessionRecord {
   version: 1;
   taskId: string;
   task: string;
+  spec?: TaskSpec;
   cwd: string;
   command: string;
   args: string[];
@@ -16,6 +19,8 @@ export interface DecisionSessionRecord {
   noOutputTimeoutMs: number;
   startedAt: string;
   turn: number;
+  repairRound?: number;
+  lastFindingSignature?: string;
   state: "active" | "closed";
   updatedAt: string;
 }
@@ -71,7 +76,7 @@ export class DecisionSessionStore {
     await this.save({ ...record, state: "closed", updatedAt: new Date().toISOString() });
   }
 
-  async update(taskId: string, patch: Partial<Pick<DecisionSessionRecord, "turn" | "updatedAt">>): Promise<void> {
+  async update(taskId: string, patch: Partial<Pick<DecisionSessionRecord, "turn" | "repairRound" | "lastFindingSignature" | "updatedAt">>): Promise<void> {
     const record = await this.load(taskId);
     if (!record || record.state !== "active") return;
     await this.save({ ...record, ...patch, updatedAt: patch.updatedAt ?? new Date().toISOString() });
@@ -94,7 +99,7 @@ export class DecisionSessionStore {
     try {
       const value = JSON.parse(await readFile(this.#recordPath(taskId), "utf8")) as Partial<DecisionSessionRecord>;
       assertNoCredentialPath(typeof value.decisionSessionFile === "string" ? resolve(value.decisionSessionFile) : "");
-      return normalizeRecord(redactRecord(value), this.#directory);
+      return normalizeRecord(redactRecord(value), this.#directory, taskId);
     } catch (error) {
       if (error instanceof Error && /ENOENT/u.test(error.message)) return undefined;
       throw error;
@@ -109,7 +114,8 @@ export class DecisionSessionStore {
         try {
           const value = JSON.parse(await readFile(join(this.#directory, name), "utf8")) as Partial<DecisionSessionRecord>;
           assertNoCredentialPath(typeof value.decisionSessionFile === "string" ? resolve(value.decisionSessionFile) : "");
-          const record = normalizeRecord(redactRecord(value), this.#directory);
+          const expectedTaskId = name.slice(0, -".json".length);
+          const record = normalizeRecord(redactRecord(value), this.#directory, expectedTaskId);
           if (!options.activeOnly || record.state === "active") records.push(record);
         } catch {
           // A torn or manually edited registry record is not recoverable.
@@ -132,14 +138,17 @@ async function writeJson(path: string, value: unknown): Promise<void> {
   await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
 }
 
-function normalizeRecord(value: Partial<DecisionSessionRecord>, directory: string): DecisionSessionRecord {
+function normalizeRecord(value: Partial<DecisionSessionRecord>, directory: string, expectedTaskId?: string): DecisionSessionRecord {
+  if (expectedTaskId !== undefined && value.taskId !== expectedTaskId) throw new Error("Decision Worker session task id mismatch");
   if (value.version !== 1 || typeof value.taskId !== "string" || !/^[0-9a-f-]{36}$/iu.test(value.taskId)
     || typeof value.task !== "string" || typeof value.cwd !== "string" || typeof value.command !== "string"
     || !Array.isArray(value.args) || value.args.some((arg) => typeof arg !== "string")
     || typeof value.decisionSessionFile !== "string" || (value.state !== "active" && value.state !== "closed")
     || typeof value.updatedAt !== "string" || !Number.isFinite(Date.parse(value.updatedAt))
     || !validLimit(value.maxTurns, 0) || !validLimit(value.deadlineMs, 0) || !validLimit(value.noOutputTimeoutMs, 0)
-    || !validLimit(value.turn, 0) || (value.startedAt !== undefined && (typeof value.startedAt !== "string" || !Number.isFinite(Date.parse(value.startedAt))))) {
+    || !validLimit(value.turn, 0) || !validLimit(value.repairRound, 0)
+    || (value.lastFindingSignature !== undefined && (typeof value.lastFindingSignature !== "string" || value.lastFindingSignature.length > 128))
+    || (value.startedAt !== undefined && (typeof value.startedAt !== "string" || !Number.isFinite(Date.parse(value.startedAt))))) {
     throw new Error("invalid Decision Worker session record");
   }
   const decisionSessionFile = resolve(value.decisionSessionFile);
@@ -150,6 +159,7 @@ function normalizeRecord(value: Partial<DecisionSessionRecord>, directory: strin
     version: 1,
     taskId: value.taskId,
     task: value.task,
+    spec: normalizeTaskSpec(value.spec, value.task),
     cwd: value.cwd,
     command: value.command,
     args: [...value.args],
@@ -160,6 +170,8 @@ function normalizeRecord(value: Partial<DecisionSessionRecord>, directory: strin
     noOutputTimeoutMs: value.noOutputTimeoutMs ?? 20 * 60_000,
     startedAt: value.startedAt ?? value.updatedAt,
     turn: value.turn ?? 0,
+    repairRound: value.repairRound ?? 0,
+    ...(typeof value.lastFindingSignature === "string" ? { lastFindingSignature: value.lastFindingSignature } : {}),
     state: value.state,
     updatedAt: value.updatedAt,
   };

package/src/decision-worker.ts

@@ -1,6 +1,6 @@
 import { access, readFile, writeFile } from "node:fs/promises";
 import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, type AgentSession } from "@earendil-works/pi-coding-agent";
-import type { WorkerEvent } from "./types.ts";
+import type { TaskSpec, WorkerEvent } from "./types.ts";
 import { redactSensitive } from "./redaction.ts";
 
 export type DecisionAction =
@@ -15,13 +15,26 @@ export interface DecisionContext {
   state: string;
   turn: number;
   maxTurns: number;
+  repairRound?: number;
+  spec?: TaskSpec;
 }
 
+export interface DecisionWorkerLike {
+  start(): Promise<void>;
+  updateContext(patch: Partial<DecisionContext>): void;
+  notify(event: WorkerEvent): void;
+  close(): Promise<void>;
+}
+
+export type DecisionWorkerFactory = (options: DecisionWorkerOptions) => DecisionWorkerLike;
+
 export interface DecisionWorkerOptions {
   context: DecisionContext;
   onAction: (action: DecisionAction, event: WorkerEvent) => Promise<void> | void;
   onFailure?: (event: WorkerEvent, error: unknown) => Promise<void> | void;
   onStartupFailure?: (error: unknown) => Promise<void> | void;
+  /** Bound each Decision Worker model request so failure handling cannot wait forever. */
+  timeoutMs?: number;
   /** Existing Pi session JSONL to restore after a Supervisor/Pi restart. */
   sessionFile?: string;
   /** Directory for newly created Pi session JSONL files. */
@@ -34,7 +47,7 @@ export interface DecisionWorkerOptions {
  * It has read-only repository tools and can request typed actions, but it
  * cannot directly spawn processes, modify files, or answer Claude's stdin.
  */
-export class PiDecisionWorker {
+export class PiDecisionWorker implements DecisionWorkerLike {
   readonly #options: DecisionWorkerOptions;
   readonly #seenEvents = new Set<string>();
   #session?: AgentSession;
@@ -43,10 +56,12 @@ export class PiDecisionWorker {
   #initialized = false;
   #sessionFile?: string;
   #context: DecisionContext;
+  readonly #timeoutMs: number;
 
   constructor(options: DecisionWorkerOptions) {
     this.#options = options;
     this.#context = { ...options.context };
+    this.#timeoutMs = options.timeoutMs ?? 120_000;
   }
 
   async start(): Promise<void> {
@@ -76,6 +91,7 @@ export class PiDecisionWorker {
       cwd: this.#options.context.cwd,
       resourceLoader,
       sessionManager,
+      thinkingLevel: "low",
       tools: ["read", "grep", "find", "ls"],
     });
     this.#session = session;
@@ -86,8 +102,9 @@ export class PiDecisionWorker {
     }
     if (!restored) {
       try {
-        await session.prompt(decisionInstructions(this.#context));
+        await withTimeout(session.prompt(decisionInstructions(this.#context)), this.#timeoutMs, "Decision Worker startup");
       } catch (error) {
+        await session.abort().catch(() => {});
         try { await this.#options.onStartupFailure?.(error); } catch { /* preserve the original startup failure */ }
         throw error;
       }
@@ -109,7 +126,7 @@ export class PiDecisionWorker {
     }
     this.#tail = this.#tail.then(async () => {
       if (!this.#session || this.#closed) return;
-      const text = await askDecision(this.#session, event, this.#context);
+      const text = await askDecision(this.#session, event, this.#context, this.#timeoutMs);
       const action = parseDecision(text, event);
       await this.#options.onAction(action, event);
     }).catch(async (error) => {
@@ -139,6 +156,7 @@ export class PiDecisionWorker {
     this.#closed = true;
     const session = this.#session;
     this.#session = undefined;
+    if (session) await session.abort().catch(() => {});
     session?.dispose();
   }
 }
@@ -153,6 +171,8 @@ Task: ${redactText(context.task)}
 Task id: ${redactText(context.taskId)}
 Working directory: ${redactText(context.cwd)}
 Maximum automatic turns: ${context.maxTurns}
+Current repair round: ${context.repairRound ?? 0}
+Task specification: ${boundedJson(context.spec ?? { goal: context.task })}
 
 Return exactly one JSON object and no markdown:
 {"action":"continue|redirect|answer|allow_permission|deny_permission|verify|retry|stop|ask_human|noop",...}
@@ -165,14 +185,19 @@ Use ask_human for product ambiguity, architecture tradeoffs with material risk,
 secrets, deployment, or any uncertainty. Never invent missing information.`;
 }
 
-async function askDecision(session: AgentSession, event: WorkerEvent, context: DecisionContext): Promise<string> {
+async function askDecision(session: AgentSession, event: WorkerEvent, context: DecisionContext, timeoutMs: number): Promise<string> {
   let text = "";
   const unsubscribe = session.subscribe((value) => {
     const record = value as unknown as { type?: string; assistantMessageEvent?: { type?: string; delta?: string } };
     if (record.type === "message_update" && record.assistantMessageEvent?.type === "text_delta") text += record.assistantMessageEvent.delta ?? "";
   });
   try {
-    await session.prompt(`UNTRUSTED SUPERVISOR EVENT:\n${boundedJson(event)}\n\nCURRENT CONTEXT:\n${boundedJson(context)}\n\nChoose one action now.`);
+    try {
+      await withTimeout(session.prompt(`UNTRUSTED SUPERVISOR EVENT:\n${boundedJson(event)}\n\nCURRENT CONTEXT:\n${boundedJson(context)}\n\nChoose one action now.`), timeoutMs, "Decision Worker request");
+    } catch (error) {
+      await session.abort().catch(() => {});
+      throw error;
+    }
   } finally {
     unsubscribe();
   }
@@ -215,6 +240,19 @@ function eventKey(event: WorkerEvent): string {
   return `${event.handle.id}:output:${event.chunk.at}:${event.chunk.text.slice(0, 80)}`;
 }
 
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T> {
+  let timer: NodeJS.Timeout | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+    timer.unref();
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
 function boundedJson(value: unknown): string {
   const text = JSON.stringify(redactDecisionValue(value), null, 2) ?? "null";
   return text.length <= 32_000 ? text : `${text.slice(0, 32_000)}\n[TRUNCATED]`;