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

package/dist/core/GthAgentRunner.d.ts

@@ -1,8 +1,9 @@
-import { type AllowlistCounts, type ApprovalRung, GthConfig, type McpAnnotationTrustChange, type McpAnnotationTrustView, type ResolvedApprovals, type ToolAnnotationHint } from '#src/config.js';
+import { type AllowlistCounts, type ApprovalRefusal, type ApprovalRefusalLift, type ApprovalRung, GthConfig, type McpAnnotationTrustChange, type McpAnnotationTrustView, type ResolvedApprovals, type ToolAnnotationHint } from '#src/config.js';
 import { BaseCheckpointSaver } from '@langchain/langgraph';
-import { AgentResolvers, AgentStreamEvent, type AttackHaltCallback, GthAgentFactory, GthAgentInterface, GthCommand, GthRunStats, Message, StatusUpdateCallback, ToolApprovalCallback } from '#src/core/types.js';
+import { AgentResolvers, AgentStreamEvent, type ApprovalOutcomeCallback, type AttackHaltCallback, GthAgentFactory, GthAgentInterface, GthCommand, GthRunStats, Message, StatusUpdateCallback, ToolApprovalCallback } from '#src/core/types.js';
 import { type ApprovalGrant } from '#src/core/approvals/grants.js';
 import { type ApprovalDecisionCapture } from '#src/core/shell/approvalCapture.js';
+import { type NegotiationDisplay } from '#src/core/shell/negotiation.js';
 /**
  * EXT-114 — the page describing the `subagents` config key, pointed at rather than paraphrased in
  * the notice itself.
@@ -22,7 +23,15 @@ export interface GthAgentRunnerInitOptions {
      * the mode prompt (`readModePrompt`), the per-command approvals posture (`resolveApprovals`) and
      * the command-specific filesystem config, so a helper agent that must run on the chat prompt —
      * the `gth pr` change-requirements discovery agent — cannot borrow it to say which verb it serves.
-     * Nothing but the wording of a notice reads this.
+     *
+     * **It is read for the wording of a notice, and for one safety decision.** [[EXT-106]] §4.6 asks
+     * whether this run's human messages are the user's own words, and answers it from
+     * `command ?? owningCommand` ({@link import('../config/shell-policy.js').commandCarriesUserProvenance}
+     * at the top of {@link GthAgentRunner#init}) — precisely because a command-less helper agent whose
+     * human turn is content the product FETCHED must not be classified by the absence of a verb. The
+     * key has to be out-of-band metadata like this field: a marker inside the message would be
+     * forgeable by the attacker-controlled text it is supposed to classify. Both that predicate and
+     * the provenance window itself fail closed, so leaving this unset never widens anything.
      */
     owningCommand?: GthCommand;
     /**
@@ -54,6 +63,12 @@ export declare class GthAgentRunner {
      * for non-interactive entrypoints (a scripted `exec` run with no TTY to prompt on).
      */
     private toolApprovalCallback;
+    /**
+     * [[EXT-150]] — consumer hook invoked once per human-answered approval, AFTER the answer has been
+     * recorded, carrying the lifetime it landed with. Set via {@link setApprovalOutcomeCallback}; when
+     * unset the outcome is simply not reported, which is where every surface was before this existed.
+     */
+    private approvalOutcomeCallback;
     /**
      * [[TUI-C68]] §6.1 — consumer hook invoked when the rater rates a command an `attack`, so an
      * interactive surface can show the red banner before the run ends. Set via
@@ -62,6 +77,22 @@ export declare class GthAgentRunner {
      * therefore keeps the halt rather than losing it.
      */
     private attackHaltCallback;
+    /**
+     * [[TUI-C69]] §5.4/§5.5 — **the surface showing this negotiation while it happens**, when one
+     * is. Set via {@link setNegotiationDisplay}.
+     *
+     * Its presence is the answer to *"is anyone watching?"*, and BOTH halves of the visible
+     * negotiation are keyed on it: the rounds are handed over as they are decided, and a negotiated
+     * approval is held on screen for {@link NEGOTIATED_APPROVAL_COOLDOWN_MS} before it takes effect.
+     *
+     * **`null` means neither happens, and that is the point.** An `exec` or CI run has nobody to
+     * show an approval to, so an 800 ms hold there would tax every headless run and every gate for a
+     * display that does not exist. Deliberately NOT keyed on {@link toolApprovalCallback}: that one
+     * answers *"is there a human to ASK"*, a different question with a different answer — a piped
+     * readline session can have one wired and no live display, and the §6.2 non-interactive path has
+     * a display and no one to ask.
+     */
+    private negotiationDisplay;
     /** The command the runner was initialized for; selects which `devTools` config applies. */
     private command;
     /**
@@ -90,12 +121,24 @@ export declare class GthAgentRunner {
      * `undefined` means no profile is configured and the rater uses the session model.
      */
     private raterModel;
