pi-daddy 0.13.0

package/dist/delegate.js

@@ -0,0 +1,261 @@
+/**
+ * Governed delegation — provisioning, not merely enforcement.
+ *
+ * The `tool_call` interceptor can only *permit or refuse* a `pi-subagents` spawn, because that package's
+ * `Agent` tool has no `tools` parameter. When we do the spawning ourselves the grant becomes an argument,
+ * which is what "give them some tools but not others" actually requires.
+ *
+ * Two properties fall out of owning the spawn:
+ *
+ *  1. **No propagation race at all.** Each child receives its own explicit `env` object, so nothing is
+ *     written to the shared `process.env`. The interceptor's constraint (only parent-level facts may be
+ *     pushed, because the channel is global) does not apply here.
+ *  2. **Depth control by capability.** `tool:delegate` is itself a capability. Grant it and the child can
+ *     sub-delegate; withhold it and the child is a leaf. No separate depth mechanism is required, though
+ *     `maxDepth` remains as a cheap backstop.
+ */
+import { planSpawn } from "./spawn.js";
+import { ceilingForDefinition, digestDefinition } from "./definitions.js";
+import { resolve, assertNarrowing } from "./resolve.js";
+import { AGENT_WILDCARD } from "./resolve.js";
+import { DELEGATE_CAPABILITY, agentCapability, maySpawnDefinition, normaliseCapability } from "./capabilities.js";
+// Re-exported so the split stays internal: `delegate.ts` has been the import site for these since 0.6.0 and
+// four modules plus the test suite name it. Moving the definitions without moving the door would be churn
+// charged to every caller for a line count they did not cause.
+export { DELEGATE_CAPABILITY, agentCapability, maySpawnDefinition, normaliseCapability } from "./capabilities.js";
+import { ENV_APPROVED, ENV_DEPTH, ENV_FANOUT, ENV_GATED, ENV_GRANT, ENV_LEDGER, ENV_MAX_DEPTH, ENV_PARENT_ID } from "./propagation.js";
+import { inheritApprovals } from "./approval.js";
+import { unknownCapabilities } from "./catalog.js";
+/**
+ * Plan a governed delegation. Pure: returns argv and env, spawns nothing.
+ *
+ * Fails closed on depth, on any requested capability the delegator does not hold, on gated capabilities
+ * without approval, and on a grant that cannot narrow (a universal capability slipping through).
+ */
+export function planDelegation(request, ctx) {
+    const childDepth = ctx.depth + 1;
+    // G6 / B-I3: every refusal carries a result, including the four below that return before `resolve()`
+    // is ever called. The extension guarded its ledger write with `if (ledgerPath && plan.result)`, so
+    // those four governance decisions — disabled, too deep, no task, unknown capability — were never
+    // audited at all. An empty result is the honest record: nothing was resolved, and that is the fact.
+    const empty = {
+        ok: false,
+        args: [],
+        env: {},
+        effective: [],
+        childDepth,
+        requested: [],
+        result: { effective: [], denied: [], clipped: [], gatedBlocked: [], universal: [], subsumedBy: [] },
+    };
+    if (ctx.maxDepth <= 0)
+        return { ...empty, reason: "delegation is disabled (maxDepth 0)" };
+    if (childDepth > ctx.maxDepth) {
+        return { ...empty, reason: `delegation depth limit reached (${ctx.maxDepth})` };
+    }
+    if (!request.task?.trim())
+        return { ...empty, reason: "a delegation needs a task" };
+    // ADR-0016. A named definition replaces the model's tool list with an operator-authored ceiling.
+    let requested;
+    let systemPrompt;
+    let definitionDigest;
+    /** The definition being spawned, hoisted so the gate below can name its authorising id (ADR-0024). */
+    let spawned;
+    if (request.agent) {
+        const definition = ctx.definitions?.get(request.agent);
+        spawned = definition;
+        // No fallback, deliberately. pi-subagents resolves an unknown type to `general-purpose`, whose
+        // omitted tool list means EVERY tool — so a typo there granted the full surface. An unknown name
+        // here is simply an error.
+        if (!definition) {
+            const known = [...(ctx.definitions?.keys() ?? [])].sort();
+            return {
+                ...empty,
+                reason: `unknown agent "${request.agent}"` +
+                    (known.length > 0 ? ` — known definitions: ${known.join(", ")}` : " — no definitions were found"),
+            };
+        }
+        // ADR-0017: authorisation comes BEFORE anything is said about the file. Which definitions this
+        // session may spawn is a governance question about the SESSION; whether the file declares its tools
+        // properly is a diagnostic about the DEFINITION, and answering the second one first would report a
+        // malformed-file error to a caller who was never allowed to spawn it either way.
+        //
+        // Recorded as a denial rather than a bare refusal, deliberately: `denied` is the escalation signal
+        // ADR-0008 designates, and asking to run a definition this session was not granted IS an attempt to
+        // exceed the grant. A refusal that left `denied` empty would keep it out of every audit query.
+        if (!maySpawnDefinition(ctx.ownGrant, definition.name)) {
+            const authorising = agentCapability(definition.name);
+            const held = ctx.ownGrant.filter((c) => c.startsWith("agent:")).sort();
+            return {
+                ...empty,
+                requested: [authorising],
+                result: { ...empty.result, denied: [authorising] },
+                reason: `cannot spawn "${definition.name}" — this session does not hold ${authorising} ` +
+                    `(the definition lives at ${definition.source}). ` +
+                    (held.length > 0
+                        ? `It may spawn: ${held.join(", ")}.`
+                        : `It may spawn no definitions at all; add ${authorising} to its grant to allow this one.`),
+            };
+        }
+        // ADR-0018. Recorded from here on — after authorisation, because the digest is a fact about a file
+        // this caller was allowed to read, and before every remaining outcome, because a spawn refused for a
+        // malformed declaration is still a spawn of THIS version of the definition.
+        //
+        // Assigned into `empty`, which every subsequent refusal spreads. That is the R-28 discipline applied
+        // to a record field rather than an argument: instead of eight `definitionDigest` spellings that a
+        // ninth return could forget, there is one, and forgetting it is not expressible. The success return
+        // does not spread `empty`, so it names the field explicitly.
+        definitionDigest = digestDefinition(definition);
+        Object.assign(empty, { definitionDigest });
+        const ceiling = ceilingForDefinition(definition);
+        if (ceiling.undeclared) {
+            return {
+                ...empty,
+                reason: `agent "${definition.name}" declares no \`allowed-tools\`, so it cannot be spawned — add one ` +
+                    `to ${definition.source}. An undeclared capability set is treated as NONE, never as everything.`,
+            };
+        }
+        if (ceiling.patterns.length > 0) {
+            return {
+                ...empty,
+                reason: `agent "${definition.name}" restricts a tool with a pattern (${ceiling.patterns.join(", ")}), ` +
+                    `which pi's --tools cannot express — it matches whole tool names only. Granting the bare tool ` +
+                    `would widen the declaration and dropping it would silently narrow, so neither is done.`,
+            };
+        }
+        requested = ceiling.capabilities;
+        systemPrompt = definition.body;
+    }
+    else {
+        requested = (request.tools ?? []).map(normaliseCapability);
+    }
+    // Unknown is reported before denied, and separately: "does not exist here" and "you lack authority"
+    // have different causes and different fixes. Collapsing them hides typos and stale grants.
+    if (ctx.catalog) {
+        const unknown = unknownCapabilities(requested, ctx.catalog);
+        if (unknown.length > 0) {
+            return {
+                ...empty,
+                requested,
+                reason: `unknown capabilit${unknown.length === 1 ? "y" : "ies"}: ${unknown.join(", ")} — not present in ` +
+                    `this session's catalog (typo, or an uninstalled package?)`,
+            };
+        }
+    }
+    const approvedCapabilities = (ctx.approved ?? []).map((a) => a.capability);
+    const result = resolve({
+        requested,
+        parentGrant: ctx.ownGrant,
+        gated: ctx.gated,
+        approved: approvedCapabilities,
+    });
+    /**
+     * ADR-0024: gating `agent:<name>` asks a human before that definition runs.
+     *
+     * `gatedBlocked` is a filter over `requested`, and for a definition spawn `requested` is the definition's
+     * CEILING — so the id that authorises it was never a candidate, and `PI_GRANTS_GATED=agent:deploy` did
+     * nothing at all on the path an operator writing it means. It half-worked when some *other* definition
+     * passed the id down in its own `allowed-tools`, which is worse than not working (R-47, R-25's shape).
+     *
+     * Evaluated here rather than by adding the id to `requested`, and that is the load-bearing part: a
+     * capability in `requested` flows to `effective`, which becomes the CHILD's grant — so the child would
+     * hold `agent:deploy` and could spawn `deploy` itself without anyone being asked. This is the parent's
+     * authority to run the definition *now*, not something the child receives.
+     *
+     * `agent:*` in the gate covers every definition, so "ask me before any definition runs" is one variable.
+     */
+    if (spawned) {
+        const authorising = agentCapability(spawned.name);
+        const gatedHere = ctx.gated.includes(authorising) || ctx.gated.includes(AGENT_WILDCARD);
+        if (gatedHere && !approvedCapabilities.includes(authorising)) {
+            result.gatedBlocked = [...result.gatedBlocked, authorising];
+        }
+    }
+    if (result.denied.length > 0) {
+        return {
+            ...empty,
+            requested,
+            result,
+            reason: `cannot grant ${result.denied.join(", ")} — this session does not hold it (capability escalation blocked)`,
+        };
+    }
+    // ADR-0011: narrowing is checked BEFORE the gate, and the order is load-bearing rather than
+    // stylistic. `assertNarrowing` refuses regardless of approval, so with the old order this returned
+    // "requires explicit approval" for a delegation that could never be approved — telling the operator
+    // to go and find a human who cannot help. `shouldSeekApproval` now also refuses to prompt in this
+    // case; this reordering makes the reported *reason* agree with what actually blocks the spawn.
+    try {
+        assertNarrowing(result);
+    }
+    catch (error) {
+        return { ...empty, requested, result, reason: String(error instanceof Error ? error.message : error) };
+    }
+    if (result.gatedBlocked.length > 0) {
+        return { ...empty, requested, result, reason: `${result.gatedBlocked.join(", ")} requires explicit approval` };
+    }
+    const canSubDelegate = result.effective.includes(DELEGATE_CAPABILITY);
+    const plan = planSpawn({
+        effective: result.effective,
+        prompt: request.task,
+        model: request.model,
+        provider: request.provider,
+        thinking: request.thinking,
+        skillPaths: ctx.skillPaths,
+        contextFiles: ctx.contextFiles,
+        systemPrompt,
+        print: ctx.interactive ? false : undefined,
+    });
+    // R-32. A `skill:` capability the catalog cannot place is refused rather than dropped. Dropping it
+    // would hand back a child whose grant claims a skill it does not have — the ledger would record a
+    // capability that never reached the process, which is precisely the kind of lie an audit trail must
+    // not contain. `unknownCapabilities` above catches names absent from the catalog entirely; this
+    // catches one that is known but whose path we could not resolve, which is a different fault.
+    if (plan.unresolvedSkills.length > 0) {
+        return {
+            ...empty,
+            requested,
+            result,
+            reason: `cannot locate ${plan.unresolvedSkills.join(", ")} on disk — granted but unresolvable, so the ` +
+                `child would silently lack it`,
+        };
+    }
+    // A child may only delegate further if it was granted the capability AND has the extension to do it.
+    const args = [...plan.args];
+    if (canSubDelegate && ctx.extensionPath) {
+        // `-e` loads even under `--no-extensions`, which planSpawn sets — that is precisely why the
+        // extension is added explicitly here and nowhere else.
+        args.splice(args.length - 1, 0, "-e", ctx.extensionPath);
+    }
+    const env = {
+        [ENV_GRANT]: result.effective.join(","),
+        [ENV_DEPTH]: String(childDepth),
+        [ENV_MAX_DEPTH]: String(ctx.maxDepth),
+    };
+    // The child's own share of the subtree budget, and its identity. Both attenuate downward like depth: a
+    // child can never be handed more budget than its parent had left, so the total bound holds across
+    // process boundaries with no shared state.
+    if (ctx.fanoutBudget !== undefined)
+        env[ENV_FANOUT] = String(ctx.fanoutBudget);
+    if (ctx.childSpawnId)
+        env[ENV_PARENT_ID] = ctx.childSpawnId;
+    if (ctx.gated.length > 0)
+        env[ENV_GATED] = ctx.gated.join(",");
+    // Approvals ride down with the grant, but only ever for what this child actually received — so
+    // `approved ⊆ grant` holds at every level (ADR-0010). Written even when empty, so this object states
+    // the child's approval set outright rather than leaving it to whatever the caller merges over; see
+    // `mergeChildEnv`, which is what actually stops the parent's value leaking through.
+    env[ENV_APPROVED] = inheritApprovals(ctx.approved ?? [], result.effective).join(",");
+    if (ctx.ledgerPath)
+        env[ENV_LEDGER] = ctx.ledgerPath;
+    return {
+        ok: true,
+        args,
+        env,
+        effective: result.effective,
+        result,
+        childDepth,
+        requested,
+        childId: ctx.childSpawnId,
+        ...(definitionDigest ? { definitionDigest } : {}),
+    };
+}
+//# sourceMappingURL=delegate.js.map

