pi-claude-supervisor 0.5.0 → 0.5.2

package/docs/engineering-plan.md

@@ -1,6 +1,6 @@
 # Pi Claude Supervisor 完整方案
 
-> 文档状态：方案设计稿 / MVP 实施基线  
+> 文档状态：`v0.5.1` 已发布；Phase A–D 加固和真实 repair/reacceptance 已在当前工作树实现；待 exact-head 独立只读 Review 门禁
 > 目标项目目录：`pi-claude-supervisor`  
 > 适用对象：W、项目负责人、实现人员、评审人员
 
@@ -36,7 +36,7 @@ Claude Code Worker
 4. Supervisor 因误判导致无限循环、危险操作或不可审计的修改。
 5. 人工无法随时接管或恢复任务。
 
-**总体判断：架构方向可以 GO。先完成兼容性 Spike、生命周期和故障恢复验证；低权限用户、OS sandbox 与网络隔离不作为当前主线或硬性阻塞，按调用者明确授权和宿主机策略运行，后续再做安全加固。**
+**当前状态：`v0.5.1` 已正式发布，已完成固定 Claude Code `2.1.270` 稳定性统计、单 Worker recovery、真实只读 Review drill 和隔离临时 worktree 的允许编辑 repair/reacceptance drill。当前工作树已落实 repairable/persistent 能力拆分、verifying stop、paused watchdog、完整 repository evidence、可取消验收/Reviewer、启动 preflight、权限门禁修复和阶段进度通知；下一项也是发布前最后硬门禁的是当前 exact head 的独立只读 Review。协同多 Worker 仍延期；低权限用户、OS sandbox 与网络隔离仍是后续安全加固。**
 
 ---
 
@@ -74,7 +74,9 @@ Claude Code 适合作为实际开发 Worker，但在长时间任务中可能出
 - 不自动 merge、deploy 或 release。
 
 当前扩展已支持多个独立任务会话并行推进，但不允许活动会话共享同一
-工作目录。事件日志由跨进程锁协调，状态和 watchdog 按会话隔离。
+工作目录。事件日志由跨进程锁协调，状态和 watchdog 按会话隔离。这里要区分两种
+“多 Worker”：**独立会话并行**已经属于当前能力；**有依赖、交接和汇总验收的协同多
+Worker**属于后续开发任务，不能通过简单地放宽 cwd 限制来实现。
 
 暂不支持：
 
@@ -979,3 +981,74 @@ 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、密钥隔离和生产监控。
+
+## 22. v0.5.1 真实演练后的自动化加固计划
+
+`v0.5.1` 发布后的真实 Claude Code `2.1.270` 演练完成了
+Worker → 验收 → 独立 Reviewer → fail-closed 人工介入链路。验收六项全部通过，
+但发现两个 P1 和两个 P2 生命周期/证据问题。正式记录、复现结果、实施阶段和门禁
+见 [`docs/automation-hardening-plan.md`](automation-hardening-plan.md)。
+
+本轮实现顺序固定为：
+
+1. **生命周期与能力模型**：拆分 `persistentSession` 与 `repairableSession`，修复非持久
+   JSONL repair 的非法终态转换，并支持 `verifying` 状态的 stop/shutdown；
+2. **watchdog 与证据完整性**：暂停 no-output 时钟，补齐 HEAD-relative staged/unstaged
+   diff 和安全的 untracked evidence；
+3. **自动化协议**：按 assistant message 边界解析 Reviewer/Decision Worker 输出，增加
+   启动 preflight、可观测 heartbeat、permission gate 一致性和 signal 生命周期；
+4. **验证门禁**：已补齐真实 capability 矩阵并完成隔离 worktree 的真实
+   repair/reacceptance 演练；当前 exact-head 独立 Reviewer 通过前不进行任何合并或发布。
+
+本轮不放宽以下边界：Reviewer 仍只读，验收仍使用 argv/`execFile`，不伪造 Claude
+`--resume`，不自动 merge/deploy/release，P0/P1、重复 finding、超时、API 错误和不完整
+证据继续 fail-closed。多 Worker 协作继续后置。

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

