pi-claude-supervisor 0.5.2 → 0.5.3

package/docs/implementation-review.md

@@ -1,15 +1,30 @@
 # Implementation Review
 
 An independent read-only reviewer examined the implementation before the final
-hardening pass. The review found no blocker in the TypeScript/Pi registration
-surface. The MVP intentionally does not provide OS sandboxing, low-privilege
-execution, or network isolation; those are deferred security-hardening items,
-not blockers for the lifecycle and recovery track.
+hardening pass. The review found release blockers in automatic startup validation,
+shell-policy lexical handling, malformed custom Reviewer results, credential
+filtering, and stale security documentation. Those findings are addressed by the
+current implementation and regression tests.
+
+Automatic mode is fail-closed at its supported Worker boundary: it requires a
+validated non-bare Git worktree, an existing full baseline commit, a non-protected
+branch, the Claude JSONL transport, and the bare `claude`/`claude.exe` command name.
+Startup resolves and pins an operator-owned, non-writable executable path (or an
+explicit `PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE` path), and the final pre-spawn check
+compares the current repository HEAD with the exact startup HEAD. The built-in Claude
+path requests Claude Code's fail-closed Bash sandbox with no outbound domains.
+Arbitrary custom executables and explicit paths are not admitted to automatic mode;
+manual/custom integrations remain responsible for their own host sandbox and network
+boundary.
 
 ## Findings addressed in this pass
 
-- Policy now evaluates the executable and argv together, including Claude
-  permission-bypass flags.
+- Policy now evaluates every shell argument as well as the executable and argv
+  together; dynamic arguments are denied because their capability cannot be checked,
+  including Claude permission-bypass flags.
+- Automatic startup pins a secure resolved Claude executable identity and rejects
+  explicit paths, persists that identity for recovery, and rechecks the exact startup
+  HEAD through the built-in adapter's final `preSpawnCheck` immediately before spawn.
 - Worker and verifier processes use a minimal environment; explicit worker
   variables can be selected with `PI_CLAUDE_SUPERVISOR_WORKER_ENV` or an
   embedding caller's `WorkerStartInput.env`.
@@ -24,12 +39,12 @@ not blockers for the lifecycle and recovery track.
 
 ## Residual risks and follow-up hardening
 
-These are verified limitations and follow-up work, not reasons to stop the
-lifecycle track:
+These are verified limitations and follow-up work after the automatic boundary
+hardening:
 
-- OS sandbox, lower-privilege execution, and network allowlisting are not
-  provided by the adapter. The caller may run with explicitly authorized host
-  permissions; the deployment owner accepts responsibility for that boundary.
+- The Claude Code sandbox is a requested runtime boundary and is fail-closed when
+  unavailable; it is not a substitute for a host-level sandbox, lower-privilege
+  account, or container policy for manual integrations.
 - Event contents can contain worker output or user messages; common credential
   patterns are now redacted and sequence recovery is persisted, but broader
   structured-secret coverage remains follow-up work.
@@ -40,9 +55,9 @@ lifecycle track:
 - Fault injection coverage now includes lifecycle-log failure, SIGTERM refusal,
   blocked stdin and managed orphan descendants; shutdown cleanup under injected
   adapter failure remains a follow-up failure-injection case.
-- The default transport is process-pipe. Claude JSONL framing is opt-in; the
-  next priority is signal, shutdown and descendant-cleanup evidence rather than
-  network or low-privilege isolation.
+- The default manual transport is process-pipe. Claude JSONL is mandatory for
+  automatic mode; the remaining transport work concerns signal, shutdown and
+  descendant-cleanup evidence rather than weakening the automatic boundary.
 
 ## Evidence
 

package/docs/independent-review.md

@@ -1,5 +1,7 @@
 # 独立子 Agent 方案评审报告
 
+> 本评审按已确认目标更新：本地开发完全无人值守；远程 push 和 main/integration merge 必须经过独立边界。文中旧的“人工升级”表述表示候选不可发布/可挂起状态，不是要求人工在线。
+
 > 评审对象：`requirement.txt`、`docs/engineering-plan.md`  
 > 评审重点：复用现有扩展、减少重复开发、形成可整合架构并验证到生产
 
