pi-daddy 0.27.4 → 0.32.0

package/src/fanout.ts

@@ -1,106 +0,0 @@
-/**
- * Bounded synchronous fan-out — ADR-0015's option A′, and the cardinality bound ADR-0008 never had.
- *
- * **The gap this closes.** ADR-0008 bounds what each child may *hold* and says nothing about how many
- * children exist. `resolve()` is a set operation; nowhere in `src/` was there a count. Blocking `delegate`
- * bounded cardinality to one *by accident of being blocking*, so the invariant was never tested. Fan-out
- * removes that accident: with `maxDepth: 2` and five children per call, five delegators each spawning five
- * is thirty concurrent model sessions — **every ledger line individually correct and narrow, the aggregate
- * a machine DoS and an uncapped bill.** The critic's verdict on this was that silence is itself a finding.
- *
- * **Why a budget rather than a per-call limit.** A per-call cap of K with depth D still permits K^D
- * descendants, which is the same exponential wearing a smaller number. A *budget* is subtractive and
- * therefore total: a session holding budget B may create at most B descendants in its whole subtree,
- * because it spends from B to spawn and hands each child a share of what is left. That composes across
- * process boundaries with **no shared state** — the same property that makes depth work — so it needs no
- * registry, no lock and no counter file.
- *
- * It is deliberately NOT a concurrency limit. How many run at once is a resource question for the executor;
- * how many may exist at all is a governance question, and this is the governance answer.
- */
-
-import { parseBound } from "./propagation.ts";
-
-/** Total descendants a session may create across its entire subtree, when nothing is configured. */
-export const DEFAULT_FANOUT_BUDGET = 8;
-
-/**
- * Hard ceiling on children in a single call, independent of budget.
- *
- * A budget alone would let one call spend all of it at once, and a hundred simultaneous `pi` processes is
- * a different failure from a hundred spread over a session. This is the blast-radius bound; the budget is
- * the total bound. Both are needed because they answer different questions.
- */
-export const MAX_CHILDREN_PER_CALL = 8;
-
-/**
- * Steps a single `delegate_chain` may contain — ADR-0033.
- *
- * **Derived from `MAX_CHILDREN_PER_CALL` so the two cannot drift.** A chain is not concurrent, so the blast-radius
- * argument for that constant does not apply directly; what does apply is that one tool call should not be able to
- * create an unbounded number of descendants, and eight is already a long pipeline. Sharing the number also means an
- * operator learns one bound rather than two.
- */
-export const MAX_CHAIN_STEPS = MAX_CHILDREN_PER_CALL;
-
-/** Read the budget from the environment, failing to the default on absent *or* malformed input. */
-export function budgetFromEnv(raw: string | undefined): number {
-  const parsed = parseBound(raw);
-  // Malformed and zero both fall back rather than disabling fan-out silently — G7's rule. A budget that a
-  // typo can switch off is the A-S4 defect wearing different clothes. To genuinely forbid delegation an
-  // operator sets `maxDepth: 0`, which says what it means.
-  return parsed === undefined || parsed === null || parsed === 0 ? DEFAULT_FANOUT_BUDGET : parsed;
-}
-
-export interface BudgetSplit {
-  ok: boolean;
-  reason?: string;
-  /** Budget each child receives. */
-  perChild: number;
-}
-
-/**
- * Spend `count` from a budget and divide the remainder among the children.
- *
- * The parent pays one unit per child it creates *before* sharing what is left, so a subtree can never
- * exceed the budget it started with: spawning is itself an expenditure, not a free act that only its
- * descendants pay for. `Math.floor` on the division means rounding always loses budget rather than
- * inventing it — the safe direction, and the reason a deep tree converges to zero instead of oscillating.
- */
-export function splitBudget(budget: number, count: number): BudgetSplit {
-  if (count <= 0) return { ok: false, reason: "a fan-out needs at least one child", perChild: 0 };
-  if (count > MAX_CHILDREN_PER_CALL) {
-    return {
-      ok: false,
-      reason: `${count} children exceeds the per-call limit of ${MAX_CHILDREN_PER_CALL}`,
-      perChild: 0,
-    };
-  }
-  if (budget < count) {
-    return {
-      ok: false,
-      reason:
-        `fan-out budget exhausted: ${count} children requested, ${budget} remaining in this subtree ` +
-        `(raise PI_GRANTS_FANOUT at the root, or delegate fewer at a time)`,
-      perChild: 0,
-    };
-  }
-  return { ok: true, perChild: Math.floor((budget - count) / count) };
-}
-
-/**
- * A ledger id that distinguishes siblings.
- *
- * **Review finding F8.** Every child was recorded as `delegate@d1`, so four concurrent children produced
- * four lines identical except `ts` — and two landing in the same millisecond were indistinguishable.
- * ADR-0008 names `parent_id`/`child_id` as the correlation keys, but they were depth *labels* wearing id
- * names, which made the ledger unjoinable to the returned result, to the OS process, or to the child's own
- * lines one level down.
- *
- * The id is hierarchical and derived, not random: a child of `d0` is `d0.1`, its own second child `d0.1.2`.
- * That means a line's ancestry is readable from the id alone with no join at all, and it is reproducible —
- * two runs of the same fan-out produce the same ids, which is what makes a ledger diffable.
- */
-export function childSpawnId(parentId: string, index: number): string {
-  return `${parentId}.${index + 1}`;
-}

