pi-daddy 0.18.1 → 0.19.0

package/src/ledger.ts

@@ -34,11 +34,17 @@ import type { StructuredRefusal } from "./refusals.ts";
 import type { RuntimeLedgerEvent } from "./ledger-events.ts";
 
 export const LEDGER_VERSION = 2 as const;
+export const LEDGER_EVENT_KINDS = [
+  "capability_decision", "workspace_lease", "child_lifecycle", "check_receipt",
+] as const;
+export type LedgerEventKind = typeof LEDGER_EVENT_KINDS[number];
+export const LEDGER_GATE_OUTCOMES = ["declined", "dismissed", "no-ui", "error"] as const;
+export type LedgerGateOutcome = typeof LEDGER_GATE_OUTCOMES[number];
 
 export interface LedgerEventBase {
   /** Optional only on the legacy-compatible `GrantRecord` public type; every v2 event builder writes it. */
   ledgerVersion?: typeof LEDGER_VERSION;
-  event?: "capability_decision" | "workspace_lease" | "child_lifecycle" | "check_receipt";
+  event?: LedgerEventKind;
   ts: string;
   childId?: string;
   correlation?: CorrelationMetadata;
@@ -104,7 +110,7 @@ export interface GrantRecord extends LedgerEventBase {
   /** Present only when the source was a live prompt, and only when one scope covers the whole set. */
   approvalScope?: ApprovalScope;
   /** A human was asked and declined. Distinct from `denied`, which is an escalation attempt. */
-  humanDenied?: boolean;
+  humanDenied?: true;
   /**
    * WHY a gate went unsatisfied, when the answer was not a yes.
    *
@@ -120,9 +126,10 @@ export interface GrantRecord extends LedgerEventBase {
    * say *"nobody was there to ask"* and be believed, so it is recorded rather than inferred.
    *
    * **Privacy is unchanged**: this is a fixed five-member enum, not text — nothing model-authored, nothing
-   * a task could carry.
+   * a task could carry. The prompt has five outcomes, but `granted` is deliberately omitted from the
+   * four-member ledger enum because the approval source/scope fields already record a yes.
    */
-  gateOutcome?: PromptOutcomeKind;
+  gateOutcome?: LedgerGateOutcome;
   /**
    * WHICH operator-authored instructions this child was given (ADR-0018).
    *
@@ -208,6 +215,12 @@ export function buildRecord(args: {
   refusal?: StructuredRefusal;
   now: Date;
 }): GrantRecord {
+  if (args.taskDigest !== undefined && !/^[a-f0-9]{64}$/i.test(args.taskDigest)) {
+    throw new TypeError("taskDigest must be a SHA-256 hex digest");
+  }
+  if (args.definitionDigest && !/^[a-f0-9]{64}$/i.test(args.definitionDigest.sha256)) {
+    throw new TypeError("definitionDigest.sha256 must be a SHA-256 hex digest");
+  }
   // R-46: the scalar is a SUMMARY, emitted only when it cannot mislead. `buildRecord` derives it rather
   // than accepting it, so a call site cannot supply one that disagrees with the map beside it.
   const sources = args.approvalSources ?? {};
@@ -217,7 +230,7 @@ export function buildRecord(args: {
   return {
     // A trusted task digest is what distinguishes a v2 capability event from the legacy construction API.
     // Production delegation always supplies it; old TypeScript callers remain able to append legacy lines.
-    ...(args.taskDigest ? { ledgerVersion: LEDGER_VERSION, event: "capability_decision" as const } : {}),
+    ...(args.taskDigest !== undefined ? { ledgerVersion: LEDGER_VERSION, event: "capability_decision" as const } : {}),
     ts: args.now.toISOString(),
     parentId: args.parentId,
     childId: args.childId,
@@ -225,7 +238,7 @@ export function buildRecord(args: {
     agentType: args.agentType,
     executor: args.executor,
     ...(args.taskFrom ? { taskFrom: args.taskFrom } : {}),
-    ...(args.taskDigest ? { taskDigest: args.taskDigest } : {}),
+    ...(args.taskDigest !== undefined ? { taskDigest: args.taskDigest } : {}),
     ...(args.correlation ? { correlation: structuredClone(args.correlation) } : {}),
     ...(args.refusal ? { refusal: structuredClone(args.refusal) } : {}),
     requested: args.requested,
@@ -302,11 +315,22 @@ export function isEscalationAttempt(record: GrantRecord): boolean {
 }
 
 export {
+  CHILD_LIFECYCLE_STATES,
+  CHILD_PROCESS_SIGNALS,
+  WORKSPACE_ACCESSES,
+  WORKSPACE_LEASE_OUTCOMES,
+  WORKSPACE_RECOVERY_VALUES,
+  buildCheckReceiptLedgerEvent,
   buildChildLifecycleEvent,
   buildWorkspaceLeaseEvent,
+  type CapabilityDecisionEvent,
   type ChildLifecycleEvent,
+  type ChildLifecycleState,
+  type ChildProcessSignal,
   type CheckReceiptLedgerEvent,
   type RuntimeLedgerEvent,
+  type WorkspaceAccess,
   type WorkspaceLeaseEvent,
   type WorkspaceLeaseOutcome,
+  type WorkspaceRecovery,
 } from "./ledger-events.ts";

package/src/propagation.ts

@@ -27,6 +27,7 @@
 
 import type { Capability } from "./resolve.ts";
 import { WILDCARD } from "./pi-tools.ts";
+import { WORKSPACE_WILDCARD } from "./resolve.ts";
 import { inheritApprovals, type InheritableApproval } from "./approval.ts";
 import { assertCapabilitiesArePropagatable } from "./capabilities.ts";
 
@@ -247,9 +248,28 @@ export interface ChildEnvInput {
  * empty grant, so they can spawn nothing. That fails closed. It is also unreachable in normal flow,
  * because a session's first provider request always precedes its first tool call.
  */
+/**
+ * The part of a grant a child may inherit: everything but the wildcards that are HELD, never handed down.
+ *
+ * `tool:*` for R-26's reason — a root that handed it down let every descendant reacquire the full catalog.
+ * `workspace:*` for the same reason one namespace over (R-131): a descendant holding it could route anywhere
+ * the registry lists, which is the attenuation failure ADR-0035 exists to close. `agent:*` is deliberately
+ * NOT stripped — ADR-0023 decided that a session authorised for any definition passes that on, because
+ * definitions are ceilings rather than roots.
+ *
+ * **Exported, and there is exactly one spelling of this rule on purpose.** It shipped as a filter inline in
+ * `childEnv` and nowhere else, so a grant travelling the OTHER path — `delegate.ts` building a child's
+ * `PI_GRANTS_GRANT` from `result.effective` — carried `workspace:*` straight down. The test written beside
+ * that fix exercised `childEnv`, which is not the path a delegated child's grant travels, so it could not
+ * catch it. R-28's shape: two routes for one rule, with the guard on the quieter one. Both call this now.
+ */
+export function inheritableGrant(grant: readonly Capability[]): Capability[] {
+  return grant.filter((c) => c !== WILDCARD && c !== WORKSPACE_WILDCARD);
+}
+
 export function childEnv(input: ChildEnvInput): Record<string, string> {
   if (input.governed === false) return {};
-  const inheritable = input.ownGrant.filter((c) => c !== WILDCARD);
+  const inheritable = inheritableGrant(input.ownGrant);
   const env: Record<string, string> = {
     [ENV_GRANT]: (assertCapabilitiesArePropagatable(inheritable), inheritable.join(",")),
     [ENV_DEPTH]: String(input.depth + 1),

package/src/refusals.ts

@@ -28,6 +28,7 @@ export const REFUSAL_CODES = [
   "LEDGER_WRITE_FAILED",
   "FANOUT_FAILED",
   "WORKSPACE_NOT_REGISTERED",
+  "WORKSPACE_NOT_AUTHORIZED",
   "WORKSPACE_WRITE_CONFLICT",
   "WORKSPACE_LEASE_STALE",
   "CHECK_NOT_CONFIGURED",

package/src/resolve.ts

@@ -76,6 +76,16 @@ import { isWellFormedCapability } from "./capabilities.ts";
  * `tool:*` — authority to grant every tool — which made the safe configuration the laborious one.
  */
 export const AGENT_WILDCARD: Capability = "agent:*";
+/**
+ * `workspace:*` covers any `workspace:<id>` — ADR-0035, and the second namespace wildcard.
+ *
+ * Added as a deliberate edit, which is what the comment in `resolve()` below asks for: there is no
+ * generalised `<ns>:*` rule, so a namespace does not acquire a wildcard by existing. Unlike `agent:*` this
+ * one is **not inheritable** (`childEnv` strips it) — R-26's rule, because a root that handed
+ * `workspace:*` down would make routing attenuation meaningless below the root, which is the exact defect
+ * R-131 records.
+ */
+export const WORKSPACE_WILDCARD: Capability = "workspace:*";
 
 export interface ResolveInput {
   /** What the delegating agent asked to give the child. */
@@ -125,7 +135,10 @@ export function resolve(input: ResolveInput): ResolveResult {
   const parent =
     input.subsumption === false ? held : new Set(expandSubsumed(input.parentGrant));
   /**
-   * `agent:*` covers any `agent:<name>` — ADR-0023, and the ONLY wildcard rule in this function.
+   * `agent:*` covers any `agent:<name>` — ADR-0023. It was the only wildcard rule in this function when
+   * that was written; ADR-0035 added a third, so `covered()` now has `tool:*`, `agent:*` and `workspace:*`.
+   * There is still no GENERALISED `<ns>:*` rule: each is a deliberate edit, which is the property worth
+   * keeping. Corrected because the sentence sat eighty lines above "all THREE wildcards are excluded".
    *
    * `resolve` is otherwise exact-match plus subsumption, deliberately: `tool:*` works not because anything
    * here understands it, but because `deriveOwnGrant` *enumerates* a session's observed tool names beside
@@ -150,13 +163,17 @@ export function resolve(input: ResolveInput): ResolveResult {
    * spellings of one rule, and the enforcing one was wrong.
    */
   const anyCapability = held.has(WILDCARD);
+  const anyWorkspace = held.has(WORKSPACE_WILDCARD);
   // A malformed id is never covered — not by an exact hold, and above all not by a wildcard's PREFIX rule,
   // which is how `agent:x,tool:bash` got admitted and then split into two capabilities in the child.
   // Landing in `denied` is the right outcome rather than a throw: it fails closed AND records an
   // escalation attempt, so the ledger shows the attempt instead of a clean line.
   const covered = (c: Capability): boolean =>
     isWellFormedCapability(c)
-    && (parent.has(c) || anyCapability || (anyDefinition && c.startsWith("agent:")));
+    && (parent.has(c) || anyCapability
+      || (anyDefinition && c.startsWith("agent:"))
+      || (anyWorkspace && c.startsWith("workspace:")));
+
   const ceiling = input.ceiling === undefined ? null : new Set(input.ceiling);
   const gated = new Set(input.gated ?? []);
   const approved = new Set(input.approved ?? []);
@@ -199,7 +216,16 @@ export function resolve(input: ResolveInput): ResolveResult {
     // F9: capabilities covered by a WILDCARD are not "subsumed" — this field means "the grant is broader
     // than its list suggests", which is the `bash`-covers-`grep` warning. A wildcard holder already knows
     // its grant is broad; listing every id under it would bury the signal the field exists to carry.
-    subsumedBy: effective.filter((c) => !held.has(c) && !anyCapability && !(anyDefinition && c.startsWith("agent:"))),
+    //
+    // All THREE wildcards are excluded. `anyWorkspace` was missing, so a caller holding `workspace:*` saw
+    // its own `workspace:prod` reported as subsumed while the `agent:*` holder correctly saw nothing — the
+    // field contradicting its own rule, and a false "broader than it looks" flag in the ledger and in
+    // `/grants`. Every wildcard added to `covered()` above needs a line here; that is now three for three.
+    subsumedBy: effective.filter((c) =>
+      !held.has(c)
+      && !anyCapability
+      && !(anyDefinition && c.startsWith("agent:"))
+      && !(anyWorkspace && c.startsWith("workspace:"))),
   };
 }
 

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/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/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 {