pi-daddy 0.18.1 → 0.20.0

package/src/routing-authority.ts

@@ -0,0 +1,121 @@
+/**
+ * ADR-0035's three routing guards, and why each one is shaped the way it is.
+ *
+ * Lifted out of `delegate.ts` when it crossed the 400-line ceiling `test/file-size.test.ts` enforces — the
+ * same move `grants.ts` made at 398 and `delegate.ts` itself made at 413. It is a real seam rather than a
+ * line-count dodge: all three answer one question, *may this caller route this child to this workspace, and
+ * is the id even usable as a capability?*, and none of them looks at anything else in a delegation. The
+ * alternative was trimming the rationale below to fit, which is how a codebase loses the reasons for its
+ * guards.
+ *
+ * Each returns a refusal DESCRIPTOR rather than a `Delegation`, so the planner keeps sole ownership of
+ * assembling records. `denied` is present exactly when the attempt should count as an escalation.
+ */
+
+import { mayRouteToWorkspace, isSafeWorkspaceId, workspaceCapability } from "./capabilities.ts";
+import { WORKSPACE_WILDCARD, type Capability } from "./resolve.ts";
+import { WILDCARD } from "./pi-tools.ts";
+import type { RefusalCode } from "./refusals.ts";
+
+export interface RoutingRefusal {
+  code: RefusalCode;
+  reason: string;
+  /**
+   * The capability to record in `denied`, when this refusal IS an escalation attempt.
+   *
+   * Absent for a malformed id, which is a bad request rather than a bid for authority — and seeding `denied`
+   * with an id that re-splits into several capabilities would make the one signal `isEscalationAttempt` reads
+   * unparseable. Present for an unauthorised route, which is exactly a bid for authority.
+   */
+  denied?: Capability[];
+}
+
+/**
+ * May this caller route a child to `boundWorkspaceId`, and is that id usable as a capability id at all?
+ *
+ * Checked before anything is said about the target, for the reason `maySpawnDefinition` is: it is a
+ * governance question about the SESSION. Before ADR-0035 nothing checked it — the registry inherited into
+ * every governed child and a child routed to `staging` could route its grandchild to `prod` (R-131, measured
+ * in `docs/probes/g36-workspace-attenuation`).
+ *
+ * **Well-formedness first, because `workspace_id` is a model-facing tool parameter** and the next step turns
+ * it into a capability id. `workspace_id: "prod,tool:bash"` produced a `WORKSPACE_NOT_AUTHORIZED` whose
+ * `denied` array held `workspace:prod,tool:bash`: no authority minted, since the refusal is terminal, but
+ * `denied` is the channel `isEscalationAttempt` and `/grants ledger` count and an id that re-splits makes it
+ * unreadable. 0.18.1 is what happens when a comma goes unremarked.
+ *
+ * **`!== undefined`, not truthiness.** `workspace_id: ""` is falsy, so it skipped BOTH checks and failed
+ * closed much later at `resolveWorkspace` with `denied: []` — an unauthorised routing attempt invisible to
+ * every audit query. An empty id is a malformed id, not an absent one.
+ */
+export function checkRoutingAuthority(
+  boundWorkspaceId: string | undefined,
+  ownGrant: readonly Capability[],
+): RoutingRefusal | null {
+  if (boundWorkspaceId === undefined) return null;
+  const authorising = workspaceCapability(boundWorkspaceId);
+  if (!isSafeWorkspaceId(boundWorkspaceId)) {
+    return {
+      code: "GRANT_ID_MALFORMED",
+      reason:
+        `workspace id ${JSON.stringify(boundWorkspaceId)} is not usable as a capability id — it would ` +
+        `become ${JSON.stringify(authorising)}, and an id must match [A-Za-z0-9][A-Za-z0-9._/-]*. Slashes ` +
+        `and dots are fine; spaces, quotes, commas, wildcards, shell metacharacters and non-ASCII are not.`,
+    };
+  }
+  if (mayRouteToWorkspace(ownGrant, boundWorkspaceId)) return null;
+  // Filtered by the grammar too: an id that cannot pass `isSafeWorkspaceId` is refused on every
+  // attempt, so listing it here points the model at a destination it can never reach.
+  const held = ownGrant
+    .filter((c) => c.startsWith("workspace:") && isSafeWorkspaceId(c.slice("workspace:".length)))
+    .sort();
+  return {
+    code: "WORKSPACE_NOT_AUTHORIZED",
+    // Recorded as a denial rather than a bare refusal, exactly as DEFINITION_NOT_AUTHORIZED is: asking to
+    // route somewhere this session was not granted IS an attempt to exceed the grant.
+    denied: [authorising],
+    reason:
+      `cannot route a child to workspace "${boundWorkspaceId}" — this session does not hold ${authorising}. ` +
+      (held.length > 0
+        ? `It may route to: ${held.join(", ")}.`
+        : `It may route to no workspace at all; add ${authorising} to its grant to allow this one.`),
+  };
+}
+
+/**
+ * May `workspace:*` be handed to a child? No — and only its HOLDER gets told so in those words.
+ *
+ * `workspace:*` is held and never inherited, so a child that "was granted" it would receive an env without
+ * it, and the ledger would record an authority the child does not have — the mirror image of R-131 and just
+ * as unreadable. `childEnv` strips it from a session's OWN grant because a root legitimately holds it; asking
+ * to hand it to a child is a different act and the honest answer is no. `NARROWING_VIOLATED` is the existing
+ * code for "this grant would not actually narrow", which is precisely what routing authority over every
+ * registered root does.
+ *
+ * **`tool:*` does NOT reach the same outcome, and an earlier comment claimed it did.** It said
+ * `assertNarrowing` produces the equivalent refusal; it does not. `UNIVERSAL_CAPABILITIES` is
+ * `["ext:pi-fabric/fabric_exec", "tool:fabric_exec"]`, so `result.universal` is empty for `tool:*` and
+ * nothing throws: requesting it for a child is allowed, recorded as granted, and silently stripped from the
+ * child env by `inheritableGrant` (R-135). The asymmetry is deliberate — an ungoverned session's own grant IS
+ * `tool:*`, so refusing to spawn from one would break governance-is-opt-in, while `workspace:*` only ever
+ * appears in `requested` because somebody asked — but it is an asymmetry, not one rule twice.
+ *
+ * **Only for a holder.** A caller without it is attempting an escalation, and this refusal would tell it the
+ * wildcard "is held, never inherited" — false about a session holding nothing of the sort — while leaving
+ * `denied` empty, so nothing counted a model probing `tools: ["workspace:*"]`. Returning `null` lets
+ * `resolve()` deny it as uncovered, which is what `agent:*` and `tool:*` already do.
+ */
+export function checkWorkspaceWildcardRequest(
+  requested: readonly Capability[],
+  ownGrant: readonly Capability[],
+): RoutingRefusal | null {
+  if (!requested.includes(WORKSPACE_WILDCARD)) return null;
+  if (!ownGrant.includes(WORKSPACE_WILDCARD) && !ownGrant.includes(WILDCARD)) return null;
+  return {
+    code: "NARROWING_VIOLATED",
+    reason:
+      `cannot grant ${WORKSPACE_WILDCARD} to a child — it is held, never inherited, because a descendant ` +
+      `holding it could route anywhere the registry lists and routing would stop attenuating below here. ` +
+      `Name the workspaces this child may route to instead (workspace:<id>, one per id).`,
+  };
+}

