pi-daddy 0.27.4 → 0.32.0

package/dist/file-lock.js

@@ -1,201 +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) {
-        super(`${label} is locked by another writer (waited ${LOCK_TIMEOUT_MS}ms)`);
-        this.name = "LockTimeoutError";
-    }
-}
-function lockPolicy(options) {
-    if (options === undefined)
-        return "age";
-    const invalid = () => { 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(path, label, work, options) {
-    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;
-        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.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, lockPath, token) {
-    let failure = 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, token, strict = false) {
-    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. */
-    }
-}
-//# sourceMappingURL=file-lock.js.map

package/dist/file-lock.js.map

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

package/dist/finalization.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"finalization.d.ts","sourceRoot":"","sources":["../src/finalization.ts"],"names":[],"mappings":"AAAA,UAAU,SAAS;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAMD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAiCpH;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAEjG"}

package/dist/finalization.js.map

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

package/dist/git-identity.d.ts

@@ -1,13 +0,0 @@
-import type { ValidatedWorkspace } from "./workspace.ts";
-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 declare function computeGitCandidateIdentity(workspace: ValidatedWorkspace): Promise<GitCandidateIdentity>;
-//# sourceMappingURL=git-identity.d.ts.map

package/dist/git-identity.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"git-identity.d.ts","sourceRoot":"","sources":["../src/git-identity.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAIzD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;4BAK4B;AAC5B,wBAAsB,2BAA2B,CAAC,SAAS,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAiC9G"}

package/dist/git-identity.js

@@ -1,47 +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.js";
-import { GovernanceRefusal, refusal } from "./refusals.js";
-const execFileAsync = promisify(execFile);
-/** 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) {
-    const dir = await mkdtemp(join(tmpdir(), "pi-daddy-index-"));
-    const index = join(dir, "index");
-    const env = {
-        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) => (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 }),
-        }]);
-}
-//# sourceMappingURL=git-identity.js.map

package/dist/git-identity.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"git-identity.js","sourceRoot":"","sources":["../src/git-identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG3D,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAO1C;;;;;4BAK4B;AAC5B,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,SAA6B;IAC7E,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,GAAG,GAAsB;QAC7B,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI;QACtB,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI;QACtB,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI;QACtB,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM;QAC1B,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM;QAC1B,cAAc,EAAE,KAAK;KACtB,CAAC;IACF,MAAM,GAAG,GAAG,KAAK,EAAE,IAAc,EAAE,EAAE,CAAC,CAAC,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,EAAE;QACjG,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;KACnD,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAClB,OAAO,iBAAiB,CAAC,KAAK,IAAI,EAAE;QAClC,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;YACjD,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;YACjC,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;YACzB,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;YAC1C,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;YACrI,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;QAC9B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,iBAAiB,CAAC,OAAO,CACjC,4BAA4B,EAC5B,0EAA0E,SAAS,CAAC,WAAW,KAAK,MAAM,CAAC,KAAK,CAAC,GAAG,EACpH,EAAE,YAAY,EAAE,SAAS,CAAC,WAAW,EAAE,CACxC,CAAC,CAAC;QACL,CAAC;IACH,CAAC,EAAE,CAAC;YACF,KAAK,EAAE,oCAAoC;YAC3C,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;SACrD,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/grant-env.d.ts

@@ -1,75 +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 { 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 declare const WITHHELD_BY_DEFAULT: readonly Capability[];
-/** Would `init` put this capability in the live grant? */
-export declare function isLiveByDefault(capability: Capability): boolean;
-export declare class UnsafeGrantError extends Error {
-}
-/** Throw rather than write a grant string that could mean something to a shell. */
-export declare function assertGrantIsWritable(grant: Capability[]): void;
-/** 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 declare function renderGrantEnv(input: GrantEnvInput): string;
-/** The capability that must always be live, or the generated file is inert (S-5). */
-export declare const ALWAYS_LIVE: Capability;
-//# sourceMappingURL=grant-env.d.ts.map

package/dist/grant-env.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"grant-env.d.ts","sourceRoot":"","sources":["../src/grant-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAA0B,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAEvE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,UAAU,EAEpD,CAAC;AAEF,0DAA0D;AAC1D,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAQ/D;AAaD,qBAAa,gBAAiB,SAAQ,KAAK;CAAG;AAE9C,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI,CAU/D;AAED,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,+FAA+F;IAC/F,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,iCAAiC;IACjC,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,6GAA6G;IAC7G,QAAQ,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;IACpC,yFAAyF;IACzF,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,sGAAsG;IACtG,kBAAkB,CAAC,EAAE,UAAU,EAAE,CAAC;IAClC,kGAAkG;IAClG,eAAe,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,UAAU,CAAA;KAAE,EAAE,CAAC;IAC5D,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CA6G3D;AAED,qFAAqF;AACrF,eAAO,MAAM,WAAW,EAAE,UAAgC,CAAC"}

package/dist/grant-env.js

