pi-claude-supervisor 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 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)
+
+
+### Bug Fixes
+
+* reconcile detached tmux leases and validate prompts ([d20262c](https://github.com/btnalit/pi-claude-supervisor/commit/d20262c8481ca761a48f7dc2b877951173d4681e))
+
 ## [0.4.0](https://github.com/btnalit/pi-claude-supervisor/compare/v0.3.0...v0.4.0) (2026-09-13)
 
 

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：
@@ -108,7 +130,9 @@ export PI_CLAUDE_SUPERVISOR_WORKER='claude --permission-mode plan'
 /supervise adopt-tmux <tmux-session-name> <task description>
 ```
 
-接管会检查 cwd、pane 中的进程，并拒绝已有其他输出 pipe 的 pane；但不宣称拥有该 session。对被接管的 session，
+接管会检查 cwd、pane 中的进程，并拒绝已有其他输出 pipe 的 pane；但不宣称拥有该 session。owned session 使用自动生成的私有 tmux socket，
+请保存 `start` 输出的完整 `attach=...` 命令。Pi 重启后重新接管时，先把该命令中的 socket 路径设置到
+`PI_CLAUDE_SUPERVISOR_TMUX_SOCKET`；只有默认 server 才能只使用 session 名称。对被接管的 session，
 `/supervise stop` 和 Pi 关闭只会断开监督，不会杀掉你的 tmux 窗口；需要关闭时请由你执行
 `tmux kill-session`。`/supervise takeover <task-id>` 会暂停 Decision Worker 自动发送，只有
 `/supervise resume-auto <task-id>` 才恢复。

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
@@ -127,11 +152,16 @@ the task:
 ```
 
 Adoption checks the session's working directory and pane command, and refuses a
-pane that already has another output pipe. It does not claim ownership: `/supervise stop` and Pi shutdown detach supervision rather
-than killing the user's tmux session. Use `tmux kill-session` yourself when the
-adopted window should be closed. `/supervise takeover <task-id>` disables
-automatic Decision Worker messages; resume them only with
-`/supervise resume-auto <task-id>`.
+pane that already has another output pipe. Owned sessions use a generated
+private tmux socket, so preserve the complete `attach=...` command printed by
+`start`. When re-adopting after a Pi restart, set
+`PI_CLAUDE_SUPERVISOR_TMUX_SOCKET` to the socket path from that command before
+running `adopt-tmux`; the session name alone is sufficient only for the default
+server. Adoption does not claim ownership: `/supervise stop` and Pi shutdown
+detach supervision rather than killing the user's tmux session. Use `tmux
+kill-session` yourself when the adopted window should be closed.
+`/supervise takeover <task-id>` disables automatic Decision Worker messages;
+resume them only with `/supervise resume-auto <task-id>`.
 
 PTY screen text is not Claude JSONL. Permission dialogs, trust prompts and
 ambiguous TUI states are escalated to a human; tmux mode must not be treated as

package/docs/architecture.md

@@ -136,7 +136,10 @@ cannot consume another task's lease. If post-start worker identity registration
 fails, owned workers are stopped before the lease is released; cleanup failure
 retains both the worker and lease fail-closed. Explicit `stop` cleans owned tmux
 sessions, while Pi shutdown detaches persistent sessions so they remain explicitly
-re-adoptable.
+re-adoptable. A detached adopted session retains its lease while the verified pane
+is alive; the extension periodically rechecks released sessions and removes the
+lease only after the pane is confirmed gone. If that check fails, the lease is
+retained rather than allowing a cwd overlap.
 
 Startup owns an `AbortController` and passes its signal to the adapter. A stop
 or shutdown request aborts the controller and calls the adapter's out-of-band
@@ -178,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;
@@ -189,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
@@ -73,15 +78,24 @@ npm run spike:signals
 npm run spike:automation
 SPIKE_AUTOMATION_PERMISSION=1 npm run spike:automation
 SPIKE_AUTOMATION_QUESTION=1 npm run spike:automation
+PI_CLAUDE_SUPERVISOR_REAL_CLAUDE_PATH=/home/yancao/.local/share/mise/installs/claude/2.1.270/claude \
 PI_CLAUDE_SUPERVISOR_REAL_CLAUDE=1 npm run spike:tmux
+PI_CLAUDE_SUPERVISOR_REAL_CLAUDE_PATH=/home/yancao/.local/share/mise/installs/claude/2.1.270/claude \
+PI_CLAUDE_SUPERVISOR_REAL_CLAUDE=1 npm run spike:tmux-interactive
 ```
 
 The tmux spike is gated, authenticated, and excluded from normal CI. It uses
-plan mode, records only protocol metadata, and verifies two real Claude turns,
-pause/resume, owned detach, and identity-bound restart re-adoption.
-
-For each release, pin and record the validated Claude Code version and resolved
-executable path. For this release the validated version is `2.1.270`. Record:
+plan mode with a fixed `opus` model, records only protocol metadata, and
+verifies three real Claude turns, exact screen-result markers, pause/resume,
+automation enabled with human takeover, direct human PTY input, owned detach,
+and identity-bound restart re-adoption. The interactive spike uses a fresh temporary
+cwd to verify Claude's trust prompt, a real Bash permission prompt, an allow-once
+response, and an exact result marker; it also records metadata only.
+
+For each release, pin and record the validated Claude Code version, resolved
+executable path, and model. The spikes reject an unpinned/mismatched executable
+version. For this release the validated version is `2.1.270` with model `opus`.
+Record:
 
 1. exact version and resolved executable path;
 2. license and source revision;
@@ -103,14 +117,17 @@ approval callbacks are deliberately not accepted without a separately
 authenticated endpoint.
 
 The tmux transport is selected with `PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux`. Before
-release, manually verify: private-socket attach, multi-line paste, prompt
-stability while Claude is busy, trust/permission dialog takeover, duplicate
-send prevention, pane replacement refusal, pause/resume, owned-session stop,
-adopted-session detach/re-adoption, bounded shutdown, and Pi shutdown without
-closing an attached window. Use `--permission-mode plan`
-and read-only tools for live Claude checks. Do not run JSONL and tmux control
-against the same Claude process, and do not treat `capture-pane` text as a
-structured permission response.
+release, verify: private-socket attach, multi-line paste, prompt stability while
+Claude is busy, trust/permission dialog takeover, duplicate send prevention, pane
+replacement refusal, pause/resume, owned-session stop, adopted-session
+detach/re-adoption, bounded shutdown, and Pi shutdown without closing an
+attached window. The two gated real-Claude spikes above cover the trust prompt,
+permission prompt, exact output, human takeover, and adopted detach paths. Use
+`--permission-mode plan` and read-only tools for ordinary live Claude checks;
+the interactive spike is restricted to one harmless `rm -f` in a disposable
+fresh directory. Do not run JSONL and tmux control against the same Claude
+process, and do not treat `capture-pane` text as a structured permission
+response.
 
 ## Failure injection
 
@@ -132,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.0",
+  "version": "0.5.0",
   "description": "A policy-gated Pi supervisor for observing and verifying Claude Code workers.",
   "license": "MIT",
   "publishConfig": {
@@ -57,6 +57,7 @@
     "test:pi": "node scripts/test-pi.mjs",
     "spike:transport": "node scripts/spike-claude-transport.mjs",
     "spike:tmux": "node scripts/spike-claude-tmux.mjs",
+    "spike:tmux-interactive": "node scripts/spike-claude-tmux-interactive.mjs",
     "spike:permissions": "node scripts/spike-claude-permissions.mjs",
     "spike:signals": "node scripts/spike-claude-signals.mjs",
     "spike:automation": "node scripts/spike-claude-automation.mjs",

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,
   };