pi-claude-supervisor 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,12 +2,24 @@
 
 All notable changes to this project will be documented here.
 
+## [0.4.0](https://github.com/btnalit/pi-claude-supervisor/compare/v0.3.0...v0.4.0) (2026-09-13)
+
+
+### Features
+
+* add cross-process cwd leases and cancellable startup ([#17](https://github.com/btnalit/pi-claude-supervisor/issues/17)) ([448cbdb](https://github.com/btnalit/pi-claude-supervisor/commit/448cbdb4c6b5dd02b9ea07ba660d3689b7e2ace8))
+
 ## [0.3.0](https://github.com/btnalit/pi-claude-supervisor/compare/v0.2.2...v0.3.0) (2026-09-13)
 
 
 ### Features
 
 * add safe tmux Claude worker transport ([1706153](https://github.com/btnalit/pi-claude-supervisor/commit/1706153289f9a6f7f9f59b2763ed98d061b79204))
+* add cross-process canonical cwd leases and identity-bound tmux handoff
+* make startup cancellation scoped per start and shutdown cleanup fail closed
+* add cgroup-v2 required/auto/off policies with verified fallback cleanup
+* harden owned/adopted tmux lifecycle, pane identity validation, and restart re-adoption
+* validate real Claude Code 2.1.270 tmux multi-turn, pause/resume, and re-adoption behavior
 
 ## [0.2.2](https://github.com/btnalit/pi-claude-supervisor/compare/v0.2.1...v0.2.2) (2026-09-12)
 
@@ -47,7 +59,7 @@ All notable changes to this project will be documented here.
 - Bounded output capture, stdin-write timeout, process-group cleanup retry and stop preemption.
 - Linux cgroup-v2 descendant cleanup, including a `setsid()` regression fixture, with required/auto modes.
 - Lifecycle event retry/order preservation, output restoration after log failure and shutdown cleanup retries.
-- Claude CLI 2.1.268 permission allow/deny and SIGTERM/SIGINT transport spike evidence.
+- 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.
@@ -55,5 +67,5 @@ All notable changes to this project will be documented here.
 
 ### Limitations
 
-- tmux/PTY screen state is not Claude JSONL: trust, permission and ambiguous TUI states require human handling. Cross-version Claude CLI permission/session semantics remain outside the pinned compatibility claim. The installed 2.1.268 CLI is covered by local permission and signal spikes, while the cgroup startup-attachment window remains.
+- tmux/PTY screen state is not Claude JSONL: trust, permission and ambiguous TUI states require human handling. Cross-version Claude CLI permission/session semantics remain outside the pinned compatibility claim. Historical permission and signal spikes use 2.1.268; current tmux validation uses 2.1.270, while the cgroup startup-attachment window remains.
 - No automatic merge, deployment, release or publication is implemented.

package/README.cn.md

@@ -42,9 +42,9 @@ export PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_FORMAT=generic
 # export PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_SECRET='shared-secret'
 ```
 
-自动模式会强制使用 `claude-jsonl`，通过 `result`、`control_request` 和进程
-`exit` 事件唤醒 Decision Worker；不会依赖 `/supervise poll` 轮询。本版本固定按已验证设备的
-Claude CLI `2.1.268` 运行，跨版本兼容性不在本轮范围内。
+自动模式默认使用 `claude-jsonl`，通过 `result`、`control_request` 和进程
+`exit` 事件唤醒 Decision Worker；显式选择 tmux 时仍使用屏幕交互，不使用 JSONL 权限协议，也不会依赖 `/supervise poll` 轮询。本版本固定按已验证设备的
+Claude CLI `2.1.270` 运行，跨版本兼容性不在本轮范围内。
 
 然后在 Pi 中使用：
 

package/README.md

@@ -104,6 +104,7 @@ For an interactive Claude Code window, opt in to the tmux transport:
 ```bash
 export PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux
 export PI_CLAUDE_SUPERVISOR_WORKER='claude --permission-mode plan'
+# tmux does not support cgroup required mode; use cgroup mode auto/off.
 # Optional automatic Decision Worker (manual mode is the default):
 # export PI_CLAUDE_SUPERVISOR_MODE=auto
 # Optional, only when adopting a non-default tmux server:

package/docs/architecture.md

@@ -39,8 +39,9 @@ are also awaited during Pi shutdown.
 
 This is a control-boundary fixture and headless transport. It does not emulate a
 terminal. Manual compatibility mode remains `process-pipe`; automatic mode
-(`PI_CLAUDE_SUPERVISOR_MODE=auto`) forces Claude JSONL and uses the CLI contract
-validated by the fixed-version spike.
+(`PI_CLAUDE_SUPERVISOR_MODE=auto`) defaults to Claude JSONL and uses the CLI
+contract validated by the fixed-version spike; an explicit tmux transport remains
+screen-based.
 
 A worker exit automatically triggers cleanup, and terminal status waits for
 that cleanup to be confirmed (or reports a cleanup error). On Linux the adapter
@@ -62,11 +63,14 @@ signals.
 ## tmux/PTY transport
 
 `TmuxWorkerAdapter` is an explicit second transport, selected with
-`PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux`. An owned worker gets a private tmux
-server/socket and a launcher file containing only the validated command, args and
-cwd. The worker environment is supplied to the tmux server through the same
-least-privilege environment builder; environment credentials are not copied into
-the launcher file; credential-shaped command arguments are rejected.
+`PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux`. Because tmux has no equivalent cgroup
+containment boundary, `PI_CLAUDE_SUPERVISOR_CGROUP_MODE=required` is rejected
+with this transport; use `auto`/`off` only when the tmux boundary is acceptable.
+An owned worker gets a private tmux server/socket and executes the validated Claude command directly in the pane,
+so its pane identity remains re-adoptable after a Pi restart. The worker
+environment is supplied to the tmux server through the same least-privilege
+environment builder; credentials are not copied into a file; credential-shaped
+command arguments are rejected.
 `load-buffer`, bracketed `paste-buffer` and `send-keys Enter` provide the input
 boundary without interpolating a task into a shell command. C0/C1 terminal
 control bytes are rejected; CRLF is normalized to a newline.
@@ -114,6 +118,34 @@ lifecycle event append fails after the state transition, it remains pending and
 is retried before the next lifecycle operation; output events restore their
 chunks for a lossless retry.
 
+### Cross-process cwd leases and startup cancellation
+
+Every start and explicit recovery acquires an atomic lease in the shared lease
+registry before spawning Claude. The default registry is
+`~/.pi/agent/claude-supervisor/cwd-leases`; `PI_CLAUDE_SUPERVISOR_CWD_LEASE_DIR`
+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.
+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
+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.
+
+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
+startup cleanup without waiting behind the serialized start operation. Each
+startup carries an opaque token, so cancelling one concurrent session cannot
+abort another. Process and tmux adapters terminate or detach their startup
+work, and the Supervisor rechecks cancellation before reporting `running`; a cancelled startup becomes
+`stopped` and never reports a worker that was not cleanup-verified.
+
 ## Event log
 
 Events are JSONL with a monotonic sequence number, timestamp, task ID and worker

package/docs/releasing.md

@@ -104,7 +104,8 @@ Major updates remain separate for explicit review. There is no blanket auto-merg
 A maintainer can retry an existing stable release from Actions:
 
 ```bash
-gh workflow run release.yml --ref main -f tag=v0.1.1
+TAG=v0.3.0
+gh workflow run release.yml --ref main -f tag="$TAG"
 ```
 
 The workflow verifies that the release tag is stable and belongs to `main`, then

package/docs/testing.md

@@ -49,8 +49,11 @@ 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 current fixtures validate one prompt, multiple turns, session resume,
+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
+`/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
 `permission_request` events, and the exact nested `control_response` envelope.
 The automation spike additionally exercises a real Pi SDK Decision Worker with
@@ -70,10 +73,15 @@ 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=1 npm run spike:tmux
 ```
 
-For this release, pin and record Claude Code `2.1.268` and its resolved
-executable path. Record:
+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:
 
 1. exact version and resolved executable path;
 2. license and source revision;
@@ -86,9 +94,10 @@ executable path. Record:
 A passing worker task is not sufficient. The independent verifier must repeat the
 relevant checks from a clean host perspective.
 
-Automatic mode is enabled with `PI_CLAUDE_SUPERVISOR_MODE=auto`; it forces JSONL
-and routes `result`, permission, and process-exit events to the persistent Pi
-Decision Worker. `process-pipe` remains the manual compatibility mode. Human
+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
 authenticated endpoint.

package/docs/transport-spike-2026-09-12.md

@@ -8,7 +8,7 @@ without exposing credentials or allowing repository changes.
 ## Environment
 
 - Node: `v26.8.1` (declared package minimum remains `>=22.19`)
-- Claude Code: `2.1.268`
+- Claude Code: `2.1.268` (historical headless probe; current release validation uses `2.1.270`)
 - Executable: resolved through `PATH` as `claude`
 - Working directory: `/home/yancao/Work`
 - Session persistence: disabled for the stateless fixture; enabled for the separate resume fixture
@@ -56,7 +56,7 @@ existing default remains generic `process-pipe`.
 
 ## Required follow-up
 
-Additional evidence was collected with Claude Code `2.1.268` using
+Historical permission evidence was collected with Claude Code `2.1.268` using
 `--permission-prompt-tool stdio --permission-mode default --tools Bash`:
 
 - The CLI emitted `control_request` with `request.subtype=can_use_tool`,
@@ -72,7 +72,7 @@ Additional evidence was collected with Claude Code `2.1.268` using
   decision at the wrong envelope level is rejected as an invalid permission
   result.
 
-The exact signal fixture also passed for `2.1.268`: after `system/init`, a group
+The exact signal fixture also passed for historical version `2.1.268`: after `system/init`, a group
 `SIGTERM` produced exit code `143` with no terminal result; group `SIGINT`
 produced exit code `0` and a terminal result with `terminal_reason=
 "aborted_streaming"` and `is_error=true`. The new adapter cgroup-v2 fixture
@@ -87,8 +87,8 @@ npm run spike:signals
 ```
 
 Remaining evidence is malformed/duplicate CLI input, no secret leakage in
-captured events, and the cgroup startup-attachment window. Release scope is
-pinned to Claude Code `2.1.268` on the validated device; cross-version
-portability is explicitly out of scope for this iteration. The adapter-level
-lifecycle track is now **GO** for the installed CLI and host; atomic OS process
-containment remains follow-up work.
+captured events, and the cgroup startup-attachment window. The current release
+also passed a real Claude Code `2.1.270` tmux validation: owned multi-turn
+interaction, pause/resume, explicit detach, and identity-bound restart
+re-adoption. The adapter-level lifecycle track is now **GO** for the installed
+CLI and host; atomic OS process containment remains follow-up work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-claude-supervisor",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A policy-gated Pi supervisor for observing and verifying Claude Code workers.",
   "license": "MIT",
   "publishConfig": {
@@ -56,6 +56,7 @@
     "test:install": "node scripts/test-install.mjs",
     "test:pi": "node scripts/test-pi.mjs",
     "spike:transport": "node scripts/spike-claude-transport.mjs",
+    "spike:tmux": "node scripts/spike-claude-tmux.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/config.ts

@@ -7,9 +7,11 @@ const allowed = new Set([
   "PI_CLAUDE_SUPERVISOR_MODE",
   "PI_CLAUDE_SUPERVISOR_AUTOMATION",
   "PI_CLAUDE_SUPERVISOR_TRANSPORT",
+  "PI_CLAUDE_SUPERVISOR_CGROUP_MODE",
   "PI_CLAUDE_SUPERVISOR_TMUX_SOCKET",
   "PI_CLAUDE_SUPERVISOR_WORKER",
   "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",

package/src/cwd-lease.ts

@@ -0,0 +1,345 @@
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, readFile, readdir, realpath, rm, stat, writeFile, rename } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { redactSensitive } from "./redaction.ts";
+
+export type CwdLeaseTransport = "process-pipe" | "jsonl" | "pty" | "tmux";
+
+export interface CwdLeaseWorker {
+  transport: CwdLeaseTransport;
+  pid?: number;
+  startTime?: string;
+  sessionName?: string;
+  tmuxSocket?: string;
+  ownership?: "owned" | "adopted";
+  cgroupPath?: string;
+  tmuxTarget?: string;
+  tmuxPaneId?: string;
+  paneStartTime?: string;
+  paneCommand?: string;
+}
+
+export interface CwdLeaseRecord {
+  version: 1;
+  leaseId: string;
+  taskId: string;
+  cwd: string;
+  ownerPid: number;
+  ownerStartTime?: string;
+  acquiredAt: string;
+  updatedAt: string;
+  worker?: CwdLeaseWorker;
+}
+
+export interface CwdLeaseHandoff {
+  sessionName: string;
+  tmuxSocket?: string;
+}
+
+export interface CwdLeaseHandle {
+  readonly record: CwdLeaseRecord;
+  updateWorker(worker: CwdLeaseWorker): Promise<void>;
+  release(): Promise<void>;
+}
+
+const LOCK_TIMEOUT_MS = 10_000;
+const STALE_LOCK_MS = 5_000;
+
+/**
+ * Cross-process working-directory lease registry.
+ *
+ * A lease is deliberately not reclaimed merely because its owner process died:
+ * a worker may have survived the Pi process. The operator must clean up an
+ * unconfirmed lease explicitly after verifying the old worker is gone.
+ */
+export class CwdLeaseStore {
+  readonly #directory: string;
+
+  constructor(directory: string) {
+    this.#directory = resolve(directory);
+  }
+
+  get directory(): string {
+    return this.#directory;
+  }
+
+  async acquire(cwd: string, taskId: string, transport: CwdLeaseTransport, options: { handoff?: CwdLeaseHandoff } = {}): Promise<CwdLeaseHandle> {
+    const canonicalCwd = await realpath(resolve(cwd));
+    const now = new Date().toISOString();
+    const lease: CwdLeaseRecord = {
+      version: 1,
+      leaseId: randomUUID(),
+      taskId,
+      cwd: canonicalCwd,
+      ownerPid: process.pid,
+      ownerStartTime: await processStartTime(process.pid),
+      acquiredAt: now,
+      updatedAt: now,
+      worker: { transport },
+    };
+    await this.#withLock(async () => {
+      const leases = await this.#readAll();
+      let handoffLease: CwdLeaseRecord | undefined;
+      for (const existing of leases) {
+        if (options.handoff && existing.cwd === canonicalCwd && await matchesHandoff(existing, options.handoff)) {
+          if (handoffLease) throw new Error("multiple matching tmux cwd leases; refusing ambiguous handoff");
+          handoffLease = existing;
+          lease.worker = { ...existing.worker!, transport };
+          continue;
+        }
+        if (!pathsOverlap(existing.cwd, canonicalCwd)) 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 });
+    });
+    return this.#handle(lease);
+  }
+
+  async list(): Promise<CwdLeaseRecord[]> {
+    return this.#withLock(() => this.#readAll());
+  }
+
+  #handle(initial: CwdLeaseRecord): CwdLeaseHandle {
+    let current = { ...initial, worker: initial.worker ? { ...initial.worker } : undefined };
+    let released = false;
+    return {
+      get record() { return current; },
+      updateWorker: async (worker) => {
+        if (released) throw new Error("cwd lease has already been released");
+        assertWorker(worker);
+        const next = { ...current, worker: { ...worker }, updatedAt: new Date().toISOString() };
+        await this.#withLock(async () => {
+          const leases = await this.#readAll();
+          const existing = leases.find((lease) => lease.leaseId === current.leaseId);
+          if (!existing) throw new Error("cwd lease disappeared before worker identity could be recorded");
+          if (existing.cwd !== current.cwd || existing.taskId !== current.taskId) throw new Error("cwd lease identity changed; refusing update");
+          await this.#write(next);
+        });
+        current = next;
+      },
+      release: async () => {
+        if (released) return;
+        await this.#withLock(async () => {
+          const leases = await this.#readAll();
+          const existing = leases.find((lease) => lease.leaseId === current.leaseId);
+          if (!existing) throw new Error("cwd lease disappeared before release");
+          await rm(this.#path(existing.leaseId), { force: true });
+        });
+        released = true;
+      },
+    };
+  }
+
+  async #readAll(): Promise<CwdLeaseRecord[]> {
+    let names: string[];
+    try {
+      names = await readdir(this.#directory);
+    } catch (error) {
+      if (error instanceof Error && /ENOENT/u.test(error.message)) return [];
+      throw error;
+    }
+    const leases: CwdLeaseRecord[] = [];
+    for (const name of names.filter((item) => item.endsWith(".json"))) {
+      const leasePath = join(this.#directory, name);
+      const leaseInfo = await lstat(leasePath);
+      if (!leaseInfo.isFile()) throw new Error(`cwd lease entry is not a regular file: ${redactText(leasePath)}`);
+      const value = JSON.parse(await readFile(leasePath, "utf8")) as Partial<CwdLeaseRecord>;
+      const lease = normalizeLease(value);
+      // A missing or replaced cwd invalidates the registry evidence. Do not
+      // silently drop that record and allow a second worker to start.
+      lease.cwd = await realpath(lease.cwd);
+      leases.push(lease);
+    }
+    return leases;
+  }
+
+  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 });
+    await rename(temporary, target);
+    await chmod(target, 0o600);
+  }
+
+  #path(leaseId: string): string {
+    return join(this.#directory, `${leaseId}.json`);
+  }
+
+  async #withLock<T>(operation: () => Promise<T>): Promise<T> {
+    await this.#ensureDirectory();
+    const lockPath = join(this.#directory, ".lock");
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    while (true) {
+      try {
+        await mkdir(lockPath);
+        await writeFile(join(lockPath, "owner.json"), JSON.stringify({
+          pid: process.pid,
+          startTime: await processStartTime(process.pid),
+          at: new Date().toISOString(),
+        }), { mode: 0o600 });
+        break;
+      } catch (error) {
+        if (!(error instanceof Error) || !/EEXIST/u.test(error.message)) throw error;
+        if (await removeStaleLock(lockPath)) continue;
+        if (Date.now() >= deadline) throw new Error(`cwd lease lock timeout: ${redactText(lockPath)}`);
+        await delay(25);
+      }
+    }
+    try {
+      return await operation();
+    } finally {
+      await rm(lockPath, { recursive: true, force: true });
+    }
+  }
+
+  async #ensureDirectory(): Promise<void> {
+    await mkdir(this.#directory, { recursive: true, mode: 0o700 });
+    const info = await lstat(this.#directory);
+    if (!info.isDirectory()) throw new Error(`cwd lease registry is not a directory: ${redactText(this.#directory)}`);
+    await chmod(this.#directory, 0o700);
+  }
+}
+
+export function pathsOverlap(first: string, second: string): boolean {
+  const left = resolve(first);
+  const right = resolve(second);
+  return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+
+export async function workerIdentity(worker: Pick<CwdLeaseWorker, "pid" | "cgroupPath" | "tmuxTarget" | "tmuxPaneId" | "paneStartTime" | "paneCommand">): Promise<Pick<CwdLeaseWorker, "pid" | "startTime" | "cgroupPath" | "tmuxTarget" | "tmuxPaneId" | "paneStartTime" | "paneCommand">> {
+  return {
+    pid: worker.pid,
+    startTime: worker.pid ? await processStartTime(worker.pid) : undefined,
+    cgroupPath: worker.cgroupPath,
+    tmuxTarget: worker.tmuxTarget,
+    tmuxPaneId: worker.tmuxPaneId,
+    paneStartTime: worker.paneStartTime,
+    paneCommand: worker.paneCommand,
+  };
+}
+
+async function removeStaleLock(lockPath: string): Promise<boolean> {
+  try {
+    const lockInfo = await lstat(lockPath);
+    if (!lockInfo.isDirectory()) throw new Error("cwd lease lock is not a directory");
+    const ownerPath = join(lockPath, "owner.json");
+    const ownerInfo = await lstat(ownerPath);
+    if (!ownerInfo.isFile()) throw new Error("cwd lease lock owner is not a regular file");
+    const info = await stat(ownerPath);
+    if (Date.now() - info.mtimeMs < STALE_LOCK_MS) return false;
+    const owner = JSON.parse(await readFile(ownerPath, "utf8")) as { pid?: unknown; startTime?: unknown };
+    if (typeof owner.pid === "number") {
+      const currentStart = await processStartTime(owner.pid);
+      if (currentStart && typeof owner.startTime === "string" && currentStart === owner.startTime) return false;
+      try {
+        process.kill(owner.pid, 0);
+        return false;
+      } catch (error) {
+        if (error instanceof Error && /EPERM/u.test(error.message)) return false;
+      }
+    }
+    await rm(lockPath, { recursive: true, force: true });
+    return true;
+  } catch (error) {
+    if (error instanceof Error && /ENOENT/u.test(error.message)) return true;
+    return false;
+  }
+}
+
+async function processIdentityLive(pid: number, expectedStartTime?: string): Promise<boolean> {
+  const currentStartTime = await processStartTime(pid);
+  if (currentStartTime && expectedStartTime) return currentStartTime === expectedStartTime;
+  if (currentStartTime) return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error instanceof Error && /EPERM/u.test(error.message);
+  }
+}
+
+async function processStartTime(pid: number): Promise<string | undefined> {
+  try {
+    const statText = await readFile(`/proc/${pid}/stat`, "utf8");
+    const closeParen = statText.lastIndexOf(")");
+    const fields = closeParen >= 0 ? statText.slice(closeParen + 2).trim().split(/\s+/u) : [];
+    const startTime = fields[19];
+    return startTime && /^\d+$/u.test(startTime) ? startTime : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function matchesHandoff(lease: CwdLeaseRecord, handoff: CwdLeaseHandoff): Promise<boolean> {
+  const worker = lease.worker;
+  if (worker?.transport !== "tmux"
+    || worker.sessionName !== handoff.sessionName
+    || worker.tmuxSocket !== handoff.tmuxSocket
+    || worker.tmuxTarget !== handoff.sessionName
+    || !worker.pid
+    || !worker.startTime
+    || !worker.tmuxPaneId
+    || !worker.paneStartTime
+    || !worker.paneCommand) return false;
+  // A live owner is still an active supervisor. Do not let another Pi consume
+  // its lease merely because the tmux session name is known.
+  return !(await processIdentityLive(lease.ownerPid, lease.ownerStartTime));
+}
+
+function assertWorker(worker: CwdLeaseWorker): void {
+  if (!["process-pipe", "jsonl", "pty", "tmux"].includes(worker.transport)
+    || (worker.pid !== undefined && (!Number.isSafeInteger(worker.pid) || worker.pid < 1))
+    || (worker.startTime !== undefined && !/^\d+$/u.test(worker.startTime))
+    || (worker.tmuxPaneId !== undefined && !/^%\d+$/u.test(worker.tmuxPaneId))
+    || (worker.cgroupPath !== undefined && !worker.cgroupPath.startsWith("/"))) {
+    throw new Error("invalid cwd lease worker identity");
+  }
+}
+
+function normalizeLease(value: Partial<CwdLeaseRecord>): CwdLeaseRecord {
+  if (value.version !== 1 || typeof value.leaseId !== "string" || !/^[0-9a-f-]{36}$/iu.test(value.leaseId)
+    || typeof value.taskId !== "string" || !/^[0-9a-f-]{36}$/iu.test(value.taskId)
+    || typeof value.cwd !== "string" || !value.cwd.startsWith("/")
+    || !Number.isSafeInteger(value.ownerPid) || (value.ownerPid ?? 0) < 1
+    || typeof value.acquiredAt !== "string" || !Number.isFinite(Date.parse(value.acquiredAt))
+    || typeof value.updatedAt !== "string" || !Number.isFinite(Date.parse(value.updatedAt))
+    || (value.ownerStartTime !== undefined && (typeof value.ownerStartTime !== "string" || !/^\d+$/u.test(value.ownerStartTime)))) {
+    throw new Error("invalid cwd lease record");
+  }
+  const worker = value.worker;
+  if (worker && (typeof worker !== "object" || !["process-pipe", "jsonl", "pty", "tmux"].includes(worker.transport as string))) throw new Error("invalid cwd lease worker identity");
+  const ownerPid = value.ownerPid!;
+  return {
+    version: 1,
+    leaseId: value.leaseId,
+    taskId: value.taskId,
+    cwd: resolve(value.cwd),
+    ownerPid,
+    ownerStartTime: typeof value.ownerStartTime === "string" ? value.ownerStartTime : undefined,
+    acquiredAt: value.acquiredAt,
+    updatedAt: value.updatedAt,
+    worker: worker ? {
+      transport: worker.transport!,
+      pid: Number.isSafeInteger(worker.pid) && worker.pid! > 0 ? worker.pid : undefined,
+      startTime: typeof worker.startTime === "string" && /^\d+$/u.test(worker.startTime) ? worker.startTime : undefined,
+      sessionName: typeof worker.sessionName === "string" ? worker.sessionName : undefined,
+      tmuxSocket: typeof worker.tmuxSocket === "string" ? worker.tmuxSocket : undefined,
+      ownership: worker.ownership === "owned" || worker.ownership === "adopted" ? worker.ownership : undefined,
+      cgroupPath: typeof worker.cgroupPath === "string" ? worker.cgroupPath : undefined,
+      tmuxTarget: typeof worker.tmuxTarget === "string" ? worker.tmuxTarget : undefined,
+      tmuxPaneId: typeof worker.tmuxPaneId === "string" && /^%\d+$/u.test(worker.tmuxPaneId) ? worker.tmuxPaneId : undefined,
+      paneStartTime: typeof worker.paneStartTime === "string" ? worker.paneStartTime : undefined,
+      paneCommand: typeof worker.paneCommand === "string" ? worker.paneCommand : undefined,
+    } : undefined,
+  };
+}
+
+function redactText(value: string): string {
+  return String(redactSensitive(value));
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}