package/src/file-lock.ts

@@ -1,178 +0,0 @@
-/**
- * One cross-process file lock, shared by producer ledgers and the approvals store.
- *
- * **Extracted rather than copied (R-49).** The ledger has had this lock since fan-out made a second writer
- * possible; the approvals store had an unlocked read-modify-write, so session 1 could load, session 2 could
- * revoke, and session 1's next save would **restore the revoked entry** — falsifying a property
- * `approval-store.ts` documents in so many words. The mitigation already existed twenty lines away. A
- * second implementation is how a fix comes to contain a smaller copy of the bug it fixed, which has happened
- * twice in this package (R-38's preview, ADR-0022's republish path), so there is exactly one of these.
- *
- * **The two callers want opposite failure behaviour, and that is the caller's decision, not this module's.**
- * A ledger write that cannot take the lock must fail the delegation closed — a child running with granted
- * capabilities and no audit line is the thing the ledger exists to prevent. An approvals write that cannot
- * take the lock must NOT fail the work: the human already said yes, and the store is a convenience cache
- * (ADR-0020). So this throws `LockTimeoutError`, distinguishable from every other failure, and each caller
- * decides what that means.
- */
-
-import { open, readFile, rm, stat } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
-
-/** How long to wait for another writer to finish before giving up. Short: failing closed beats hanging. */
-export const LOCK_TIMEOUT_MS = 2000;
-/** A lock older than this is treated as abandoned by a killed process and broken. */
-export const STALE_LOCK_MS = 10_000;
-
-/**
- * Raised only when the wait ran out. Its own type so a caller can tell "somebody else is writing" from
- * "this filesystem rejected the write", which want different messages and, for the approvals store,
- * different outcomes.
- */
-export class LockTimeoutError extends Error {
-  constructor(label: string) {
-    super(`${label} is locked by another writer (waited ${LOCK_TIMEOUT_MS}ms)`);
-    this.name = "LockTimeoutError";
-  }
-}
-
-export interface FileLockOptions { readonly staleRecovery?: "age" | "disabled" }
-function lockPolicy(options: FileLockOptions | undefined): "age" | "disabled" {
-  if (options === undefined) return "age";
-  const invalid = (): never => { throw new TypeError("invalid file lock options"); };
-  if (options === null || typeof options !== "object" || Array.isArray(options) ||
-      ![Object.prototype, null].includes(Object.getPrototypeOf(options))) return invalid();
-  const keys = Reflect.ownKeys(options);
-  if (keys.some(key => key !== "staleRecovery")) return invalid();
-  if (!keys.length) return "age";
-  const field = Object.getOwnPropertyDescriptor(options, "staleRecovery")!;
-  if (!Object.hasOwn(field, "value") || !field.enumerable || !["age", "disabled"].includes(field.value)) return invalid();
-  return field.value;
-}
-
-/**
- * Run `work` while holding an exclusive lock beside `path`.
- * Explicit disabled recovery never reclaims by age/liveness. V4 selects it internally; an orphan
- * requires separately authorized quiescent recovery, not a timer or automatic operator action.
- * The age-based behavior described below remains the default for legacy callers.
- *
- * **Why a lock at all.** `O_APPEND` is atomic for one write to a regular file on a POSIX filesystem, and the
- * guarantee does **not** hold on drvfs (`/mnt/c` under WSL2) or NFS — which is exactly where this project
- * runs. The approvals store never had the guarantee anyway: read-modify-write is not one write.
- *
- * **A lock introduces its own failure mode and it is handled deliberately.** A process killed while holding
- * the lock would otherwise block every future write forever, so a lock older than `STALE_LOCK_MS` is broken.
- * Every delete proves ownership first (`removeIfOurs`) — see the token comment in the loop for the two
- * mutual-exclusion breaks that came from not doing so, both reproduced across real OS processes.
- *
- * **What staleness actually measures, stated because it is not what it sounds like.** `STALE_LOCK_MS`
- * compares the lock's mtime to now; it never checks whether the owner is alive. So *any* 10s stall of the
- * holder hands the lock on — a `SIGSTOP`, a laptop suspend, swap thrash, a debugger breakpoint, a long GC
- * pause. Measured on this project's own filesystems, no realistic `work()` comes near it: one ledger append
- * is 0.1ms on ext4 and 21ms on drvfs, and a 10,000-entry `saveApproval` is 30ms / 97ms. Sixteen-way
- * contention raises *waiters'* time, never the holder's — max hold measured at 49ms. So the threshold is
- * two orders of magnitude clear of normal operation and is not guarded against abnormal suspension.
- *
- * The timeout is short *on purpose*: work refused because a file was busy is recoverable and loud, while
- * work that hangs waiting for a lock is neither.
- */
-export async function withFileLock<T>(path: string, label: string, work: () => Promise<T>, options?: FileLockOptions): Promise<T> {
-  const staleRecovery = lockPolicy(options); // Detached once, before I/O or any wait.
-  const lockPath = `${path}.lock`;
-  const deadline = Date.now() + LOCK_TIMEOUT_MS;
-
-  for (;;) {
-    // **A token, and the reason mutual exclusion depends on it (R-67).** `rm(path)` deletes whatever is at
-    // the path *now*, not the lock this process created — so the previous version broke its own invariant
-    // two ways, both reproduced across real OS processes:
-    //
-    //  - the stale-break `stat` and `rm` are two awaits, so a process descheduled between them could delete
-    //    a LIVE lock another waiter had just created, and then succeed at its own create: two holders;
-    //  - worse, the `finally` removed the lock unconditionally. A holder whose lock had been broken out
-    //    from under it still freed the NEW owner's lock on the way out — and the damage then propagated to
-    //    processes that raced nothing and observed nothing wrong, which is how one break became a chain.
-    //
-    // Writing a unique token and re-reading it before every delete makes both inexpressible: this process
-    // only ever removes a file it can prove is its own. The docstring used to claim "whichever wins the
-    // exclusive create proceeds, which is correct because only one can" — true of the create and false of
-    // the delete, which is what made it convincing.
-    const token = `${process.pid}:${randomUUID()}`;
-    let handle: Awaited<ReturnType<typeof open>> | undefined;
-    try {
-      handle = await open(lockPath, "wx");
-      await handle.writeFile(`${token}\n`, "utf8");
-    } catch (error) {
-      // The handle may exist even though the WRITE failed (ENOSPC, EDQUOT, EFBIG). The old code jumped
-      // straight here and rethrew, so the already-created lock file was left on disk and its descriptor
-      // leaked to GC — an orphan that blocks every writer for a full STALE_LOCK_MS and feeds the EMFILE
-      // path below. Close and remove before doing anything else; `ours` is safe because we just made it.
-      if (handle) {
-        await handle.close().catch(() => undefined);
-        await removeIfOurs(lockPath, token);
-        handle = undefined;
-      }
-      const code = (error as { code?: string }).code;
-      if (code !== "EEXIST") throw error;
-
-      // Someone else holds it. Break it only if it is old enough to be abandoned — and only the exact file
-      // we judged, so a lock created in the gap survives.
-      if (staleRecovery === "age") try {
-        const held = await stat(lockPath);
-        if (Date.now() - held.mtimeMs > STALE_LOCK_MS) {
-          const abandoned = await readFile(lockPath, "utf8").catch(() => undefined);
-          if (abandoned !== undefined) await removeIfOurs(lockPath, abandoned.trim());
-        }
-      } catch {
-        /* it vanished between the check and the stat — the next attempt will simply take it */
-      }
-
-      if (Date.now() >= deadline) throw new LockTimeoutError(label);
-      await new Promise((r) => setTimeout(r, 25));
-      continue;
-    }
-
-    let bodyFailed = false;
-    try {
-      return await work();
-    } catch (error) { bodyFailed = true; throw error; }
-    finally {
-      if (staleRecovery === "disabled") {
-        try { await releaseDisabledLock(handle, lockPath, token); }
-        catch (error) { if (!bodyFailed) throw error; } // Preserve even a falsy primary rejection.
-      } else {
-        await handle.close().catch(() => undefined);
-        // Legacy age policy remains best effort; never remove a demonstrably different token.
-        await removeIfOurs(lockPath, token);
-      }
-    }
-  }
-}
-
-/** Disabled ownership cannot silently manufacture an indefinite orphan after a successful body.
- * Try token-checked removal even if close failed; report the first failure after both attempts.
- * Appended bytes are not rolled back, and a primary body error takes precedence at the caller. */
-async function releaseDisabledLock(handle: Awaited<ReturnType<typeof open>>, lockPath: string, token: string): Promise<void> {
-  let failure: { error: unknown } | null = null;
-  try { await handle.close(); } catch (error) { failure = { error }; }
-  try { await removeIfOurs(lockPath, token, true); }
-  catch (error) { failure ??= { error }; }
-  if (failure) throw failure.error;
-}
-
-/**
- * Delete the lock only if it still holds `token`.
- *
- * Read-then-delete is itself two operations, so this is not atomic either — but it narrows the window from
- * "the whole of `work()`" to "between a read and an unlink", and it removes the *systematic* break entirely:
- * a process can no longer delete a lock it demonstrably never owned.
- */
-async function removeIfOurs(lockPath: string, token: string, strict = false): Promise<void> {
-  try {
-    const held = await readFile(lockPath, "utf8");
-    if (held.trim() !== token) return;
-    await rm(lockPath, { force: true });
-  } catch (error) {
-    if (strict) throw error; // No ownership inference or force-delete after a failed read.
-    /* Legacy: already gone, or unreadable — this process must not force removal. */
-  }
-}