+    /**
+     * [[EXT-127]] — the model the ALIGNMENT CHECKER runs on, when `approvals.alignmentChecker` (or, by
+     * its read-site default, `approvals.rater`) names an identity profile. Resolved ONCE at
+     * {@link init}, exactly as {@link raterModel} is; `undefined` means the session model.
+     */
+    private alignmentCheckerModel;
     /**
      * EXT-66 — how many rating calls this session gave up on. Counted so the notice can say "3 times
      * this session" rather than repeating an identical line, and so a silent drift toward
      * escalate-everything has a number attached to it.
      */
     private raterTimeouts;
+    /**
+     * [[EXT-82]] — the consecutive-failure tracker behind the session-level signal, per runner and
+     * therefore per session (the ACP surface runs several at once). See
+     * {@link import('#src/core/shell/raterHealth.js').RaterHealth}.
+     */
+    private readonly raterHealth;
     /**
      * EXT-71 §3.1/§6 — what the escalation menu granted at run time, for the life of THIS runner
      * instance: {@link ApprovalEntry} objects, never prefixes, and never anything from config (the
@@ -117,6 +160,19 @@ export declare class GthAgentRunner {
      */
     private persistedGrants;
     private persistedGrantsLoaded;
+    /**
+     * [[EXT-107]] — the persisted (`always`) **refusal** store, from
+     * `.gsloth/.gsloth-settings/shell-denylist.json`. The mirror of {@link persistedGrants}, and the
+     * reason the menu's most emphatic answer is no longer its most forgetful one.
+     *
+     * Null when the file cannot be loaded at all, in which case an `always` refusal degrades to a
+     * session one. **Not "a re-prompt next session, never an execution":** nothing in the unreadable
+     * file applies to any call, so next session a call it covered is left to the rest of the gate — it
+     * may be refused by another rule, it may be prompted for, or it may run without asking, under
+     * `bypass` or a matching saved allow. The user is told at load time.
+     */
+    private persistedDenials;
+    private persistedDenialsLoaded;
     /**
      * [[EXT-29]] §5 — the state of the agent↔rater negotiation at `auto`: the transcript, §5.3's
      * consecutive-rejection counter and the reachability bound. Instance-scoped for the same reason
@@ -142,6 +198,21 @@ export declare class GthAgentRunner {
      * Without a handler the runner rejects pending tool calls (see {@link toolApprovalCallback}).
      */
     setToolApprovalCallback(callback: ToolApprovalCallback | null): void;
+    /**
+     * [[EXT-150]] — register the handler that is told **what a human's answer actually landed as**.
+     * Pass `null` to clear.
+     *
+     * Separate from {@link setToolApprovalCallback} for the reason {@link setAttackHaltCallback} is
+     * separate: it is a different question asked at a different moment. The approval callback is
+     * consulted *before* anything is written and returns the human's REQUEST; the scope that survives
+     * is decided here afterwards, because [[EXT-149]] degrades an `always` whose write did not reach
+     * disk to the `session` answer it really is. A surface with no way to hear that can only confirm
+     * the key that was pressed — and core's own ERROR naming the unwritten file then contradicts it.
+     *
+     * It reports; it never decides. Nothing downstream reads it, so a surface that ignores it, or
+     * never wires it, changes no behaviour of the gate.
+     */
+    setApprovalOutcomeCallback(callback: ApprovalOutcomeCallback | null): void;
     /**
      * [[TUI-C68]] §6.1 — register the handler that shows the **attack banner**, the one way a human
      * gets past an `attack` verdict. Pass `null` to clear.
@@ -152,6 +223,17 @@ export declare class GthAgentRunner {
      * other surface keeps the halt (see {@link attackHaltCallback}).
      */
     setAttackHaltCallback(callback: AttackHaltCallback | null): void;
