pi-daddy 0.27.4 → 0.32.0

package/src/workspace-lease.ts

@@ -1,363 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import {
-  atomicMetadata,
-  leasePaths,
-  readMetadata,
-  type LeaseMetadata,
-  type LeaseReleaseOutcome,
-  type WorkspaceLease,
-} from "./lease-record.ts";
-export type { LeaseReleaseOutcome, WorkspaceLease } from "./lease-record.ts";
-import { once } from "node:events";
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { GovernanceRefusal, refusal } from "./refusals.ts";
-import type { ValidatedWorkspace, WorkspaceAccess } from "./workspace.ts";
-import { assertCloseBounds, HELPER_SOURCE, LEASE_READY, unrefStream } from "./lease-helper.ts";
-
-export const ENV_WORKSPACE_LEASE_DIR = "PI_GRANTS_WORKSPACE_LEASE_DIR";
-
-export function defaultWorkspaceLeaseDir(env: NodeJS.ProcessEnv = process.env): string {
-  const agentDir = env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
-  return env[ENV_WORKSPACE_LEASE_DIR] ?? join(agentDir, "pi-daddy", "workspace-leases");
-}
-
-
-/**
- * The ledger outcome for a release. Exported because call sites had their own copies and the check runner's
- * asserted `released` unconditionally — reproducing in the evidence path the exact defect this union was
- * added to expose (R-100/R-103).
- *
- * **It is NOT the only definition, and saying so here was wrong.** `extensions/workspace-runtime.ts` keeps a
- * private copy with no `not-held` arm, and it is the one the whole delegation path uses — so releasing a
- * *read* lease on a delegated child is still recorded `released`, a handover the kernel never performed.
- * Measured; open as R-141; the sentence claiming a single definition survived two review passes because
- * `test/workspace.test.ts` pins the `not-held` arm on THIS function, which no delegation path calls.
- */
-export function leaseReleaseLedgerOutcome(
-  outcome: LeaseReleaseOutcome | "retained",
-  reason: string,
-): "timeout" | "released" | "released-unrecorded" | "lost" | "retained" | "uncontended" {
-  if (outcome === "retained") return "retained";
-  if (outcome === "lost") return "lost";
-  if (outcome === "released-unrecorded") return "released-unrecorded";
-  if (outcome === "not-held") return "uncontended";
-  // `released-superseded` is a clean handover as far as the ledger is concerned: the lock went back and the
-  // record is correct — it just belongs to somebody else now.
-  return reason === "timeout" ? "timeout" : "released";
-}
-
-/**
- * `acquired` must mean the kernel actually excluded somebody. A read lease takes no lock (R-105), and an
- * unreadable predecessor record is not proof of a crash (R-100) — so neither may be reported as one.
- */
-export function leaseAcquisitionOutcome(
-  access: "read" | "write",
-  recovered: boolean | "unknown",
-): "acquired" | "uncontended" | "recovered" {
-  if (access === "read") return "uncontended";
-  return recovered === true ? "recovered" : "acquired";
-}
-
-export async function acquireWorkspaceLease(input: {
-  workspace: ValidatedWorkspace;
-  access: WorkspaceAccess;
-  leaseDir: string;
-  ownerId: string;
-  signal?: AbortSignal;
-  flockCommand?: string;
-  acquisitionTimeoutMs?: number;
-  /**
-   * Bound on how long ONE `herdr tab close` attempt may take before it counts as failed (R-146). A hung
-   * herdr is not a failed herdr: without this the attempt never returns and the retry bound below is
-   * unreachable.
-   */
-  herdrCloseTimeoutMs?: number;
-  /** Bound on the helper's `herdr tab close` retries before it releases the lock anyway (R-102). */
-  herdrCloseAttempts?: number;
-}): Promise<WorkspaceLease> {
-  // Before the read-lease return, so both paths are validated (R-152).
-  assertCloseBounds(input);
-  if (input.access === "read") {
-    return {
-      workspace: input.workspace,
-      access: "read",
-      ownerId: input.ownerId,
-      recovered: false,
-      attachProcess: () => {},
-      attachHerdrTab: () => {},
-      // A read lease took no kernel lock, so there is nothing to keep: `not-held` is the same answer
-      // `release()` gives, and it is the truth rather than a retention that never happened (R-152).
-      markRetained: async () => "not-held" as const,
-      readCloseFailure: async () => null,
-      lost: new Promise(() => {}),
-      // No kernel lock was ever taken, so there is no handover to claim (R-105, release side).
-      release: async () => "not-held",
-    };
-  }
-  if (input.signal?.aborted) {
-    throw new GovernanceRefusal(refusal("WORKSPACE_WRITE_CONFLICT", `writer lease for ${input.workspace.workspaceId} was cancelled before acquisition`));
-  }
-
-  await mkdir(input.leaseDir, { recursive: true, mode: 0o700 });
-  const paths = leasePaths(input.leaseDir, input.workspace.root);
-  const { spawn } = await import("node:child_process");
-  const holder = spawn(input.flockCommand ?? "flock", [
-    "--exclusive", "--nonblock", "--conflict-exit-code", "73", paths.lock,
-    process.execPath, "--input-type=module", "-e", HELPER_SOURCE,
-  ], {
-    stdio: ["pipe", "pipe", "pipe"],
-    env: {
-      ...process.env,
-      PI_DADDY_LEASE_MARKER: paths.marker,
-      PI_DADDY_LEASE_CLOSE_ATTEMPTS: String(input.herdrCloseAttempts ?? 10),
-      PI_DADDY_LEASE_CLOSE_TIMEOUT_MS: String(input.herdrCloseTimeoutMs ?? 15_000),
-    },
-    // Own process group, for two reasons. It lets teardown kill `flock` AND the helper holding the lock
-    // file descriptor as one unit even before the helper has reported its pid (R-99), and it stops a
-    // stray group signal — a terminal Ctrl-C, a closed window — from releasing a live writer's lock as
-    // a side effect.
-    detached: true,
-  });
-
-  const timeoutMs = input.acquisitionTimeoutMs ?? 2000;
-  let ready = false;
-  let helperPid: number | undefined;
-  let stderr = "";
-  /**
-   * Kill the whole holder GROUP — one signal, no ordering. (The pid-by-pid fallback below is the
-   * only path that kills in sequence, and only when the group is already reaped.) `flock` does not pass `--close`, so the helper inherits
-   * the lock file descriptor and holds the lock in its own right — killing only `flock` leaves the
-   * lock HELD by an orphan, and every later acquisition then reports WORKSPACE_WRITE_CONFLICT, which
-   * is the one message an operator would use to conclude another agent is writing. Measured in
-   * `docs/probes/g35-flock-fd-inheritance` (R-99).
-   */
-  const hardKill = () => {
-    // The GROUP, so this works on the readiness-timeout path too — there `helperPid` is usually still
-    // unknown, and killing only the wrapper leaves a half-booted helper free to inherit the lock file
-    // descriptor and hold it forever. Fall back to individual pids if the group is already reaped.
-    if (holder.pid !== undefined) {
-      try { process.kill(-holder.pid, "SIGKILL"); return; } catch { /* group gone */ }
-    }
-    if (Number.isInteger(helperPid)) {
-      try { process.kill(helperPid!, "SIGKILL"); } catch { /* already gone */ }
-    }
-    holder.kill("SIGKILL");
-  };
-  holder.stderr?.on("data", (chunk) => { stderr += String(chunk); });
-  try {
-    await new Promise<void>((resolveReady, rejectReady) => {
-      const timer = setTimeout(() => rejectReady(new GovernanceRefusal(refusal(
-        "WORKSPACE_LEASE_STALE", `writer lease helper did not become ready within ${timeoutMs}ms`,
-      ))), timeoutMs);
-      const cleanup = () => {
-        clearTimeout(timer);
-        input.signal?.removeEventListener("abort", onAbort);
-      };
-      const onAbort = () => rejectReady(new GovernanceRefusal(refusal(
-        "WORKSPACE_WRITE_CONFLICT", `writer lease for ${input.workspace.workspaceId} was cancelled before acquisition`,
-      )));
-      input.signal?.addEventListener("abort", onAbort, { once: true });
-      holder.once("error", (error) => {
-        cleanup();
-        rejectReady(new GovernanceRefusal(refusal(
-          "WORKSPACE_LEASE_STALE", `workspace writer leases require a working flock command (${String(error)})`,
-        )));
-      });
-      holder.once("close", (code) => {
-        if (ready) return;
-        cleanup();
-        const codeName = code === 73 ? "WORKSPACE_WRITE_CONFLICT" : "WORKSPACE_LEASE_STALE";
-        rejectReady(new GovernanceRefusal(refusal(
-          codeName,
-          code === 73
-            ? `workspace ${input.workspace.workspaceId} already has an active pi-daddy-governed writer`
-            : `workspace lease helper exited before acquisition${stderr ? ` (${stderr.trim()})` : ""}`,
-          { workspace_id: input.workspace.workspaceId, root: input.workspace.root },
-        )));
-      });
-      holder.stdout?.on("data", (chunk) => {
-        const output = String(chunk);
-        if (!output.includes(LEASE_READY) || ready) return;
-        helperPid = Number(output.match(new RegExp(`${LEASE_READY}:(\\d+)`))?.[1]);
-        ready = true;
-        cleanup();
-        resolveReady();
-      });
-    });
-  } catch (error) {
-    hardKill();
-    throw error;
-  }
-
-  const previous = await readMetadata(paths.metadata);
-  // "malformed" is not "no prior owner": an unreadable record cannot prove a clean handover (R-100).
-  const recovered: boolean | "unknown" = previous === "malformed" ? "unknown" : previous?.state === "active";
-  const token = randomUUID();
-  const metadata: LeaseMetadata = {
-    version: 1,
-    state: "active",
-    token,
-    owner_id: input.ownerId,
-    workspace_id: input.workspace.workspaceId,
-    root: input.workspace.root,
-    pid: Number.isInteger(helperPid) ? helperPid! : (holder.pid ?? process.pid),
-    acquired_at: new Date().toISOString(),
-  };
-  try {
-    await atomicMetadata(paths.metadata, metadata);
-  } catch (error) {
-    holder.stdin?.end();
-    throw new GovernanceRefusal(refusal(
-      "WORKSPACE_LEASE_STALE", `acquired the kernel writer lock but could not record its owner (${String(error)})`,
-      { workspace_id: input.workspace.workspaceId, root: input.workspace.root },
-    ));
-  }
-
-  // TWO variables, deliberately. `releasing` goes up the instant release begins, because the handshake
-  // below closes the helper on purpose — and if `lost` could still fire during it, an intentional release
-  // would report itself as a lost lease. `settled` memoizes the ANSWER, so a second call cannot invent a
-  // clean handover. Collapsing these into one flag set at the end broke every check-runner test.
-  let releasing = false;
-  let settled: LeaseReleaseOutcome | undefined;
-  let lose!: (error: Error) => void;
-  const lost = new Promise<Error>((resolveLost) => { lose = resolveLost; });
-  const lostError = () => new Error(`workspace writer lease helper exited for ${input.workspace.workspaceId}`);
-  holder.once("close", () => { if (!releasing) lose(lostError()); });
-  if (holder.exitCode !== null || holder.signalCode !== null) queueMicrotask(() => lose(lostError()));
-  const attach = (value: { process_pid: number } | { herdr_tab: string }) => {
-    if (releasing || holder.exitCode !== null || holder.signalCode !== null || !holder.stdin?.writable) {
-      throw new GovernanceRefusal(refusal(
-        "WORKSPACE_LEASE_STALE", `writer lease for ${input.workspace.workspaceId} was lost before child attachment`,
-      ));
-    }
-    holder.stdin.write(`${JSON.stringify(value)}\n`);
-  };
-  return {
-    workspace: input.workspace,
-    access: "write",
-    ownerId: input.ownerId,
-    recovered,
-    attachProcess(pid) { attach({ process_pid: pid }); },
-    attachHerdrTab(tabId) { attach({ herdr_tab: tabId }); },
-    lost,
-    async markRetained(reason = "retained") {
-      // Deliberately does NOT touch the kernel lock or the helper: the pane may still be live. It only
-      // stops the record from looking like a crash.
-      //
-      // **Both guards below exist because the CALLER ledgers whatever this returns (R-152).**
-      //
-      // Already settled: `release()` checked `settled` and this did not, so a completed handover could be
-      // rewritten into `retained:…` and the memoized answer flipped with it — the mirror of the defect R-146
-      // fixed, reachable by the `try { … } finally { await lease.release() }` shape this API invites.
-      if (settled) return settled;
-      // Already dead: the helper is gone and the kernel lock with it, so the fact is `lost`. Recording a
-      // retention here tells an operator a pane may still be live and tells the next owner nothing crashed —
-      // precisely the two facts R-103's outcome union was added to keep apart.
-      if (holder.exitCode !== null || holder.signalCode !== null) return (settled = "lost");
-      const current = await readMetadata(paths.metadata);
-      let recorded = false;
-      if (current !== "malformed" && current?.token === token) {
-        recorded = await atomicMetadata(paths.metadata, {
-          ...metadata, state: "released", released_at: new Date().toISOString(), release_reason: `retained:${reason}`,
-        }).then(() => true, () => false);
-      }
-      /**
-       * **It must, however, let THIS process exit (R-146).** Leaving the helper alone is the decision;
-       * leaving the parent's three pipes and the child handle referenced was an accident, and it meant a
-       * retained lease wedged its own process forever — measured `exit=124` against `exit=0` for the same
-       * sequence ending in `release()`.
-       *
-       * **Which hosts it actually wedged, corrected after review.** `process.exit()` runs `exit` handlers and
-       * ignores pending handles, so this only bites a host that lets the loop drain: pi's **print** mode sets
-       * `process.exitCode` and returns (`dist/main.js`), and a library consumer — an ADR-0034 external
-       * controller calling this package directly — does the same. pi's interactive and rpc modes call
-       * `process.exit()` explicitly (`dist/modes/interactive/interactive-mode.js:3148`), so there the process
-       * still leaves and `pane-reaper`'s `process.once("exit")` sweep still runs. An earlier version of this
-       * comment claimed the sweep was lost generally and cited `src/cli.ts`, which has one subcommand
-       * (`init`) and can neither hold a lease nor open a pane.
-       *
-       * Unref rather than close, because the lock must outlive this call: when the parent does exit, the
-       * helper sees EOF and runs the path it was written for — bounded `herdr tab close` attempts, a marker
-       * file, then release anyway (R-102: an unreleasable lock strands a worktree with no in-product
-       * recovery, which is strictly worse than a recorded failure to close). Narrowed to this path on
-       * purpose: at spawn it would remove the accidental guarantee that a process cannot exit while a lease
-       * is still ACTIVE, which is a different decision and not this fix.
-       */
-      /**
-       * **Terminal (R-146).** `releasing` stops a late `holder.close` being reported as a lost lease, and
-       * `settled` stops a later `release()` running the clean handshake — which it did: measured, it returned
-       * `released`, overwrote `retained:herdr-close-failed` with `completed`, and sent `{release:true}` so the
-       * helper exited `clean` and never attempted the close. The pane retention exists to protect was
-       * abandoned silently, and the ledger asserted a clean handover for a lease kept *because* a pane would
-       * not close. No in-tree caller does this — but `WorkspaceLease` is a public export and
-       * `try { … } finally { await lease.release() }` is the obvious shape for the external controllers this
-       * whole fix is for.
-       */
-      releasing = true;
-      // **Settle only if the record was actually written.** An unwritable lease directory used to leave the
-      // record `state: "active"` while the ledger said `retained`, so the next owner reported a phantom
-      // `recovered: true` — and making retention terminal removed the later `release()` that would still have
-      // written the handover. Unsettled, that repair is available again; the residue is stated in R-152
-      // rather than implied, because nothing here can write a record to a directory that refuses writes.
-      if (recorded) settled = "retained";
-      holder.unref();
-      unrefStream(holder.stdout);
-      unrefStream(holder.stderr);
-      return "retained";
-    },
-    async readCloseFailure() {
-      try {
-        return JSON.parse(await readFile(paths.marker, "utf8")) as { reason: string; herdr_tab?: string };
-      } catch {
-        return null;
-      }
-    },
-    async release(reason = "completed"): Promise<LeaseReleaseOutcome> {
-      // Memoized, not a boolean. A second call used to answer "released" whatever the first returned, so a
-      // retry — or a `finally` after an explicit release — read a clean handover that never happened.
-      if (settled) return settled;
-      releasing = true;
-      // Already gone: this owner never released anything, and saying so is the caller's business to
-      // record. Throwing here discarded completed work and masked the real error (R-99).
-      if (holder.exitCode !== null || holder.signalCode !== null) return (settled = "lost");
-
-      // Default FALSE: "recorded" must mean this owner actually wrote its own handover. Anything else —
-      // an unreadable record, or a successor's token in place of ours — means the lock goes back but the
-      // record does not say so, and the NEXT owner will report a recovery that never happened unless the
-      // caller ledgers it (R-100). Only the current token may mark the handover, so a stale lease object
-      // can never overwrite a live successor.
-      // Three outcomes, because they call for three different responses: we wrote our handover; a
-      // successor already owns the record and we correctly left it alone; or the record is unreadable or
-      // unwritable and somebody has to be told.
-      let how: LeaseReleaseOutcome = "released-unrecorded";
-      const current = await readMetadata(paths.metadata);
-      if (current !== "malformed" && current?.token === token) {
-        try {
-          await atomicMetadata(paths.metadata, {
-            ...metadata,
-            state: "released",
-            released_at: new Date().toISOString(),
-            release_reason: reason,
-          });
-          how = "released";
-        } catch {
-          how = "released-unrecorded";
-        }
-      } else if (current !== "malformed" && current !== null) {
-        // A live successor's record. Declining to overwrite it is the token guard working, not a fault.
-        how = "released-superseded";
-      }
-
-      holder.stdin?.write(`${JSON.stringify({ release: true })}\n`);
-      holder.stdin?.end();
-      if (holder.exitCode === null && holder.signalCode === null) {
-        await Promise.race([once(holder, "close"), new Promise((resolveWait) => setTimeout(resolveWait, 1000))]);
-      }
-      // The helper holds the lock fd in its own right, so the wrapper alone is not enough (R-99).
-      if (holder.exitCode === null && holder.signalCode === null) hardKill();
-      return (settled = how);
-    },
-  };
-}