package/src/finalization.ts

@@ -1,79 +0,0 @@
-interface Finalizer {
-  label: string;
-  run: () => void | Promise<void>;
-}
-
-const FINALIZER_ERRORS = Symbol("pi-daddy.finalizer-errors");
-
-type ErrorWithFinalizers = Error & { [FINALIZER_ERRORS]?: unknown[] };
-
-/**
- * Run every finalizer without allowing one of their failures to replace the operation's primary error.
- *
- * Error identity is preserved when possible: refusal codes and `instanceof` checks are part of callers'
- * control flow. Finalizer failures are attached and added to the primary message instead of wrapping it.
- */
-export async function runWithFinalizers<T>(operation: () => Promise<T>, finalizers: readonly Finalizer[]): Promise<T> {
-  let primaryPresent = false;
-  let primary: unknown;
-  let result: T | undefined;
-
-  try {
-    result = await operation();
-  } catch (error) {
-    primaryPresent = true;
-    primary = error;
-  }
-
-  const failures: Array<{ label: string; error: unknown }> = [];
-  for (const finalizer of finalizers) {
-    try {
-      await finalizer.run();
-    } catch (error) {
-      failures.push({ label: finalizer.label, error });
-    }
-  }
-
-  if (primaryPresent) {
-    if (failures.length > 0) throw appendFinalizerFailures(primary, failures);
-    throw primary;
-  }
-  if (failures.length === 1) throw failures[0].error;
-  if (failures.length > 1) {
-    throw new AggregateError(
-      failures.map((failure) => failure.error),
-      failures.map((failure) => `${failure.label}: ${String(failure.error)}`).join("; "),
-    );
-  }
-  return result as T;
-}
-
-/** True when a primary error retained a finalizer failure of the requested kind. */
-export function hasFinalizerError(error: unknown, predicate: (value: unknown) => boolean): boolean {
-  return error instanceof Error && (error as ErrorWithFinalizers)[FINALIZER_ERRORS]?.some(predicate) === true;
-}
-
-function appendFinalizerFailures(primary: unknown, failures: ReadonlyArray<{ label: string; error: unknown }>): unknown {
-  if (primary instanceof Error) {
-    const target = primary as ErrorWithFinalizers;
-    try {
-      const prior = target[FINALIZER_ERRORS] ?? [];
-      Object.defineProperty(target, FINALIZER_ERRORS, {
-        configurable: true,
-        value: [...prior, ...failures.map((failure) => failure.error)],
-      });
-      target.message = [
-        target.message,
-        ...failures.map((failure) => `${failure.label}: ${String(failure.error)}`),
-      ].join("; ");
-      return target;
-    } catch {
-      // A frozen foreign error cannot be annotated. Keep it as the first AggregateError member and cause.
-    }
-  }
-  return new AggregateError(
-    [primary, ...failures.map((failure) => failure.error)],
-    [String(primary), ...failures.map((failure) => `${failure.label}: ${String(failure.error)}`)].join("; "),
-    { cause: primary },
-  );
-}