+    /**
+     * [[TUI-C69]] §5.4/§5.5 — **declare that this surface is showing the negotiation as it happens.**
+     * Pass `null` to clear.
+     *
+     * §5.4's requirement is not decoration: *"the spec's own justification for letting the agent
+     * argue with the rater at all is that a human can watch it, and an argument conducted in the dark
+     * is a different thing from one that can be interrupted."* Wiring this is a surface saying it
+     * has somewhere to draw that, which is also what makes §5.5's hold meaningful — see
+     * {@link negotiationDisplay} for why one seam carries both.
+     */
+    setNegotiationDisplay(display: NegotiationDisplay | null): void;
     /**
      * §6.1 — **the single seam between an `attack` verdict and the end of the run.** Both rating
      * paths — the §3.2 allow-match tripwire and the ordinary rater decision — go through here, so the
@@ -202,11 +284,56 @@ export declare class GthAgentRunner {
      */
     getAllowlistCounts(): AllowlistCounts;
     /**
-     * CFG-27 — the session's deny entries for display: the declared `approvals.deny` entries
-     * (rendered one line each) followed by whatever the escalation menu's *always reject* added at
-     * run time. Both refuse a call, so both are shown.
+     * CFG-27/[[EXT-107]] — **every refusal in force, and which of the three lists holds it**: the
+     * declared `approvals.deny` entries, the escalation menu's session-scoped refusals, and the ones
+     * saved to the project's deny file.
+     *
+     * The origins are kept apart rather than concatenated into one list of strings, because they have
+     * different lifetimes and different owners and only two of the three can be lifted from here.
+     * A merged list makes {@link liftRefusal} impossible to describe honestly.
+     *
+     * **This is the one list.** {@link liftRefusal} resolves its argument against exactly this
+     * sequence, so the number a user reads and the number they type cannot name different entries.
+     *
+     * Numbering is 1-based, and the order is config → saved → session: the entries a user cannot lift
+     * here come first and stay put, so the numbers of the ones they can are not reshuffled by a
+     * config edit between two renderings.
+     */
+    getRefusals(): ApprovalRefusal[];
+    /**
+     * [[EXT-107]] — the refusals in force with their entries attached, which is what
+     * {@link liftRefusal} needs and {@link getRefusals} renders. ONE builder, so the displayed order
+     * and the removal order are the same order by construction rather than by two functions agreeing.
+     *
+     * A saved refusal is held in both runtime stores ({@link recordDenial} writes both), so the
+     * session list is filtered against the saved one by entry identity — the same de-duplication
+     * {@link getGrants} does. A configured entry is NOT de-duplicated against them: it is a different
+     * thing with a different owner, and hiding it would let a lift report success while the config
+     * line went on refusing the call.
+     */
+    private refusalRecords;
+    /**
+     * [[EXT-107]] — **lift one refusal**, by its number in {@link getRefusals}. The escape hatch, and
+     * the reason persisting a refusal is safe to ship: a saved refusal the user cannot find or undo
+     * is a trap, and the person who hits it first is whoever pressed `[d]` by reflex and needed the
+     * command an hour later. Telling them to delete a file they have not been told exists is not an
+     * answer.
+     *
+     * A saved refusal is removed from the file AND from the in-memory store, because it is in both —
+     * dropping only the file would leave the call refused for the rest of the session by a rule the
+     * display no longer shows.
+     *
+     * **A configured entry is reported, never removed.** `approvals.deny` is something the user
+     * wrote; rewriting their config file out from under them is not a thing a session command may do,
+     * and silently no-oping would be worse. They are told where it lives.
+     *
+     * **`stillSaved` is the deletion that did not reach disk** ([[EXT-149]]). The file rewrite can
+     * fail after the in-memory removal has succeeded — a checkout that is not writable, a settings
+     * directory that has gone — and the entry then comes back in the next session. The store now
+     * answers that question ({@link PersistedApprovalGrants.remove}) instead of reporting every
+     * removal as landed, so the notice can stop promising *it will not come back*.
      */
-    getDenylist(): string[];
+    liftRefusal(index: number): ApprovalRefusalLift;
     /**
      * §3/§4.7.4 — **the grants themselves**, for an approvals view that shows *what* was granted,
      * *when*, and *under which effective annotations*. The counterpart of {@link getAllowlistCounts},
@@ -424,6 +551,88 @@ export declare class GthAgentRunner {
      * whenever the shell gate is on, so §2.5's rule that the deny list survives `bypass` is untouched.)
      */
     private decideToolApproval;
