@nathapp/nax-agent 0.1.0

package/dist/permissions/approvals-store.d.ts

@@ -0,0 +1,168 @@
+export interface ApprovalEntry {
+    readonly stage: string;
+    readonly command: string;
+    readonly root: string;
+    readonly origin: "escalate" | "askRule";
+    readonly matchedRule: string | null;
+    readonly approvedAt: string;
+    readonly approvedBy: string;
+    readonly naxCommit: string;
+}
+/**
+ * Written by nax itself when a FORGE-CAPABLE run uses the store (#2199): every
+ * entry beside it is untrusted, and the next run that trusts the cache
+ * discards them. See approvals-taint.ts for the trust argument.
+ */
+export interface ApprovalsTaint {
+    readonly since: string;
+    readonly runId: string;
+    /** The tainting nax process; `undefined` when absent or malformed on disk. */
+    readonly pid: number | undefined;
+}
+export interface ApprovalsFile {
+    readonly entries: readonly ApprovalEntry[];
+    readonly taint: ApprovalsTaint | undefined;
+}
+/**
+ * The classification a `readApprovalsFileDetailed` call reports. `missing` is a
+ * path that resolves to no file at all (ENOENT, or a parent dir that does not
+ * exist); `unparseable` is a file whose contents the read could not turn into
+ * the entries+taint shape the cache needs; `ok` is a file the read accepts.
+ */
+export type ApprovalsFileState = "ok" | "missing" | "unparseable";
+/**
+ * What `readApprovalsFileDetailed` returns: the same `ApprovalsFile` shape
+ * `readApprovalsFile` always has, plus a classification and the count of array
+ * elements the read dropped for not being approval entries. `droppedMalformed`
+ * is `0` unless `state === "ok"` -- an unparseable file has no entries to
+ * drop, and a missing file has no file at all.
+ */
+export interface ApprovalsFileRead {
+    readonly file: ApprovalsFile;
+    readonly state: ApprovalsFileState;
+    readonly droppedMalformed: number;
+}
+/**
+ * The run's output dir, NOT the tool root. `root` is storyExecRoot -- the repo
+ * OR WORKTREE root -- so a root-relative file is deleted by the
+ * `git worktree remove --force` that ends the run. That is the exact defect
+ * recorded in toolAuditDir's docblock (src/config/paths/index.ts:138-150).
+ */
+export declare function approvalsPath(outputDir: string): string;
+/**
+ * Stable, derived id for an entry. The id is a function of (stage, command,
+ * approvedAt) alone -- NOT of the entry's position in the file, or of any
+ * sibling entry -- so it survives other entries being added or removed and
+ * two entries recorded for the same triple share an id and are removed
+ * together (US-001).
+ *
+ * Computed on every read and never stored. A missing or non-string
+ * `approvedAt` reads as the empty string so the id is still a well-defined
+ * 8-character hex value for the malformed-on-disk entries the cache admits.
+ */
+export declare function approvalId(entry: ApprovalEntry): string;
+/**
+ * Classify a store read. `missing` means the file is absent (or its parent
+ * directory is); `unparseable` means a file is present but its contents are
+ * not a `{ entries, taint }` object the cache can trust; `ok` means the read
+ * accepted the file and `file.entries` lists every element `isApprovalEntry`
+ * accepted, with `droppedMalformed` counting the rejections.
+ *
+ * A present `taint` is still parsed when the rest of the file is unparseable:
+ * a forged `entries` array must not strip the marker.
+ *
+ * A read failure (EACCES/EIO) is not a parse failure and is not classified
+ * here — it propagates so a caller that must surface it (the `nax approvals`
+ * CLI) can report it instead of mislabelling it `unparseable`. Callers that
+ * must stay fail-closed use `readApprovalsFile`, which catches it.
+ */
+export declare function readApprovalsFileDetailed(path: string): Promise<ApprovalsFileRead>;
+/**
+ * Missing, malformed OR unreadable reads as empty: the CACHE fails, the chain
+ * does not. A permissions/IO error is caught here (rather than propagating
+ * from `readApprovalsFileDetailed`) so it cannot abort an approval lookup; a
+ * caller that must distinguish it calls the detailed read directly.
+ */
+export declare function readApprovalsFile(path: string): Promise<ApprovalsFile>;
+export declare function readApprovals(path: string): Promise<readonly ApprovalEntry[]>;
+/** Serialize the whole store. Callers hold the path lock. */
+export declare function writeApprovalsFile(path: string, file: ApprovalsFile): Promise<void>;
+/**
+ * Lock the read-modify-write. Worktree-isolated parallel stories share one
+ * project-scoped file BY DESIGN (that is why `root` is not part of the key), so
+ * two "Allow + remember" taps can race and drop one. `withPathFileLock` is the
+ * shared primitive for exactly this shape; it fails closed on timeout rather
+ * than entering over a possible holder.
+ *
+ * The taint marker is PRESERVED: a "remember" tapped during a forge-capable run
+ * lands in a store that stays untrusted.
+ */
+export declare function appendApproval(path: string, entry: ApprovalEntry): Promise<void>;
+/**
+ * The decision `removeApprovals` asks the caller for, once the read has
+ * classified the file. The caller picks which entries to drop with `remove` --
+ * a predicate over the kept entries from the read -- or refuses the operation
+ * with `refuse`. The two arms are mutually exclusive: a single decision is
+ * either "remove these" or "I will not act, because: ...".
+ */
+export type RemovalDecision = {
+    readonly remove: (entry: ApprovalEntry) => boolean;
+} | {
+    readonly refuse: string;
+};
+/**
+ * What `removeApprovals` reports back. `refused` covers both the file being
+ * unparseable (so the read refuses the call to `decide`) and the caller's own
+ * `refuse` decision: the caller cannot distinguish the two from the result
+ * alone, only from the message. `removed` reports exactly the entries the
+ * caller chose to drop plus the count of malformed array elements the read
+ * dropped for being non-entries. `unchanged` is returned for both a missing
+ * file and a present file whose predicate selected nothing.
+ */
+export type RemovalResult = {
+    readonly outcome: "removed";
+    readonly removed: readonly ApprovalEntry[];
+    readonly droppedMalformed: number;
+} | {
+    readonly outcome: "unchanged";
+} | {
+    readonly outcome: "refused";
+    readonly reason: string;
+};
+/**
+ * Locked, taint-preserving removal. Holds the same path-scoped lock
+ * `appendApproval` holds, so a removal racing an append cannot drop one of the
+ * two writes; whichever runs first inside the lock, the other sees the
+ * post-write state on its next read.
+ *
+ * The order of the guards matters and is documented in the story:
+ *   1. `state === "unparseable"` -> `refused`, no `decide` call, no write.
+ *      Rewriting would erase whatever the file holds, including a taint
+ *      marker we did not write.
+ *   2. `decide(read)` returns `{ refuse }` -> `refused`, no write.
+ *   3. The predicate selected no entry (or the file was missing) ->
+ *      `unchanged`, no write, and neither the data file nor its parent
+ *      directory is created.
+ *   4. Otherwise write `{ taint: read.file.taint, entries: kept }` with the
+ *      SAME taint that was read. Nothing in this function clears a taint;
+ *      only `clearApprovalsTaint` (approvals-taint.ts) does, and only from a
+ *      trusted run.
+ *
+ * The lock file must live next to the target, so the lock is only taken when
+ * that parent directory already exists. A path whose parent is missing is by
+ * definition a missing store: the read-decide path runs without the lock and
+ * creates nothing -- taking the lock there would require `mkdir`, which rule 3
+ * forbids. `decide` is still invoked exactly once in that arm, so the missing
+ * read reaches the caller as it does under the lock.
+ */
+export declare function removeApprovals(path: string, decide: (read: ApprovalsFileRead) => RemovalDecision): Promise<RemovalResult>;
+/**
+ * BYTE-EXACT. No normalization. See the module docblock.
+ *
+ * `projectRoot`, when given, also requires the entry's `root` to be that root
+ * or lie inside it. Worktrees (`<projectRoot>/.nax-wt/<id>`) and monorepo
+ * package dirs both do, so parallel stories still share entries. This is
+ * HYGIENE, not authentication: it drops entries another project wrote into a
+ * shared outputDir, but a forger can write any `root` it likes (#2199).
+ */
+export declare function findApproval(entries: readonly ApprovalEntry[], stage: string, command: string, projectRoot?: string): ApprovalEntry | undefined;