package/dist/delegate.js.map

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

package/dist/fanout.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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.
+ */
+/** Total descendants a session may create across its entire subtree, when nothing is configured. */
+export declare 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 declare const MAX_CHILDREN_PER_CALL = 8;
+/** Read the budget from the environment, failing to the default on absent *or* malformed input. */
+export declare function budgetFromEnv(raw: string | undefined): number;
+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 declare function splitBudget(budget: number, count: number): BudgetSplit;
+/**
+ * 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 declare function childSpawnId(parentId: string, index: number): string;
+//# sourceMappingURL=fanout.d.ts.map

package/dist/fanout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fanout.d.ts","sourceRoot":"","sources":["../src/fanout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,oGAAoG;AACpG,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,mGAAmG;AACnG,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAM7D;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAmBtE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpE"}

package/dist/fanout.js

@@ -0,0 +1,84 @@
+/**
+ * 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.js";
+/** 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;
+/** Read the budget from the environment, failing to the default on absent *or* malformed input. */
+export function budgetFromEnv(raw) {
+    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;
+}
+/**
+ * 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, count) {
+    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, index) {
+    return `${parentId}.${index + 1}`;
+}
+//# sourceMappingURL=fanout.js.map

package/dist/fanout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fanout.js","sourceRoot":"","sources":["../src/fanout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,oGAAoG;AACpG,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC,mGAAmG;AACnG,MAAM,UAAU,aAAa,CAAC,GAAuB;IACnD,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAC/B,wGAAwG;IACxG,sGAAsG;IACtG,yDAAyD;IACzD,OAAO,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,MAAM,CAAC;AAClG,CAAC;AASD;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,KAAa;IACvD,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,oCAAoC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IAChG,IAAI,KAAK,GAAG,qBAAqB,EAAE,CAAC;QAClC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,GAAG,KAAK,2CAA2C,qBAAqB,EAAE;YAClF,QAAQ,EAAE,CAAC;SACZ,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,GAAG,KAAK,EAAE,CAAC;QACnB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EACJ,6BAA6B,KAAK,wBAAwB,MAAM,6BAA6B;gBAC7F,mEAAmE;YACrE,QAAQ,EAAE,CAAC;SACZ,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,KAAa;IAC1D,OAAO,GAAG,QAAQ,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;AACpC,CAAC"}

package/dist/file-lock.d.ts

@@ -0,0 +1,54 @@
+/**
+ * One cross-process file lock, used by both files this package writes.
+ *
+ * **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.
+ */
+/** How long to wait for another writer to finish before giving up. Short: failing closed beats hanging. */
+export declare const LOCK_TIMEOUT_MS = 2000;
+/** A lock older than this is treated as abandoned by a killed process and broken. */
+export declare const STALE_LOCK_MS = 10000;
+/**
+ * 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 declare class LockTimeoutError extends Error {
+    constructor(label: string);
+}
+/**
+ * Run `work` while holding an exclusive lock beside `path`.
+ *
+ * **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 declare function withFileLock<T>(path: string, label: string, work: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=file-lock.d.ts.map

package/dist/file-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.d.ts","sourceRoot":"","sources":["../src/file-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,2GAA2G;AAC3G,eAAO,MAAM,eAAe,OAAO,CAAC;AACpC,qFAAqF;AACrF,eAAO,MAAM,aAAa,QAAS,CAAC;AAEpC;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,KAAK,EAAE,MAAM;CAI1B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA+DrG"}

package/dist/file-lock.js

@@ -0,0 +1,142 @@
+/**
+ * One cross-process file lock, used by both files this package writes.
+ *
+ * **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";
+    }
+}
+/**
+ * Run `work` while holding an exclusive lock beside `path`.
+ *
+ * **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) {
+    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.
+            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;
+        }
+        try {
+            return await work();
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+            // Only if it is still OURS. A lock broken out from under us belongs to somebody else now, and
+            // deleting it is what turned one lost race into a cascade.
+            await removeIfOurs(lockPath, token);
+        }
+    }
+}
+/**
+ * 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) {
+    try {
+        const held = await readFile(lockPath, "utf8");
+        if (held.trim() !== token)
+            return;
+        await rm(lockPath, { force: true });
+    }
+    catch {
+        /* already gone, or unreadable — either way this process is not the one that should force it */
+    }
+}
+//# sourceMappingURL=file-lock.js.map

package/dist/file-lock.js.map

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