pi-daddy 0.18.0 → 0.19.0

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.

package/src/ledger-events.ts

@@ -9,6 +9,24 @@ import type { ExecutorKind } from "./executor.ts";
 import type { CorrelationMetadata } from "./correlation.ts";
 import type { StructuredRefusal } from "./refusals.ts";
 
+export const WORKSPACE_ACCESSES = ["read", "write"] as const;
+export type WorkspaceAccess = typeof WORKSPACE_ACCESSES[number];
+
+export const WORKSPACE_RECOVERY_VALUES = [false, true, "unknown"] as const;
+export type WorkspaceRecovery = typeof WORKSPACE_RECOVERY_VALUES[number];
+
+export const CHILD_LIFECYCLE_STATES = ["starting", "completed", "failed"] as const;
+export type ChildLifecycleState = typeof CHILD_LIFECYCLE_STATES[number];
+
+/** The complete Node signal vocabulary accepted by a v2 child-lifecycle event. */
+export const CHILD_PROCESS_SIGNALS = [
+  "SIGABRT", "SIGALRM", "SIGBUS", "SIGCHLD", "SIGCONT", "SIGFPE", "SIGHUP", "SIGILL", "SIGINT", "SIGIO",
+  "SIGIOT", "SIGKILL", "SIGPIPE", "SIGPOLL", "SIGPROF", "SIGPWR", "SIGQUIT", "SIGSEGV", "SIGSTKFLT",
+  "SIGSTOP", "SIGSYS", "SIGTERM", "SIGTRAP", "SIGTSTP", "SIGTTIN", "SIGTTOU", "SIGUNUSED", "SIGURG",
+  "SIGUSR1", "SIGUSR2", "SIGVTALRM", "SIGWINCH", "SIGXCPU", "SIGXFSZ", "SIGBREAK", "SIGLOST", "SIGINFO",
+] as const satisfies readonly NodeJS.Signals[];
+export type ChildProcessSignal = typeof CHILD_PROCESS_SIGNALS[number];
+
 /**
  * `released` is a handover this owner performed. FOUR members were added by the 0.18.0 review pass, and
  * they were not all previously recorded the same way — `uncontended` was recorded as an *acquisition*, and
@@ -20,16 +38,11 @@ import type { StructuredRefusal } from "./refusals.ts";
  *   `uncontended` a read lease took no kernel lock at all, so counting it as an acquisition
  *              overstated how many exclusions the kernel actually performed (R-105).
  */
