pi-daddy 0.28.0 → 0.32.1

package/dist/kernel/resolve.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Grant resolution — the entire security surface of capability governance, as a pure function.
+ *
+ * The invariant (ADR-0008): a capability set may only ever SHRINK as it passes down a delegation
+ * tree. Escalation is impossible by construction rather than by policy, because a parent can never
+ * confer what it does not itself hold.
+ *
+ *   effective = ( requested ∩ parentGrant ∩ ceiling ) \ (gated \ approved)
+ *
+ * Being pure — no I/O, no model, no network — this is exhaustively testable, which matters because it
+ * is the only place an escalation could be introduced.
+ */
+/** `tool:read` · `ext:pi-web-access/web_search` · `skill:review` · `agent:researcher` */
+export type Capability = string;
+/**
+ * Capabilities that transitively confer everything else. Granting one is equivalent to granting the
+ * whole catalog, so they can never be a *narrowing* grant.
+ *
+ * `ext:pi-fabric/fabric_exec` is here on measured evidence, not suspicion: a child granted
+ * `tools: []` (nothing at all) plus `recursive: true` still reached `pi.write` and `pi.bash` and
+ * spawned a grandchild that wrote to disk. See probe `pi-fabric-eval` (probes 2, 4, 7, 8).
+ */
+export declare const UNIVERSAL_CAPABILITIES: readonly Capability[];
+/**
+ * Capabilities that functionally contain others.
+ *
+ * `bash` can run `grep`, `find`, `ls`, `cat`, and `sed` — so a session holding it can already do
+ * everything the file and search tools do, whatever the tool list says. Modelling this explicitly serves
+ * two purposes:
+ *
+ *  1. It removes false escalation reports. pi's *default* surface is only `read`, `bash`, `edit`, `write`
+ *     (measured, not assumed), so an agent type declaring `tools: read, grep, find, ls` would otherwise
+ *     look like an escalation from any normal parent — despite being strictly weaker.
+ *  2. It makes the uncomfortable truth visible rather than implied: **a grant containing `bash` is not a
+ *     narrow grant.** `subsumedBy` in the result says so, so a reviewer can see what the grant really means.
+ */
+export declare const SUBSUMPTION: Readonly<Record<Capability, readonly Capability[]>>;
+/** Expand a grant to everything it functionally confers. */
+export declare function expandSubsumed(grant: Capability[]): Capability[];
+/**
+ * "Any definition" — ADR-0023, and one of two wildcards this module understands.
+ *
+ * Declared here rather than beside `WILDCARD` because `pi-tools.ts` imports `Capability` from this module.
+ * That import is `import type`, so it is erased and the runtime dependency runs one way only — which is
+ * what makes importing `WILDCARD` back safe.
+ *
+ * Deliberately weaker than `tool:*`: it confers **no tool authority**, so `agent:*,tool:read` may spawn
+ * every definition on disk and hand each of them nothing but `read`. It exists because the alternative was
+ * `tool:*` — authority to grant every tool — which made the safe configuration the laborious one.
+ */
+export declare const AGENT_WILDCARD: Capability;
+/**
+ * `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 declare const WORKSPACE_WILDCARD: Capability;
+export interface ResolveInput {
+    /** What the delegating agent asked to give the child. */
+    requested: Capability[];
+    /** What the delegating agent itself holds. The root's grant is configured, never defaulted to all. */
+    parentGrant: Capability[];
+    /** Declarative maximum for the child's agent type (its frontmatter). Omit for no ceiling. */
+    ceiling?: Capability[];
+    /** Destructive capabilities that may never enter a grant without explicit human approval. */
+    gated?: Capability[];
+    /** Gated capabilities a human has approved for this specific spawn. */
+    approved?: Capability[];
+    /**
+     * Honour functional subsumption when deciding what the parent covers (default true).
+     * Set false for a strict name-equality check.
+     */
+    subsumption?: boolean;
+}
+export interface ResolveResult {
+    /** The capability set the child may hold. */
+    effective: Capability[];
+    /** Requested but NOT held by the parent — the escalation-attempt signal. Log every one. */
+    denied: Capability[];
+    /** Held by the parent but outside the child type's declared ceiling. */
+    clipped: Capability[];
+    /** Allowed by the tree but gated and unapproved. */
+    gatedBlocked: Capability[];
+    /** Universal capabilities that survived resolution — see `assertNarrowing`. */
+    universal: Capability[];
+    /**
+     * Capabilities the parent covers only through subsumption, not by holding them directly — e.g. `grep`
+     * covered because the parent holds `bash`. Non-empty means the grant is broader than its list suggests.
+     */
+    subsumedBy: Capability[];
+}
+/**
+ * Resolve a child's grant. Total and side-effect free; every rejected capability is reported rather
+ * than silently dropped, because a grant nobody can audit proves nothing.
+ */
+export declare function resolve(input: ResolveInput): ResolveResult;
+/**
+ * Fail closed on a grant that cannot actually narrow anything.
+ *
+ * A universal capability in an "attenuated" grant is not a narrow grant with one extra item — it is
+ * full authority wearing a narrow grant's clothing. Callers must opt in explicitly rather than
+ * discover this at runtime.
+ */
+export declare function assertNarrowing(result: ResolveResult, allowUniversal?: boolean): void;
+/**
+ * Project an effective grant onto pi's `--tools` allowlist.
+ *
+ * pi core is the enforcement point — verified: `--tools` and `--no-tools` both hard-block extension
+ * tools, and an explicitly `-e`-loaded extension cannot re-add its tool past them
+ * (probe `pi-fabric-eval` probes 9–11). That is why enforcement needs no in-descendant runtime.
+ *
+ * Returns `null` when the grant contains no callable tools, meaning the caller should pass
+ * `--no-tools` rather than an empty `--tools` (an empty list is not a valid allowlist).
+ */
+export declare function toPiToolsAllowlist(effective: Capability[]): string[] | null;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/kernel/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/kernel/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,yFAAyF;AACzF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,UAAU,EAAsD,CAAC;AAE/G;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,UAAU,EAAE,CAAC,CAE3E,CAAC;AAEF,4DAA4D;AAC5D,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAMhE;AAKD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,EAAE,UAAsB,CAAC;AACpD;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,UAA0B,CAAC;AAE5D,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB,sGAAsG;IACtG,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,6FAA6F;IAC7F,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;IACvB,6FAA6F;IAC7F,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB,2FAA2F;IAC3F,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,wEAAwE;IACxE,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,oDAAoD;IACpD,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,+EAA+E;IAC/E,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB;;;OAGG;IACH,UAAU,EAAE,UAAU,EAAE,CAAC;CAC1B;AAID;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,CAoG1D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,EAAE,cAAc,UAAQ,GAAG,IAAI,CAQnF;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,UAAU,EAAE,GAAG,MAAM,EAAE,GAAG,IAAI,CAQ3E"}