package/src/run-child.ts

@@ -13,6 +13,15 @@ import { spawn } from "node:child_process";
 import { StringDecoder } from "node:string_decoder";
 import { parseBound } from "./propagation.ts";
 
+interface RunChildTestControl { hardDeadlineAtAfterSpawn(): number }
+const TEST_CONTROL = Symbol.for("pi-daddy.internal.run-child-test-control");
+
+function currentRunChildTestControl(): RunChildTestControl | undefined {
+  if (process.env.NODE_TEST_CONTEXT !== "child-v8") return undefined;
+  const storage = (globalThis as Record<symbol, { getStore(): RunChildTestControl | undefined }>)[TEST_CONTROL];
+  return storage?.getStore();
+}
+
 /**
  * The longest prefix of `text` that fits in `budget` BYTES, never splitting a character.
  *
@@ -64,9 +73,11 @@ export interface ChildRunRequest {
   signal?: AbortSignal;
   /** Hard cap on captured output. Beyond it the child is killed and the result flagged. */
   maxOutputBytes?: number;
-  /** Wall-clock cap. On expiry: SIGTERM, then SIGKILL after `killGraceMs`. */
+  /** Soft wall-clock cap. On expiry: SIGTERM, then SIGKILL after `killGraceMs`. */
   timeoutMs?: number;
   killGraceMs?: number;