+    /**
+     * [[EXT-29]] §5.3 / [[TUI-C69]] §5.4 — **a person was reached, so the exchange is over**: the
+     * gate's own transcript is spent and the surface showing it is told, on the same event.
+     *
+     * Every direct `humanReached()` in this class goes through here, which is what keeps the two from
+     * drifting: a new site that spent the transcript without telling the display would leave a
+     * finished argument standing on screen, and at an escalation it would put the same exchange on an
+     * unscrollable dialog twice — once live, once in the prompt about to render all of it.
+     */
+    private endNegotiation;
+    /**
+     * [[TUI-C69]] §5.4 — **take the finished argument off the screen WITHOUT spending the gate's
+     * transcript.**
+     *
+     * The two are separate on purpose. `humanReached()` clears the rounds *and* the reachability
+     * bound, which is correct only when a person was actually reached; calling it merely to tidy the
+     * panel would hand the agent a fresh {@link MAX_REJECTIONS_BEFORE_HUMAN} budget it had already
+     * spent, turning a display concern into a way to argue indefinitely. [[EXT-108]] made an approved
+     * call stop clearing the transcript for exactly this reason, so the tidy-up cannot be the thing
+     * that puts it back.
+     *
+     * Guarded, like {@link showNegotiationRound}: a surface that throws while clearing must never
+     * change what the gate decided, or become the reason a turn ends.
+     */
+    private clearNegotiationDisplay;
+    /**
+     * [[TUI-C69]] §5.4 — **tell the agent to forget the tool-call ids the rater bounced**, on every
+     * event that ends a turn's display state: a new turn, and `/clear`.
+     *
+     * The runner decides *when* because it owns the turn boundary; the agent holds the set because it
+     * owns the rendering. Fail-soft in the shape {@link resetRunStats} uses — an agent without the
+     * method (a test double, a renderer-less agent) is simply skipped, and a tone hint must never be
+     * the reason a turn fails to start.
+     */
+    private clearRaterClarifications;
+    /**
+     * [[TUI-C69]] §5.4 — **hand one round of the argument to the surface that is showing it**, the
+     * moment the gate decided it.
+     *
+     * The round travels raw. Every surface lays it out from the SAME rows the escalation prompt
+     * draws, at its own terminal width, so the rounds a person watches and the rounds they later rule
+     * on cannot be two different renderings of one exchange — and the rater's turns are yellow in
+     * both because the rows carry the voice rather than a colour.
+     *
+     * No-ops when no surface is watching, which is the §5.5 seam as well as this one.
+     */
+    private showNegotiationRound;
+    /**
+     * [[TUI-C69]] §5.4/§5.5 — **the rater agreeing is the last round of the argument, and it is held
+     * on screen before it takes effect.**
+     *
+     * Two things, in this order, because the order is the requirement: the approving round is drawn,
+     * and only then does the minimum visible interval run. A hold before the draw would be a pause
+     * over nothing.
+     *
+     * **It is a visibility pause, not a reading window**, and it must never be relied on as an
+     * opportunity to evaluate the command — nobody reads a command in 800 ms. What it buys is that
+     * the approving round is on screen as its own event instead of being overwritten by the tool
+     * output that follows it immediately.
+     *
+     * **What it is NOT, on either surface, is a guaranteed abort window — do not restore that claim
+     * without building the mechanism.** Stated precisely, because the previous wording asserted a
+     * mechanism that is not here and a comment like that stops the next reader checking:
+     *
+     * - **Event/TUI path.** An abort raised during the hold does end the run with the tool unrun, but
+     *   *this code is not why*. The runner never re-checks the signal after the hold — it issues the
+     *   approving resume regardless — and what stops the tool is that LangGraph refuses an
+     *   already-aborted signal downstream. True today, and true by someone else's invariant.
+     * - **Plain/readline path.** Not true at all. `resolveToolInterrupts` threads no signal, and
+     *   `waitForEscape` is armed inside `streamFromInput` and torn down before the hold begins — the
+     *   hold happens *between* streams. Esc during it is not handled, so the command runs. The pause
+     *   still buys the visibility above, which is why it is not conditioned on the surface.
+     *
+     * Making the affordance real by construction — checking the signal here, and threading one into
+     * the readline path so there is something to check — is deliberately left out of scope rather
+     * than half-built, since a window honoured on one surface and not the other is the more dangerous
+     * shape: it is what teaches the user the gesture that then silently fails.
+     *
+     * **Both halves are gated on a surface being wired**, so a headless `exec`/CI run neither draws
+     * nor sleeps and pays nothing. See {@link negotiationDisplay}.
+     */
+    private showNegotiatedApproval;
     /**
      * [[TUI-C27]] — {@link decideToolApprovalInner} with the record closed off on EVERY exit.
      *
@@ -435,6 +644,17 @@ export declare class GthAgentRunner {
     private recordedDecision;
     /** The decision itself; {@link decideToolApproval} wraps it with §5.3's reset. */
     private decideToolApprovalInner;
