pi-claude-supervisor 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented here.
 
+## [0.5.1](https://github.com/btnalit/pi-claude-supervisor/compare/v0.5.0...v0.5.1) (2026-09-14)
+
+
+### Bug Fixes
+
+* harden single-worker recovery lifecycle ([14c01ec](https://github.com/btnalit/pi-claude-supervisor/commit/14c01ec610b1210eda1ea2d60269fad25b8b3575))
+
 ## [0.5.0](https://github.com/btnalit/pi-claude-supervisor/compare/v0.4.1...v0.5.0) (2026-09-14)
 
 
@@ -17,6 +24,9 @@ All notable changes to this project will be documented here.
 - 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.
+- Durable Decision Worker recovery claims with stale-owner reconciliation and explicit fail-closed takeover.
+- Identity-bound tmux handoff cleanup and recovery/lease lifecycle coverage.
+- Claude Code 2.1.270 bounded stability matrix evidence in `docs/stability-matrix-2.1.270.md`.
 
 ## [0.4.1](https://github.com/btnalit/pi-claude-supervisor/compare/v0.4.0...v0.4.1) (2026-09-14)
 
@@ -85,7 +95,7 @@ All notable changes to this project will be documented here.
 - Historical Claude CLI 2.1.268 permission allow/deny and SIGTERM/SIGINT transport spike evidence; current release validation uses Claude CLI 2.1.270.
 - Event-driven JSONL `control_request`/`result`/exit events, permission responses, persistent Pi Decision Worker automation, bounded duplicate/turn handling, and outbound human-intervention webhooks.
 - Long-task defaults are now 100 automatic turns, 4 hours wall time and 20 minutes without output; Decision Worker API failures alert human operators directly instead of attempting an LLM fallback.
-- Automatic Decision Worker sessions now persist as Pi JSONL with a 0600 task registry. Unclean Pi restarts expose explicit `/supervise recover <task-id>` recovery; Claude work is not silently duplicated.
+- Automatic Decision Worker sessions now persist as Pi JSONL with a 0600 task registry. Unclean Pi restarts expose explicit `/supervise recover [--takeover] <task-id>` recovery; Claude work is not silently duplicated.
 - Local tests and package-content checks.
 
 ### Limitations

package/README.cn.md

@@ -54,7 +54,7 @@ Claude CLI `2.1.270` 运行，跨版本兼容性不在本轮范围内。
 /supervise start --spec ./task.json
 /supervise poll
 /supervise sessions
-/supervise recover <task-id>
+/supervise recover [--takeover] <task-id>
 /supervise stop human requested stop
 /supervise verify
 /supervise approve <task-id> allow|deny [request-id]
@@ -94,17 +94,20 @@ Claude CLI `2.1.270` 运行，跨版本兼容性不在本轮范围内。
 
 当前 webhook 是出站通知，不直接接受批准命令；批准或接管仍通过 Pi。
 自动模式会将 Decision Worker 会话持久化到状态目录。Pi 非正常重启后，`/supervise sessions`
-会显示 `recoverable` 任务；显式执行 `/supervise recover <task-id>` 会恢复 Decision Worker 上下文并
-重新启动 Claude Worker，不会静默恢复或重复执行任务。
+会显示 `recoverable` 任务；显式执行 `/supervise recover [--takeover] <task-id>` 会恢复 Decision Worker 上下文并
+重新启动 Claude Worker，不会静默恢复或重复执行任务。旧 Pi 进程已退出且租约确认旧 Worker
+进程组已消失且 cgroup 仍是真实、可读取的空边界时，才可显式添加 `--takeover`；缺失、仍存活或无法确认的 Worker 会被拒绝。持久 tmux
+Worker 应使用 `adopt-tmux`，而不是 takeover。
 自动模式下，Decision Worker 可以安全拒绝 `AskUserQuestion`，让 Claude 将问题转成普通文本，
 再根据任务和仓库证据自动回答；无法确定时才升级人工。如需微信内闭环，需要另建带签名验证、
 一次性 action token 和重放保护的入站 callback 服务。
 
-近期自动化目标是先稳定完成“多命令验收—独立只读 Reviewer—结构化修复轮次—再次验收”闭环。
+`v0.5.0` 已完成并发布“多命令验收—独立只读 Reviewer—结构化修复轮次—再次验收”闭环。
 任务可通过 API 或 JSON spec 提供 `goal`、`scope`、`constraints`、`forbidden` 和多个
 `acceptance` 命令；旧的纯文本任务继续使用默认 `git diff --check`。Reviewer 只能使用
-`read`、`grep`、`find`、`ls`，不会修改工作树或批准权限。当前稳定性验证固定针对 Claude Code
-`2.1.270`，暂不把多版本兼容、sandbox、低权限和网络隔离作为本阶段门禁。
+`read`、`grep`、`find`、`ls`，不会修改工作树或批准权限。短期剩余门禁是固定 Claude Code
+`2.1.270` 的重复稳定性统计和 recovery 测试；协同多 Worker 属于后续独立开发阶段，
+暂不把多版本兼容、sandbox、低权限和网络隔离作为本阶段门禁。
 
 ### tmux/PTY 交互模式
 
@@ -150,6 +153,11 @@ PTY 屏幕文字不是 Claude JSONL。权限/信任对话框和无法确定的 T
 /supervise send <task-id> continue after checking the test failure
 ```
 
+当前支持的是**独立任务会话并行**，不是共享工作树的协同多 Worker。后续多 Worker
+开发任务会引入 parent/child 任务图、依赖、并发上限、结构化 handoff、汇总验收和
+跨进程恢复，但不会放宽“一个 worktree 一个写入者”的边界，也不会自动 merge 或 publish。
+该阶段应安排在固定 Claude `2.1.270` 稳定性统计和单 Worker recovery 语义完成之后。
+
 Pull Request 必须通过聚合的 `CI / Quality gate`。Release Please 根据 Conventional Commits 创建版本 PR；维护者合并后，Release workflow 会针对精确 tag commit 重新验证，并通过受保护的 `npm` environment 使用 npm provenance 发布。
 
 详细内容见 [engineering-plan.md](docs/engineering-plan.md)、[independent-review.md](docs/independent-review.md)、[architecture.md](docs/architecture.md)、[testing.md](docs/testing.md) 和 [releasing.md](docs/releasing.md)。

package/README.md

@@ -59,7 +59,7 @@ export PI_CLAUDE_SUPERVISOR_WORKER=claude
 /supervise start inspect the current repository and report what should be changed
 /supervise start --spec ./task.json
 /supervise sessions
-/supervise recover <task-id>
+/supervise recover [--takeover] <task-id>
 /supervise poll
 /supervise poll all
 /supervise send continue with read-only inspection
@@ -100,24 +100,36 @@ The supervisor allows only one active JSONL request per session: poll until its
 yet exposed by the adapter. Multiple independent task sessions can run
 concurrently when they use different canonical working directories or
 worktrees; same-directory starts are rejected even when concurrent, and
-`/supervise sessions` lists the sessions. Unattended use still requires the
-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:
+`/supervise sessions` lists the sessions. This is independent-session
+parallelism, not coordinated multi-worker collaboration. A future multi-worker
+milestone will add explicit parent/child task graphs, dependencies, bounded
+scheduling, structured handoffs, aggregate acceptance and graph-aware recovery;
+it will not relax the one-writer-per-worktree rule or enable automatic
+merge/publish. Unattended use still requires the 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 `v0.5.0` 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
+permissions. The next gates are pinned Claude Code `2.1.270` stability statistics
+and explicit session recovery. Coordinated multi-worker scheduling is a later
+milestone; CI will use deterministic fake Workers/replay fixtures, and real
+multi-worker Claude tests will remain authenticated manual Spikes. 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
+tasks; `/supervise recover [--takeover] <task-id>` explicitly restores the Decision Worker
 context and starts a new Claude Worker. It never silently resumes or duplicates
-work. The adapter intentionally does not inherit arbitrary host environment variables.
+work. If the old Pi owner is dead, add `--takeover` only after the lease proves
+the old Worker's process group is gone and its cgroup is a real, readable empty
+boundary; missing or unverifiable Worker evidence is refused.
+For a persistent tmux Worker, use explicit `adopt-tmux` instead of takeover.
+The adapter intentionally does not inherit arbitrary host environment variables.
 Pass credentials through an explicit `WorkerStartInput.env` in an embedding
 integration. For the built-in command, opt in to named variables, for example
 `PI_CLAUDE_SUPERVISOR_WORKER_ENV=ANTHROPIC_API_KEY`.

package/docs/architecture.md

@@ -27,6 +27,28 @@ directories/worktrees; same-cwd and parent/child cwd starts are rejected before
 spawn, including concurrent starts, to prevent uncoordinated edits. Pending starts
 are also awaited during Pi shutdown.
 
+### Multi-worker boundary and roadmap
+
+The current implementation supports multiple **independent** task sessions, not
+coordinated shared-worktree editing. Every active session must own a
+non-overlapping canonical cwd/worktree and has an isolated Supervisor,
+watchdog, Worker handle and acceptance/review loop. The shared EventLog is only
+an audit stream; it is not a collaboration or authorization channel.
+
+A future multi-worker scheduler must introduce an explicit parent/child task
+graph, roles, dependencies, bounded concurrency and structured handoff
+artifacts. Child Workers must communicate through validated evidence and event
+references rather than another Worker's control channel. Each child is accepted
+independently; the parent can complete only after aggregate acceptance and
+independent Review. Integration, conflict resolution, merge and publication
+remain explicit human-controlled operations in a separate integration worktree.
+
+Recovery and shutdown must be graph-aware: a parent with an unknown child state
+cannot complete, cancellation must propagate within a bounded budget, and Pi
+shutdown must leave every child either cleanup-verified or explicitly
+recoverable. This work is scheduled after single-worker stability and session
+recovery, not by relaxing the current cwd lease rule.
+
 ## MVP transport
 
 `ProcessWorkerAdapter` uses `node:child_process.spawn` with:
@@ -126,9 +148,12 @@ registry before spawning Claude. The default registry is
 may point all Pi processes at an alternate shared directory. Canonical paths
 conflict with both their parents and descendants, and the registry lock
 serializes acquisition across independent Pi processes. A lease is released
-only after the adapter confirms the worker and its descendant cleanup; an
-unconfirmed lease left by a crashed Pi is intentionally retained and requires
-operator verification/manual cleanup rather than unsafe automatic reclamation.
+only after the adapter confirms the worker and its descendant cleanup. An
+unconfirmed lease left by a crashed Pi is intentionally retained. Ordinary
+recovery refuses it; an operator may use `recover --takeover` only when the old
+owner is dead, the Worker process group is gone, and the lease independently
+reads a real empty cgroup boundary for the old Worker. Missing or unverifiable
+Worker evidence still requires manual cleanup rather than unsafe reclamation.
 An explicitly adopted tmux session may hand off an existing lease only after
 its owner identity is no longer live and its canonical cwd, tmux session/socket,
 pane id, pane PID/start time, and pane command all match; ordinary starts
@@ -170,7 +195,8 @@ duplicate turns. The adapter also exposes event subscriptions for `result`,
 `control_request`, permission requests and process exit. Automatic mode routes
 those events to a persistent, read-only Pi Decision Worker; its Pi session JSONL
 and task mapping are persisted under the supervisor state directory. After an
-unclean Pi restart, recovery is explicit: `/supervise recover <task-id>` restores
+unclean Pi restart, recovery is explicit: `/supervise recover [--takeover]
+<task-id>` restores
 the Decision Worker context and starts a new Claude Worker. It does not silently
 resume or duplicate a task. It does not poll to detect turn completion. A watchdog timer remains only as a deadlock safety
 fallback. Permission actions pass through `evaluatePermission` and can be

package/docs/engineering-plan.md

@@ -1,6 +1,6 @@
 # Pi Claude Supervisor 完整方案
 
-> 文档状态：方案设计稿 / MVP 实施基线  
+> 文档状态：`v0.5.0` 已发布 / 后续开发路线图
 > 目标项目目录：`pi-claude-supervisor`  
 > 适用对象：W、项目负责人、实现人员、评审人员
 
@@ -36,7 +36,7 @@ Claude Code Worker
 4. Supervisor 因误判导致无限循环、危险操作或不可审计的修改。
 5. 人工无法随时接管或恢复任务。
 
-**总体判断：架构方向可以 GO。先完成兼容性 Spike、生命周期和故障恢复验证；低权限用户、OS sandbox 与网络隔离不作为当前主线或硬性阻塞，按调用者明确授权和宿主机策略运行，后续再做安全加固。**
+**当前状态：`v0.5.0` 已完成“验收—独立 Review—自动修复—再验收”闭环并正式发布。下一阶段先完成固定 Claude Code `2.1.270` 的稳定性统计和恢复语义，再推进有边界的多 Worker 协作；低权限用户、OS sandbox 与网络隔离仍是后续安全加固，不作为当前主线硬性阻塞。**
 
 ---
 
@@ -74,7 +74,9 @@ Claude Code 适合作为实际开发 Worker，但在长时间任务中可能出
 - 不自动 merge、deploy 或 release。
 
 当前扩展已支持多个独立任务会话并行推进，但不允许活动会话共享同一
-工作目录。事件日志由跨进程锁协调，状态和 watchdog 按会话隔离。
+工作目录。事件日志由跨进程锁协调，状态和 watchdog 按会话隔离。这里要区分两种
+“多 Worker”：**独立会话并行**已经属于当前能力；**有依赖、交接和汇总验收的协同多
+Worker**属于后续开发任务，不能通过简单地放宽 cwd 限制来实现。
 
 暂不支持：
 
@@ -979,3 +981,52 @@ Reviewer 必须使用独立 Pi session，只允许 `read`、`grep`、`find`、`l
 - OS sandbox、低权限执行和网络隔离；
 - 自动 merge、deploy、release、publish；
 - 多 Worker 在同一工作树协作。
+
+## 21. 后续开发路线图
+
+`v0.5.0` 的发布不代表所有自动化目标都已完成。后续任务按“稳定性 → 恢复 → 协同
+调度 → 安全加固”推进；多 Worker 可以纳入开发任务，但应作为独立阶段，不能与当前
+单 Worker 稳定性门禁混在一起。
+
+### 21.1 短期：稳定性收尾
+
+- 完成真实 Claude Code `2.1.270` 重复 Spike：普通任务连续 10 次，权限和问题回退各至少 5 次；
+- 补齐 replay：多轮修复、验收失败修复、repair budget 耗尽、takeover、recover 和 Pi shutdown；
+- 补齐边界测试：Reviewer 流式输出上限、`DecisionSessionStore.list()` 任务 ID 校验、跨进程恢复和超时/输出截断；
+- 继续观察 npm `0.5.0`、GitHub Release 资产、provenance 和回滚路径；
+- 验收标准：无重复动作、错误 complete、未清理 Worker 或未审计的自动放行。
+
+### 21.2 中期：恢复能力
+
+- 设计安全的 Claude session resume；明确 `--resume` 与实时 PTY attach 的边界；
+- 完善 takeover、recover、Pi shutdown、Worker 崩溃和部分完成的状态语义；
+- 增加跨进程恢复端到端测试，包括 cwd lease、Decision Worker session、Worker 身份和事件日志一致性；
+- 恢复失败必须进入 `HUMAN_REQUIRED`，不能静默重放原始任务或重复发送输入。
+
+### 21.3 后续：多 Worker 协作与调度
+
+第一阶段只做**独立 worktree 的多 Worker 编排**，不允许共享工作树写入。建议拆成以下
+开发任务：
+
+1. **任务图与角色模型**：增加 `parentTaskId`、Worker role、`dependsOn`、worktree、handoff
+   artifact 和子任务状态；明确 root task 与 child task 的审计关联。
+2. **受限调度器**：实现并发上限、依赖就绪、全局时间/修复预算、取消传播和失败隔离；
+   不让任意 Worker 自行启动、停止或批准另一个 Worker。
+3. **结构化交接**：Worker 之间只通过受限 artifact、事件引用和验收报告交接，不直接共享
+   控制通道；交接内容必须经过 schema 校验和大小限制。
+4. **汇总验收**：每个 child 先独立验收，root task 再汇总目标、diff、测试和 Reviewer 结果；
+   冲突、缺失证据或任一 P0/P1 自动升级人工。
+5. **恢复与关闭**：支持单个 child、整棵任务图和 Pi shutdown 的一致性恢复；父任务不能在
+   子任务状态未知时报告 `completed`。
+6. **冲突检测和人工整合**：只允许在独立 integration worktree 中进行显式整合；不自动
+   merge/publish，冲突和整合动作必须保留人工控制权。
+
+多 Worker 阶段的最小验收矩阵：两个独立 Worker 并行、依赖顺序、一个 Worker 失败、取消
+传播、重复交接、工作树冲突、单 child 恢复、整棵任务图恢复和 shutdown 中断。通过这些
+门禁后，才评估是否需要更复杂的 lead-worker 或动态任务分解。
+
+### 21.4 后置：安全加固
+
+- CLI 多版本兼容矩阵；
+- OS sandbox、低权限执行、网络隔离/allowlist；
+- 更深的供应链、SBOM、密钥隔离和生产监控。

package/docs/recovery-review.md

@@ -0,0 +1,24 @@
+# Recovery follow-up review
+
+The independent read-only review of the recovery changes initially returned
+`BLOCK` with three P1 findings, one P2 finding, and a coverage note. The findings
+were addressed in this follow-up.
+
+- Stale `starting`/`registered`/`recovered_idle` claims now persist recovery
+  owner PID/start time, are reconciled only after the old owner and Worker
+  boundary are independently gone, and return to an explicit `interrupted`
+  state.
+- `--takeover` requires a dead owner, dead Worker/process group, and a real,
+  readable empty cgroup boundary; missing or unverifiable Worker evidence is
+  rejected.
+- Worker registration and `recovered_idle` transitions require an active record,
+  persist atomically, and are read back and checked before the recovered session
+  is exposed.
+- Adopted tmux handoff reports the replaced task and closes its old Decision
+  session mapping only after worker identity registration succeeds.
+- Session closure now carries cleanup evidence and intent; uncertain cleanup
+  retains the active record and cwd lease.
+
+Validation: `npm run check`, `npm run build`, the pinned Claude Code 2.1.270
+question matrix (5/5 verified), and the bounded stability evidence in
+[`stability-matrix-2.1.270.md`](stability-matrix-2.1.270.md).

package/docs/stability-matrix-2.1.270.md

@@ -0,0 +1,32 @@
+# Claude Code 2.1.270 stability matrix
+
+Run date: 2026-09-14. The executable was resolved as
+`/home/yancao/.local/share/mise/installs/claude/2.1.270/claude` and reported
+`2.1.270 (Claude Code)`. Runs used the authenticated local provider and
+`scripts/spike-claude-automation.mjs`; no Claude `--resume` was used.
+
+## Required matrix (120 s bounded run)
+
+| Scenario | Runs | Completed + verified | Fail-closed outcomes |
+| --- | ---: | ---: | --- |
+| ordinary task | 10 | 9 | 1 stopped at the bounded deadline without verification |
+| permission handling | 5 | 5 | 0 |
+| question handling | 5 | 5 | 0 |
+
+The ordinary outlier was not treated as success: the spike exited non-zero,
+kept verification false, and stopped rather than retrying or replaying the task.
+This is the intended timeout fail-closed behavior. An earlier question spike also
+escalated after invalid Decision Worker output; it was likewise not counted as a
+success. The five-run question matrix above was then rerun with a 180 s bound and
+all five completed with `verified=true` and zero human interventions.
+
+## Bounded follow-up
+
+Three additional ordinary and three additional question runs with the same
+pinned executable and a 180 s bound also completed with `verified=true` and zero
+human interventions. These runs support a provider-latency explanation for the
+120 s outliers; they do not turn an outlier into a success.
+
+The deterministic replay, acceptance, recovery-state, lease, cleanup and
+package checks remain the CI evidence. Authenticated Claude runs are manual
+release evidence only.

package/docs/testing.md

@@ -67,8 +67,10 @@ 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
-<task-id>` restores the Decision Worker history before starting a new Claude
-Worker.
+[--takeover] <task-id>` restores the Decision Worker history before starting a new
+Claude Worker. `--takeover` is accepted only when the old Pi owner is dead, the
+Worker process group is gone, and its cgroup is a real readable empty boundary;
+persistent tmux sessions use `adopt-tmux`.
 Run the permission and signal probes explicitly when validating a CLI release:
 
 ```bash
@@ -94,7 +96,9 @@ 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`.
+version. For this release the validated version is `2.1.270` with model `opus`;
+the bounded matrix and its fail-closed outliers are recorded in
+[`docs/stability-matrix-2.1.270.md`](stability-matrix-2.1.270.md).
 Record:
 
 1. exact version and resolved executable path;
@@ -152,7 +156,8 @@ the managed process group.
 
 ## Near-term automation acceptance gate
 
-The next implementation milestone focuses on real stability for the pinned
+The `v0.5.0` implementation of the acceptance—independent Review—repair—reacceptance
+loop is shipped. The remaining gate 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.
 
@@ -186,6 +191,30 @@ The adapter/replay matrix must cover:
 
 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.
+Worker and replay fixtures. The short-term stability gate is still pending and
+must 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.
+
+## Future multi-worker test plan
+
+Multiple independent task sessions already run concurrently when their canonical
+cwd/worktrees do not overlap. This is not yet coordinated multi-worker
+collaboration. The future multi-worker milestone must be tested as a task graph,
+not as unrestricted shared-worker access.
+
+Required deterministic and integration coverage:
+
+- two independent Workers with separate worktrees and aggregated parent status;
+- dependency ordering and a blocked child that must not start early;
+- child failure, timeout, cancellation propagation and bounded global budgets;
+- schema-validated handoff artifacts with duplicate/oversized/stale handoffs;
+- conflicting diffs detected before integration, with no same-worktree writes;
+- 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.
+
+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
+Claude multi-worker Spikes remain manual and version-pinned.

package/package.json

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

package/src/cwd-lease.ts

@@ -36,8 +36,25 @@ export interface CwdLeaseHandoff {
   tmuxSocket?: string;
 }
 
+/**
+ * Explicit recovery takeover. This is intentionally separate from ordinary
+ * acquisition: an old Pi owner may have died while its Worker survived.
+ */
+export interface CwdLeaseTakeover {
+  taskId: string;
+  /** Run before the old lease is removed; failure leaves the old lease intact. */
+  beforeReplace?: (lease: CwdLeaseRecord) => Promise<void>;
+}
+
+export interface CwdLeaseAcquireOptions {
+  handoff?: CwdLeaseHandoff;
+  takeover?: CwdLeaseTakeover;
+}
+
 export interface CwdLeaseHandle {
   readonly record: CwdLeaseRecord;
+  /** Task id whose lease was explicitly handed off/taken over, if any. */
+  readonly replacedTaskId?: string;
   updateWorker(worker: CwdLeaseWorker): Promise<void>;
   release(): Promise<void>;
 }
@@ -63,7 +80,9 @@ export class CwdLeaseStore {
     return this.#directory;
   }
 
-  async acquire(cwd: string, taskId: string, transport: CwdLeaseTransport, options: { handoff?: CwdLeaseHandoff } = {}): Promise<CwdLeaseHandle> {
+  async acquire(cwd: string, taskId: string, transport: CwdLeaseTransport, options: CwdLeaseAcquireOptions = {}): Promise<CwdLeaseHandle> {
+    assertTaskId(taskId);
+    if (options.takeover) assertTaskId(options.takeover.taskId);
     const canonicalCwd = await realpath(resolve(cwd));
     const now = new Date().toISOString();
     const lease: CwdLeaseRecord = {
@@ -77,6 +96,7 @@ export class CwdLeaseStore {
       updatedAt: now,
       worker: { transport },
     };
+    let replacedTaskId: string | undefined;
     await this.#withLock(async () => {
       const leases = await this.#readAll();
       let handoffLease: CwdLeaseRecord | undefined;
@@ -88,23 +108,35 @@ export class CwdLeaseStore {
           continue;
         }
         if (!pathsOverlap(existing.cwd, canonicalCwd)) continue;
+        if (options.takeover?.taskId === existing.taskId
+          && existing.cwd === canonicalCwd
+          && await canTakeoverLease(existing)) {
+          await options.takeover.beforeReplace?.(existing);
+          replacedTaskId = existing.taskId;
+          await rm(this.#path(existing.leaseId), { force: true });
+          continue;
+        }
         throw new Error(`working-directory lease is held by task ${existing.taskId}: ${redactText(existing.cwd)}`);
       }
       await this.#write(lease);
-      if (handoffLease) await rm(this.#path(handoffLease.leaseId), { force: true });
+      if (handoffLease) {
+        replacedTaskId = handoffLease.taskId;
+        await rm(this.#path(handoffLease.leaseId), { force: true });
+      }
     });
-    return this.#handle(lease);
+    return this.#handle(lease, replacedTaskId);
   }
 
   async list(): Promise<CwdLeaseRecord[]> {
     return this.#withLock(() => this.#readAll());
   }
 
-  #handle(initial: CwdLeaseRecord): CwdLeaseHandle {
+  #handle(initial: CwdLeaseRecord, replacedTaskId?: string): CwdLeaseHandle {
     let current = { ...initial, worker: initial.worker ? { ...initial.worker } : undefined };
     let released = false;
     return {
       get record() { return current; },
+      get replacedTaskId() { return replacedTaskId; },
       updateWorker: async (worker) => {
         if (released) throw new Error("cwd lease has already been released");
         assertWorker(worker);
@@ -157,8 +189,8 @@ export class CwdLeaseStore {
   async #write(lease: CwdLeaseRecord): Promise<void> {
     await this.#ensureDirectory();
     const target = this.#path(lease.leaseId);
-    const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(temporary, `${JSON.stringify(lease, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    const temporary = `${target}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(lease, null, 2)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
     await rename(temporary, target);
     await chmod(target, 0o600);
   }
@@ -252,6 +284,10 @@ async function processIdentityLive(pid: number, expectedStartTime?: string): Pro
   const currentStartTime = await processStartTime(pid);
   if (currentStartTime && expectedStartTime) return currentStartTime === expectedStartTime;
   if (currentStartTime) return true;
+  return processExists(pid);
+}
+
+async function processExists(pid: number): Promise<boolean> {
   try {
     process.kill(pid, 0);
     return true;
@@ -260,6 +296,55 @@ async function processIdentityLive(pid: number, expectedStartTime?: string): Pro
   }
 }
 
+async function processGroupExists(pid: number): Promise<boolean> {
+  try {
+    process.kill(-pid, 0);
+    return true;
+  } catch (error) {
+    return error instanceof Error && /EPERM/u.test(error.message);
+  }
+}
+
+async function cgroupHasProcesses(path: string): Promise<boolean> {
+  // Lease files are untrusted state. Never read an arbitrary path during
+  // takeover; only a real, canonical cgroup below the kernel cgroup root is
+  // eligible for this check. Missing/unreadable evidence is not proof of an
+  // empty cgroup: a descendant may have escaped before the cgroup disappeared.
+  const cgroupRoot = resolve("/sys/fs/cgroup");
+  const cgroupPath = resolve(path);
+  if (cgroupPath === cgroupRoot || !cgroupPath.startsWith(`${cgroupRoot}/`)) return true;
+  try {
+    const cgroupInfo = await lstat(cgroupPath);
+    if (!cgroupInfo.isDirectory() || cgroupInfo.isSymbolicLink()) return true;
+    const canonicalPath = await realpath(cgroupPath);
+    if (canonicalPath !== cgroupPath || !canonicalPath.startsWith(`${cgroupRoot}/`)) return true;
+    const procsPath = join(canonicalPath, "cgroup.procs");
+    const procsInfo = await lstat(procsPath);
+    if (!procsInfo.isFile() || procsInfo.isSymbolicLink()) return true;
+    const contents = await readFile(procsPath, "utf8");
+    return contents.split(/\s+/u).some((pid) => /^\d+$/u.test(pid));
+  } catch {
+    return true;
+  }
+}
+
+async function canTakeoverLease(lease: CwdLeaseRecord): Promise<boolean> {
+  // The old supervisor owner must be gone. A dead owner is not enough when
+  // the detached Worker itself is still alive.
+  if (await processExists(lease.ownerPid)) return false;
+  const worker = lease.worker;
+  if (!worker) return false;
+  if (worker.transport === "tmux") return false;
+  if (!worker.pid) return false;
+  if (await processExists(worker.pid)) return false;
+  if (await processGroupExists(worker.pid)) return false;
+  // A process-group check cannot see a setsid descendant. Explicit takeover
+  // therefore requires the verified cgroup boundary used by the adapter.
+  if (!worker.cgroupPath || !resolve(worker.cgroupPath).startsWith(`${resolve("/sys/fs/cgroup")}/`)) return false;
+  if (await cgroupHasProcesses(worker.cgroupPath)) return false;
+  return true;
+}
+
 async function processStartTime(pid: number): Promise<string | undefined> {
   try {
     const statText = await readFile(`/proc/${pid}/stat`, "utf8");
@@ -288,6 +373,10 @@ async function matchesHandoff(lease: CwdLeaseRecord, handoff: CwdLeaseHandoff):
   return !(await processIdentityLive(lease.ownerPid, lease.ownerStartTime));
 }
 
+function assertTaskId(taskId: string): void {
+  if (!/^[0-9a-f-]{36}$/iu.test(taskId)) throw new Error("invalid cwd lease task id");
+}
+
 function assertWorker(worker: CwdLeaseWorker): void {
   if (!["process-pipe", "jsonl", "pty", "tmux"].includes(worker.transport)
     || (worker.pid !== undefined && (!Number.isSafeInteger(worker.pid) || worker.pid < 1))