@@ -1,154 +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.js";
-import { DEFAULT_GATED } from "./propagation.js";
-import { UNIVERSAL_CAPABILITIES } from "./resolve.js";
-/**
- * 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 = [
-    ...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) {
-    // 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) {
-    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.`);
-    }
-}
-/**
- * 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) {
-    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 = DELEGATE_CAPABILITY;
-//# sourceMappingURL=grant-env.js.map

package/dist/grant-env.js.map

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

package/dist/grant-store.d.ts

@@ -1,96 +0,0 @@
-/**
- * The init choice for a directory, stored **outside** it: its grant and, in v2, explicit project-ledger
- * consent.
- *
- * `PI_GRANTS_GRANT` and `PI_GRANTS_LEDGER` remain the propagation channel to children — a parent writes them
- * and every child inherits them. The store is a root-session source only, so an operator does not have to
- * `source` a file and restart pi after making the project choice.
- *
- * **Outside the workspace, and that is the whole design.** A grant is a ceiling; a ceiling a governed child
- * can rewrite is not a ceiling. `<cwd>/.pi/grants.env` is writable by any child holding `tool:write`, so
- * storing the live grant there would let a child widen the *next* session's ceiling — ADR-0014's
- * self-defeating case verbatim, which is why persisted approvals were moved out of the workspace in the
- * first place. This reuses that pattern exactly: `$PI_CODING_AGENT_DIR/grants/<slug>-<hash>.json`, keyed by
- * the directory, unwritable by a narrowed child because a narrowed child holds no write access to `$HOME`.
- *
- * **It does not defend against a child holding `bash`** (ADR-0012). Nothing here does.
- *
- * `.pi/grants.env` is still written by `init` and is still worth committing — it is the *reviewable record*
- * of the decision, diffable in a PR. It is simply no longer the thing the enforcer reads.
- */
-import type { Capability } from "./resolve.ts";
-export interface StoredGrant {
-    grant: Capability[];
-    /** Whether a root session defaults to `<cwd>/.pi/grants.jsonl`. False for every legacy v1 store. */
-    projectLedger: boolean;
-}
-export type GrantStoreRefusalReason = "malformed" | "unsupported-version" | "unreadable" | "wrong-cwd";
-export type StoredGrantState = {
-    state: "absent";
-} | {
-    state: "valid";
-    stored: StoredGrant;
-} | {
-    state: "refuse";
-    reason: GrantStoreRefusalReason;
-};
-export interface SaveGrantOptions {
-    projectLedger?: boolean;
-}
-/**
- * Where this directory's grant lives.
- *
- * Slug plus a 64-bit hash, exactly as `approvalsPath` does it and for the same two reasons: the basename
- * keeps the directory legible to a human reading it, and the hash is what makes it unambiguous, since two
- * checkouts can share a basename.
- */
-export declare function grantStorePath(cwd: string): string;
-/**
- * Parse a store file's text into its versioned project choice, or null.
- *
- * Split out from the readers so the **one** validation lives in one place: both the sync and async paths
- * must agree, and two parsers is how they come to disagree.
- *
- * Rejects every doubt at this parser boundary — it never constructs a partial ceiling. The session currently
- * treats absent and invalid stores alike (R-175), so do not call that wider behavior fail-closed. The `cwd`
- * check is R-27's: a copied file describes a directory nobody authorised it for.
- */
-export declare function parseStoredGrantState(text: string, cwd: string): StoredGrantState;
-export declare function parseStoredGrant(text: string, cwd: string): StoredGrant | null;
-/** Compatibility view for callers that need only the capability ceiling. */
-export declare function parseGrantFile(text: string, cwd: string): Capability[] | null;
-/**
- * Read this directory's stored grant, synchronously.
- *
- * **Sync on purpose, and this is the constraint that shapes the feature.** Whether `delegate` is registered
- * at all is decided when the extension factory runs (S-5: a session without `tool:delegate` must not be
- * offered the tool), and that is before any `await` is possible. An async read would resolve after the
- * decision it exists to inform, so the store would silently fail to grant delegation — the exact class of
- * defect R-38 and R-39 were.
- */
-export declare function loadStoredGrantStateSync(cwd: string): StoredGrantState;
-export declare function loadStoredGrantSync(cwd: string): StoredGrant | null;
-export declare function loadGrantSync(cwd: string): Capability[] | null;
-/** Async twin, for callers that already have one. Same parser, so they cannot disagree. */
-export declare function loadStoredGrantState(cwd: string): Promise<StoredGrantState>;
-export declare function loadStoredGrant(cwd: string): Promise<StoredGrant | null>;
-export declare function loadGrant(cwd: string): Promise<Capability[] | null>;
-/** The one project-local default ADR-0037 binds to an explicit v2 init choice. */
-export declare function projectLedgerPath(cwd: string): string;
-export type SaveOutcome = "saved" | "failed" | "busy";
-/**
- * Write this directory's grant and optional project-ledger consent as one atomic choice.
- *
- * Locked with the same lock the ledger and the approval store use, for the same reason: two sessions in one
- * directory running `/grants init` concurrently must not interleave. A lock this cannot take yields `busy`
- * and changes nothing — the caller reports it and the operator retries, which is the honest outcome for a
- * write that never looked at the file (R-68).
- *
- * `wx` on the temp file refuses to follow a pre-existing symlink, and `rename` is atomic within a
- * filesystem, so a reader never sees a half-written grant. Both copied from `writeFileSafely`, deliberately
- * — a second, subtly different atomic-write is how the two come to disagree about what "safe" meant.
- */
-export declare function saveGrant(cwd: string, grant: Capability[], options?: SaveGrantOptions): Promise<SaveOutcome>;
-/** Remove this directory's stored grant. True when a file was there to remove. */
-export declare function clearGrant(cwd: string): Promise<boolean>;
-//# sourceMappingURL=grant-store.d.ts.map