+    /**
+     * [[EXT-150]] — tell the surface what its own answer landed as, and hand the decision straight
+     * back.
+     *
+     * A one-liner returning the decision, exactly as {@link stage} is, and for the identical reason:
+     * the report happens ON the return that carries the decision rather than on the line above it, so
+     * no early return can later be inserted between the two and leave a surface waiting for an answer
+     * that never comes. There is one return out of {@link decideToolApprovalInner} after the callback
+     * is awaited, and this is it.
+     */
+    private reportOutcome;
     /**
      * [[TUI-C27]] — attribute the deciding stage and hand the decision straight back.
      *
@@ -449,6 +669,23 @@ export declare class GthAgentRunner {
      * only in what they do with the answer.
      */
     private rateCommand;
+    /**
+     * [[EXT-127]] — **one alignment check**, with the `user` role fed from the settled provenance
+     * channel and nothing else.
+     *
+     * **`provenance` is `ShellNegotiationState.retainedUserMessages()`, read ONCE by the caller and
+     * handed down**, exactly as §4.6's floor reads it. Three things are true of it and only of it: it
+     * is EMPTY until `admitUserProvenance` positively established that this session's human turns are
+     * the user's own words (so `review` and `pr`, which fold a fetched diff into a human message,
+     * contribute nothing); it is not `noteUserMessages`' raw store, which answers a different question
+     * for a different reader; and it is not `humanMessageTexts`, the unfiltered upstream. Reading any
+     * of the other three here would make the one place this design says provenance is structural the
+     * one place it is not.
+     *
+     * The prior rounds come from the transcript's own alignment decisions, so the checker meets its
+     * earlier turns as its own turns rather than as a quoted summary of them.
+     */
+    private checkAlignment;
     /**
      * EXT-58 (§4.3/§4.4) — the built-in tools already granted at the session's CURRENT rung, as
      * names plus one-line locally-authored descriptions, for the rater prompt.
@@ -488,6 +725,25 @@ export declare class GthAgentRunner {
      * knows how to reach the user.
      */
     private getPersistedGrants;