package/src/git-identity.ts

@@ -1,56 +0,0 @@
-import { execFile } from "node:child_process";
-import { mkdtemp, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { promisify } from "node:util";
-import { runWithFinalizers } from "./finalization.ts";
-import { GovernanceRefusal, refusal } from "./refusals.ts";
-import type { ValidatedWorkspace } from "./workspace.ts";
-
-const execFileAsync = promisify(execFile);
-
-export interface GitCandidateIdentity {
-  headSha: string;
-  treeSha: string;
-}
-
-/** Compute HEAD plus NON-IGNORED tracked/untracked candidate content without changing the real index.
- *
- * NOT the exact working tree: `git add -A` honours `.gitignore`, `core.excludesFile` and
- * `$GIT_DIR/info/exclude`, and records only a gitlink for a submodule. And it is not read-only — it writes
- * blob objects into the real `.git/objects`. `docs/SPEC.md` retracted the word "exact"; this comment said
- * it for one more round. */
-export async function computeGitCandidateIdentity(workspace: ValidatedWorkspace): Promise<GitCandidateIdentity> {
-  const dir = await mkdtemp(join(tmpdir(), "pi-daddy-index-"));
-  const index = join(dir, "index");
-  const env: NodeJS.ProcessEnv = {
-    PATH: process.env.PATH,
-    HOME: process.env.HOME,
-    LANG: process.env.LANG,
-    LC_ALL: process.env.LC_ALL,
-    TMPDIR: process.env.TMPDIR,
-    GIT_INDEX_FILE: index,
-  };
-  const git = async (args: string[]) => (await execFileAsync("git", ["-C", workspace.root, ...args], {
-    env, encoding: "utf8", maxBuffer: 16 * 1024 * 1024,
-  })).stdout.trim();
-  return runWithFinalizers(async () => {
-    try {
-      const headSha = await git(["rev-parse", "HEAD"]);
-      await git(["read-tree", "HEAD"]);
-      await git(["add", "-A"]);
-      const treeSha = await git(["write-tree"]);
-      if (!/^[a-f0-9]{40,64}$/i.test(headSha) || !/^[a-f0-9]{40,64}$/i.test(treeSha)) throw new Error("Git returned an invalid object id");
-      return { headSha, treeSha };
-    } catch (error) {
-      throw new GovernanceRefusal(refusal(
-        "CHECK_IDENTITY_UNAVAILABLE",
-        `could not compute exact Git head/candidate-tree identity for workspace ${workspace.workspaceId} (${String(error)})`,
-        { workspace_id: workspace.workspaceId },
-      ));
-    }
-  }, [{
-    label: "temporary Git index cleanup failed",
-    run: () => rm(dir, { recursive: true, force: true }),
-  }]);
-}

package/src/grant-env.ts

@@ -1,221 +0,0 @@
-/**
- * The `.pi/grants.env` an operator reads, edits and commits — and what `init` refuses to put in it live.
- *
- * Split out of `init.ts` when ADR-0029's grant-width rule pushed that file past the 400-line ceiling and
- * `test/file-size.test.ts` refused it. The seam is the natural one: `init.ts` decides *what is true about
- * the installed packages*, this file decides *how that is presented to a human for review*.
- *
- * **ADR-0029.** `init` used to emit the union of every declared ceiling as a live grant. A critic's reading
- * killed it in one sentence: the handoff's safety argument for a third party authoring `allowed-tools` is
- * that *"the operator's `PI_GRANTS_GRANT` still bounds it"* — and a generated union makes the bound and the
- * bounded have the same author, who is not the operator. So capabilities that can change a machine are
- * emitted **commented**, with the definitions that need them named. `init` + `source` yields a working
- * read-only setup; the wide ones cost one deliberate uncomment.
- *
- * That is a decision about the **starting grant**, which is a stronger act than choosing a ceiling and is
- * why it needed its own ADR rather than a paragraph in ADR-0028.
- */
-
-import { DELEGATE_CAPABILITY } from "./capabilities.ts";
-import { DEFAULT_GATED } from "./propagation.ts";
-import { UNIVERSAL_CAPABILITIES, type Capability } from "./resolve.ts";
-
-/**
- * Capabilities `init` will never put LIVE in a generated grant.
- *
- * **This list is a judgement, and it is written down in one place so it can be argued with** — which is the
- * whole reason ADR-0029 exists. The rule behind it: a capability that can *change the machine* or *execute*
- * does not become live because a package asked for it. Everything else (reading, searching, listing) does.
- *
- *  - `DEFAULT_GATED` — whatever a governed session already asks a human about. Today `tool:bash`, and taking
- *    it from there rather than restating it means the two cannot drift apart.
- *  - `tool:write`, `tool:edit`, `tool:edit-diff` — mutate the working tree, and **are not gated by default**,
- *    so a source-and-go operator would hand them to a child with no dialog at all. That gap is exactly what
- *    made "the union is mitigated by gating" untrue (R-76).
- *  - `UNIVERSAL_CAPABILITIES` — confer the whole catalog by measurement (`docs/probes/pi-fabric-eval`).
- *    `assertNarrowing` refuses a grant containing one anyway; leaving it out of the file keeps the operator
- *    from ever holding it by accident.
- */
-export const WITHHELD_BY_DEFAULT: readonly Capability[] = [
-  ...new Set([...DEFAULT_GATED, "tool:write", "tool:edit", "tool:edit-diff", ...UNIVERSAL_CAPABILITIES]),
-];
-
-/** 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);
-}
-
-/**
- * Every character allowed in a generated `PI_GRANTS_GRANT` value.
- *
- * **A structural backstop, not the main defence** (R-78). The per-entry whitelist in `skill-packages.ts` is
- * what refuses a hostile capability id; this refuses to write the FILE AT ALL if anything unexpected reached
- * the string regardless. R-77 and R-78 were the same defect found twice, on two channels into one
- * interpolation, so the third channel — whatever it turns out to be — should cost a refusal rather than an
- * injection. A guard that depends on my enumeration being complete is not a guard.
- */
-const GRANT_VALUE = /^[A-Za-z0-9:@,._/-]*$/;
-
-export class UnsafeGrantError extends Error {}
-
-/** Throw rather than write a grant string that could mean something to a shell. */
-export function assertGrantIsWritable(grant: Capability[]): void {
-  const value = grant.join(",");
-  if (!GRANT_VALUE.test(value)) {
-    throw new UnsafeGrantError(
-      `refusing to write .pi/grants.env: the assembled grant contains characters that are not part of a ` +
-        `capability id (${JSON.stringify(value)}). This file is meant to be sourced by a shell, so it is ` +
-        `not written at all rather than written unsafely. Report this — a declared capability reached the ` +
-        `grant that should have been refused at discovery.`,
-    );
-  }
-}
-
-/** One definition's declared ceiling, as far as the grant file is concerned. */
-export interface GrantEnvSkill {
-  name: string;
-  ceiling: Capability[];
-  /** Present when the definition cannot be spawned at all; the string is why, for the reader. */
-  unspawnable?: string;
-}
-
-export interface GrantEnvInput {
-  skills: GrantEnvSkill[];
-  /** Capabilities emitted live. */
-  live: Capability[];
-  /** Withheld capability → the definitions that declared it. Emitted commented, for a deliberate uncomment. */
-  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[];
-}
-
-/**
- * Render the file.
- *
- * Every capability is annotated with the definition it came from, because the whole claim of this feature is
- * that the capability decision is visible and diffable. A grant nobody can read is a grant nobody reviews.
- */
-export function renderGrantEnv(input: GrantEnvInput): string {
-  const lines = [
-    "# .pi/grants.env — written by `pi-daddy init`. REVIEW IT, then commit it.",
-    "#",
-    "# Every capability below was read from a SKILL.md's own `allowed-tools`. pi-daddy chose none of them:",
-    "# a ceiling belongs in a file a human reviews, not in a default applied when a sub-agent is spawned.",
-    "# Delete an `agent:` id to withhold that definition; delete a `tool:` id to withhold that tool from",
-    "# every child. You cannot grant a child what this session does not hold, so this file is the ceiling",
-    "# over the whole delegation tree.",
-    "#",
-  ];
-
-  const spawnable = input.skills.filter((s) => !s.unspawnable);
-  if (spawnable.length > 0) {
-    lines.push("# What each definition declares — a child receives this ∩ the grant below:");
-    const width = Math.max(...spawnable.map((s) => s.name.length));
-    for (const skill of spawnable) {
-      lines.push(`#   ${skill.name.padEnd(width)}  ${skill.ceiling.join(", ") || "(nothing — a child with no tools)"}`);
-    }
-    lines.push("#");
-  }
-
-  const unspawnable = input.skills.filter((s) => s.unspawnable);
-  if (unspawnable.length > 0) {
-    lines.push("# NOT AUTHORISED — pi-daddy refuses to spawn these, so no `agent:` id is granted for them:");
-    for (const skill of unspawnable) lines.push(`#   ${skill.name}: ${skill.unspawnable}`);
-    lines.push("#");
-  }
-
-  // ADR-0029. The wide capabilities, commented, with the definitions that need them named — so authorising
-  // one is a deliberate act and reading the file tells you exactly what it buys and what it costs.
-  if (input.withheld.size > 0) {
-    lines.push(
-      "# WITHHELD BY DEFAULT — these can change your machine, so `pi-daddy init` does not grant them.",
-      "# Uncomment a capability to authorise it for every child, then add the definitions that need it to",
-      "# PI_GRANTS_GRANT below. `tool:bash` is asked about at spawn time as well; `tool:write` and",
-      "# `tool:edit` are NOT, so granting them here is the whole decision.",
-    );
-    const width = Math.max(...[...input.withheld.keys()].map((c) => c.length));
-    for (const [capability, needed] of [...input.withheld].sort()) {
-      lines.push(`#   ${capability.padEnd(width)}  (${needed.join(", ")})`);
-    }
-    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("#");
-  }
-
-  // A ceiling may legitimately name `agent:<other>` — that is how a delegator is told what IT may spawn.
-  // Granting one for a definition `init` did not write would authorise a file from some other skill root
-  // that the operator is not reviewing here, which is the same objection rule 3 makes to undeclared skills.
-  if (input.crossReferences.length > 0) {
-    lines.push("# NOT GRANTED — a definition here names another definition that pi-daddy did not write:");
-    for (const ref of input.crossReferences) {
-      lines.push(`#   ${ref.from} declares ${ref.capability}, which is not one of the definitions above.`);
-    }
-    lines.push(
-      "#   Add it by hand if you mean it — it would authorise spawning that name from ANY skill root,",
-      "#   including ~/.pi/agent/skills, which other tools install into.",
-      "#",
-    );
-  }
-
-  for (const caution of input.cautions) lines.push(`# CAUTION: ${caution}`);
-  if (input.cautions.length > 0) lines.push("#");
-
-  lines.push(
-    "# tool:delegate is what registers the delegation tools at all — withhold it and this session is a leaf.",
-    `export PI_GRANTS_GRANT="${input.live.join(",")}"`,
-    "",
-    "# Init enables this project ledger. It is LOAD-BEARING: a spawn that cannot be recorded is refused.",
-    '# PI_GRANTS_LEDGER still overrides the stored default used by plain `pi` after `/grants init`.',
-    'export PI_GRANTS_LEDGER=".pi/grants.jsonl"',
-    "",
-    "# Optional. tool:bash is ALREADY gated by default, so this line only matters if you widen it:",
-    "# gating is closed under subsumption, so gating tool:write also gates tool:bash (bash can write).",
-    '#export PI_GRANTS_GATED="tool:bash,tool:write"',
-    "",
-  );
-
-  return lines.join("\n");
-}
-
-/** The capability that must always be live, or the generated file is inert (S-5). */
-export const ALWAYS_LIVE: Capability = DELEGATE_CAPABILITY;