@@ -18,7 +20,7 @@
 - `pi-interactive-shell` 如果通过版本、API、许可证和故障测试，应优先复用其 PTY 和人工接管实现。
 - `pi-claude-code`、`pi-harness-delegate` 在完成供应链、API 和故障语义审计前，不作为核心依赖。
 
-**结论：架构方向 GO；先完成固定版本 Spike、生命周期和故障恢复主线。低权限用户、sandbox 与网络隔离属于后续安全加固，不作为当前主线硬阻塞。**
+**结论：架构方向 GO；先完成固定版本 Spike、生命周期和故障恢复主线。当前自动模式已把直接 Claude 的 fail-closed sandbox、无出站域名、JSONL transport、Git baseline 和分支校验作为启动边界，并拒绝任意自定义可执行文件；手动集成的 host-level 低权限和网络隔离仍是后续加固。另经产品确认，本地开发必须完全无人值守；远程 push 和 main/integration merge 是 Worker 不具备权限的独立边界。详见 [autonomy-target.md](autonomy-target.md)。**
 
 ## 2. 外部参考源审查结果
 
@@ -163,7 +165,7 @@ interface WorkerAdapter {
 - Policy Gate；
 - 预算和最大轮数；
 - 重复停顿检测；
-- 人工升级；
+- 自动决策、重试和候选挂起；
 - 事件日志；
 - 证据收集；
 - 独立验收；
@@ -194,11 +196,11 @@ interface WorkerAdapter {
 创建任务
   → 启动 Claude
   → 读取输出
-  → 处理普通提问
-  → 人工接管
-  → 恢复执行
-  → 测试
+  → 自动处理普通提问和决策
+  → 测试 / 修复 / 重试
   → 独立验收
+  → 本地提交候选
+  → 独立远程/main 边界
   → 输出报告
 ```
 
@@ -219,8 +221,8 @@ interface WorkerAdapter {
 MVP 必须满足：
 
 - 单仓库、单 worktree、单 Worker；
-- 低风险动作才可自动继续；
-- 架构和危险动作人工审批；
+- 本地开发动作按任务授权自动继续、修复或挂起；
+- 不授予 Worker 远程 push 或 main/integration merge 权限；
 - 事件可以完整回放；
 - 人工 takeover 后零自动发送；
 - 验收失败绝不进入 `COMPLETE`；
@@ -235,17 +237,18 @@ MVP 必须满足：
 
 - 依赖 lockfile 和 SBOM；
 - 包来源校验；
-- 可选最小权限和 sandbox；
-- 可选网络白名单；
-- 密钥隔离；
+- 手动/自定义集成的最小权限和 host-level sandbox；
+- 手动/自定义集成的网络白名单；自动 Claude 路径已请求无出站域名并在不可用时失败；
+- 更广泛的密钥隔离；
 - 日志脱敏；
 - 成本和时间告警；
 - 灰度 feature flag；
 - 可随时关闭自动化；
-- 故障回滚和人工值守。
+- 故障回滚、候选挂起和可选通知。
 
-其中低权限用户、sandbox 和网络白名单不阻塞当前生命周期验证；运行权限由
-调用者明确授权，危险操作仍由 Policy Gate 和人工审批控制。
+其中手动/自定义集成的 host-level 低权限、sandbox 和网络白名单不阻塞当前生命周期验证；
+自动模式不接受没有 Claude sandbox 边界的自定义 Worker。本地运行权限由任务和调用方授权策略
+控制，远程 push/main merge 仍由独立边界控制。
 
 ### 5.4 建议 Go / No-Go 门槛
 
@@ -262,11 +265,11 @@ MVP 必须满足：
 - 通过一组固定任务的成功率、恢复率和费用门槛。
 
 未满足生命周期、恢复、审计和独立验收门槛时只能称为 PoC 或生产候选；
-安全加固项未完成时，不应称为安全加固完成或适合无人工值守部署。
+候选不得进入远程或 main/integration 分支。安全加固项的完成度应单独标注，不能以本地无人值守目标替代安全证据。
 
 ## 6. 回滚方案
 
-任何以下情况发生时，立即停止自动发送并进入 `HUMAN_REQUIRED`：
+任何以下情况发生时，立即停止自动发送并进入 `blocked`/`candidate_failed` 或恢复检查状态：
 
 - 状态不一致；
 - 重复发送指令；
@@ -277,15 +280,17 @@ MVP 必须满足：
 - 发现权限越界或密钥风险；
 - watchdog 与 Worker 状态矛盾。
 
+上述情况应保留现场并可选发送通知，但不得把人工在线作为恢复前提，也不得因此放行远程 push 或 main/integration merge。
+
 回滚动作：
 
 1. 停止自动控制；
 2. 保留 worktree、事件日志和原始输出；
 3. 终止或交还 Worker 控制权；
-4. 人工接管；
+4. 将任务挂起并保留候选证据；
 5. 使用锁定的旧 Adapter 或直接使用 Claude CLI；
 6. 生成故障报告；
-7. 未完成根因分析前，不重新打开自动化开关。
+7. 未完成根因分析前，不重新打开自动化开关；需要人工接管时作为可选后续操作。
 
 第三方包升级必须通过 lockfile、独立 worktree、回放测试和 feature flag 灰度，不能直接替换生产版本。
 

package/docs/releasing.md

@@ -1,9 +1,14 @@
 # Releasing
 
+Local automation may develop, test, repair and commit a candidate, but it does not
+push to a remote or merge into `main`. Remote repository entry and main-branch
+integration are independent protected boundaries; this release workflow is the
+publication path after those boundaries pass. See [the confirmed autonomy target](autonomy-target.md).
+
 ## Pull request gate
 
-All changes must enter `main` through a pull request. Use a Conventional Commit
-PR title, for example:
+All changes must enter `main` through a pull request and its independent CI/review
+boundary. Use a Conventional Commit PR title, for example:
 
 ```text
 feat: persist Decision Worker sessions

package/docs/testing.md

@@ -1,5 +1,7 @@
 # Testing
 
+> Autonomy target: local editing, testing, repair and local commits run without a human being online. Invalid output, unavailable evidence, duplicate findings, P0/P1 findings and exhausted budgets become parked/non-publishable candidates rather than synchronous human gates. Remote push and main/integration merge remain independent-boundary tests. See [autonomy-target.md](autonomy-target.md).
+
 ## Local checks
 
 ```bash
@@ -17,7 +19,7 @@ the published TypeScript source directly and there is no second runtime bundle.
 
 ## Test layers
 
-- `policy.test.ts`: deterministic allow/review/deny behavior.
+- `policy.test.ts`: deterministic local allow and hard-boundary deny behavior; legacy approval cannot override denial.
 - `state.test.ts`: legal and illegal lifecycle transitions.
 - `events.test.ts`: ordered JSONL persistence, sequence recovery and credential-shaped redaction.
 - `decision-session-store.test.ts`: atomic Decision Worker task mapping, permissions, restart discovery and corrupt-record isolation.
@@ -57,13 +59,12 @@ owned tmux turns, pause/resume, and restart re-adoption.
 The adapter regression suite also verifies event subscription, parsed
 `permission_request` events, and the exact nested `control_response` envelope.
 The automation spike additionally exercises a real Pi SDK Decision Worker with
-Claude: ordinary completion, harmless Bash permission approval, and an
+Claude: ordinary completion, harmless Bash permission handling, 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.
+cause a later run to fail closed as a parked/non-publishable candidate 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. Automatic startup preflights the state/lease directories, cwd,
 worker executable, transport dependency and required cgroup boundary before model
@@ -92,7 +93,7 @@ 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 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,
+manual takeover, direct 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.
@@ -117,21 +118,33 @@ relevant checks from a clean host perspective.
 
 Automatic mode is enabled with `PI_CLAUDE_SUPERVISOR_MODE=auto`; it defaults to
 JSONL and routes `result`, permission, and process-exit events to the persistent
-Pi Decision Worker. An explicit `PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux` selection
-remains screen-based and does not use the JSONL permission protocol. `process-pipe` remains the manual compatibility mode. Human
-escalation is outbound-only through `PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_URL`;
-approval callbacks are deliberately not accepted without a separately
+Pi Decision Worker. Task autonomy defaults to unattended local work, a required
+local commit on a non-protected task branch and two bounded Decision Worker retries. Configure
+`PI_CLAUDE_SUPERVISOR_REQUIRE_LOCAL_COMMIT=0` or task `autonomy.requireLocalCommit`
+only to disable the local-commit deliverability check; automatic mode still requires a Git
+baseline and non-protected worktree. An explicit `PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux` selection
+remains screen-based and does not use the JSONL permission protocol. `process-pipe` remains the manual compatibility mode. Candidate/failure notification is optional and outbound-only through
+`PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_URL`; it is not a synchronous approval
+callback. Approval callbacks are deliberately not accepted without a separately
 authenticated endpoint.
 
 The tmux transport is selected with `PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux`.
-Automatic mode rejects an explicit `process-pipe` transport; use JSONL or tmux for
-bounded decisions and repair. Before
-release, verify: private-socket attach, multi-line paste, prompt stability while
-Claude is busy, trust/permission dialog takeover, duplicate send prevention, pane
+Automatic mode rejects explicit `process-pipe` and `tmux` transports; use JSONL for
+bounded decisions and repair. Built-in Claude workers also receive a fail-closed
+sandbox setting (`failIfUnavailable`, `allowUnsandboxedCommands=false`, no outbound
+network domains); verify that startup fails if the sandbox cannot be initialized.
+Automatic startup also requires a full existing Git baseline, non-bare non-protected
+worktree and the bare `claude`/`claude.exe` command name. It resolves and pins an
+operator-owned, non-writable executable path (or the path configured by
+`PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE`), rejects explicit/custom executable paths, and
+compares the exact startup HEAD again immediately before spawn. Before release, verify:
+private-socket attach,
+multi-line paste, prompt stability while
+Claude is busy, trust/permission policy handling, 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 prompt, exact output, optional 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
@@ -165,7 +178,7 @@ the managed process group.
 
 The `v0.5.0` implementation of the acceptance—independent Review—repair—reacceptance
 loop is shipped. The `v0.5.1` real read-only drill reached acceptance and independent
-Review, then correctly stopped at human intervention after two P1 and two P2 findings.
+Review, then correctly produced a non-publishable candidate after two P1 and two P2 findings under the then-current human-gated compatibility path.
 A separate real edit-capable Claude Code `2.1.270` drill then exercised one bounded
 acceptance failure, repair turn, reacceptance and independent Reviewer `pass` in an
 isolated temporary worktree. The current hardening plan and evidence paths are recorded
@@ -182,8 +195,8 @@ 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;
+- invalid Reviewer JSON and Reviewer API failure becoming a parked/non-publishable candidate without requiring a live callback;
+- repair rounds, repeated finding detection, P0/P1 parking and repair-budget exhaustion;
 - non-persistent JSONL verification failure without duplicate terminal transitions;
 - repairable-but-not-persistent JSONL multi-turn repair;
 - stop and Pi shutdown from `verifying`, including Decision Worker closure and cwd lease release;
@@ -191,7 +204,8 @@ Deterministic tests must cover:
 
 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
+bounded; timeout or API failure parks the candidate instead of auto-completing or
+requiring a human to be online. Review reports
 are persisted as bounded event payloads and are not treated as permission grants.
 
 ### JSONL protocol and replay fixtures
@@ -233,7 +247,7 @@ Required deterministic and integration coverage:
 - independent child acceptance followed by root-task aggregate acceptance and Review;
 - single-child recovery, whole-graph recovery and Pi shutdown during scheduling;
 - no child can grant permissions, send control input to another child or bypass Policy Gate;
-- explicit human-controlled integration in a separate worktree; no automatic merge or publish.
+- independent integration in a separate worktree; the Worker has no remote push or main/integration merge authority, and no candidate bypasses that boundary.
 
 The multi-worker gate should be added only after the pinned single-worker stability
 and recovery gates pass. CI should use fake Workers and replay fixtures; authenticated
@@ -243,8 +257,8 @@ Claude multi-worker Spikes remain manual and version-pinned.
 
 A live review must record the exact Claude executable/version, transport, cgroup mode,
 permission flags, task id, acceptance result, Reviewer result, cleanup status and cwd lease
-status. A human-required result is a valid safety outcome and must not be converted into a
-pass by retrying the same task automatically.
+status. A parked/non-publishable result is a valid safety outcome and must not be converted into a
+pass by retrying the same task automatically or by treating the absence of a human callback as approval.
 
 For the hardening release, the completed gate record is:
 

package/package.json

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

package/src/acceptance.ts

@@ -18,6 +18,7 @@ export function normalizeTaskSpec(value: unknown, fallbackGoal: string): TaskSpe
     forbidden: stringList(source.forbidden, "forbidden"),
     acceptance: normalizeChecks(source.acceptance),
     maxRepairRounds: normalizeRepairRounds(source.maxRepairRounds),
+    autonomy: normalizeAutonomy(source.autonomy),
   };
 }
 
@@ -82,3 +83,18 @@ function normalizeRepairRounds(value: unknown): number {
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > 10) throw new Error("maxRepairRounds must be between 0 and 10");
   return value;
 }
+
+function normalizeAutonomy(value: unknown): TaskSpec["autonomy"] {
+  if (value === undefined) return { unattended: true, requireLocalCommit: true, maxDecisionRetries: 2 };
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("task spec autonomy must be an object");
+  const source = value as Record<string, unknown>;
+  if (source.unattended !== undefined && typeof source.unattended !== "boolean") throw new Error("task spec autonomy.unattended must be boolean");
+  if (source.requireLocalCommit !== undefined && typeof source.requireLocalCommit !== "boolean") throw new Error("task spec autonomy.requireLocalCommit must be boolean");
+  const retries = source.maxDecisionRetries ?? 2;
+  if (typeof retries !== "number" || !Number.isSafeInteger(retries) || retries < 0 || retries > 10) throw new Error("task spec autonomy.maxDecisionRetries must be between 0 and 10");
+  return {
+    unattended: source.unattended !== false,
+    requireLocalCommit: source.requireLocalCommit !== false,
+    maxDecisionRetries: retries,
+  };
+}

package/src/config.ts

@@ -10,14 +10,32 @@ const allowed = new Set([
   "PI_CLAUDE_SUPERVISOR_CGROUP_MODE",
   "PI_CLAUDE_SUPERVISOR_TMUX_SOCKET",
   "PI_CLAUDE_SUPERVISOR_WORKER",
+  "PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE",
   "PI_CLAUDE_SUPERVISOR_STATE_DIR",
   "PI_CLAUDE_SUPERVISOR_CWD_LEASE_DIR",
   "PI_CLAUDE_SUPERVISOR_WORKER_ENV",
   "PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_URL",
   "PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_FORMAT",
   "PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_SECRET",
+  "PI_CLAUDE_SUPERVISOR_UNATTENDED",
+  "PI_CLAUDE_SUPERVISOR_REQUIRE_LOCAL_COMMIT",
+  "PI_CLAUDE_SUPERVISOR_MAX_DECISION_RETRIES",
 ]);
 
+export interface AutonomyDefaults {
+  unattended: boolean;
+  requireLocalCommit: boolean;
+  maxDecisionRetries: number;
+}
+
+export function autonomyDefaults(env: NodeJS.ProcessEnv = process.env): AutonomyDefaults {
+  return {
+    unattended: readBoolean(env.PI_CLAUDE_SUPERVISOR_UNATTENDED, true),
+    requireLocalCommit: readBoolean(env.PI_CLAUDE_SUPERVISOR_REQUIRE_LOCAL_COMMIT, true),
+    maxDecisionRetries: readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_MAX_DECISION_RETRIES, 2, 0, 10),
+  };
+}
+
 export function loadSupervisorEnvironment(): string | undefined {
   const path = process.env.PI_CLAUDE_SUPERVISOR_ENV_FILE ?? join(homedir(), ".config", "pi-claude-supervisor", "env");
   if (!existsSync(path)) return undefined;
@@ -37,3 +55,16 @@ export function loadSupervisorEnvironment(): string | undefined {
     return undefined;
   }
 }
+
+function readBoolean(value: string | undefined, fallback: boolean): boolean {
+  if (value === undefined) return fallback;
+  if (/^(?:1|true|yes|on)$/iu.test(value.trim())) return true;
+  if (/^(?:0|false|no|off)$/iu.test(value.trim())) return false;
+  return fallback;
+}
+
+function readBoundedInteger(value: string | undefined, fallback: number, minimum: number, maximum: number): number {
+  if (value === undefined) return fallback;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed >= minimum && parsed <= maximum ? parsed : fallback;
+}

package/src/decision-session-store.ts

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { chmod, lstat, mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { redactSensitive } from "./redaction.ts";
 import { normalizeTaskSpec } from "./acceptance.ts";
 import type { TaskSpec } from "./types.ts";
@@ -27,6 +27,10 @@ export interface DecisionSessionRecord {
   deadlineMs: number;
   noOutputTimeoutMs: number;
   startedAt: string;
+  baseCommit?: string;
+  baseBranch?: string;
+  /** Real executable identity pinned by automatic startup and recovery. */
+  resolvedExecutable?: string;
   turn: number;
   repairRound?: number;
   lastFindingSignature?: string;
@@ -75,6 +79,7 @@ export class DecisionSessionStore {
     assertSessionPath(decisionSessionFile, this.#directory, record.taskId);
     assertNoCredentialPath(decisionSessionFile);
     assertNoCredentialPath(record.cwd);
+    if (record.resolvedExecutable !== undefined) assertResolvedExecutable(record.resolvedExecutable);
     await this.#withLock(() => this.#saveUnlocked({ ...record, decisionSessionFile }));
   }
 
@@ -354,6 +359,9 @@ function normalizeRecord(value: Partial<DecisionSessionRecord>, directory: strin
     || (value.recoveryOwnerStartTime !== undefined && (typeof value.recoveryOwnerStartTime !== "string" || !/^\d+$/u.test(value.recoveryOwnerStartTime)))
     || (value.recoveryState !== undefined && !isRecoveryState(value.recoveryState))
     || (value.lastFindingSignature !== undefined && (typeof value.lastFindingSignature !== "string" || value.lastFindingSignature.length > 128))
+    || (value.baseCommit !== undefined && (typeof value.baseCommit !== "string" || !/^[0-9a-f]{40,64}$/iu.test(value.baseCommit)))
+    || (value.baseBranch !== undefined && (typeof value.baseBranch !== "string" || !/^[A-Za-z0-9._/-]+$/u.test(value.baseBranch)))
+    || (value.resolvedExecutable !== undefined && (typeof value.resolvedExecutable !== "string" || !isAbsolute(value.resolvedExecutable) || value.resolvedExecutable.length > 4_096))
     || (value.startedAt !== undefined && (typeof value.startedAt !== "string" || !Number.isFinite(Date.parse(value.startedAt))))
     || (value.recoveryWorker !== undefined && !isRecoveryWorker(value.recoveryWorker))) {
     throw new Error("invalid Decision Worker session record");
@@ -362,6 +370,7 @@ function normalizeRecord(value: Partial<DecisionSessionRecord>, directory: strin
   assertSessionPath(decisionSessionFile, directory, value.taskId);
   assertNoCredentialPath(decisionSessionFile);
   assertNoCredentialPath(value.cwd);
+  if (value.resolvedExecutable !== undefined) assertResolvedExecutable(value.resolvedExecutable);
   const recoveryWorker = value.recoveryWorker && {
     id: value.recoveryWorker.id,
     ...(value.recoveryWorker.pid !== undefined ? { pid: value.recoveryWorker.pid } : {}),
@@ -381,6 +390,9 @@ function normalizeRecord(value: Partial<DecisionSessionRecord>, directory: strin
     deadlineMs: value.deadlineMs ?? 4 * 60 * 60_000,
     noOutputTimeoutMs: value.noOutputTimeoutMs ?? 20 * 60_000,
     startedAt: value.startedAt ?? value.updatedAt,
+    ...(typeof value.baseCommit === "string" ? { baseCommit: value.baseCommit } : {}),
+    ...(typeof value.baseBranch === "string" ? { baseBranch: value.baseBranch } : {}),
+    ...(typeof value.resolvedExecutable === "string" ? { resolvedExecutable: value.resolvedExecutable } : {}),
     turn: value.turn ?? 0,
     repairRound: value.repairRound ?? 0,
     ...(typeof value.lastFindingSignature === "string" ? { lastFindingSignature: value.lastFindingSignature } : {}),
@@ -415,6 +427,12 @@ function assertNoCredentialPath(path: string): void {
   if (!path || String(redactSensitive(path)) !== path) throw new Error("Decision Worker session path contains credential-shaped text");
 }
 
+function assertResolvedExecutable(path: string): void {
+  if (!isAbsolute(path) || path.length > 4_096 || String(redactSensitive(path)) !== path) {
+    throw new Error("Decision Worker resolved executable identity is invalid");
+  }
+}
+
 function assertTaskId(taskId: string): void {
   if (!/^[0-9a-f-]{36}$/iu.test(taskId) || basename(taskId) !== taskId) throw new Error("invalid task id");
 }

package/src/decision-worker.ts

@@ -12,7 +12,8 @@ const MAX_DECISION_FIELD_BYTES = 8 * 1024;
 export type DecisionAction =
   | { action: "continue" | "redirect" | "answer"; message: string; reason: string; confidence?: number }
   | { action: "allow_permission" | "deny_permission"; requestId: string; toolUseId: string; reason: string; confidence?: number }
-  | { action: "verify" | "retry" | "stop" | "ask_human" | "noop"; reason: string; question?: string; confidence?: number };
+  | { action: "verify" | "stop" | "park" | "ask_human" | "noop"; reason: string; question?: string; confidence?: number }
+  | { action: "retry"; reason: string; message?: string; confidence?: number };
 
 export interface DecisionContext {
   taskId: string;
@@ -130,12 +131,7 @@ export class PiDecisionWorker implements DecisionWorkerLike {
       const first = this.#seenEvents.values().next().value;
       if (first) this.#seenEvents.delete(first);
     }
-    this.#tail = this.#tail.then(async () => {
-      if (!this.#session || this.#closed) return;
-      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) => {
+    this.#tail = this.#tail.then(() => this.#processEvent(event)).catch(async (error) => {
       try {
         if (this.#options.onFailure) await this.#options.onFailure(event, error);
       } catch {
@@ -144,6 +140,29 @@ export class PiDecisionWorker implements DecisionWorkerLike {
     });
   }
 
+  async #processEvent(event: WorkerEvent): Promise<void> {
+    if (!this.#session || this.#closed) return;
+    const maxRetries = this.#context.spec?.autonomy.maxDecisionRetries ?? 2;
+    let attempt = 0;
+    while (true) {
+      let text: string;
+      try {
+        text = await askDecision(this.#session, event, this.#context, this.#timeoutMs);
+      } catch (error) {
+        if (attempt >= maxRetries || this.#closed) throw error;
+        attempt += 1;
+        await new Promise<void>((resolve) => setTimeout(resolve, Math.min(1_000, 100 * attempt)));
+        if (!this.#session || this.#closed) return;
+        continue;
+      }
+      const action = parseDecision(text, event);
+      // An action handler may stop or close the session. Do not replay an
+      // already-decoded action if the handler itself fails.
+      await this.#options.onAction(action, event);
+      return;
+    }
+  }
+
   get sessionFile(): string | undefined {
     return this.#sessionFile;
   }
@@ -181,14 +200,20 @@ 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",...}
+{"action":"continue|redirect|answer|allow_permission|deny_permission|verify|retry|stop|park|noop",...}
 For continue/redirect/answer include message and reason. For permission actions include
-requestId and toolUseId. For ask_human optionally include question. Never choose allow_permission unless the request is low-risk, directly required by the task, and the policy evidence supports it.
-For AskUserQuestion, prefer deny_permission when the question can be converted into ordinary Claude text;
-then use answer on the resulting turn only when the task and repository make the answer unambiguous.
-Use verify when a turn result indicates the task is complete, even if Claude says it will stop; choose stop only for an explicit human stop, unrecoverable failure, or a safety reason.
-Use ask_human for product ambiguity, architecture tradeoffs with material risk, unknown tools,
-secrets, deployment, or any uncertainty. Never invent missing information.`;
+requestId and toolUseId. Retry may include a corrective message. Never choose allow_permission
+for a command that crosses the remote push or main/integration merge boundary; the deterministic
+policy will deny it.
+For AskUserQuestion, choose deny_permission when the question can be converted into ordinary
+Claude text, then use answer on the resulting turn. For product ambiguity or an architecture
+choice, inspect the repository and task evidence, select the best task-compatible option, state
+the assumption in reason, and instruct Claude Code with answer or redirect. Do not ask a human
+for ordinary uncertainty. Use verify when a turn result indicates the task is complete, even if
+Claude says it will stop; choose stop only for an explicit stop or technical containment reason.
+Use park only when the task cannot safely produce a candidate because required evidence,
+authority, or runtime capability is unavailable. A parked candidate is asynchronous and must not
+wait for a human to be online.`;
 }
 
 async function askDecision(session: AgentSession, event: WorkerEvent, context: DecisionContext, timeoutMs: number): Promise<string> {
@@ -249,12 +274,12 @@ function textFromMessage(content: unknown): string {
 
 function parseDecision(text: string, event: WorkerEvent): DecisionAction {
   const candidate = text.trim();
-  if (!candidate) return { action: "ask_human", reason: "Decision Worker returned no JSON action" };
+  if (!candidate) return { action: "park", reason: "Decision Worker returned no JSON action" };
   try {
     const value = JSON.parse(candidate) as Record<string, unknown>;
     const action = value.action;
     if (typeof action !== "string") throw new Error("missing action");
-    const allowed = new Set(["continue", "redirect", "answer", "allow_permission", "deny_permission", "verify", "retry", "stop", "ask_human", "noop"]);
+    const allowed = new Set(["continue", "redirect", "answer", "allow_permission", "deny_permission", "verify", "retry", "stop", "park", "ask_human", "noop"]);
     if (!allowed.has(action)) throw new Error(`unsupported action: ${action}`);
     const reason = typeof value.reason === "string" && value.reason.trim() ? boundedDecisionText(value.reason, "reason") : "no reason provided";
     const confidence = value.confidence === undefined ? undefined : typeof value.confidence === "number" && Number.isFinite(value.confidence) && value.confidence >= 0 && value.confidence <= 1
@@ -271,9 +296,12 @@ function parseDecision(text: string, event: WorkerEvent): DecisionAction {
       if (!requestId || !toolUseId) throw new Error("permission requestId/toolUseId required");
       return { action: action as "allow_permission" | "deny_permission", requestId, toolUseId, reason, confidence };
     }
-    return { action: action as "verify" | "retry" | "stop" | "ask_human" | "noop", reason, question: typeof value.question === "string" ? boundedDecisionText(value.question, "question") : undefined, confidence };
+    if (action === "retry") {
+      return { action, reason, message: typeof value.message === "string" ? boundedDecisionText(value.message, "message") : undefined, confidence };
+    }
+    return { action: action as "verify" | "stop" | "park" | "ask_human" | "noop", reason, question: typeof value.question === "string" ? boundedDecisionText(value.question, "question") : undefined, confidence };
   } catch (error) {
-    return { action: "ask_human", reason: `invalid Decision Worker action: ${error instanceof Error ? error.message : String(error)}` };
+    return { action: "park", reason: `invalid Decision Worker action: ${error instanceof Error ? error.message : String(error)}` };
   }
 }