pi-daddy 0.18.1 → 0.20.0

package/src/delegate.ts

@@ -6,13 +6,22 @@
 import { planSpawn } from "./spawn.ts";
 import { ceilingForDefinition, digestDefinition, type DefinitionDigest, type SkillDefinition } from "./definitions.ts";
 import { assertNarrowing, type Capability, type ResolveResult } from "./resolve.ts";
-import { DELEGATE_CAPABILITY, agentCapability, maySpawnDefinition, normaliseCapability } from "./capabilities.ts";
+import { checkRoutingAuthority, checkWorkspaceWildcardRequest } from "./routing-authority.ts";
+import {
+  DELEGATE_CAPABILITY,
+  agentCapability,
+  maySpawnDefinition,
+  normaliseCapability,
+} from "./capabilities.ts";
 
 // Re-exported so the split stays internal: `delegate.ts` has been the import site for these since 0.6.0 and
 // four modules plus the test suite name it. Moving the definitions without moving the door would be churn
 // charged to every caller for a line count they did not cause.
 export { DELEGATE_CAPABILITY, agentCapability, maySpawnDefinition, normaliseCapability } from "./capabilities.ts";
-import { ENV_APPROVED, ENV_DEPTH, ENV_FANOUT, ENV_GATED, ENV_GRANT, ENV_LEDGER, ENV_MAX_DEPTH, ENV_PARENT_ID } from "./propagation.ts";
+import {
+  ENV_APPROVED, ENV_DEPTH, ENV_EXECUTION_ID, ENV_FANOUT, ENV_GATED, ENV_GRANT, ENV_LEDGER, ENV_MAX_DEPTH,
+  ENV_PARENT_ID, inheritableGrant,
+} from "./propagation.ts";
 import { inheritApprovals, type InheritableApproval } from "./approval.ts";
 import { suggestForUnknown, unknownCapabilities, type Catalog } from "./catalog.ts";
 import { GovernanceRefusal, refusal, type RefusalCode, type StructuredRefusal } from "./refusals.ts";
@@ -72,6 +81,17 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
   }
   if (!request.task?.trim()) return denied({ ...empty, reason: "a delegation needs a task" }, "TASK_MISSING");
 
+  // ADR-0035's routing guards live in `routing-authority.ts` with their rationale; both are checked here,
+  // before anything is said about the target, because they are governance questions about the SESSION.
+  const routing = checkRoutingAuthority(request.boundWorkspaceId, ctx.ownGrant);
+  if (routing) {
+    return denied({
+      ...empty,
+      ...(routing.denied ? { requested: routing.denied, result: { ...empty.result, denied: routing.denied } } : {}),
+      reason: routing.reason,
+    }, routing.code);
+  }
+
   // ADR-0016. A named definition replaces the model's tool list with an operator-authored ceiling.
   let requested: Capability[];
   let systemPrompt: string | undefined;
@@ -181,6 +201,13 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
     }
   }
 