package/dist/kernel/resolve.js

@@ -0,0 +1,201 @@
+/**
+ * Grant resolution — the entire security surface of capability governance, as a pure function.
+ *
+ * The invariant (ADR-0008): a capability set may only ever SHRINK as it passes down a delegation
+ * tree. Escalation is impossible by construction rather than by policy, because a parent can never
+ * confer what it does not itself hold.
+ *
+ *   effective = ( requested ∩ parentGrant ∩ ceiling ) \ (gated \ approved)
+ *
+ * Being pure — no I/O, no model, no network — this is exhaustively testable, which matters because it
+ * is the only place an escalation could be introduced.
+ */
+/**
+ * Capabilities that transitively confer everything else. Granting one is equivalent to granting the
+ * whole catalog, so they can never be a *narrowing* grant.
+ *
+ * `ext:pi-fabric/fabric_exec` is here on measured evidence, not suspicion: a child granted
+ * `tools: []` (nothing at all) plus `recursive: true` still reached `pi.write` and `pi.bash` and
+ * spawned a grandchild that wrote to disk. See probe `pi-fabric-eval` (probes 2, 4, 7, 8).
+ */
+export const UNIVERSAL_CAPABILITIES = ["ext:pi-fabric/fabric_exec", "tool:fabric_exec"];
+/**
+ * Capabilities that functionally contain others.
+ *
+ * `bash` can run `grep`, `find`, `ls`, `cat`, and `sed` — so a session holding it can already do
+ * everything the file and search tools do, whatever the tool list says. Modelling this explicitly serves
+ * two purposes:
+ *
+ *  1. It removes false escalation reports. pi's *default* surface is only `read`, `bash`, `edit`, `write`
+ *     (measured, not assumed), so an agent type declaring `tools: read, grep, find, ls` would otherwise
+ *     look like an escalation from any normal parent — despite being strictly weaker.
+ *  2. It makes the uncomfortable truth visible rather than implied: **a grant containing `bash` is not a
+ *     narrow grant.** `subsumedBy` in the result says so, so a reviewer can see what the grant really means.
+ */
+export const SUBSUMPTION = {
+    "tool:bash": ["tool:grep", "tool:find", "tool:ls", "tool:read", "tool:write", "tool:edit", "tool:edit-diff"],
+};
+/** Expand a grant to everything it functionally confers. */
+export function expandSubsumed(grant) {
+    const expanded = new Set(grant);
+    for (const held of grant) {
+        for (const implied of SUBSUMPTION[held] ?? [])
+            expanded.add(implied);
+    }
+    return [...expanded].sort();
+}
+import { WILDCARD } from "./pi-tools.js";
+import { isWellFormedCapability } from "./capabilities.js";
+/**
+ * "Any definition" — ADR-0023, and one of two wildcards this module understands.
+ *
+ * Declared here rather than beside `WILDCARD` because `pi-tools.ts` imports `Capability` from this module.
+ * That import is `import type`, so it is erased and the runtime dependency runs one way only — which is
+ * what makes importing `WILDCARD` back safe.
+ *
+ * Deliberately weaker than `tool:*`: it confers **no tool authority**, so `agent:*,tool:read` may spawn
+ * every definition on disk and hand each of them nothing but `read`. It exists because the alternative was
+ * `tool:*` — authority to grant every tool — which made the safe configuration the laborious one.
+ */
+export const AGENT_WILDCARD = "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 = "workspace:*";
+const unique = (xs) => [...new Set(xs)].sort();
+/**
+ * Resolve a child's grant. Total and side-effect free; every rejected capability is reported rather
+ * than silently dropped, because a grant nobody can audit proves nothing.
+ */
+export function resolve(input) {
+    const requested = unique(input.requested);
+    const held = new Set(input.parentGrant);
+    const parent = input.subsumption === false ? held : new Set(expandSubsumed(input.parentGrant));
+    /**
+     * `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
+     * it. Definitions are not tools, so nothing enumerates them — which is why `maySpawnDefinition` had to
+     * special-case the wildcard, and why this needs stating rather than falling out.
+     *
+     * Scoped to one namespace on purpose. There is no generalised `<ns>:*` rule, so a namespace added later
+     * does not silently acquire a wildcard; adding one is a deliberate edit and another decision.
+     */
+    const anyDefinition = held.has(AGENT_WILDCARD);
+    /**
+     * `tool:*` satisfies **any** capability, including `skill:` and `agent:` ids.
+     *
+     * Missing until 0.11.2, and the omission broke the one rule this package must never break by accident:
+     * *governance is opt-in*. An ungoverned session holds `[tool:*, …observed tools]` and nothing else, so
+     * spawning a definition whose `allowed-tools` names `agent:worker` or `skill:review` — the composition
+     * ADR-0017 created and ADR-0023's own example uses — was refused with **"capability escalation
+     * blocked"**, and recorded as an escalation attempt, in a session that had opted out.
+     *
+     * `maySpawnDefinition` had always honoured `tool:*` for definition ids and the README had always
+     * claimed it "satisfies any capability". This function disagreed with both, which is R-28's shape: two
+     * 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) => 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 ?? []);
+    // Order is irrelevant to the outcome (set intersection is commutative), so each rejection reason is
+    // reported independently rather than being masked by whichever filter happened to run first.
+    const denied = requested.filter((c) => !covered(c));
+    const clipped = requested.filter((c) => covered(c) && ceiling !== null && !ceiling.has(c));
+    /**
+     * Is this capability gated, directly or by subsuming something gated?
+     *
+     * ADR-0012. Exact-name gating was defeatable by handing down a broader capability: the package's own
+     * `SUBSUMPTION` table says `bash` confers `write`, so gating `write` produced **no prompt** when `bash`
+     * was granted instead. The gate read as satisfied because the string never appeared.
+     *
+     * The direction is load-bearing and easy to invert. A capability is gated when it **subsumes**
+     * something gated — never when it **is subsumed by** something gated. Gating `bash` must not quietly
+     * gate a plain `write` grant, which would make gating a broad capability restrict the narrow ones and
+     * invert least privilege.
+     */
+    const isGated = (c) => {
+        if (gated.has(c))
+            return true;
+        if (input.subsumption === false)
+            return false;
+        return (SUBSUMPTION[c] ?? []).some((implied) => gated.has(implied));
+    };
+    const gatedBlocked = requested.filter((c) => covered(c) && (ceiling === null || ceiling.has(c)) && isGated(c) && !approved.has(c));
+    const rejected = new Set([...denied, ...clipped, ...gatedBlocked]);
+    const effective = requested.filter((c) => !rejected.has(c));
+    return {
+        effective,
+        denied,
+        clipped,
+        gatedBlocked,
+        universal: effective.filter((c) => UNIVERSAL_CAPABILITIES.includes(c)),
+        // 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.
+        //
+        // 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:"))),
+    };
+}
+/**
+ * Fail closed on a grant that cannot actually narrow anything.
+ *
+ * A universal capability in an "attenuated" grant is not a narrow grant with one extra item — it is
+ * full authority wearing a narrow grant's clothing. Callers must opt in explicitly rather than
+ * discover this at runtime.
+ */
+export function assertNarrowing(result, allowUniversal = false) {
+    if (!allowUniversal && result.universal.length > 0) {
+        throw new Error(`refusing to issue a grant containing universal capabilities: ${result.universal.join(", ")}. ` +
+            `These transitively confer the whole catalog, so the grant would not narrow anything. ` +
+            `Pass allowUniversal to override deliberately.`);
+    }
+}
+/**
+ * Project an effective grant onto pi's `--tools` allowlist.
+ *
+ * pi core is the enforcement point — verified: `--tools` and `--no-tools` both hard-block extension
+ * tools, and an explicitly `-e`-loaded extension cannot re-add its tool past them
+ * (probe `pi-fabric-eval` probes 9–11). That is why enforcement needs no in-descendant runtime.
+ *
+ * Returns `null` when the grant contains no callable tools, meaning the caller should pass
+ * `--no-tools` rather than an empty `--tools` (an empty list is not a valid allowlist).
+ */
+export function toPiToolsAllowlist(effective) {
+    const names = effective
+        .filter((c) => c.startsWith("tool:") || c.startsWith("ext:"))
+        // `tool:read` -> `read`; `ext:pkg/web_search` -> `web_search` (pi matches on bare tool name)
+        .map((c) => (c.startsWith("tool:") ? c.slice(5) : c.slice(c.lastIndexOf("/") + 1)))
+        .filter((n) => n.length > 0);
+    const deduped = [...new Set(names)].sort();
+    return deduped.length > 0 ? deduped : null;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/kernel/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/kernel/resolve.ts"],"names":[],"mappings":"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"}

package/dist/kernel/routing-authority.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 { type Capability } from "./resolve.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 probe `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 declare function checkRoutingAuthority(boundWorkspaceId: string | undefined, ownGrant: readonly Capability[]): RoutingRefusal | null;
+/**
+ * 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 declare function checkWorkspaceWildcardRequest(requested: readonly Capability[], ownGrant: readonly Capability[]): RoutingRefusal | null;
+//# sourceMappingURL=routing-authority.d.ts.map

package/dist/kernel/routing-authority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-authority.d.ts","sourceRoot":"","sources":["../../src/kernel/routing-authority.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAEnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,QAAQ,EAAE,SAAS,UAAU,EAAE,GAC9B,cAAc,GAAG,IAAI,CA6BvB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,SAAS,UAAU,EAAE,EAChC,QAAQ,EAAE,SAAS,UAAU,EAAE,GAC9B,cAAc,GAAG,IAAI,CAUvB"}

package/dist/kernel/routing-authority.js

@@ -0,0 +1,100 @@
+/**
+ * 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.js";
+import { WORKSPACE_WILDCARD } from "./resolve.js";
+import { WILDCARD } from "./pi-tools.js";
+/**
+ * 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 probe `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, ownGrant) {
+    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, ownGrant) {
+    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).`,
+    };
+}
+//# sourceMappingURL=routing-authority.js.map

package/dist/kernel/routing-authority.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-authority.js","sourceRoot":"","sources":["../../src/kernel/routing-authority.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAChG,OAAO,EAAE,kBAAkB,EAAmB,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAgBzC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,qBAAqB,CACnC,gBAAoC,EACpC,QAA+B;IAE/B,IAAI,gBAAgB,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAChD,MAAM,WAAW,GAAG,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;IAC1D,IAAI,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACzC,OAAO;YACL,IAAI,EAAE,oBAAoB;YAC1B,MAAM,EACJ,gBAAgB,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,+CAA+C;gBAC/F,UAAU,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,8DAA8D;gBACnG,mGAAmG;SACtG,CAAC;IACJ,CAAC;IACD,IAAI,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,CAAC;QAAE,OAAO,IAAI,CAAC;IACjE,8FAA8F;IAC9F,oFAAoF;IACpF,MAAM,IAAI,GAAG,QAAQ;SAClB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;SAC5F,IAAI,EAAE,CAAC;IACV,OAAO;QACL,IAAI,EAAE,0BAA0B;QAChC,sGAAsG;QACtG,kFAAkF;QAClF,MAAM,EAAE,CAAC,WAAW,CAAC;QACrB,MAAM,EACJ,sCAAsC,gBAAgB,kCAAkC,WAAW,IAAI;YACvG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;gBACd,CAAC,CAAC,oBAAoB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBACxC,CAAC,CAAC,4CAA4C,WAAW,kCAAkC,CAAC;KACjG,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,6BAA6B,CAC3C,SAAgC,EAChC,QAA+B;IAE/B,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,kBAAkB,CAAC;QAAE,OAAO,IAAI,CAAC;IACzD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IACxF,OAAO;QACL,IAAI,EAAE,oBAAoB;QAC1B,MAAM,EACJ,gBAAgB,kBAAkB,kEAAkE;YACpG,oGAAoG;YACpG,mFAAmF;KACtF,CAAC;AACJ,CAAC"}

package/dist/kernel/run-child.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Run a governed child process under hard limits.
+ *
+ * G8 (review findings A-R1/B-I5, A-R3). `delegate` used to spawn `pi` with no output cap, no timeout,
+ * an abort listener attached too late to observe an already-aborted signal, and a non-zero exit reported
+ * to the model as an ordinary result. Each of those is a way for a child to outlive or overwhelm the
+ * orchestrator that is supposed to be governing it — which is the whole premise of this package.
+ *
+ * It lives here, out of `extensions/grants.ts`, so it can be tested against real processes without pi.
+ */
+export { ENV_CHILD_IDLE_TIMEOUT, ENV_CHILD_TIMEOUT } from "./env-names.ts";
+/**
+ * The longest prefix of `text` that fits in `budget` BYTES, never splitting a character.
+ *
+ * Both halves matter. Truncating by `String.prototype.slice` counts UTF-16 code units against a byte budget,
+ * which overruns by the encoding width of whatever the child printed. Truncating the *buffer* instead would
+ * respect the budget and split a multi-byte character or a surrogate pair, putting a lone `\ud83d` in the
+ * result. So the walk is by code POINT (`for…of` iterates code points, keeping surrogate pairs whole) and the
+ * budget is checked in bytes before each one is admitted.
+ *
+ * Exported for the test that feeds it CJK and emoji: an ASCII-only test cannot fail on any of this, which is
+ * exactly why the original defect survived a test named for it.
+ */
+export declare function takeBytes(text: string, budget: number): string;
+/**
+ * Operator override for the child wall-clock limit, in seconds.
+ *
+ * Deliberately NOT in `GRANT_ENV_KEYS`: those are stripped from a child's environment and re-supplied
+ * only by the spawn plan, which is right for capability state and wrong for an operator preference. This
+ * one should simply inherit, so a bound set at the root applies all the way down.
+ */
+/** Read the override, falling back to the default on absent *or* malformed input (G7's rule). */
+export declare function timeoutFromEnv(raw: string | undefined): number;
+/** The inactivity bound, same rule: absent, malformed and zero all select the default rather than disabling it. */
+export declare function idleTimeoutFromEnv(raw: string | undefined): number;
+export interface ChildRunRequest {
+    command: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    signal?: AbortSignal;
+    /** Hard cap on captured output. Beyond it the child is killed and the result flagged. */
+    maxOutputBytes?: number;
+    /** Wall-clock ceiling. On expiry: SIGTERM, then SIGKILL after `killGraceMs`. A runaway bound, not the working bound. */
+    timeoutMs?: number;
+    killGraceMs?: number;
+    /**
+     * Inactivity bound (ADR-0038 note, PR 3e): the child is stopped when this long passes with no activity. Activity
+     * is any stdout/stderr byte, or a change in what `activityProbe` returns. Undefined means no inactivity bound.
+     */
+    idleTimeoutMs?: number;
+    /**
+     * A cheap marker of the child's progress that is not on its stdout, polled every `activityProbeIntervalMs`: the
+     * size and mtime of its pi session file, which pi appends to on every message and tool result. A change resets
+     * the inactivity clock; `undefined` (file not there yet) counts as no change. Never awaited on the control path.
+     */
+    activityProbe?: () => Promise<string | number | undefined> | string | number | undefined;
+    activityProbeIntervalMs?: number;
+    /** Absolute epoch-millisecond hard cap: SIGKILL fires here even when the SIGTERM grace has not elapsed. */
+    hardDeadlineAt?: number;
+    /**
+     * Called with each chunk as it arrives, for the parent's progress display (ADR-0032).
+     *
+     * **Display only, and the distinction is load-bearing.** The child's answer is still `text`, assembled here
+     * and returned; a caller must never treat what it saw streamed as the result. A partial stream that could be
+     * mistaken for a complete answer is R-03's defect — a missing result indistinguishable from an empty one —
+     * with a new cause.
+     *
+     * Bounded by the same `maxOutputBytes` as `text`, so the cap governs the transcript and not merely memory.
+     *
+     * Exceptions are swallowed: a renderer is not a governance control, and one that throws must not kill a
+     * governed child mid-task.
+     */
+    onOutput?: (chunk: string) => void;
+    /** Optional raw observation; isolated from control, never awaited, separate from display text. */
+    onObservation?: (stream: "stdout" | "stderr", bytes: Uint8Array) => void;
+    /** Passive EOF observation. Never a replacement child/settlement handle. Exceptions are isolated. */
+    onStreamEnd?: (stream: "stdout" | "stderr") => void;
+    /** Security hook called immediately after spawn, before output handling (for lease attachment). */
+    onSpawn?: (pid: number) => void;
+}
+export interface ChildRunResult {
+    /** Exit code, or `null` when nothing was spawned or the child was killed by a signal. */
+    code: number | null;
+    text: string;
+    truncated: boolean;
+    timedOut: boolean;
+    /** Set with `timedOut` when it was the inactivity bound, not the wall-clock ceiling, that stopped the child. */
+    idle?: true;
+    aborted: boolean;
+    /** Signal that ended the process, separate from the nullable numeric exit code. */
+    signal?: NodeJS.Signals | null;
+    /** Set when the process could not be started at all. */
+    spawnError?: string;
+}
+/** 1 MiB. A delegation returns a summary; anything larger is a runaway, not an answer. */
+export declare const DEFAULT_MAX_OUTPUT_BYTES: number;
+/**
+ * Six hours (PR 3e, 2026-09-22). No longer the working bound: `DEFAULT_IDLE_TIMEOUT_MS` is what stops a hung child.
+ * This is the runaway ceiling for a child that keeps producing events forever, and it exists so that no typo in the
+ * inactivity variable can make a child unbounded. The history: ten minutes, twenty (ADR-0038), sixty (its note), each
+ * time because a working child was cut off by a wall clock that cannot tell working from hung.
+ */
+export declare const DEFAULT_TIMEOUT_MS: number;
+/** Fifteen minutes with no stdout byte and no session-file change. A hung child is a silent one; a build is not. */
+export declare const DEFAULT_IDLE_TIMEOUT_MS: number;
+export declare const DEFAULT_ACTIVITY_PROBE_INTERVAL_MS = 2000;
+/** Grace between SIGTERM and SIGKILL. A child that ignores SIGTERM must not make the timeout advisory. */
+export declare const DEFAULT_KILL_GRACE_MS = 5000;
+export declare function runChild(request: ChildRunRequest): Promise<ChildRunResult>;
+//# sourceMappingURL=run-child.d.ts.map

package/dist/kernel/run-child.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-child.d.ts","sourceRoot":"","sources":["../../src/kernel/run-child.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAa3E;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAY9D;AAED;;;;;;GAMG;AAEH,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAK9D;AAED,mHAAmH;AACnH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGlE;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yFAAyF;IACzF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wHAAwH;IACxH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACzF,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,2GAA2G;IAC3G,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,kGAAkG;IAClG,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAAE,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACzE,qGAAqG;IACrG,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,KAAK,IAAI,CAAC;IACpD,mGAAmG;IACnG,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,yFAAyF;IACzF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,gHAAgH;IAChH,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IAC/B,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,0FAA0F;AAC1F,eAAO,MAAM,wBAAwB,QAAc,CAAC;AACpD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAAqB,CAAC;AACrD,oHAAoH;AACpH,eAAO,MAAM,uBAAuB,QAAiB,CAAC;AACtD,eAAO,MAAM,kCAAkC,OAAO,CAAC;AACvD,0GAA0G;AAC1G,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAwQ1E"}