package/src/workspace.ts

@@ -1,308 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import { execFile } from "node:child_process";
-import { once } from "node:events";
-import { mkdir, open, readFile, realpath, rename, stat, writeFile } from "node:fs/promises";
-import type { FileHandle } from "node:fs/promises";
-import { constants } from "node:fs";
-import { homedir } from "node:os";
-import { isAbsolute, join } from "node:path";
-import { promisify } from "node:util";
-import { GovernanceRefusal, refusal } from "./refusals.ts";
-import { isSafeWorkspaceId, workspaceCapability } from "./capabilities.ts";
-
-const execFileAsync = promisify(execFile);
-export const ENV_WORKSPACE_REGISTRY = "PI_GRANTS_WORKSPACE_REGISTRY";
-
-
-export type WorkspaceAccess = "read" | "write";
-
-export interface WorkspaceRegistryFile {
-  version: 1;
-  workspaces: Record<string, { path: string }>;
-  /**
-   * Where this was loaded from, carried so a refusal can NAME it.
-   *
-   * `docs/SPEC.md` claimed an unregistered id is refused "with `WORKSPACE_NOT_REGISTERED`, which names the
-   * file", and `catalog.ts` justified exempting the whole namespace from the unknown check on the strength of
-   * that — *"a second, weaker check here can only turn that precise refusal into a misleading one"*. The
-   * refusal named no file: the registry object had no idea where it came from. Carried on the object rather
-   * than passed per call so a caller cannot forget it. Optional because a hand-built literal (tests,
-   * `workspaceEntries` fixtures) has no source.
-   */
-  source?: string;
-}
-
-export interface ValidatedWorkspace {
-  workspaceId: string;
-  /** Canonical Git worktree root and the child's validated initial CWD. Not a sandbox. */
-  root: string;
-  gitCommonDir: string;
-}
-
-/**
- * How long a registry read may take before it is a refusal rather than a wait.
- *
- * **R-79's defect class, and this reader reintroduced it.** That entry records a probe that hung forever on
- * a FIFO with "no timeout anywhere in the path". This function used a bare `readFile`, which was survivable
- * while it ran only at spawn time — and stopped being survivable when 0.19.0 began reading the registry from
- * `buildCatalog` and `registeredWorkspaceIds`, both awaited inside `session_start`. Measured on `52135ca`:
- * `PI_GRANTS_WORKSPACE_REGISTRY` pointing at a FIFO blocked session start indefinitely, so the session never
- * reached the `holding [...]` line, the executor probe, or any control after it — and `delegate` awaits the
- * same promise, so delegation hung too. A blocking special file, an unresponsive network mount or a hostile
- * `mkfifo` all reach it.
- *
- * Two seconds because this is an operator-authored local JSON file: any legitimate one is a single-digit
- * millisecond read (measured: 8ms), so the bound is three orders of magnitude of headroom and still bounded.
- */
-const REGISTRY_READ_TIMEOUT_MS = 2_000;
-
-/** A registry is an operator-authored JSON file; anything approaching this is not one. */
-const REGISTRY_MAX_BYTES = 1 << 20;
-
-export async function loadWorkspaceRegistry(path: string): Promise<WorkspaceRegistryFile> {
-  // **One handle, opened non-blocking, and every check made against THAT handle.** Three defects made this
-  // the shape rather than `stat`-then-`readFile`:
-  //
-  //  - `AbortSignal.timeout` cannot rescue a FIFO: a signal is observed between chunks, while a FIFO blocks
-  //    inside `open(2)` before any read begins. `O_NONBLOCK` makes the open itself return instead (measured:
-  //    1ms), which is what actually bounds this path. R-79's defect class, and R-136's.
-  //  - `stat` by name followed by `readFile` by name is a TOCTOU: swapping a regular file for a FIFO between
-  //    the two hung the loader indefinitely, and the attacker is any process at the same uid — precisely the
-  //    actor the mode check below cannot exclude. Measured, 5 of 6 iterations completing in ~1ms and the
-  //    sixth never returning. `fstat` on a held descriptor has no name to re-resolve.
-  //  - a second reader (the ADR-0035 registry pin, since reverted to its own PR) reimplemented the guards and
-  //    got them wrong. One reader is why that cannot happen again.
-  let handle: FileHandle;
-  try {
-    handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
-  } catch (error) {
-    throw new GovernanceRefusal(refusal(
-      "WORKSPACE_NOT_REGISTERED",
-      `workspace registry ${path} could not be opened (${String(error)})`,
-      { registry_path: path },
-    ));
-  }
-  let raw: string;
-  try {
-    const info = await handle.stat();
-    if (!info.isFile()) {
-      throw new GovernanceRefusal(refusal(
-        "WORKSPACE_NOT_REGISTERED",
-        `workspace registry ${path} is not a regular file — refusing to read it. A FIFO, device or socket ` +
-          `at ${ENV_WORKSPACE_REGISTRY} would block session start rather than fail, because opening one ` +
-          `waits for a writer that may never come.`,
-        { registry_path: path },
-      ));
-    }
-    if (info.size > REGISTRY_MAX_BYTES) {
-      throw new GovernanceRefusal(refusal(
-        "WORKSPACE_NOT_REGISTERED",
-        `workspace registry ${path} is ${info.size} bytes, over the ${REGISTRY_MAX_BYTES} limit — refusing ` +
-          `rather than reading it into memory at session start.`,
-        { registry_path: path },
-      ));
-    }
-    // **Ownership and mode are NOT checked here, and that is a scope decision (R-137, ADR-0036).** A
-    // previous revision refused a registry not owned by this user or writable by others. Those guards are
-    // about *tamper resistance*, which is a different question from the one ADR-0035 raised, and they went in
-    // mid-review without an ADR — where they promptly acquired a false claim ("nobody ELSE may rewrite it":
-    // it inspects the file and never its parent directory, and `rename(2)` needs only directory write) and a
-    // false-positive refusal of `0664`, which `umask 002` produces for every file an operator creates.
-    //
-    // What IS checked above is what ADR-0035 made this reader's problem: it began reading the registry at
-    // SESSION START, so the read must be bounded and must not block. Integrity is R-137, open and measured.
-    // The deadline is checked BETWEEN chunks, which is all `AbortSignal.timeout` ever did on the previous
-    // implementation — review measured 74 of 200 one-MiB reads completing in full with `signal.aborted`
-    // already true, because a signal is never observed *inside* a libuv read request. An explicit check makes
-    // the bound as real as it can be in-process, and its limit is the same one honestly stated below: a
-    // stalled `open` or a single wedged read cannot be interrupted from here.
-    const deadline = Date.now() + REGISTRY_READ_TIMEOUT_MS;
-    const buffer = Buffer.allocUnsafe(REGISTRY_MAX_BYTES + 1);
-    let filled = 0;
-    while (filled < buffer.length) {
-      if (Date.now() > deadline) {
-        throw new GovernanceRefusal(refusal(
-          "WORKSPACE_NOT_REGISTERED",
-          `workspace registry ${path} did not finish reading within ${REGISTRY_READ_TIMEOUT_MS}ms — ` +
-            `refusing rather than waiting, because session start awaits this read.`,
-          { registry_path: path },
-        ));
-      }
-      const { bytesRead } = await handle.read(buffer, filled, buffer.length - filled, filled);
-      if (bytesRead === 0) break;
-      filled += bytesRead;
-    }
-    if (filled > REGISTRY_MAX_BYTES) {
-      throw new GovernanceRefusal(refusal(
-        "WORKSPACE_NOT_REGISTERED",
-        `workspace registry ${path} exceeded the ${REGISTRY_MAX_BYTES} limit while being read — it grew ` +
-          `after its size was checked. Refusing rather than allocating it.`,
-        { registry_path: path },
-      ));
-    }
-    raw = buffer.subarray(0, filled).toString("utf8");
-  } catch (error) {
-    if (error instanceof GovernanceRefusal) throw error;
-    const timedOut = error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
-    throw new GovernanceRefusal(refusal(
-      "WORKSPACE_NOT_REGISTERED",
-      timedOut
-        ? `workspace registry ${path} did not return within ${REGISTRY_READ_TIMEOUT_MS}ms — refusing rather ` +
-          `than waiting, because session start awaits this read.`
-        : `workspace registry ${path} could not be read (${String(error)})`,
-      { registry_path: path },
-    ));
-  } finally {
-    await handle.close().catch(() => {});
-  }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (error) {
-    throw new GovernanceRefusal(refusal(
-      "WORKSPACE_NOT_REGISTERED",
-      `workspace registry ${path} is not valid JSON (${String(error)})`,
-      { registry_path: path },
-    ));
-  }
-  const file = parsed as Partial<WorkspaceRegistryFile>;
-  if (file?.version !== 1 || !file.workspaces || typeof file.workspaces !== "object" || Array.isArray(file.workspaces)) {
-    throw new GovernanceRefusal(refusal(
-      "WORKSPACE_NOT_REGISTERED",
-      `workspace registry ${path} must contain {version:1, workspaces:{id:{path}}}`,
-      { registry_path: path },
-    ));
-  }
-  for (const [id, value] of Object.entries(file.workspaces)) {
-    if (!id || !value || typeof value.path !== "string" || !isAbsolute(value.path)) {
-      throw new GovernanceRefusal(refusal(
-        "WORKSPACE_NOT_REGISTERED",
-        `workspace registry entry ${JSON.stringify(id)} must name an absolute path`,
-        { registry_path: path, workspace_id: id },
-      ));
-    }
-    // ADR-0035 made a registry id the tail of a CAPABILITY id (`workspace:<id>`), so this file is an input
-    // to the grant grammar and has to obey it — the STRICT one. This shipped with the loose
-    // `isWellFormedCapability` blocklist, and review measured what that let through: an id of `*` minted
-    // `WORKSPACE_WILDCARD` (an operator naming one worktree held routing over all of them), an id with a
-    // space became two capabilities because `ceilingForDefinition` splits on `[\s,]+`, and quote/`$()` ids
-    // reached a generated file whose own instructions say to paste them into `PI_GRANTS_GRANT`. See
-    // `isSafeCapability`, which is now the one grammar for both channels into that file.
-    if (!isSafeWorkspaceId(id)) {
-      throw new GovernanceRefusal(refusal(
-        "GRANT_ID_MALFORMED",
-        `workspace registry id ${JSON.stringify(id)} cannot be used: since ADR-0035 an id becomes the ` +
-          `capability ${JSON.stringify(workspaceCapability(id))}, and an id must match ` +
-          `[A-Za-z0-9][A-Za-z0-9._/-]* — slashes and dots are fine (a worktree named after its branch ` +
-          `works), but not spaces, quotes, commas, wildcards, shell metacharacters or non-ASCII, each of ` +
-          `which either splits into several capabilities or reaches a file you are told to source. ` +
-          `Rename it in ${path}.`,
-        { registry_path: path, workspace_id: id },
-      ));
-    }
-  }
-  return { version: 1, workspaces: structuredClone(file.workspaces), source: path };
-}
-
-/**
- * The registered workspace ids, for `planInit` to scaffold and `/grants` to list. `[]` when there is no registry or it is broken.
- *
- * Fails SOFT, and only because nothing here is an authority: this decides which ids appear as COMMENTS in a
- * generated file. `loadWorkspaceRegistry` throws a GovernanceRefusal naming the file, and that refusal is
- * the operator's signal at the point of use, where routing genuinely depends on it. Swallowing it there
- * would be unsafe; swallowing it here costs a suggestion. Same argument as `buildCatalog`'s.
- *
- * Lives here rather than in `init.ts` because it reads the filesystem, and `planInit` — the centrepiece of
- * that module — documents itself as "Pure: no filesystem". It is a registry concern; this is where the
- * registry lives. Moved when `init.ts` crossed the 400-line ceiling, which this project splits for rather
- * than raising (`delegate.ts` at 413, `grants.ts` at 398).
- */
-export async function registeredWorkspaceIds(registryPath = process.env[ENV_WORKSPACE_REGISTRY]): Promise<string[]> {
-  if (!registryPath) return [];
-  try {
-    return Object.keys((await loadWorkspaceRegistry(registryPath)).workspaces).sort();
-  } catch {
-    return [];
-  }
-}
-
-export async function resolveWorkspace(registry: WorkspaceRegistryFile, workspaceId: string): Promise<ValidatedWorkspace> {
-  const registered = Object.hasOwn(registry.workspaces, workspaceId) ? registry.workspaces[workspaceId] : undefined;
-  const known = Object.keys(registry.workspaces).sort();
-  if (!registered) {
-    throw new GovernanceRefusal(refusal(
-      "WORKSPACE_NOT_REGISTERED",
-      `workspace ${JSON.stringify(workspaceId)} is not present in the operator-owned registry` +
-        (registry.source ? ` ${registry.source}` : "") +
-        (known.length > 0 ? ` — it lists: ${known.join(", ")}` : " — it lists nothing"),
-      { workspace_id: workspaceId, ...(registry.source ? { registry_path: registry.source } : {}) },
-    ));
-  }
-  return validateRegisteredWorkspace({ workspaceId, registeredRoot: registered.path });
-}
-
-/**
- * Canonicalize and validate the initial workspace against Git's registered worktree list.
- * This prevents accidental misrouting. It does not constrain any path a child accesses after spawn.
- */
-export async function validateRegisteredWorkspace(input: {
-  workspaceId: string;
-  registeredRoot: string;
-  suppliedRoot?: string;
-}): Promise<ValidatedWorkspace> {
-  let registered: string;
-  let supplied: string;
-  try {
-    registered = await realpath(input.registeredRoot);
-    supplied = await realpath(input.suppliedRoot ?? input.registeredRoot);
-    if (!(await stat(registered)).isDirectory()) throw new Error("registered root is not a directory");
-  } catch (error) {
-    throw new GovernanceRefusal(refusal(
-      "WORKSPACE_NOT_REGISTERED",
-      `workspace ${input.workspaceId} root could not be canonicalized (${String(error)})`,
-      { workspace_id: input.workspaceId },
-    ));
-  }
-  if (registered !== supplied) {
-    throw new GovernanceRefusal(refusal(
-      "WORKSPACE_NOT_REGISTERED",
-      `workspace ${input.workspaceId} resolved to ${supplied}, not its registered worktree ${registered}`,
-      { workspace_id: input.workspaceId, supplied_root: supplied, registered_root: registered },
-    ));
-  }
-
-  try {
-    const top = (await execFileAsync("git", ["-C", registered, "rev-parse", "--show-toplevel"], { encoding: "utf8" })).stdout.trim();
-    const canonicalTop = await realpath(top);
-    if (canonicalTop !== registered) throw new Error(`path is inside worktree ${canonicalTop}, not its root`);
-    const commonRaw = (await execFileAsync("git", ["-C", registered, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8" })).stdout.trim();
-    const gitCommonDir = await realpath(commonRaw);
-    const list = (await execFileAsync("git", ["-C", registered, "worktree", "list", "--porcelain"], { encoding: "utf8" })).stdout;
-    const registeredWorktrees = await Promise.all(
-      list.split("\n").filter((line) => line.startsWith("worktree ")).map((line) => realpath(line.slice(9))),
-    );
-    if (!registeredWorktrees.includes(registered)) throw new Error("Git does not list this path as a worktree");
-    return { workspaceId: input.workspaceId, root: registered, gitCommonDir };
-  } catch (error) {
-    throw new GovernanceRefusal(refusal(
-      "WORKSPACE_NOT_REGISTERED",
-      `workspace ${input.workspaceId} is not the registered Git worktree it claims to be (${String(error)})`,
-      { workspace_id: input.workspaceId, registered_root: registered },
-    ));
-  }
-}
-
-/**
- * The governed-writer lease lives in `./workspace-lease.ts` and is re-exported here so that
- * "the workspace module" remains one import for callers. Split only to stay under the 400-line
- * module ceiling this project enforces mechanically.
- */
-export {
-  ENV_WORKSPACE_LEASE_DIR,
-  acquireWorkspaceLease,
-  defaultWorkspaceLeaseDir,
-  leaseAcquisitionOutcome,
-  leaseReleaseLedgerOutcome,
-  type LeaseReleaseOutcome,
-  type WorkspaceLease,
-} from "./workspace-lease.ts";