@@ -65,10 +65,15 @@ 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,
+0600 task mapping. Automatic startup preflights the state/lease directories, cwd,
+worker executable, transport dependency and required cgroup boundary before model
+execution. Progress callbacks expose the current phase and periodic Worker
+heartbeat. 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 +99,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;
@@ -116,7 +123,9 @@ escalation is outbound-only through `PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_URL`;
 approval callbacks are deliberately not accepted without a separately
 authenticated endpoint.
 
-The tmux transport is selected with `PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux`. Before
+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
 replacement refusal, pause/resume, owned-session stop, adopted-session
@@ -133,28 +142,38 @@ response.
 
 The automated adapter matrix covers external `SIGTERM`, `SIGINT`, `SIGKILL`,
 `SIGSTOP`/`SIGCONT`, SIGTERM refusal/escalation, leader-early-exit descendant
-cleanup, required cgroup cleanup of a `setsid()` descendant, repeated stop,
-spawn failure, output truncation, blocked stdin write timeouts, and immediate
-JSONL results. The Supervisor matrix also covers
-retrying failed lifecycle events, preserving startup event order, stopping under
-persistent timeout-event failure, and restoring output after event-log failure. The Supervisor matrix covers startup rejection, externally terminated
-workers, lifecycle serialization and stop races.
+cleanup, required cgroup bootstrap containment of a pre-attachment detached
+and `setsid()` descendant, repeated stop, spawn failure, output truncation,
+blocked stdin write timeouts, and immediate JSONL results. The Supervisor
+matrix also covers retrying failed lifecycle events, preserving startup event
+order, stopping under persistent timeout-event failure, and restoring output
+after event-log failure. The Supervisor matrix covers startup rejection,
+externally terminated workers, lifecycle serialization and stop races.
 
 Before release, manually test at least: immediate crash, hung process, malformed
 output, duplicate send, send/exit race, Pi `SIGTERM`/`SIGINT` shutdown,
 verification failure, blocked stdin writes/stop preemption, corrupt event-log
 tails, and descendants that call `setsid()` when cgroup mode is unavailable (expected
-fallback limitation). The cgroup test proves cleanup after attachment but does
-not eliminate the post-spawn attachment window. `SIGSTOP` and `SIGKILL` of the Pi host cannot be handled;
-verify and document the resulting orphan behavior.
+fallback limitation). In cgroup mode, a small bootstrap joins the cgroup before
+launching Worker code, and cleanup also validates and reaps the detached process
+group; this closes the post-spawn attachment window. `SIGSTOP` and `SIGKILL` of
+the Pi host cannot be handled; 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.
+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.
+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
+in [`docs/automation-hardening-plan.md`](automation-hardening-plan.md). Deterministic
+coverage now includes repairable-vs-persistent capability assertions, cancellation
+of acceptance commands, stop-from-verifying precedence, paused watchdog baselining,
+staged/untracked evidence and untracked symlink rejection. The remaining release gate
+is the exact-head independent read-only review.
 
 ### Acceptance and Reviewer fixtures
 
@@ -165,6 +184,9 @@ Deterministic tests must cover:
 - 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;
+- 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;
 - completion being impossible without passing all required checks and review.
 
 Reviewer sessions use only `read`, `grep`, `find` and `ls`; they must not modify
@@ -182,10 +204,57 @@ The adapter/replay matrix must cover:
 - 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.
+  multi-turn, verifier failure/repair, takeover and explicit recovery;
+- staged and untracked repository evidence, symlink rejection and truncation fail-closed;
+- paused watchdog behavior and resume-time no-output rebasing;
+- assistant-message-bounded Reviewer and Decision Worker output parsing.
 
 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 pinned stability matrix is the compatibility evidence
+for this release line; any future CLI change must rerun 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.
+
+## Live drill and hardening gate
+
+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.
+
+For the hardening release, the completed gate record is:
+
+1. `npm run check`, `npm run test:pi`, `npm run test:install`, `npm run build`;
+2. deterministic lifecycle/evidence/capability tests;
+3. a disposable temporary-worktree real Claude repair/reacceptance spike with an edit-capable
+   Worker;
+4. cleanup verification: no Worker, no Decision Worker, no unreconciled lease and clean Git
+   worktree.
+
+The remaining gate is a read-only review of the exact resulting commit. The drill evidence is
+recorded in `docs/automation-hardening-plan.md`; it did not run against this release worktree,
+did not use Claude `--resume`, and did not merge, publish or release automatically.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-claude-supervisor",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "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))