+  // See `checkWorkspaceWildcardRequest`: refused for a HOLDER (the ledger must not record authority the
+  // child will not receive), and left to `resolve()` for anyone else, so the probe lands in `denied`.
+  const wildcardRequest = checkWorkspaceWildcardRequest(requested, ctx.ownGrant);
+  if (wildcardRequest) {
+    return denied({ ...empty, requested, reason: wildcardRequest.reason }, wildcardRequest.code);
+  }
+
   const { result, approvalBinding, bindingMismatch } = resolveDelegationApproval({
     task: request.task,
     agent: request.agent,
@@ -266,8 +293,14 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
     args.splice(args.length - 1, 0, "-e", ctx.extensionPath);
   }
 
+  // `inheritableGrant`, not `result.effective` directly: this is the path a DELEGATED child's grant
+  // actually travels, and the "held but never inherited" rule for `tool:*` and `workspace:*` was enforced
+  // only in `childEnv`. A parent holding `workspace:*` could request it for its child and this line handed
+  // it over, so the rule ADR-0035 advertises held by accident — masked downstream rather than enforced
+  // here. One spelling of the rule, called from both paths.
+  const inheritable = inheritableGrant(result.effective);
   const env: Record<string, string> = {
-    [ENV_GRANT]: (assertCapabilitiesArePropagatable(result.effective), result.effective.join(",")),
+    [ENV_GRANT]: (assertCapabilitiesArePropagatable(inheritable), inheritable.join(",")),
     [ENV_DEPTH]: String(childDepth),
     [ENV_MAX_DEPTH]: String(ctx.maxDepth),
   };
@@ -276,12 +309,17 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
   // process boundaries with no shared state.
   if (ctx.fanoutBudget !== undefined) env[ENV_FANOUT] = String(ctx.fanoutBudget);
   if (ctx.childSpawnId) env[ENV_PARENT_ID] = ctx.childSpawnId;
+  if (ctx.childExecutionId) env[ENV_EXECUTION_ID] = ctx.childExecutionId;
   if (ctx.gated.length > 0) env[ENV_GATED] = ctx.gated.join(",");
   // Approvals ride down with the grant, but only ever for what this child actually received — so
   // `approved ⊆ grant` holds at every level (ADR-0010). Written even when empty, so this object states
   // the child's approval set outright rather than leaving it to whatever the caller merges over; see
   // `mergeChildEnv`, which is what actually stops the parent's value leaking through.
-  env[ENV_APPROVED] = inheritApprovals(ctx.approved ?? [], result.effective).join(",");
+  // Clamped to what the child actually INHERITS, not to what it was granted. The two differ only for a
+  // non-inheritable wildcard, and passing down an approval for a capability the child does not hold would
+  // leave banked authority with nothing to spend it on — `childEnv` clamps to `inheritable` for the same
+  // reason on the other path.
+  env[ENV_APPROVED] = inheritApprovals(ctx.approved ?? [], inheritable).join(",");
   if (ctx.ledgerPath) env[ENV_LEDGER] = ctx.ledgerPath;
 
   return {
@@ -293,6 +331,7 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
     childDepth,
     requested,
     childId: ctx.childSpawnId,
+    executionId: ctx.childExecutionId,
     taskDigest,
     ...(correlation ? { correlation } : {}),
     ...(approvalBinding ? { approvalBinding } : {}),

package/src/delegation-approval.ts

@@ -1,5 +1,5 @@
 import { DELEGATE_SUBJECT, type InheritableApproval } from "./approval.ts";
-import { agentCapability } from "./capabilities.ts";
+import { agentCapability, workspaceCapability } from "./capabilities.ts";
 import {
   approvalBindingsEqual,
   buildApprovalBinding,
@@ -7,7 +7,7 @@ import {
   type CorrelationMetadata,
 } from "./correlation.ts";
 import type { DefinitionDigest, SkillDefinition } from "./definitions.ts";
-import { AGENT_WILDCARD, resolve, type Capability, type ResolveResult } from "./resolve.ts";
+import { AGENT_WILDCARD, WORKSPACE_WILDCARD, resolve, type Capability, type ResolveResult } from "./resolve.ts";
 
 /**
  * Resolve the approval half of one delegation after its requested capability set is known.
@@ -44,15 +44,32 @@ export function resolveDelegationApproval(input: {
     approved: [],
   });
 
-  // ADR-0024: a definition's authorising id is gated as the PARENT's authority to run it now. It never
-  // joins requested/effective, because that would hand the child authority to recursively spawn itself.
-  let authorisingCapability: Capability | undefined;
-  if (input.spawned) {
-    const authorising = agentCapability(input.spawned.name);
-    if (input.gated.includes(authorising) || input.gated.includes(AGENT_WILDCARD)) {
-      authorisingCapability = authorising;
+  /**
+   * Authorities the PARENT is spending on this one delegation, gated as such.
+   *
+   * ADR-0024 established the shape for `agent:<name>`: the id is gated as the parent's authority to run
+   * that definition *now*, and never joins requested/effective, because that would hand the child authority
+   * to recursively spawn itself. ADR-0035 added a second member of the category — `workspace:<id>`, the
+   * authority to route this child somewhere — and shipped without it, so `PI_GRANTS_GATED=workspace:prod`
+   * was accepted, recorded, and silently inert: no human was ever asked. The ADR claimed the opposite in
+   * three places.
+   *
+   * A LIST rather than two variables on purpose. This is the third namespace whose authorising id is gated
+   * per-delegation rather than granted downward, and the first two were written as one special case each;
+   * a fourth should extend an array, not add a third `if` and a third field to thread through.
+   */
+  const authorisingCapabilities: Capability[] = [];
+  const gateAuthority = (authorising: Capability, wildcard: Capability) => {
+    if (input.gated.includes(authorising) || input.gated.includes(wildcard)) {
+      authorisingCapabilities.push(authorising);
       unapproved.gatedBlocked = [...unapproved.gatedBlocked, authorising];
     }
+  };
+  if (input.spawned) gateAuthority(agentCapability(input.spawned.name), AGENT_WILDCARD);
+  // Trusted: `boundWorkspaceId` is set only from a routing spec resolved against the operator registry,
+  // never from a model-supplied `correlation` claim (R-110).
+  if (input.boundWorkspaceId) {
+    gateAuthority(workspaceCapability(input.boundWorkspaceId), WORKSPACE_WILDCARD);
   }
 
   const potential = resolve({
@@ -92,8 +109,16 @@ export function resolveDelegationApproval(input: {
     gated: input.gated,
     approved: approvedCapabilities,
   });
-  if (authorisingCapability && !approvedCapabilities.includes(authorisingCapability)) {
-    result.gatedBlocked = [...result.gatedBlocked, authorisingCapability];
-  }
+  // Filtered against what `resolve()` already listed, not just against approvals. In the ORDINARY chained
+  // configuration — route the child to `prod` AND grant it `workspace:prod` so it can route onward — the
+  // authorising id and the requested id are spelled identically, so appending unconditionally produced
+  // `gatedBlocked: ["workspace:prod","workspace:prod"]`, which reached the refusal text a model reads
+  // (*"workspace:prod, workspace:prod requires explicit approval"*) and the append-only ledger, whose schema
+  // has no `uniqueItems`. The old `agent:`-only code had the same shape and never hit it, because a
+  // self-recursive `agent:X` ceiling is not a thing anybody writes.
+  const stillGated = authorisingCapabilities.filter(
+    (c) => !approvedCapabilities.includes(c) && !result.gatedBlocked.includes(c),
+  );
+  if (stillGated.length > 0) result.gatedBlocked = [...result.gatedBlocked, ...stillGated];
   return { result, ...(approvalBinding ? { approvalBinding } : {}), bindingMismatch };
 }

package/src/execution-id.ts

@@ -0,0 +1,18 @@
+import { randomUUID } from "node:crypto";
+
+/** Unique identity for one governed execution occurrence. Logical child ids remain readable positions. */
+export type ExecutionId = `exec:${string}`;
+
+const EXECUTION_ID_RE = /^exec:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export function isExecutionId(value: unknown): value is ExecutionId {
+  return typeof value === "string" && EXECUTION_ID_RE.test(value);
+}
+
+export function newExecutionId(): ExecutionId {
+  return `exec:${randomUUID()}`;
+}
+
+export function assertExecutionId(value: unknown, field = "executionId"): asserts value is ExecutionId {
+  if (!isExecutionId(value)) throw new TypeError(`${field} must be a pi-daddy execution id`);
+}

package/src/executor.ts

@@ -18,7 +18,8 @@ import type { HerdrProbe } from "./herdr-cli.ts";
 
 export const ENV_HERDR = "PI_GRANTS_HERDR";
 
-export type ExecutorKind = "herdr" | "process";
+export const EXECUTOR_KINDS = ["process", "herdr"] as const;
+export type ExecutorKind = typeof EXECUTOR_KINDS[number];
 
 export interface ExecutorChoice {
   kind: ExecutorKind;

package/src/grant-env.ts

@@ -42,6 +42,12 @@ export const WITHHELD_BY_DEFAULT: readonly Capability[] = [
 
 /** Would `init` put this capability in the live grant? */
 export function isLiveByDefault(capability: Capability): boolean {
+  // No `workspace:<id>` is ever live by default (ADR-0035), and this is the same rule the list above states
+  // rather than a new one: authority "does not become live because a package asked for it". A registry id is
+  // a *choice of where a child runs*, which is the operator's to make and cannot be inferred from a
+  // declaration — ADR-0028's whole position. Enumerated ids are unbounded, so this is a namespace test and
+  // not a list membership.
+  if (capability.startsWith("workspace:")) return false;
   return !WITHHELD_BY_DEFAULT.includes(capability);
 }
 
@@ -87,6 +93,8 @@ export interface GrantEnvInput {
   withheld: Map<Capability, string[]>;
   /** Definitions whose `agent:` id is withheld because they need a withheld capability. */
   withheldDefinitions: string[];
+  /** `workspace:<id>` ids this project could route to (ADR-0035). Rendered commented, never granted. */
+  routableWorkspaces?: Capability[];
   /** `agent:<name>` ids a ceiling names that `init` did not write here. Reported, never granted. */
   crossReferences: { from: string; capability: Capability }[];
   cautions: string[];
@@ -140,13 +148,37 @@ export function renderGrantEnv(input: GrantEnvInput): string {
     for (const [capability, needed] of [...input.withheld].sort()) {
       lines.push(`#   ${capability.padEnd(width)}  (${needed.join(", ")})`);
     }
-    if (input.withheldDefinitions.length > 0) {
-      lines.push(
-        `#   …and then: ${input.withheldDefinitions.map((n) => `agent:${n}`).join(",")}`,
-        "#   Their `agent:` ids are withheld too: a definition that cannot receive what it declares would",
-        "#   be authorised to run and then refused, which is a worse answer than not being authorised.",
-      );
-    }
+    lines.push("#");
+  }
+
+  // OUTSIDE the block above, and that is the fix. This is the file's only statement that a withheld
+  // definition's `agent:` id must be granted too — and it used to render only when `withheld` was non-empty,
+  // so a package whose sole withheld capability is a ROUTING id (the common read-only routing case) lost it
+  // entirely once `workspace:` ids stopped going into that map. The reason line above still said "see below"
+  // and pointed at nothing.
+  if (input.withheldDefinitions.length > 0) {
+    lines.push(
+      `#   …and then: ${input.withheldDefinitions.map((n) => `agent:${n}`).join(",")}`,
+      "#   Their `agent:` ids are withheld too: a definition that cannot receive what it declares would",
+      "#   be authorised to run and then refused, which is a worse answer than not being authorised.",
+      "#",
+    );
+  }
+
+  // ADR-0035. Routing became a capability in 0.19.0, which made every existing grant that routes start
+  // refusing — so the migration has to be visible from the file the operator already opens. Listed and NOT
+  // granted: which worktree a child starts in is the operator's decision and cannot be read off a
+  // declaration (ADR-0028), and granting one because a package named it is the "does not become live because
+  // a package asked for it" rule that `WITHHELD_BY_DEFAULT` above states.
+  if (input.routableWorkspaces && input.routableWorkspaces.length > 0) {
+    lines.push(
+      "# ROUTABLE WORKSPACES — routing a child to a registered worktree needs the id in PI_GRANTS_GRANT",
+      "# (ADR-0035, 0.19.0). Without it a delegation naming one is refused WORKSPACE_NOT_AUTHORIZED. Add the",
+      "# ones this project's children may start in; a child can only pass on ids it holds itself, so this is",
+      "# also the list of what any DESCENDANT could reach. Not granted for you: `workspace:*` exists but is",
+      "# held and never inherited, which makes it the wrong answer for anything but a single-worktree setup.",
+    );
+    for (const capability of input.routableWorkspaces) lines.push(`#   ${capability}`);
     lines.push("#");
   }
 

package/src/index.ts

@@ -11,9 +11,14 @@ export {
 export {
   appendLedgerEvent,
   appendRecord,
+  buildCheckReceiptLedgerEvent,
   buildChildLifecycleEvent,
   buildRecord,
   buildWorkspaceLeaseEvent,
+  buildWorkflowFactEvent,
+  WORKFLOW_FACT_KINDS,
+  WORKFLOW_FACT_PROVENANCE,
+  WORKFLOW_FACT_STATES,
   isEscalationAttempt,
   LEDGER_VERSION,
   type CheckReceiptLedgerEvent,
@@ -23,6 +28,10 @@ export {
   type RuntimeLedgerEvent,
   type WorkspaceLeaseEvent,
   type WorkspaceLeaseOutcome,
+  type WorkflowFactEvent,
+  type WorkflowFactKind,
+  type WorkflowFactProvenance,
+  type WorkflowFactState,
 } from "./ledger.ts";
 
 export { planSpawn, type SpawnPlan, type SpawnPlanInput } from "./spawn.ts";
@@ -96,6 +105,23 @@ export {
   type CheckRegistry,
 } from "./check-runner.ts";
 
+export {
+  isExecutionId,
+  newExecutionId,
+  type ExecutionId,
+} from "./execution-id.ts";
+
+export {
+  parseDashboardLedger,
+  type DashboardNode,
+  type DashboardProjection,
+  type DashboardState,
+  type DashboardWorkflow,
+  type DashboardWorkflowFact,
+} from "./dashboard-projection.ts";
+
+export { renderDashboard, type DashboardRenderOptions } from "./dashboard-render.ts";
+
 export {
   createApprovalGate,
   createApprovalGateProvider,

package/src/init.ts

@@ -24,7 +24,7 @@
 
 import { mkdir, open, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { agentCapability } from "./capabilities.ts";
+import { agentCapability, workspaceCapability } from "./capabilities.ts";
 import { ceilingForDefinition } from "./definitions.ts";
 import { ALWAYS_LIVE, assertGrantIsWritable, isLiveByDefault, renderGrantEnv, type GrantEnvSkill } from "./grant-env.ts";
 import { PI_BUILTIN_TOOLS } from "./pi-tools.ts";
@@ -78,6 +78,8 @@ export interface InitPlan {
   grant: Capability[];
   /** Withheld capability → the definitions that declared it (ADR-0029). Emitted commented. */
   withheldCapabilities: Map<Capability, string[]>;
+  /** `workspace:<id>` this project could route to (ADR-0035). Always commented — `init` does not choose. */
+  routableWorkspaces: Capability[];
   grantEnvPath: string;
   grantEnvContent: string;
   /** Capabilities a declared ceiling names that pi 0.84.1 has no tool for — a caution, not a verdict. */
@@ -143,7 +145,20 @@ function unknownToolIds(capabilities: Capability[]): Capability[] {
  * tools at all and the whole file is inert. Everything else is emitted commented, named, and one uncomment
  * away (ADR-0029).
  */
-export function planInit(packages: SkillPackage[], cwd: string): InitPlan {
+export function planInit(
+  packages: SkillPackage[],
+  cwd: string,
+  /**
+   * Ids from the operator's workspace registry, when one is configured — read by the CALLER, because
+   * `planInit` is pure and stays that way.
+   *
+   * ADR-0035 made routing a capability and said `init` "scaffolds the registered ids so the common path is a
+   * one-line grant edit". It did not: `init` had never heard of the registry, so the ADR's own stated
+   * migration path for a breaking change did not exist. These are emitted **commented**, never live —
+   * offering the ids while refusing to choose among them is exactly ADR-0028's position.
+   */
+  registeredWorkspaceIds: readonly string[] = [],
+): InitPlan {
   const skills: PlannedSkill[] = [];
   const collisions: string[] = [];
   const seen = new Set<string>();
@@ -190,6 +205,20 @@ export function planInit(packages: SkillPackage[], cwd: string): InitPlan {
   for (const skill of declared) {
     for (const capability of skill.ceiling) {
       if (isLiveByDefault(capability)) continue;
+      // A routing destination is withheld but does NOT belong in this map, and the difference is not
+      // cosmetic. This map drives two things: the "WITHHELD BY DEFAULT — these can change your machine"
+      // block, and `/grants init`'s dialog. Review found a `workspace:` id reaching both — described to the
+      // operator with `tool:bash`'s rationale (routing does not change your machine, and unlike `bash` it
+      // *is* gateable), and then granted **live and persisted** on one "Yes", off a third-party package's
+      // declaration. That is the rule `grant-env.ts` states — "does not become live because a package asked
+      // for it" — honoured by the rendered file and broken by the dialog beside it: two surfaces of one
+      // command disagreeing, which is R-28's shape inside the fix for R-28.
+      //
+      // Which worktree a child starts in is not derivable from a declaration (ADR-0028), so `init` lists
+      // routing and never grants it. `routableWorkspaces` below is where these go; the definition that
+      // declared one still loses its live `agent:` id via the `needs-withheld` pass, so nothing becomes
+      // spawnable behind the operator's back either.
+      if (capability.startsWith("workspace:")) continue;
       withheldCapabilities.set(capability, [...(withheldCapabilities.get(capability) ?? []), skill.name]);
     }
   }
@@ -246,11 +275,19 @@ export function planInit(packages: SkillPackage[], cwd: string): InitPlan {
     ...(s.withheld ? { unspawnable: describe[s.withheld](s) } : {}),
   }));
 
+  // Registry ids the operator could route to, plus any a copied definition actually declares — a package
+  // naming `workspace:prod` is evidence that id matters here, and it must still be uncommented by hand.
+  const declaredWorkspaces = skills.flatMap((s) => s.ceiling.filter((c) => c.startsWith("workspace:")));
+  const routableWorkspaces = [
+    ...new Set([...registeredWorkspaceIds.map(workspaceCapability), ...declaredWorkspaces]),
+  ].sort();
+
   return {
     skills,
     collisions,
     grant,
     withheldCapabilities,
+    routableWorkspaces,
     grantEnvPath: join(cwd, ".pi", "grants.env"),
     grantEnvContent: renderGrantEnv({
       skills: grantEnvSkills,
@@ -259,6 +296,7 @@ export function planInit(packages: SkillPackage[], cwd: string): InitPlan {
       withheldDefinitions: skills.filter((s) => s.withheld === "needs-withheld").map((s) => s.name),
       crossReferences,
       cautions,
+      routableWorkspaces,
     }),
     cautions,
   };

package/src/lease-helper.ts

@@ -0,0 +1,97 @@
+/**
+ * **The lock helper: a separate program, and the parent's side of its pipes.**
+ *
+ * Split out of `workspace-lease.ts` because `test/file-size.test.ts` refused that file — at 405 lines on the
+ * ADR-0035 branch when PR #14 merged into it, and at 435 here once R-152's guards landed. Both branches take
+ * the same seam so they converge rather than diverge, and the cap has never been raised: `delegate.ts` was
+ * split at 413 the same way (rule: when a guard fails, obey it).
+ *
+ * The seam is not arbitrary. Everything here concerns the process that HOLDS the kernel lock — the source it
+ * runs, the readiness token it prints, and the parent-side handles that keep it referenced.
+ * `workspace-lease.ts` keeps the lease lifecycle that talks to it.
+ */
+
+export 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).
+//
+// **Each attempt is bounded in WALL CLOCK, not just in count (R-146).** `execFile` with no `timeout`
+// never calls back if `herdr` accepts the close and does not answer, so the retry counter never
+// decrements, `giveUp` never runs and no marker is written — the lock is held forever. That was masked
+// while the parent could not exit, because the operator saw a hung `pi` instead; measured with a `herdr`
+// that sleeps, the parent then exited in 82ms and left a silent strand, which is R-102's rejected outcome
+// reached quietly. A bound on retries is not a bound on time.
+export 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=last=>{try{if(process.env.PI_DADDY_LEASE_MARKER)writeFileSync(process.env.PI_DADDY_LEASE_MARKER,JSON.stringify({reason:last&&(last.killed||last.signal==="SIGKILL")?"herdr-close-timeout":"herdr-close-failed",herdr_tab:target.herdr_tab})+"\\n")}catch{}process.exit(0)};const close=()=>execFile("herdr",["tab","close",target.herdr_tab],{timeout:Number(process.env.PI_DADDY_LEASE_CLOSE_TIMEOUT_MS||15000),killSignal:"SIGKILL"},error=>{if(!error)return process.exit(0);if(--left<=0)return giveUp(error);setTimeout(close,1000)});close();});
+process.stdin.resume();`;
+
+/**
+ * `unref` the parent's end of one of the helper's pipes.
+ *
+ * A spawned pipe is a `net.Socket`, which has `unref`; `ChildProcess.stdin` is typed `Writable`, which does
+ * not. Hence the narrow cast. The optional call is **defensive, not load-bearing** — the holder is spawned at
+ * exactly one site with three pipes, so none of these is ever `null`, and an earlier version of this comment
+ * claimed otherwise by citing a `stdio: "ignore"` caller that does not exist.
+ *
+ * Only `stdout` and `stderr` are unref'ed. `stdin` was too, until a line-by-line reversion showed the suite
+ * stayed green without it — an unforced line inside the fix that exists to be forced, which is exactly the
+ * shape R-122 was about.
+ */
+export const unrefStream = (stream: unknown): void => {
+  (stream as { unref?: () => void } | null)?.unref?.();
+};
+
+/**
+ * The bounds on the helper's `herdr tab close` attempts live here, with the attempts they bound — moved out of
+ * `workspace-lease.ts` when the line ceiling refused it at 402 lines, once both this branch's ADR-0035 work and
+ * `main`'s R-152 guards had landed in it. Third time that guard has fired on this file and third time the
+ * answer was a seam rather than a bigger cap.
+ */
+/**
+ * **A bound that is not a bound throws, and it throws a `RangeError` (R-146, R-152).**
+ *
+ * Both ends fail, in opposite directions and both silently:
+ *
+ *  - `0` reads as "no limit" and Node agrees — `execFile` treats `timeout: 0` as *no* timeout (measured: the
+ *    callback for a 3s sleep arrives at 3004ms with no error), reinstating the unbounded hang the bound exists
+ *    to prevent. Negatives behave identically.
+ *  - anything above `2^31 - 1` truncates: `setTimeout` warns `TimeoutOverflowWarning … set to 1`, so
+ *    `Number.MAX_SAFE_INTEGER` — the plausible "effectively no limit" sentinel, given the argument about `0`
+ *    — SIGKILLs every `herdr tab close` after 1ms, before herdr can act. Measured: callback at 3ms.
+ *
+ * **Not a `GovernanceRefusal`.** It was one, carrying `WORKSPACE_LEASE_STALE`, which everywhere else in this
+ * package means *the lease went stale or was lost* — so an ADR-0034 controller switching on codes (the reason
+ * codes exist, R-103) would classify a permanent caller bug as transient and retry a call that can never
+ * succeed. A refusal is a governance outcome that gets ledgered; a bad argument is neither.
+ *
+ * Checked for read leases too, which the first version did not: it sat below the read-lease early return, so a
+ * controller smoke-testing its configuration against a read lease got a false all-clear.
+ */
+export const assertCloseBounds = (input: { herdrCloseTimeoutMs?: number; herdrCloseAttempts?: number }): void => {
+  const MAX_TIMER = 2_147_483_647;
+  for (const [name, value, ceiling] of [
+    ["herdrCloseTimeoutMs", input.herdrCloseTimeoutMs, MAX_TIMER],
+    ["herdrCloseAttempts", input.herdrCloseAttempts, Number.MAX_SAFE_INTEGER],
+  ] as const) {
+    if (value === undefined) continue;
+    if (!Number.isInteger(value) || value < 1 || value > ceiling) {
+      throw new RangeError(
+        `${name} must be a whole number between 1 and ${ceiling}, not ${String(value)}. Zero and negatives ` +
+          `are not "no limit" but no bound at all, a value past ${MAX_TIMER} truncates to 1ms, and a ` +
+          `fractional count is not a count — this bound exists so a hung herdr cannot hold the writer lock ` +
+          `forever (R-146).`,
+      );
+    }
+  }
+};

package/src/lease-record.ts

@@ -53,13 +53,18 @@ export interface WorkspaceLease {
    * Needed because a retained lease never calls `release()`, so the metadata stays `state: "active"` and
    * whoever acquires next reports `recovered: true` — blaming a crash on a known-good path.
    */
-  markRetained(reason?: string): Promise<void>;
+  /**
+   * Record that the lease is being KEPT rather than handed back, and answer what actually happened — the
+   * caller ledgers this word (R-152). It is not always `retained`: a helper that has already died makes the
+   * fact `lost`, and a lease already settled by `release()` keeps the outcome it had.
+   */
+  markRetained(reason?: string): Promise<LeaseReleaseOutcome>;
   /** Reads the give-up marker the helper leaves when it could not close a herdr writer tab. */
   readCloseFailure(): Promise<{ reason: string; herdr_tab?: string } | null>;
 }
 
 /**
- * What a release actually did. Five members rather than three, because the first version conflated facts
+ * What a release actually did. Six members rather than three, because the first version conflated facts
  * that call for different responses — and one of them is an alarm:
  *   `released`             the lock went back and THIS owner wrote its own handover;
  *   `released-unrecorded`  the lock went back and the record does not say so, so the next owner will report
@@ -77,7 +82,14 @@ export type LeaseReleaseOutcome =
   | "released-unrecorded"
   | "released-superseded"
   | "not-held"
-  | "lost";
+  | "lost"
+  /**
+   * The lease was RETAINED and is therefore already settled — `release()` after `markRetained()` answers
+   * this instead of running the clean handshake (R-146). It was previously expressible only as the
+   * `| "retained"` bolted onto two signatures, which is why `release()` could not say it and claimed
+   * `released` instead: a clean handover for a lease kept precisely because a pane would not close.
+   */
+  | "retained";
 
 export function leasePaths(leaseDir: string, root: string) {
   // Canonical root, never caller-chosen workspace ID: aliases for one worktree must contend.