package/dist/permissions/approvals-store.js

@@ -0,0 +1,259 @@
+/**
+ * Durable store for remembered approvals (P2 design section 6.6).
+ *
+ * A remembered approval is a CACHED HUMAN DECISION, not a rule. Lookup is
+ * BYTE-EXACT on (stage, command) with no normalization of any kind -- not
+ * trimming, not whitespace collapsing, not quote folding. Any normalization is
+ * a place where the string that was approved and the string that runs can
+ * diverge, and the whole value of the cache is that they cannot.
+ *
+ * Synthesizing a `Bash(...)` rule instead would be materially broader than what
+ * the operator approved: rule matching is a token-wise PREFIX match with no
+ * length ceiling (src/tools/policy-bash.ts:72-83), so a rule made from
+ * `bun run test` would also grant `bun run test --reporter=./x`.
+ *
+ * The file may also carry a `taint` marker (#2199) -- see approvals-taint.ts.
+ *
+ * Revocation goes through `src/cli/approvals.ts`, the surface D20 relies on:
+ * `removeApprovals` here is the locked, taint-preserving read-decide-write
+ * primitive that surface calls into.
+ */
+import { createHash } from "node:crypto";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { withPathFileLock } from "#src/internal/path-file-lock";
+const EMPTY_FILE = { entries: [], taint: undefined };
+/**
+ * The run's output dir, NOT the tool root. `root` is storyExecRoot -- the repo
+ * OR WORKTREE root -- so a root-relative file is deleted by the
+ * `git worktree remove --force` that ends the run. That is the exact defect
+ * recorded in toolAuditDir's docblock (src/config/paths/index.ts:138-150).
+ */
+export function approvalsPath(outputDir) {
+    return join(outputDir, "approvals.json");
+}
+/**
+ * The shape findApproval relies on. A malformed element (null, a string, an
+ * object missing `stage`/`command`) is DROPPED rather than returned: an
+ * unvalidated array makes `findApproval`'s `e.stage` throw, and a poisoned
+ * cache read would fail the whole ask chain instead of just this entry.
+ */
+function isApprovalEntry(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if (!("stage" in value) || !("command" in value))
+        return false;
+    return typeof value.stage === "string" && typeof value.command === "string";
+}
+/**
+ * ANY present `taint` value taints, however malformed: the marker exists to
+ * withhold trust, so an unparseable one must not grant it.
+ */
+function parseTaint(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const raw = typeof value === "object" ? { ...value } : {};
+    return {
+        since: typeof raw.since === "string" ? raw.since : "",
+        runId: typeof raw.runId === "string" ? raw.runId : "",
+        pid: typeof raw.pid === "number" && Number.isInteger(raw.pid) ? raw.pid : undefined,
+    };
+}
+/**
+ * Stable, derived id for an entry. The id is a function of (stage, command,
+ * approvedAt) alone -- NOT of the entry's position in the file, or of any
+ * sibling entry -- so it survives other entries being added or removed and
+ * two entries recorded for the same triple share an id and are removed
+ * together (US-001).
+ *
+ * Computed on every read and never stored. A missing or non-string
+ * `approvedAt` reads as the empty string so the id is still a well-defined
+ * 8-character hex value for the malformed-on-disk entries the cache admits.
+ */
+export function approvalId(entry) {
+    const approvedAt = typeof entry.approvedAt === "string" ? entry.approvedAt : "";
+    const digest = createHash("sha256");
+    digest.update(`${entry.stage}\0${entry.command}\0${approvedAt}`);
+    return digest.digest("hex").slice(0, 8);
+}
+/**
+ * Classify a store read. `missing` means the file is absent (or its parent
+ * directory is); `unparseable` means a file is present but its contents are
+ * not a `{ entries, taint }` object the cache can trust; `ok` means the read
+ * accepted the file and `file.entries` lists every element `isApprovalEntry`
+ * accepted, with `droppedMalformed` counting the rejections.
+ *
+ * A present `taint` is still parsed when the rest of the file is unparseable:
+ * a forged `entries` array must not strip the marker.
+ *
+ * A read failure (EACCES/EIO) is not a parse failure and is not classified
+ * here — it propagates so a caller that must surface it (the `nax approvals`
+ * CLI) can report it instead of mislabelling it `unparseable`. Callers that
+ * must stay fail-closed use `readApprovalsFile`, which catches it.
+ */
+export async function readApprovalsFileDetailed(path) {
+    let contents;
+    try {
+        contents = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return { state: "missing", file: EMPTY_FILE, droppedMalformed: 0 };
+        }
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch {
+        return { state: "unparseable", file: EMPTY_FILE, droppedMalformed: 0 };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { state: "unparseable", file: EMPTY_FILE, droppedMalformed: 0 };
+    }
+    const { entries, taint } = parsed;
+    if ("entries" in parsed && !Array.isArray(entries)) {
+        return { state: "unparseable", file: { entries: [], taint: parseTaint(taint) }, droppedMalformed: 0 };
+    }
+    const array = Array.isArray(entries) ? entries : [];
+    const kept = [];
+    let dropped = 0;
+    for (const element of array) {
+        if (isApprovalEntry(element)) {
+            kept.push(element);
+        }
+        else {
+            dropped += 1;
+        }
+    }
+    return { state: "ok", file: { entries: kept, taint: parseTaint(taint) }, droppedMalformed: dropped };
+}
+/**
+ * Missing, malformed OR unreadable reads as empty: the CACHE fails, the chain
+ * does not. A permissions/IO error is caught here (rather than propagating
+ * from `readApprovalsFileDetailed`) so it cannot abort an approval lookup; a
+ * caller that must distinguish it calls the detailed read directly.
+ */
+export async function readApprovalsFile(path) {
+    try {
+        return (await readApprovalsFileDetailed(path)).file;
+    }
+    catch {
+        return EMPTY_FILE;
+    }
+}
+export async function readApprovals(path) {
+    return (await readApprovalsFile(path)).entries;
+}
+/** Serialize the whole store. Callers hold the path lock. */
+export async function writeApprovalsFile(path, file) {
+    const body = file.taint === undefined ? { entries: file.entries } : { taint: file.taint, entries: file.entries };
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(body, null, 2)}\n`, "utf8");
+}
+/**
+ * Lock the read-modify-write. Worktree-isolated parallel stories share one
+ * project-scoped file BY DESIGN (that is why `root` is not part of the key), so
+ * two "Allow + remember" taps can race and drop one. `withPathFileLock` is the
+ * shared primitive for exactly this shape; it fails closed on timeout rather
+ * than entering over a possible holder.
+ *
+ * The taint marker is PRESERVED: a "remember" tapped during a forge-capable run
+ * lands in a store that stays untrusted.
+ */
+export async function appendApproval(path, entry) {
+    await mkdir(dirname(path), { recursive: true });
+    await withPathFileLock(path, async () => {
+        const existing = await readApprovalsFile(path);
+        await writeApprovalsFile(path, { taint: existing.taint, entries: [...existing.entries, entry] });
+    });
+}
+/**
+ * The locked read-decide-write body shared by the two `removeApprovals` arms.
+ * Pure read -> guard -> decide -> filter -> write: no mkdir, no lock handling.
+ */
+async function applyRemoval(path, decide) {
+    const read = await readApprovalsFileDetailed(path);
+    if (read.state === "unparseable") {
+        return { outcome: "refused", reason: "approvals.json could not be parsed; not rewriting it" };
+    }
+    const decision = decide(read);
+    if ("refuse" in decision) {
+        return { outcome: "refused", reason: decision.refuse };
+    }
+    const removed = [];
+    const kept = [];
+    for (const entry of read.file.entries) {
+        if (decision.remove(entry)) {
+            removed.push(entry);
+        }
+        else {
+            kept.push(entry);
+        }
+    }
+    if (removed.length === 0) {
+        return { outcome: "unchanged" };
+    }
+    await writeApprovalsFile(path, { taint: read.file.taint, entries: kept });
+    return { outcome: "removed", removed, droppedMalformed: read.droppedMalformed };
+}
+/** `true` iff `dir` exists and is a directory (symlinks followed). */
+async function directoryExists(dir) {
+    try {
+        return (await stat(dir)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Locked, taint-preserving removal. Holds the same path-scoped lock
+ * `appendApproval` holds, so a removal racing an append cannot drop one of the
+ * two writes; whichever runs first inside the lock, the other sees the
+ * post-write state on its next read.
+ *
+ * The order of the guards matters and is documented in the story:
+ *   1. `state === "unparseable"` -> `refused`, no `decide` call, no write.
+ *      Rewriting would erase whatever the file holds, including a taint
+ *      marker we did not write.
+ *   2. `decide(read)` returns `{ refuse }` -> `refused`, no write.
+ *   3. The predicate selected no entry (or the file was missing) ->
+ *      `unchanged`, no write, and neither the data file nor its parent
+ *      directory is created.
+ *   4. Otherwise write `{ taint: read.file.taint, entries: kept }` with the
+ *      SAME taint that was read. Nothing in this function clears a taint;
+ *      only `clearApprovalsTaint` (approvals-taint.ts) does, and only from a
+ *      trusted run.
+ *
+ * The lock file must live next to the target, so the lock is only taken when
+ * that parent directory already exists. A path whose parent is missing is by
+ * definition a missing store: the read-decide path runs without the lock and
+ * creates nothing -- taking the lock there would require `mkdir`, which rule 3
+ * forbids. `decide` is still invoked exactly once in that arm, so the missing
+ * read reaches the caller as it does under the lock.
+ */
+export async function removeApprovals(path, decide) {
+    if (!(await directoryExists(dirname(path)))) {
+        return applyRemoval(path, decide);
+    }
+    return withPathFileLock(path, () => applyRemoval(path, decide));
+}
+/**
+ * BYTE-EXACT. No normalization. See the module docblock.
+ *
+ * `projectRoot`, when given, also requires the entry's `root` to be that root
+ * or lie inside it. Worktrees (`<projectRoot>/.nax-wt/<id>`) and monorepo
+ * package dirs both do, so parallel stories still share entries. This is
+ * HYGIENE, not authentication: it drops entries another project wrote into a
+ * shared outputDir, but a forger can write any `root` it likes (#2199).
+ */
+export function findApproval(entries, stage, command, projectRoot) {
+    return entries.find((e) => e.stage === stage && e.command === command && (projectRoot === undefined || isWithin(projectRoot, e.root)));
+}
+function isWithin(projectRoot, root) {
+    if (typeof root !== "string" || root === "")
+        return false;
+    const rel = relative(resolve(projectRoot), resolve(root));
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}

package/dist/permissions/approvals-taint.d.ts

@@ -0,0 +1,33 @@
+export declare const _approvalsTaintDeps: {
+    pid: () => number;
+    now: () => Date;
+    isProcessAlive: (pid: number) => boolean;
+};
+/**
+ * A run can forge the approvals file when any stage runs a raw shell outside
+ * the sandbox. With the sandbox enabled the file is always in `denyWrite`, and
+ * a raw stage is either wrapped or refused. Config-only: no probe dependency.
+ */
+export declare function isForgeCapable(stageModes: readonly string[], sandboxEnabled: boolean): boolean;
+/** Drop every entry and record who tainted the store. */
+export declare function taintApprovals(path: string, runId: string): Promise<void>;
+/** `held`: a still-running forge-capable nax process owns the taint. */
+export type ClearTaintOutcome = "clean" | "cleared" | "held";
+/**
+ * Start a trusted epoch. Entries that sat beside a taint are dropped, never
+ * promoted: nothing distinguishes a forged one from a human's.
+ */
+export declare function clearApprovalsTaint(path: string, runId: string): Promise<ClearTaintOutcome>;
+export interface PrepareApprovalsStoreOptions {
+    readonly approvalsFile: string;
+    readonly runId: string;
+    /** Absent for a run-scoped (post-run) dispatch scope. */
+    readonly storyId?: string;
+    readonly forgeCapable: boolean;
+}
+/**
+ * Taint (forge-capable) or clear (trusted) the store. Never throws: a failed
+ * clear leaves the taint in place, so the link abstains and the cost is
+ * prompts; a failed taint is logged, since a later run may then trust entries.
+ */
+export declare function prepareApprovalsStore(opts: PrepareApprovalsStoreOptions): Promise<void>;

package/dist/permissions/approvals-taint.js

@@ -0,0 +1,138 @@
+/**
+ * Cross-run provenance for the approvals cache (#2199).
+ *
+ * THE PROBLEM. `approvals.json` is project-scoped and outlives the run. A run
+ * with any `bashApproval: raw` stage and no sandbox ("forge-capable") has a
+ * shell that can append arbitrary entries, and a LATER run that trusts the
+ * cache would auto-allow them as `decidedBy: "cache"`. Checking only the
+ * current run's stage modes cannot see that history.
+ *
+ * WHY NOT A SIGNATURE. An unsandboxed raw shell runs as the same OS user as
+ * nax. Any key nax can read from disk -- under ~/.nax or anywhere else -- that
+ * shell can read too, and then mint valid signatures. Signing would look
+ * stronger than it is, so it is deliberately not done (ADR-030 said the same).
+ *
+ * THE DESIGN: a taint marker that only nax writes, at points no agent runs.
+ *  1. A forge-capable run TAINTS the store before a dispatch scope's agents
+ *     start (a story, or a post-run fix loop) and again after they finish: every entry is dropped and a `taint` record is
+ *     written. The end-of-story re-taint wipes whatever the story's agents
+ *     wrote, even an agent that knew to strip the first marker. One final seal
+ *     runs at the end of the run (`buildApprovalsSeal`, awaited by `cleanupRun`
+ *     and by the signal teardown), covering agents dispatched outside any
+ *     dispatch-ask scope after the last per-scope re-taint.
+ *  2. The cache link ABSTAINS on a tainted store, whatever it contains.
+ *  3. A run that trusts the cache clears a taint before building its link by
+ *     dropping every entry with it, so a trusted epoch starts empty. It leaves
+ *     the taint alone while the tainting run may still be writing: the same
+ *     run (a sibling story in a forge-capable package), or another nax process
+ *     that is still alive.
+ *
+ * RESIDUAL RISK, stated so it is not overclaimed. The guarantee is against an
+ * agent that forges entries during its turn, not against a hostile one that
+ * understands this scheme. Out of reach of any on-disk mechanism:
+ *  - a process the agent leaves running past its story (e.g. a detached
+ *    `sleep; rewrite`) that strips the marker and forges after the last
+ *    re-taint;
+ *  - a forge-capable run killed by a death no handler sees (SIGKILL, power
+ *    loss) between an agent stripping the marker and the run-end seal. Normal
+ *    exits and handled signals both seal: `cleanupRun` awaits the seal in the
+ *    runner's finally, and `performTeardown` awaits it after the PID sweep.
+ * An unsandboxed raw shell can equally edit shell rc files or git hooks, so
+ * this sits inside the posture ADR-030 already discloses; the sandbox, which
+ * always write-denies this file, is the real boundary.
+ */
+import { getSafeLogger } from "#src/infra/index";
+import { withPathFileLock } from "#src/internal/path-file-lock";
+import { readApprovalsFile, writeApprovalsFile } from "./approvals-store.js";
+/** `kill(pid, 0)` failing with EPERM means the process exists but is not ours. */
+const ERRNO_NO_PERMISSION = "EPERM";
+export const _approvalsTaintDeps = {
+    pid: () => process.pid,
+    now: () => new Date(),
+    isProcessAlive: (pid) => {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (err) {
+            return err.code === ERRNO_NO_PERMISSION;
+        }
+    },
+};
+/**
+ * A run can forge the approvals file when any stage runs a raw shell outside
+ * the sandbox. With the sandbox enabled the file is always in `denyWrite`, and
+ * a raw stage is either wrapped or refused. Config-only: no probe dependency.
+ */
+export function isForgeCapable(stageModes, sandboxEnabled) {
+    return stageModes.includes("raw") && !sandboxEnabled;
+}
+/** Drop every entry and record who tainted the store. */
+export async function taintApprovals(path, runId) {
+    const taint = { since: _approvalsTaintDeps.now().toISOString(), runId, pid: _approvalsTaintDeps.pid() };
+    await withPathFileLock(path, async () => writeApprovalsFile(path, { taint, entries: [] }));
+}
+/**
+ * Whether the tainting run may still be writing. A taint from THIS run is held:
+ * stories can resolve different sandbox settings per package, so a trusted
+ * story must not clear the marker a forge-capable sibling story just wrote. A
+ * taint from an earlier run in this same process is not held.
+ */
+function taintIsHeld(taint, runId) {
+    if (taint.runId === runId)
+        return true;
+    const owner = taint.pid;
+    if (owner === undefined || owner === _approvalsTaintDeps.pid())
+        return false;
+    return _approvalsTaintDeps.isProcessAlive(owner);
+}
+/**
+ * Start a trusted epoch. Entries that sat beside a taint are dropped, never
+ * promoted: nothing distinguishes a forged one from a human's.
+ */
+export async function clearApprovalsTaint(path, runId) {
+    return withPathFileLock(path, async () => {
+        const { taint } = await readApprovalsFile(path);
+        if (taint === undefined)
+            return "clean";
+        if (taintIsHeld(taint, runId))
+            return "held";
+        await writeApprovalsFile(path, { taint: undefined, entries: [] });
+        return "cleared";
+    });
+}
+/**
+ * Taint (forge-capable) or clear (trusted) the store. Never throws: a failed
+ * clear leaves the taint in place, so the link abstains and the cost is
+ * prompts; a failed taint is logged, since a later run may then trust entries.
+ */
+export async function prepareApprovalsStore(opts) {
+    const logger = getSafeLogger();
+    try {
+        if (opts.forgeCapable) {
+            await taintApprovals(opts.approvalsFile, opts.runId);
+            return;
+        }
+        const outcome = await clearApprovalsTaint(opts.approvalsFile, opts.runId);
+        if (outcome === "held") {
+            logger?.warn("permissions", "[approvals] store tainted by a forge-capable run still in progress; cache stays off", {
+                storyId: opts.storyId,
+                approvalsFile: opts.approvalsFile,
+            });
+        }
+        else if (outcome === "cleared") {
+            logger?.info("permissions", "[approvals] discarded entries written under a forge-capable run", {
+                storyId: opts.storyId,
+                approvalsFile: opts.approvalsFile,
+            });
+        }
+    }
+    catch (error) {
+        logger?.warn("permissions", "[approvals] could not update the store's taint marker", {
+            storyId: opts.storyId,
+            approvalsFile: opts.approvalsFile,
+            forgeCapable: opts.forgeCapable,
+            error,
+        });
+    }
+}

package/dist/permissions/ask-chain.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The ask-tier resolver chain (P2 design section 4).
+ *
+ * One decision point for every permission adjudicator: the approvals cache,
+ * a future classifier (P5) and the human gate are all LINKS here. The channel
+ * that asks a human lives in src/interaction/ and is not a peer of this chain
+ * -- it is what the human link talks to.
+ *
+ * Fail-closed by construction: the chain appends its own terminal deny, so an
+ * exhausted or all-abstaining chain denies whether or not the last link is
+ * total. A link that throws is treated as no answer, never as permission.
+ */
+import type { AskRequest } from "./types.ts";
+/** A link's answer. `abstain` means "no opinion, try the next link". */
+export type AskDecision = "allow" | "deny" | "abstain";
+/** Who actually decided. Carried into the ledger so it never has to be inferred. */
+export type AskDecidedBy = "cache" | "model" | "human" | "timeout" | "unavailable" | "cancelled" | "unshowable";
+/**
+ * Per-ask control (US-003), carried SEPARATELY from the `AskRequest` so the
+ * request the ledger records stays the pure request and a resolver can react
+ * to the orchestrating turn being cancelled.
+ */
+export interface AskControl {
+    /** The turn's abort signal; aborted while a waiter sits on-screen or queued. */
+    readonly signal?: AbortSignal;
+    /** Notifies the turn loop that this ask is waiting on a human. */
+    readonly onWaiting?: () => void;
+}
+export interface AskLinkOutcome {
+    readonly decision: AskDecision;
+    readonly decidedBy: AskDecidedBy;
+}
+/**
+ * One adjudicator. A link ALWAYS names who decided, because a single link can
+ * answer for more than one reason -- the human link resolves as `human` when
+ * someone taps and as `timeout` when nobody does.
+ */
+export interface AskLink {
+    readonly name: string;
+    resolve(req: AskRequest, control?: AskControl): Promise<AskLinkOutcome>;
+}
+/** What the runtime consumes. Never `abstain`. */
+export interface AskVerdict {
+    readonly decision: "allow" | "deny";
+    readonly decidedBy: AskDecidedBy;
+    readonly latencyMs: number;
+}
+export interface AskResolver {
+    /**
+     * Whether a human can answer at all (ADR-030, amended for P4): an interaction
+     * channel exists for this run. Absent means false. Only the escalate Bash
+     * DESCRIPTION reads it; the verdict never depends on it.
+     */
+    readonly humanReachable?: boolean;
+    resolve(req: AskRequest, control?: AskControl): Promise<AskVerdict>;
+}
+/**
+ * Compose links into a resolver. First non-abstain wins.
+ *
+ * A throwing link abstains rather than propagating: `runtime.callTool` turns an
+ * exception out of the resolver into a TOOL ERROR surfaced to the model, not a
+ * denial, which would lose the `denied:ask` ledger row and hand the agent
+ * something it may retry around.
+ *
+ * US-003: forwards the same `control` object to every link so a turn-cancel
+ * signal reaches whichever link would have answered, not just the first one
+ * that asks.
+ */
+export declare function chainAskLinks(links: readonly AskLink[]): AskResolver;