+  /** Absolute epoch-millisecond hard cap: SIGKILL fires here even when the SIGTERM grace has not elapsed. */
+  hardDeadlineAt?: number;
   /**
    * Called with each chunk as it arrives, for the parent's progress display (ADR-0032).
    *
@@ -106,9 +117,11 @@ export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
 export const DEFAULT_KILL_GRACE_MS = 5000;
 
 export function runChild(request: ChildRunRequest): Promise<ChildRunResult> {
+  const testControl = currentRunChildTestControl();
   const maxOutputBytes = request.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
   const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const killGraceMs = request.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+  const hardDeadlineAt = request.hardDeadlineAt;
 
   // A-R3: checked BEFORE spawning. `AbortSignal` does not replay, so a listener attached after an
   // `await` cannot observe an abort that already happened — and the child would then run to completion
@@ -160,6 +173,16 @@ export function runChild(request: ChildRunRequest): Promise<ChildRunResult> {
       timers.push(setTimeout(() => child.kill("SIGKILL"), killGraceMs));
     };
 
+    // A timer phase may run before libuv delivers an exit that the OS already observed, especially after the
+    // controller event loop was blocked across the deadline. Give pending child-process events one turn to
+    // publish exitCode/signalCode before deciding that a governed PID is still live.
+    const controlIfRunning = (control: () => void) => {
+      setImmediate(() => {
+        if (done || child.exitCode !== null || child.signalCode !== null) return;
+        control();
+      });
+    };
+
     /** How much of `text` the progress display has already been shown. */
     let emittedUpTo = 0;
 
