pi-daddy 0.13.0

package/dist/approval-store.js

@@ -0,0 +1,311 @@
+/**
+ * Persistence for `always`-scoped approvals — the package's only mutable state outside the ledger.
+ *
+ * DESIGN NOTE, because it is easy to get backwards: this file is a CONVENIENCE CACHE, not a security
+ * control. The security decision was already made by a human at the moment of approval. So a failure here
+ * must never fail the work — an unwritable file downgrades the approval to session scope (see the boolean
+ * return of `saveApproval`), and an unreadable one simply grants nothing.
+ *
+ * Read on demand, never cached at session start, so **a revoke takes effect at the next gate check** —
+ * including a revoke performed from another session while this one is running.
+ *
+ * That sentence used to read *"takes effect immediately"* and claimed two different things, one of which was
+ * false and one of which is impossible:
+ *
+ *  - **False, and fixed (R-49).** Every write is load → modify → write and it was unlocked, so a save could
+ *    restore an entry another session had just revoked. Writes now hold the same file lock the ledger uses
+ *    (`src/file-lock.ts`, `underLock` below).
+ *  - **Impossible, and stated rather than fixed.** A spawn whose gate check has already passed is not
+ *    retracted by a revoke arriving microseconds later. No lock closes that: the read has to finish before
+ *    the spawn starts, so there is always an instant where the decision is made and the process is not yet
+ *    running. Inherent to revoking anything, not a gap in this one.
+ *
+ * Reads deliberately take no lock. A read that loses a race sees the previous state, which is exactly what
+ * "at the next gate check" already means.
+ *
+ * **One file per project** (ADR-0020), and **no model-authored text, ever** (ADR-0021) — see `approvalsPath`
+ * and `sanitise` for why each of those is a decision rather than a detail.
+ *
+ * Pruning is deliberately lazy: `loadApprovals` never writes, so a read is a read. Invalid entries are
+ * dropped from the file on the next `saveApproval` or `revokeApproval`.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { withFileLock } from "./file-lock.js";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { entryVerdict } from "./approval.js";
+/**
+ * Where persisted approvals live — **outside the governed workspace** (ADR-0014).
+ *
+ * It used to be `<cwd>/.pi/grants-approvals.json`, which was self-defeating in this package's own
+ * recommended configuration: `PI_GRANTS_GATED=tool:write` means *"may use write, may not pass it down
+ * without a human"*, and **a session that may use `write` can write the approvals file**. A reviewer
+ * demonstrated it end to end, including authoring a matching agent-type file so `grantAtApproval`
+ * compared equal — no dialog, and a ledger line reading `approvalSource: "persisted"`, indistinguishable
+ * from a real human approval.
+ *
+ * A narrowed child does not hold write access to the user's home directory, so it cannot forge an entry
+ * here. Each entry still carries its own `cwd` and `entryVerdict` still checks it — that check exists for
+ * R-27 and refuses an entry copied between checkouts or machines, which per-project files do not make
+ * redundant.
+ *
+ * **This does not defend against a child holding `bash`** — see ADR-0012, which accepts that such a
+ * child can escape governance entirely. The point of this change is to close the *self-defeating* case,
+ * not to claim a boundary the package does not have.
+ *
+ * **ONE FILE PER PROJECT since 0.11.0 (ADR-0020).** It was one shared document keyed only by
+ * `capability@subject`, which produced four defects in eight lines — approving in one checkout deleted
+ * another's entries (R-41), `revoke --all` cleared every project (R-43), two concurrent writes lost both
+ * (R-42), and an unlocked read-modify-write could resurrect a revoked entry (R-49, fixed in 0.13.0). The
+ * unfixable one was the keyspace: two checkouts holding definitions of the same name — `review`, `deploy`,
+ * i.e. what happens the moment an operator reuses their own conventions — could not both hold an approval,
+ * so they took turns indefinitely. Per-project files make the collision **inexpressible** rather than
+ * handled, and `revoke --all` cannot name another project's file.
+ *
+ * The `cwd` is hashed as well as named: the basename keeps the file legible to a human reading the
+ * directory, and the hash is what makes it unambiguous, since two checkouts can share a basename.
+ *
+ * **It took a `cwd` parameter and ignored it until 0.10.2**, which was not a harmless vestige: the unit
+ * suite passed a `mkdtemp` directory to it, reasonably believed the result was hermetic, and spent every
+ * `npm test` rewriting and clearing the developer's real store in `$HOME` (R-40). That was invisible while
+ * the store was unwritable and became destructive the day ADR-0019 made it reachable. The parameter is now
+ * real and required, which is the opposite failure mode: forgetting it is a type error.
+ */
+export function approvalsPath(cwd) {
+    const slug = (basename(cwd) || "root").replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 40);
+    // 16 hex = 64 bits, not the 6 this shipped with. ADR-0020 deleted the `foreign-cwd` carry-through on the
+    // premise that one file means one directory — so inside a hash collision R-41 returns *with its
+    // mitigation removed*: the second project's save deletes the first's entries. At 24 bits a deliberate
+    // collision costs about 16.7M hashes, well under a second, and an accidental one arrives at a few
+    // thousand governed directories. The premise has to be worth what was removed to rely on it.
+    const hash = createHash("sha256").update(cwd, "utf8").digest("hex").slice(0, 16);
+    return join(agentDir(), "grants-approvals", `${slug}-${hash}.json`);
+}
+/**
+ * The shared single-file store, so it can be REPORTED rather than read (ADR-0020).
+ *
+ * Deliberately not migrated. Splitting it by each entry's own `cwd` would be mechanical and lossless — the
+ * trust root is unchanged, unlike ADR-0014's move out of the workspace — but it is code that runs once, is
+ * exercised on exactly one input per machine, and lives in the layer with nine recorded defects. Re-approving
+ * costs a click; a migration bug costs a silently wrong approval.
+ */
+export function sharedApprovalsPath() {
+    return join(agentDir(), "grants-approvals.json");
+}
+/**
+ * The old in-workspace location, so it can be REPORTED rather than read.
+ *
+ * Deliberately not migrated. Importing a legacy file would import exactly the entries whose
+ * trustworthiness this change exists to remove — a forged approval would survive the fix that was
+ * supposed to stop it. The extension names the file and ignores it; re-approving is a few keystrokes and
+ * the only honest path.
+ */
+export function legacyApprovalsPath(cwd) {
+    return join(cwd, ".pi", "grants-approvals.json");
+}
+/** `$PI_CODING_AGENT_DIR`, or pi's default. Matches how pi-subagents resolves the same directory. */
+function agentDir() {
+    return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+}
+/** The subject half of `capability@subject`. Capability ids contain `:` but never `@`. */
+function subjectOf(key) {
+    return key.slice(key.indexOf("@") + 1);
+}
+/** Guard: reject entries that don't have the shape of an ApprovalEntry. */
+function isValidEntryShape(entry) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        return false;
+    }
+    const obj = entry;
+    return (typeof obj.approvedAt === "string" &&
+        typeof obj.expiresAt === "string" &&
+        typeof obj.cwd === "string" &&
+        Array.isArray(obj.grantAtApproval));
+}
+/**
+ * Project every entry through its DECLARED fields on the way out (ADR-0021).
+ *
+ * The instance this closes: `taskAtApproval` stored the model-authored task string, which `src/ledger.ts`
+ * forbids in unqualified terms — *"the task is not recorded, anywhere, ever"*. Removing the field from the
+ * type is not enough on its own, because entries are parsed from JSON and a rewrite would carry any
+ * undeclared property straight back to disk.
+ *
+ * A whitelist rather than a delete, so this closes the class: no future field can reach the store by being
+ * present on a parsed object, and adding one is a deliberate edit here.
+ */
+function sanitise(valid) {
+    return Object.fromEntries([...valid].map(([key, e]) => [
+        key,
+        {
+            approvedAt: e.approvedAt,
+            expiresAt: e.expiresAt,
+            cwd: e.cwd,
+            grantAtApproval: e.grantAtApproval,
+            ...(e.bodyAtApproval !== undefined ? { bodyAtApproval: e.bodyAtApproval } : {}),
+        },
+    ]));
+}
+async function readFileSafely(cwd) {
+    try {
+        const parsed = JSON.parse(await readFile(approvalsPath(cwd), "utf8"));
+        if (!parsed || typeof parsed !== "object")
+            return { version: 1, approvals: {} };
+        const file = parsed;
+        if (file.version !== 1 || !file.approvals || typeof file.approvals !== "object") {
+            return { version: 1, approvals: {} };
+        }
+        return { version: 1, approvals: file.approvals };
+    }
+    catch {
+        // Missing is normal; corrupt grants nothing. Either way the caller re-prompts, which is safe.
+        return { version: 1, approvals: {} };
+    }
+}
+/** Load the approvals valid HERE and NOW, plus the ones that were dropped and why. */
+export async function loadApprovals(input) {
+    const file = await readFileSafely(input.cwd);
+    const valid = new Map();
+    const dropped = [];
+    for (const [key, entry] of Object.entries(file.approvals)) {
+        // Validate entry shape before passing to entryVerdict. Malformed entries cannot take valid ones
+        // with them — one bad shape means that one entry is dropped, the rest are still evaluated.
+        if (!isValidEntryShape(entry)) {
+            dropped.push({ key, entry: entry, verdict: "expired" });
+            continue;
+        }
+        const verdict = entryVerdict({
+            entry,
+            cwd: input.cwd,
+            now: input.now,
+            current: input.snapshotOf(subjectOf(key)),
+        });
+        if (verdict === "valid")
+            valid.set(key, entry);
+        else
+            dropped.push({ key, entry, verdict });
+    }
+    return { valid, dropped };
+}
+/**
+ * Write the file atomically, and never through a symlink (ADR-0014).
+ *
+ * Two defects this closes:
+ *
+ *  - **B-I6** — writes followed project-controlled symlinks and were not atomic, so a crash or a
+ *    concurrent writer could leave a half-written file that the next read discards entirely.
+ *  - **A-R2** — a corrupt file made the next legitimate write destroy every other entry, because entries
+ *    are validated on read but pruned only on write. Writing to a temp file and renaming makes the
+ *    replacement all-or-nothing; `wx` on the temp refuses to follow an existing link.
+ *
+ * `rename` is atomic within a filesystem, and the temp file is created in the same directory precisely so
+ * that holds.
+ */
+async function writeFileSafely(cwd, file) {
+    const path = approvalsPath(cwd);
+    // Same directory as the target: `rename` is only atomic within one filesystem.
+    //
+    // **Unique per CALL, not per process.** It was `${path}.${pid}.tmp`, so two concurrent `saveApproval`
+    // calls in one process collided: the second's `wx` failed EEXIST, its `catch` unlinked the *first's*
+    // in-flight temp, and the first's `rename` then failed ENOENT — **both returned false and nothing was
+    // written**, on a perfectly writable file. Measured with two different keys, so it was not limited to
+    // the shared-dialog case: any two concurrent writes lost both. `delegate_all` is exactly that shape, and
+    // both callers would report "could not persist the approval — it applies for this session only", which
+    // named the wrong cause.
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        // `wx` fails rather than following a pre-existing symlink or clobbering another writer's temp.
+        await writeFile(temp, `${JSON.stringify(file, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+        await rename(temp, path);
+        return true;
+    }
+    catch {
+        try {
+            await unlink(temp);
+        }
+        catch {
+            /* nothing to clean up */
+        }
+        return false;
+    }
+}
+/**
+ * Persist one approval, pruning anything THIS session can see has become invalid.
+ *
+ * Returns false when the write failed. The caller must then downgrade to session scope and warn — NOT
+ * refuse the delegation. The human already said yes; refusing work because a cache could not be written
+ * would be failing closed on the wrong thing.
+ */
+export async function saveApproval(cwd, key, entry, snapshotOf, now) {
+    return underLock(cwd, false, false, async () => {
+        const { valid } = await loadApprovals({ cwd, now, snapshotOf });
+        valid.set(key, entry);
+        // ADR-0020: this file belongs to ONE project, so there is nothing here that another project could own and
+        // pruning cannot reach across a boundary. The `foreign-cwd` carry-through 0.10.2 needed is gone with the
+        // shared file that made it necessary.
+        return writeFileSafely(cwd, { version: 1, approvals: sanitise(valid) });
+    });
+}
+export async function revokeApproval(cwd, key, snapshotOf, now) {
+    return underLock(cwd, "busy", "failed", async () => {
+        const { valid } = await loadApprovals({ cwd, now, snapshotOf });
+        if (!valid.has(key))
+            return "absent";
+        valid.delete(key);
+        return (await writeFileSafely(cwd, { version: 1, approvals: sanitise(valid) })) ? "revoked" : "failed";
+    });
+}
+/**
+ * Clear every approval **for this directory**. Returns false if the write failed.
+ *
+ * Scoped rather than global, and the old behaviour was the surprising one: `/grants revoke --all` wrote an
+ * empty file, so revoking in one project silently revoked every other project's approvals too. An operator
+ * running it in one checkout is answering for that checkout — there is no interface for "and everywhere
+ * else", and it should not be the default reading of a command that names neither.
+ */
+export async function revokeAll(cwd) {
+    return underLock(cwd, false, false, () => writeFileSafely(cwd, { version: 1, approvals: {} }));
+}
+/**
+ * Hold the store's lock for one read-modify-write (R-49).
+ *
+ * **The race it closes.** Every write here is load → modify → write, and it was unlocked, so: session 1
+ * loads; session 2 revokes; session 1 saves an unrelated approval and **restores the revoked entry** for the
+ * rest of its 30 days, with no error and no warning. `approval-store.ts` documents that *"a revoke takes
+ * effect immediately — including one performed from another session while this one is running"*, and that
+ * sentence was false. Narrow (ADR-0020 scoped it to two sessions in the same directory) and cheap to close,
+ * because the lock already existed for the ledger — `src/file-lock.ts`, one implementation, two callers.
+ *
+ * **A lock this cannot take does NOT fail the work**, which is the opposite of the ledger's choice with the
+ * same lock and follows from what the two files are. The ledger is a security control: no audit line, no
+ * spawn. This store is a convenience cache (ADR-0020) — the human already said yes, and refusing their work
+ * because a cache was busy would be failing closed on the wrong thing. So a timeout yields `busy`, which the
+ * caller reports as an ordinary write failure and downgrades to session scope.
+ */
+async function underLock(cwd, onBusy, onError, work) {
+    const path = approvalsPath(cwd);
+    // **The discriminant is whether anything was READ, not which error was thrown.** Keying on
+    // `LockTimeoutError` looked right and was not: `EMFILE` — the classic transient, and one a fan-out of
+    // children plus herdr panes produces — happens before the load just as a timeout does, yet took the
+    // `failed` branch, whose message asserts the approval "is still in effect" about an entry nobody looked
+    // for, and blames a path that is perfectly writable. That is the very defect the fourth outcome was
+    // added to prevent, one error code to the left.
+    let entered = false;
+    try {
+        // The lock lives beside the file, so its directory must exist before the lock can be taken — and on a
+        // first-ever approval it does not. `writeFileSafely` creates it, which is one step too late: every
+        // write failed with ENOENT on the LOCK and was reported as busy. Caught by the existing round-trip
+        // tests within a minute of adding the lock, which is the argument for having them.
+        await mkdir(dirname(path), { recursive: true });
+        return await withFileLock(path, "approvals file", () => {
+            entered = true;
+            return work();
+        });
+    }
+    catch {
+        // Never reached the load, so nothing may be claimed about the entry — whatever the cause.
+        return entered ? onError : onBusy;
+    }
+}
+//# sourceMappingURL=approval-store.js.map

package/dist/approval-store.js.map

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

package/dist/approval.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Approval model for gated capabilities — pure, so it is exhaustively testable without pi.
+ *
+ * `resolve()` computes `gatedBlocked`: capabilities a session legitimately holds but which may not enter
+ * a child's grant without a human saying so. This module decides WHAT a yes means — how far it reaches,
+ * how long it lasts, and what it is keyed to. It never performs I/O and never prompts; see
+ * `approval-store.ts` and `approval-prompt.ts` for those.
+ *
+ * ADR-0010 records the four decisions encoded here.
+ */
+import type { Capability, ResolveResult } from "./resolve.ts";
+/** How far a single yes reaches in time. */
+export type ApprovalScope = "once" | "session" | "always";
+/** Where a yes came from, for the ledger. These call for different follow-ups, so they stay distinct. */
+export type ApprovalSource = "prompt" | "session" | "persisted" | "inherited";
+/** Which call site is asking. Determines the scopes offered — see `offeredScopes`. */
+export type ApprovalPath = "definition" | "delegate";
+/**
+ * Subject used for delegate-path approvals.
+ *
+ * The delegate tool has no human-authored subject: the only things naming a child are the task string and
+ * the tool list, both chosen by the model. A key the model controls is not a key, so delegate approvals
+ * use this fixed literal — "allow write for delegations this session" — and are never persisted.
+ * Angle brackets cannot appear in an agent-type name (`parseAgentType` reads an identifier), so this can
+ * never collide with a real type.
+ */
+export declare const DELEGATE_SUBJECT = "<delegate>";
+/**
+ * Lifetime of a persisted approval.
+ *
+ * Deliberately a constant rather than an environment variable: a knob that silently extends every gate is
+ * the first thing an impatient operator would reach for.
+ */
+export declare const APPROVAL_TTL_DAYS = 30;
+/** `tool:write` + `docs-writer` -> `tool:write@docs-writer`. */
+export declare function approvalKey(capability: Capability, subject: string): string;
+/**
+ * May this resolution raise an approval dialog?
+ *
+ * `resolve()` computes `denied` and `gatedBlocked` INDEPENDENTLY (deliberately — each rejection reason is
+ * reported rather than masked by whichever filter ran first), and both `decideSpawn` and `planDelegation`
+ * refuse outright on `denied` while still attaching the full result. So a request mixing a gated capability
+ * with one the session does not hold at all would otherwise prompt a human about the gated one and then be
+ * refused anyway for the other.
+ *
+ * That is not merely noise. A *session* yes is recorded and republished to children, and an *always* yes is
+ * written to disk for 30 days — both banked against a spawn that never happened, and both reachable by a
+ * model that appends one unheld capability to an otherwise ordinary request. A person is therefore only
+ * asked about a spawn that would actually proceed if they said yes.
+ *
+ * `clipped` is deliberately NOT a bar: it does not refuse a spawn, it just drops those capabilities from
+ * the child's grant, so the spawn does proceed and the question is real.
+ */
+export declare function shouldSeekApproval(result: ResolveResult | undefined): boolean;
+/**
+ * Scopes a given call site may offer. `always` requires a **human-authored subject**.
+ *
+ * ADR-0019. The rule is unchanged; which paths satisfy it is not. `"interceptor"` used to be the only one
+ * and ADR-0016 deleted it, leaving `always` offerable from nowhere — 220 lines of persistence no live path
+ * could write to. `"definition"` is `delegate({agent})`, where ADR-0017 makes the subject an
+ * operator-authored file the session must hold `agent:<name>` to name at all. `"delegate"` is the `tools:`
+ * form, where the original reasoning stands untouched: the only things naming that child are the task and
+ * the tool list, both model-chosen, and a key the model controls is not a key.
+ */
+export declare function offeredScopes(path: ApprovalPath): ApprovalScope[];
+/**
+ * The approval an inheriting child may hold.
+ *
+ * Intersecting with the child's grant is what keeps ADR-0008 intact once approvals became inheritable:
+ * `approved ⊆ grant` at every level, by construction. An approval can therefore never name a capability
+ * the session does not hold — it only ever unblocks part of a grant, never widens one.
+ *
+ * The wildcard is filtered for the same reason `childEnv` filters it out of grants (R-26): inheriting it
+ * would let a descendant treat every future gate as pre-approved.
+ */
+/** An approval as it crosses a boundary: the capability, WHO it was for, and HOW LONG it was meant to last. */
+export interface InheritableApproval {
+    capability: Capability;
+    /** The agent type, or `<delegate>`. Carried because an approval is for a subject, not for a word. */
+    subject: string;
+    scope: ApprovalScope;
+    /**
+     * The definition's body digest at the time of approval (ADR-0022). Absent for `<delegate>`, which names
+     * no file to hash — and, per ADR-0019, is never persisted or offered `always` for the same reason.
+     */
+    bodySha256?: string;
+}
+/**
+ * What a child may inherit, as `capability@subject` keys.
+ *
+ * ADR-0014 changed this in two ways, and both were cases of a human's explicit choice being discarded
+ * one hop down:
+ *
+ *  - **`once` is dropped** (A-S1). The scope chosen was not carried, so a `once` approval was written
+ *    into the child's `PI_GRANTS_APPROVED` and republished onward — the most conservative answer a human
+ *    can give produced the least conservative outcome, across an entire descendant subtree.
+ *  - **The subject is kept** (A-S6). Bare capabilities were published, so a `<delegate>`-subject approval
+ *    matched *any* subject below. `approvalKey`'s own doc argues at length that a model-controlled name
+ *    is not a key; erasing the subject made that argument moot exactly where it mattered.
+ *
+ * The clamp to `grant` is unchanged and still load-bearing: **approval cannot conjure a capability**, so
+ * an inherited yes is only ever honoured for something the child independently holds.
+ */
+export declare function inheritApprovals(approved: InheritableApproval[], grant: Capability[]): string[];
+/**
+ * Read the inherited set back on the child side.
+ *
+ * Anything that is not a well-formed `capability@subject` pair is dropped rather than guessed at. An
+ * unparseable entry granting nothing is a missing prompt; an unparseable entry granting *something* is a
+ * silent escalation, so the direction of the failure is not a matter of taste.
+ */
+export declare function parseInherited(raw: string | undefined): Map<string, string | undefined>;
+/**
+ * Drop inherited approvals that were given for different instructions (ADR-0022).
+ *
+ * The hole this closes: `resolveApprovals` checks `inherited` FIRST and none of it had ever been through
+ * `entryVerdict`, so ADR-0019's headline property — an approval is void once the instructions change — held
+ * on the one path that persists and neither of the two that do not. A child is a fresh process: it re-reads
+ * the definition from disk, so a `git pull` between the parent's approval and the child's spawn meant the
+ * child ran a rewritten body under a yes given about the old one, recording `approvalSource: "inherited"`.
+ *
+ * An entry with **no** digest is honoured, and that is not a hole: `<delegate>` legitimately has none, and
+ * neither does a pre-0.11 parent. It is the same trade `entryVerdict` refuses to make for a *persisted*
+ * entry — but that entry is 30 days old and read off disk, whereas this one was handed over by a live parent
+ * process in the same tree, which is a much shorter chain to trust.
+ */
+export declare function verifyInherited(parsed: ReadonlyMap<string, string | undefined>, snapshotOf: (subject: string) => SubjectSnapshot | null): Set<string>;
+/** When an approval granted now stops being valid. Computed once at write time and stored, so an entry's
+ *  lifetime is visible in the file rather than implied by whichever version of the code reads it. */
+export declare function expiryFor(approvedAt: Date): string;
+/** A persisted approval, keyed externally by subject and capability. Only the `"definition"` path writes one. */
+export interface ApprovalEntry {
+    approvedAt: string;
+    expiresAt: string;
+    /** The directory the human was sitting in. See `entryVerdict` and R-27. */
+    cwd: string;
+    /** The agent type's ceiling AT APPROVAL TIME. Load-bearing, not decorative — see `entryVerdict`. */
+    grantAtApproval: Capability[];
+    /**
+     * The definition's body digest AT APPROVAL TIME (ADR-0019, using ADR-0018's hash).
+     *
+     * `grantAtApproval` pins the tools; this pins the INSTRUCTIONS. Without it an `always` approval survives
+     * a total rewrite of what the child is told to do, because `ceilingForDefinition` reads only
+     * `allowed-tools` — R-35's hazard reappearing inside the persistence layer. Absent means the entry
+     * predates 0.10.0 and cannot be verified, which `entryVerdict` treats as changed: fail closed.
+     */
+    bodyAtApproval?: string;
+}
+export type EntryVerdict = "valid" | "expired" | "foreign-cwd" | "type-changed" | "instructions-changed" | "type-missing";
+/**
+ * What a subject looks like RIGHT NOW — one lookup, not two (ADR-0019).
+ *
+ * Deliberately a single snapshot rather than parallel `ceilingOf` / `digestOf` callbacks. R-28 was one
+ * call site supplying one argument and omitting another; a shape that cannot be half-supplied is the
+ * structural form of remembering.
+ */
+export interface SubjectSnapshot {
+    ceiling: Capability[];
+    /** SHA-256 of the definition body — `digestDefinition(...).sha256`. */
+    bodySha256: string;
+}
+export interface EntryValidityInput {
+    entry: ApprovalEntry;
+    /** The directory this session is running in. */
+    cwd: string;
+    now: Date;
+    /** The subject's CURRENT ceiling and body digest, or null when it no longer exists. */
+    current: SubjectSnapshot | null;
+}
+/**
+ * Decide whether a persisted approval still means what the human meant.
+ *
+ * Four ways it can stop meaning that, and each is reported distinctly so `/grants approvals` can explain
+ * itself rather than silently showing fewer rows:
+ *
+ *  - `foreign-cwd`  — the file was copied or committed and opened somewhere else. Nobody in THIS checkout
+ *                     was asked, so it authorises nothing here (R-27).
+ *  - `expired`      — a gate opened during one project must not still be open next quarter.
+ *  - `type-changed` — the confused deputy. The key names a file whose contents can change after approval:
+ *                     approve `tool:write@docs-writer` when it declares `read, write`, and later that file
+ *                     gains `bash`. The entry would still match the key while describing something the
+ *                     human never saw.
+ *  - `instructions-changed` — the same confused deputy, one level deeper. The tools are untouched but the
+ *                     BODY was rewritten, so the child would now be told to do something the human never
+ *                     saw. Only checkable since ADR-0018 gave the body a digest; an entry carrying no body
+ *                     pin lands here too, because unverifiable is not the same as unchanged.
+ *  - `type-missing` — the type was deleted or renamed; a new file could later claim the same name.
+ */
+export declare function entryVerdict(input: EntryValidityInput): EntryVerdict;
+export interface ResolveApprovalsInput {
+    /** `ResolveResult.gatedBlocked` — held and within ceiling, but awaiting a human. */
+    gated: Capability[];
+    subject: string;
+    /** Approval KEYS approved for this session, in memory only. */
+    sessionApprovals: ReadonlySet<string>;
+    /** Persisted entries by key, ALREADY validity-filtered by the store. */
+    persisted: ReadonlyMap<string, ApprovalEntry>;
+    /** Capabilities approved further up the tree and inherited with the grant. */
+    /**
+     * `capability@subject` keys inherited from the delegator (ADR-0014).
+     *
+     * Was `Capability[]` — bare names that matched any subject, and included `once` approvals that were
+     * never meant to leave the level they were given at.
+     */
+    inherited?: Set<string>;
+}
+export interface ResolveApprovalsResult {
+    approved: Capability[];
+    /** Gated capabilities still requiring a live human. */
+    needsPrompt: Capability[];
+    sources: Record<Capability, ApprovalSource>;
+}
+/**
+ * Satisfy as much of `gated` as possible without asking anyone.
+ *
+ * Precedence is inherited -> session -> persisted -> prompt. Order matters only for what gets REPORTED
+ * (the ledger's `approvalSource`); any hit satisfies equally. Checking all three before prompting is what
+ * stops an orchestrator's tenth delegation from raising a tenth identical dialog.
+ */
+export declare function resolveApprovals(input: ResolveApprovalsInput): ResolveApprovalsResult;
+//# sourceMappingURL=approval.d.ts.map

package/dist/approval.d.ts.map

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