+    /**
+     * [[EXT-107]] — lazily load (once per instance) the persisted **refusal** store, the mirror of
+     * {@link getPersistedGrants}. Returns null when it cannot be loaded at all, in which case an
+     * `always` refusal degrades to `session`.
+     *
+     * **No `bypass` guard, and no v1 migration**, and the two are the same decision. The allow side
+     * skips the file at `bypass` so a session with the gate switched off neither reads nor *rewrites*
+     * the project's grants; the only thing that rewrites on load is the v1 `prefixes` migration, and
+     * turning it off here makes this store's load a pure read. That is what lets it be consulted at
+     * every rung — which it must be, because a refusal is resolved before the `bypass` return and a
+     * saved refusal that lapsed when the gate was relaxed would be worthless.
+     *
+     * It is also loaded by the `/approvals` DISPLAY, unlike its allow-side twin. The rule there — a
+     * display must not create the store in order to show it — is a rule about writing, and this load
+     * cannot write. The reason to break the symmetry is that the display is the escape hatch: a saved
+     * refusal a user cannot see is one they cannot lift, and a fresh session has made no gated call
+     * yet.
+     */
+    private getPersistedDenials;
     /**
      * §3.1/§4.7.4/§6 — **the grant a sticky choice would write for this call**, or `undefined` when
      * none is on offer. The one place that question is answered, so the menu's *this is what will be
@@ -560,7 +816,7 @@ export declare class GthAgentRunner {
      * - **`run_shell_command` arriving as a TOOL subject gets a tool entry** — a shell call whose
      *   `command` argument cannot even be read. On the allow side that entry would auto-approve every
      *   future unreadable shell call, which is why it is excluded there; as a refusal it stops the
-     *   shell tool for the session, and the dialog says so in the words the entry is written in.
+     *   shell tool outright, and the dialog says so in the words the entry is written in.
      *
      * The one genuine exclusion is an **MCP call whose server could not be attributed**
      * ({@link toolGrantEntry} returns `null`): the grammar's `server` cannot be the empty string, so
@@ -570,16 +826,38 @@ export declare class GthAgentRunner {
      */
     private denyEntryFor;
     /**
-     * §6 — record the menu's *always reject* choice, for the life of this runner instance.
-     *
-     * It lands in the same store `approvals.deny` entries are matched from ({@link approvalRuleLists}
-     * concatenates the two), so a refusal the human made at the prompt and one they wrote in their
-     * config are one list to the matcher and one list to `/approvals`.
-     *
-     * **Session-lifetime, and there is nothing else to choose.** There is no persisted deny file;
-     * whether there should be is a question about a file users live with, not about this prompt. What
-     * the surfaces must not do is say otherwise — a confirmation promising a persistence that did not
-     * happen is §6's *offered and then refused* with the evidence hidden.
+     * §6/[[EXT-107]] — record the menu's *always reject* choice at the given scope. `once` remembers
+     * nothing; `session` holds the refusal for the life of this runner instance; `always` additionally
+     * writes it to the project's deny file, so it is still in force after a restart.
+     *
+     * It lands in the same lists `approvals.deny` entries are matched from ({@link approvalRuleLists}
+     * concatenates the three), so a refusal the human made at the prompt and one they wrote in their
+     * config are one list to the matcher.
+     *
+     * **The recorded scope is derived from whether the entry REACHED THE FILE** ([[EXT-149]]) — what
+     * {@link PersistedApprovalGrants.add} returns — and not from whether the store was allowed to try.
+     * Those differ on a read-only checkout, where the file is simply absent, so the load did not fail,
+     * `canPersist()` is true, and every write throws: asking permission stamped `always` on an answer
+     * that reached no disk, and nothing told the user. **Do not describe that gap's cost as "one
+     * re-prompt next session":** the entry is not on disk, so next session it applies to nothing and
+     * the call is left to the rest of the gate — another rule may refuse it, it may be prompted for,
+     * or it may run without asking under `bypass` or a matching saved allow.
+     *
+     * **Two records, not one patched afterwards.** {@link ApprovalGrantStore.add} holds the very
+     * object it is handed whenever the grant carries no annotation snapshot — which every refusal
+     * does, since {@link denyEntryFor} builds an entry and never a snapshot — so stamping one object
+     * `always` and correcting it after the write would reach inside whatever {@link denyGrants}
+     * already holds and whatever the display renders from it. The persisted store is handed the
+     * `always` record it will hold if the write lands (and takes back if it does not); the session
+     * store is handed its own record, stamped from the answer.
+     *
+     * The persisted store is still told even when it cannot write, because telling it is what reports
+     * the refused or failed write to the user, and it declines to hold what it did not write.
+     *
+     * **It RETURNS the lifetime it recorded** ([[EXT-150]]) — the same value it stamps the record with,
+     * handed back rather than left for a caller to re-derive. The surface that asked has to say what
+     * happened, and re-deriving it there would put the "did the write land" question in two places
+     * that could come to disagree, which is the whole failure this and [[EXT-149]] are about.
      */
     private recordDenial;
     /**
@@ -589,6 +867,24 @@ export declare class GthAgentRunner {
      *
      * What is recorded was decided by {@link stickyGrantFor} and shown to the human before they
      * answered; this only stamps it with when and at what scope.
+     *
+     * **The stamped scope says whether this grant REACHED THE FILE**, the mirror of
+     * {@link recordDenial} and derived the same way ([[EXT-149]]): an `always` whose store is absent,
+     * whose file could not be read and so must not be rewritten ([[EXT-144]]), or whose write threw on
+     * a checkout nothing can write, is recorded as the `session` grant it actually is — and the store
+     * reports the last of those rather than swallowing it.
+     *
+     * Two records rather than one patched afterwards, for the reason argued in {@link recordDenial}:
+     * {@link ApprovalGrantStore.add} holds the object it is handed for a grant with no annotation
+     * snapshot — every shell grant — so a scope corrected after the write would be corrected inside
+     * {@link sessionGrants}.
+     *
+     * The store is still loaded only for `always`, unchanged: a display must not create the file in
+     * order to show it, and a `session` grant has no business opening it.
+     *
+     * **It RETURNS the lifetime it recorded** ([[EXT-150]]), the mirror of {@link recordDenial} and for
+     * the same reason: the surface's confirmation is written from this value rather than from the key
+     * the human pressed.
      */
     private recordApproval;
     /**