@@ -225,11 +248,20 @@ export function runChild(request: ChildRunRequest): Promise<ChildRunResult> {
     child.stderr?.on("data", capture);
 
     timers.push(
-      setTimeout(() => {
+      setTimeout(() => controlIfRunning(() => {
         timedOut = true;
         stop();
-      }, timeoutMs),
+      }), timeoutMs),
     );
+    const activeHardDeadlineAt = testControl?.hardDeadlineAtAfterSpawn() ?? hardDeadlineAt;
+    if (activeHardDeadlineAt !== undefined) {
+      // Independent of the soft timer and measured from the recorded epoch, not from `spawn`: neither a
+      // delayed soft callback nor spawn/setup time may start a fresh grace period beyond the lifecycle bound.
+      timers.push(setTimeout(() => controlIfRunning(() => {
+        timedOut = true;
+        child.kill("SIGKILL");
+      }), Math.max(0, activeHardDeadlineAt - Date.now())));
+    }
 
     const onAbort = () => {
       aborted = true;

package/src/run-herdr.ts

@@ -98,6 +98,8 @@ export interface HerdrRunRequest {
    * name a human can switch to **while the child is alive**, which is the whole point of the pane surviving.
    */
   onPane?: (paneId: string, agentName: string) => void;
+  /** Called only after agent start and prompt both succeed; pane creation alone is still `starting`. */
+  onRunning?: (paneId: string, agentName: string) => void;
   /** Security hook for attaching a writer lease to the tab. Unlike display callbacks, errors fail the run. */
   onTab?: (tabId: string) => void;
   /** Close even a settled pane before releasing a writer lease; no post-lease prompt may remain live. */
@@ -300,6 +302,13 @@ export async function runHerdrPane(request: HerdrRunRequest): Promise<ChildRunRe
 
     const prompted = parseReply(await exec(["agent", "prompt", agentName, request.prompt]));
     if (prompted.error) return { ...empty, spawnError: `herdr agent prompt failed: ${prompted.error}` };
+    if (request.onRunning) {
+      try {
+        request.onRunning(paneId, agentName);
+      } catch {
+        /* display/observation only */
+      }
+    }
 
     const settled = await waitForSettled(exec, { ...request, name: agentName }, before, deadline, maxOutputBytes);
     if (settled.aborted || settled.timedOut) {

package/src/skill-packages.ts

@@ -30,7 +30,8 @@ import { homedir } from "node:os";
 import { join, resolve, sep } from "node:path";
 import { ceilingForDefinition, parseSkillDefinition, type SkillDefinition } from "./definitions.ts";
 import { WILDCARD } from "./pi-tools.ts";
-import { AGENT_WILDCARD, type Capability } from "./resolve.ts";
+import { AGENT_WILDCARD, WORKSPACE_WILDCARD, type Capability } from "./resolve.ts";
+import { isSafeCapability } from "./capabilities.ts";
 
 export interface DiscoveredSkill {
   definition: SkillDefinition;
@@ -107,21 +108,27 @@ export function isSafeName(name: string): boolean {
  * grants), which is right for the enforcement path — the catalog refuses what it does not know — and is
  * exactly why the check has to be here, at the boundary that *generates* rather than the one that enforces.
  *
- * The grammar is the one `docs/SPEC.md` documents: `tool:<name>`, `skill:<name>`, `agent:<name>`, and
- * `ext:<pkg>/<tool>` where `<pkg>` may be npm-scoped. No wildcards — those are refused separately and
- * loudly, because "you tried to grant yourself everything" is a different fact from "that is not a name".
+ * The grammar is the one `docs/SPEC.md` documents: `tool:<name>`, `skill:<name>`, `agent:<name>`,
+ * `workspace:<id>`, and `ext:<pkg>/<tool>` where `<pkg>` may be npm-scoped. No wildcards — those are refused
+ * separately and loudly, because "you tried to grant yourself everything" is a different fact from "that is
+ * not a name".
+ *
+ * `workspace:` was absent until 2026-08-21, so the boundary that GENERATES grants could not emit the one
+ * capability ADR-0035's breaking change made mandatory: a package needing to route was reported as declaring
+ * something that "is not a name". A namespace has to be added here as well as to the enforcing path, and
+ * that is the whole lesson of the review this came out of.
  */
-export function isSafeCapability(id: Capability): boolean {
-  const segment = "[A-Za-z0-9][A-Za-z0-9._-]*";
-  return (
-    new RegExp(`^(tool|skill|agent):${segment}$`).test(id) ||
-    new RegExp(`^ext:(@${segment}/)?${segment}/${segment}$`).test(id)
-  );
-}
+// Imported as well as re-exported: a bare `export … from` does not bind the name in this module's scope, and
+// `refusalFor` below calls it. Re-exported because this has been the import site since 0.13.0.
+export { isSafeCapability };
 
-/** The two ids that confer root authority. A package declaring one is claiming it, not describing a need. */
+/**
+ * The ids that confer authority over a whole namespace. A package declaring one is claiming it, not
+ * describing a need — so it is reported as a *wildcard claim* rather than as a malformed name, which is a
+ * different sentence to show an operator. `workspace:*` belongs here for the same reason `agent:*` does.
+ */
 function wildcardsIn(capabilities: Capability[]): Capability[] {
-  return capabilities.filter((c) => c === WILDCARD || c === AGENT_WILDCARD);
+  return capabilities.filter((c) => c === WILDCARD || c === AGENT_WILDCARD || c === WORKSPACE_WILDCARD);
 }
 
 /**

package/src/workflow-fact-id.ts

@@ -0,0 +1,16 @@
+const WORKFLOW_FACT_ID_RE = /^fact:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const WORKFLOW_IDENTIFIER_RE = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/;
+
+export function isWorkflowFactId(value: unknown): value is string {
+  return typeof value === "string" && WORKFLOW_FACT_ID_RE.test(value);
+}
+
+export function isWorkflowIdentifier(value: unknown): value is string {
+  return typeof value === "string" && WORKFLOW_IDENTIFIER_RE.test(value);
+}
+
+export function workflowFactStateMatches(provenance: unknown, state: unknown): boolean {
+  return (provenance === "planned" && state === "pending") ||
+    (provenance === "observed" && state === "observed") ||
+    (provenance === "controller_validated" && ["started", "completed", "blocked"].includes(String(state)));
+}

package/src/workflow-facts.ts

@@ -0,0 +1,65 @@
+import { LEDGER_VERSION } from "./ledger.ts";
+import { normaliseCorrelation, type CorrelationMetadata } from "./correlation.ts";
+import { isWorkflowFactId, isWorkflowIdentifier, workflowFactStateMatches } from "./workflow-fact-id.ts";
+import { assertLedgerV3Wire } from "./ledger-v3-validation.ts";
+
+export const WORKFLOW_FACT_PROVENANCE = ["planned", "observed", "controller_validated"] as const;
+export type WorkflowFactProvenance = typeof WORKFLOW_FACT_PROVENANCE[number];
+export const WORKFLOW_FACT_KINDS = ["workflow_phase", "inline_skill", "transition"] as const;
+export type WorkflowFactKind = typeof WORKFLOW_FACT_KINDS[number];
+export const WORKFLOW_FACT_STATES = ["pending", "observed", "started", "completed", "blocked"] as const;
+export type WorkflowFactState = typeof WORKFLOW_FACT_STATES[number];
+
+export interface WorkflowFactEvent {
+  ledgerVersion: typeof LEDGER_VERSION;
+  event: "workflow_fact";
+  ts: string;
+  factId: string;
+  /** Package/controller identifier, not free-form display text. */
+  source: string;
+  provenance: WorkflowFactProvenance;
+  kind: WorkflowFactKind;
+  /** Phase, skill, or transition identifier. Never task text. */
+  subject: string;
+  state: WorkflowFactState;
+  /** run_id is required by the builder; other values remain non-authoritative labels. */
+  correlation: CorrelationMetadata;
+}
+
+export function buildWorkflowFactEvent(args: {
+  factId: string;
+  source: string;
+  provenance: WorkflowFactProvenance;
+  kind: WorkflowFactKind;
+  subject: string;
+  state: WorkflowFactState;
+  correlation: CorrelationMetadata;
+  now: Date;
+}): WorkflowFactEvent {
+  if (!isWorkflowFactId(args.factId)) throw new TypeError("factId must be a pi-daddy workflow fact id");
+  if (!isWorkflowIdentifier(args.source)) throw new TypeError("workflow fact source must be an identifier");
+  if (!WORKFLOW_FACT_PROVENANCE.includes(args.provenance)) throw new TypeError("workflow fact provenance is not recognised");
+  if (!WORKFLOW_FACT_KINDS.includes(args.kind)) throw new TypeError("workflow fact kind is not recognised");
+  if (!isWorkflowIdentifier(args.subject)) throw new TypeError("workflow fact subject must be an identifier, not task text");
+  if (!WORKFLOW_FACT_STATES.includes(args.state)) throw new TypeError("workflow fact state is not recognised");
+  const correlation = normaliseCorrelation(args.correlation);
+  if (!correlation?.run_id) throw new TypeError("workflow facts require correlation.run_id");
+  if (!workflowFactStateMatches(args.provenance, args.state)) {
+    const expected = args.provenance === "planned" ? "pending" : args.provenance === "observed"
+      ? "observed" : "started, completed, or blocked";
+    throw new TypeError(`${args.provenance.replaceAll("_", "-")} workflow facts must use ${expected}`);
+  }
+  const event: WorkflowFactEvent = {
+    ledgerVersion: LEDGER_VERSION,
+    event: "workflow_fact",
+    ts: args.now.toISOString(),
+    factId: args.factId,
+    source: args.source,
+    provenance: args.provenance,
+    kind: args.kind,
+    subject: args.subject,
+    state: args.state,
+    correlation,
+  };
+  return assertLedgerV3Wire(event);
+}

package/src/workspace-lease.ts

@@ -14,6 +14,7 @@ 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";
 
@@ -22,28 +23,17 @@ export function defaultWorkspaceLeaseDir(env: NodeJS.ProcessEnv = process.env):
   return env[ENV_WORKSPACE_LEASE_DIR] ?? join(agentDir, "pi-daddy", "workspace-leases");
 }
 
-const LEASE_READY = "PI_DADDY_LEASE_READY";
-// The lock holder also owns crash cleanup for the governed child. If the parent dies, stdin closes;
-// the helper signals the attached process, or closes the herdr tab, before releasing flock. A raw
-// descendant deliberately detached by bash remains ADR-0012's OS-containment boundary, not a lease
-// guarantee. The process branch SIGTERMs, escalates to SIGKILL at +500ms, and releases at +750ms
-// WITHOUT confirming death (R-101). The herdr branch retries `tab close` a BOUNDED number of times
-// and then releases anyway, leaving a marker file: an unreleasable lock strands a worktree forever
-// with no in-product recovery, which is strictly worse than a recorded failure to close (R-102).
-const HELPER_SOURCE = `
-import { execFile } from "node:child_process";
-import { writeFileSync } from "node:fs";
-let clean=false, target=null, buffered="";
-process.stdout.write(${JSON.stringify(`${LEASE_READY}:`)}+process.pid+"\\n");
-process.stdin.setEncoding("utf8");
-process.stdin.on("data",chunk=>{buffered+=chunk;for(;;){const i=buffered.indexOf("\\n");if(i<0)break;const line=buffered.slice(0,i);buffered=buffered.slice(i+1);try{const value=JSON.parse(line);if(value.release)clean=true;else if(value.process_pid)target={process_pid:value.process_pid};else if(value.herdr_tab)target={herdr_tab:value.herdr_tab};}catch{}}});
-process.stdin.on("end",()=>{if(clean||!target)return process.exit(0);if(target.process_pid){try{process.kill(target.process_pid,"SIGTERM")}catch{return process.exit(0)}setTimeout(()=>{try{process.kill(target.process_pid,"SIGKILL")}catch{}},500);return setTimeout(()=>process.exit(0),750);}let left=Number(process.env.PI_DADDY_LEASE_CLOSE_ATTEMPTS||10);const giveUp=()=>{try{if(process.env.PI_DADDY_LEASE_MARKER)writeFileSync(process.env.PI_DADDY_LEASE_MARKER,JSON.stringify({reason:"herdr-close-failed",herdr_tab:target.herdr_tab})+"\\n")}catch{}process.exit(0)};const close=()=>execFile("herdr",["tab","close",target.herdr_tab],error=>{if(!error)return process.exit(0);if(--left<=0)return giveUp();setTimeout(close,1000)});close();});
-process.stdin.resume();`;
 
 /**
- * The ledger outcome for a release. ONE definition, exported, because two call sites had their own copies
- * and the check runner's copy asserted `released` unconditionally — reproducing in the evidence path the
- * exact defect this union was added to expose (R-100/R-103).
+ * 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",
@@ -78,9 +68,17 @@ export async function acquireWorkspaceLease(input: {
   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,
@@ -89,7 +87,9 @@ export async function acquireWorkspaceLease(input: {
       recovered: false,
       attachProcess: () => {},
       attachHerdrTab: () => {},
-      markRetained: async () => {},
+      // 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).
@@ -108,7 +108,12 @@ export async function acquireWorkspaceLease(input: {
     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) },
+    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
@@ -240,12 +245,67 @@ export async function acquireWorkspaceLease(input: {
     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) {
-        await atomicMetadata(paths.metadata, {
+        recorded = await atomicMetadata(paths.metadata, {
           ...metadata, state: "released", released_at: new Date().toISOString(), release_reason: `retained:${reason}`,
-        }).catch(() => undefined);
+        }).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 {