-export type WorkspaceLeaseOutcome =
-  | "acquired"
-  | "uncontended"
-  | "refused"
-  | "released"
-  | "released-unrecorded"
-  | "lost"
-  | "retained"
-  | "timeout"
-  | "recovered";
+export const WORKSPACE_LEASE_OUTCOMES = [
+  "acquired", "uncontended", "refused", "released", "released-unrecorded", "lost", "retained", "timeout",
+  "recovered",
+] as const;
+export type WorkspaceLeaseOutcome = typeof WORKSPACE_LEASE_OUTCOMES[number];
 
 export interface WorkspaceLeaseEvent extends LedgerEventBase {
   ledgerVersion: typeof LEDGER_VERSION;
@@ -37,10 +50,10 @@ export interface WorkspaceLeaseEvent extends LedgerEventBase {
   childId: string;
   workspaceId: string;
   root: string;
-  access: "read" | "write";
+  access: WorkspaceAccess;
   outcome: WorkspaceLeaseOutcome;
   /** `"unknown"` when the prior owner's record was unreadable — not evidence of a clean handover. */
-  recovered?: boolean | "unknown";
+  recovered?: WorkspaceRecovery;
   releaseReason?: string;
   refusal?: StructuredRefusal;
 }
@@ -49,13 +62,13 @@ export interface ChildLifecycleEvent extends LedgerEventBase {
   ledgerVersion: typeof LEDGER_VERSION;
   event: "child_lifecycle";
   childId: string;
-  state: "starting" | "completed" | "failed";
+  state: ChildLifecycleState;
   executor: ExecutorKind;
   exitCode?: number | null;
-  signal?: NodeJS.Signals | null;
-  timedOut?: boolean;
-  aborted?: boolean;
-  truncated?: boolean;
+  signal?: ChildProcessSignal | null;
+  timedOut?: true;
+  aborted?: true;
+  truncated?: true;
   reason?: string;
 }
 
@@ -69,8 +82,14 @@ export interface CheckReceiptLedgerEvent extends LedgerEventBase {
   treeSha: string;
 }
 
+export type CapabilityDecisionEvent = GrantRecord & {
+  ledgerVersion: typeof LEDGER_VERSION;
+  event: "capability_decision";
+  taskDigest: string;
+};
+
 export type RuntimeLedgerEvent =
-  | (GrantRecord & { ledgerVersion: typeof LEDGER_VERSION; event: "capability_decision" })
+  | CapabilityDecisionEvent
   | WorkspaceLeaseEvent
   | ChildLifecycleEvent
   | CheckReceiptLedgerEvent;
@@ -79,9 +98,9 @@ export function buildWorkspaceLeaseEvent(args: {
   childId: string;
   workspaceId: string;
   root: string;
-  access: "read" | "write";
+  access: WorkspaceAccess;
   outcome: WorkspaceLeaseOutcome;
-  recovered?: boolean | "unknown";
+  recovered?: WorkspaceRecovery;
   releaseReason?: string;
   refusal?: StructuredRefusal;
   correlation?: CorrelationMetadata;
@@ -107,12 +126,37 @@ export function buildWorkspaceLeaseEvent(args: {
   };
 }
 
+export function buildCheckReceiptLedgerEvent(args: {
+  childId: string;
+  receiptId: string;
+  workspaceId: string;
+  checkId: string;
+  treeSha: string;
+  correlation?: CorrelationMetadata;
+  now: Date;
+}): CheckReceiptLedgerEvent {
+  if (!/^[a-f0-9]{64}$/i.test(args.receiptId)) {
+    throw new TypeError("receiptId must be a SHA-256 hex digest");
+  }
+  return {
+    ledgerVersion: LEDGER_VERSION,
+    event: "check_receipt",
+    ts: args.now.toISOString(),
+    childId: args.childId,
+    receiptId: args.receiptId,
+    workspaceId: args.workspaceId,
+    checkId: args.checkId,
+    treeSha: args.treeSha,
+    ...(args.correlation ? { correlation: structuredClone(args.correlation) } : {}),
+  };
+}
+
 export function buildChildLifecycleEvent(args: {
   childId: string;
-  state: "starting" | "completed" | "failed";
+  state: ChildLifecycleState;
   executor: ExecutorKind;
   exitCode?: number | null;
-  signal?: NodeJS.Signals | null;
+  signal?: ChildProcessSignal | null;
   timedOut?: boolean;
   aborted?: boolean;
   truncated?: boolean;

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,7 +27,9 @@
 
 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";
 
 export const ENV_GRANT = "PI_GRANTS_GRANT";
 /**
@@ -246,11 +248,30 @@ 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]: inheritable.join(","),
+    [ENV_GRANT]: (assertCapabilitiesArePropagatable(inheritable), inheritable.join(",")),
     [ENV_DEPTH]: String(input.depth + 1),
     [ENV_MAX_DEPTH]: String(input.maxDepth),
   };

package/src/refusals.ts

@@ -1,5 +1,6 @@
 export const REFUSAL_CODES = [
   "CAPABILITY_ESCALATION",
+  "GRANT_ID_MALFORMED",
   "DEFINITION_NOT_AUTHORIZED",
   "UNDECLARED_TOOLS",
   "UNKNOWN_TOOL",
@@ -27,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

@@ -62,6 +62,7 @@ export function expandSubsumed(grant: Capability[]): Capability[] {
 }
 
 import { WILDCARD } from "./pi-tools.ts";
+import { isWellFormedCapability } from "./capabilities.ts";
 
 /**
  * "Any definition" — ADR-0023, and one of two wildcards this module understands.
@@ -75,6 +76,16 @@ import { WILDCARD } from "./pi-tools.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. */
@@ -124,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
@@ -149,8 +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 =>
-    parent.has(c) || anyCapability || (anyDefinition && c.startsWith("agent:"));
+    isWellFormedCapability(c)
+    && (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 ?? []);
@@ -193,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).`,
+  };
+}