approval-md 0.2.0 → 0.4.0

package/dist/src/core/harness-wait.d.ts

@@ -2,13 +2,16 @@
  * How long a harness hook waits, and how long the question it opened outlives
  * that wait (APRV-287).
  *
- * Two numbers with two readers each, which is the whole reason they live here
- * rather than beside either one. `cli/hook.ts` uses them to decide when a
- * request it opened has been abandoned; `cli/channel-telegram.ts` uses the wait
+ * Three numbers with two readers each, which is the whole reason they live
+ * here rather than beside any one of them. `cli/hook.ts` uses them to decide
+ * when a request it opened has been abandoned; `cli/channel-telegram.ts` uses the wait
  * to decide which pending requests on a listener's first cycle are stale enough
  * to collapse into one message. Two copies of the same duration would be two
  * answers to "is anybody still waiting on this", and the channel would collapse
  * questions the hook was still holding open, or leave a dead queue on a phone.
+ * The third, APRV-423's margin, is read by the hook (which refuses a harness
+ * ceiling too short to hold a human's answer) and by `core/state.ts` (which
+ * judges every request against the window that ceiling leaves).
  *
  * Nothing here reads a clock, a policy or the log: these are durations, and
  * every judgment made with them is made by a caller that already holds the
@@ -53,3 +56,79 @@ export declare const HOOK_RETRY_GRACE_MS: number;
  * caller states about when it started waiting.
  */
 export declare function abandonedAfterMs(waitMs: number, graceMs: number): number;
+/**
+ * How far below a harness's own timeout a hook-originated request must lapse
+ * (APRV-423).
+ *
+ * A harness bounds the hook process: Hermes caps a `pre_tool_call` entry at
+ * 300 s, Claude Code kills the hook at the `timeout` in its settings file, and
+ * every one of them treats the killed process as a NON-BLOCKING error and runs
+ * the tool call. So when the harness gives up first the hook is already gone,
+ * the request is still pending on somebody's phone, and the tap that arrives
+ * afterwards is recorded as a grant on a call nobody holds (APRV-410, observed
+ * 2026-09-20). The two records then disagree about the same moment: one says
+ * denied, the other says approved.
+ *
+ * The fix is to make the question end BEFORE the process that asked it does,
+ * and this is the distance between the two. It is 60 s because the daemon's
+ * TTL sweep runs on a 30 s interval (`daemon/daemon.ts`'s
+ * `DEFAULT_INTERVAL_MS`): a request that lapses one millisecond after a sweep
+ * waits a whole interval for the next one, so a margin of two intervals leaves
+ * the `approval.expired` append a full tick of room in the common case, and it
+ * lands inside the cap. Anything smaller would make the ordering this task is
+ * about depend on where in the sweep cycle the lapse fell.
+ *
+ * The common case, and not a guarantee. `Daemon.tick` skips a sweep when the
+ * previous tick is still running, and the request record's `ts` is stamped at
+ * the write boundary, some intake latency after the harness spawned the hook,
+ * so the cap runs from an instant slightly before the one the margin counts
+ * from. An overrunning tick plus a slow intake can put the `approval.expired`
+ * record after the kill. What keeps a late tap safe regardless is not this
+ * margin but the lazy refusal: `core/state.ts` judges the lapse by arithmetic
+ * whether or not the record exists, so `decide` refuses the tap `expired` and
+ * materialises the record then. The margin buys the ORDERING in the common
+ * case, so the two records agree without a human ever seeing the disagreement;
+ * the refusal is what makes the grant impossible in every case.
+ *
+ * It is a floor on the cap as well as a subtraction from it. A cap at or below
+ * the margin leaves no window in which a human could answer at all: `cli/hook.ts`
+ * refuses such a configuration rather than opening a question that is already
+ * dead, and `schema/event.schema.json` refuses a record carrying one at the
+ * write boundary (its `minimum` is this constant plus one, pinned equal by
+ * `tests/harness-cap-ttl.test.ts`).
+ */
+export declare const HARNESS_CAP_MARGIN_MS = 60000;
+/**
+ * The deadline a hook-originated request is judged by: the SHORTER of the
+ * policy's TTL and the harness's cap minus {@link HARNESS_CAP_MARGIN_MS}
+ * (APRV-423).
+ *
+ * `null` means no deadline, exactly as `defaults.approval_ttl`'s absence means
+ * it (SPEC.md §6): nothing lapses, and no duration is invented for a policy
+ * that declared none.
+ *
+ * **The cap may only shorten.** It is a self-reported field (the hook states
+ * the ceiling its own harness runs it under), and SPEC.md §11.1 invariant 4
+ * says such a field never reduces scrutiny. Recording it raw and taking the
+ * minimum HERE is what makes that structural: a cap larger than the policy TTL
+ * changes nothing, a cap of an hour under a one-minute TTL changes nothing, and
+ * the only direction a requester can move its own deadline is earlier. The same
+ * shape as `core/gate-window.ts`'s `expires_at`, which clamps a claimed window
+ * against the derived one for the same reason.
+ *
+ * A cap that does not clear the margin yields `0`, which reads as lapsed from
+ * the instant the request is written. That is the fail-closed answer for a
+ * harness whose ceiling leaves no room for a human, and it is unreachable
+ * through the write path: the hook refuses the configuration before it
+ * appends, and the event schema refuses the record for any caller that did
+ * not come through the hook.
+ */
+export declare function harnessCappedTtlMs(policyTtlMs: number | null, capMs: number | null): number | null;
+/**
+ * Does `capMs` leave a window a human could answer in?
+ *
+ * The one question `cli/hook.ts` asks before it opens a request under a cap.
+ * Strictly greater: a cap EQUAL to the margin yields a zero-length window,
+ * which is a question that expires as it is asked.
+ */
+export declare function harnessCapFitsMargin(capMs: number): boolean;

package/dist/src/core/harness-wait.js

@@ -2,13 +2,16 @@
  * How long a harness hook waits, and how long the question it opened outlives
  * that wait (APRV-287).
  *
- * Two numbers with two readers each, which is the whole reason they live here
- * rather than beside either one. `cli/hook.ts` uses them to decide when a
- * request it opened has been abandoned; `cli/channel-telegram.ts` uses the wait
+ * Three numbers with two readers each, which is the whole reason they live
+ * here rather than beside any one of them. `cli/hook.ts` uses them to decide
+ * when a request it opened has been abandoned; `cli/channel-telegram.ts` uses the wait
  * to decide which pending requests on a listener's first cycle are stale enough
  * to collapse into one message. Two copies of the same duration would be two
  * answers to "is anybody still waiting on this", and the channel would collapse
  * questions the hook was still holding open, or leave a dead queue on a phone.
+ * The third, APRV-423's margin, is read by the hook (which refuses a harness
+ * ceiling too short to hold a human's answer) and by `core/state.ts` (which
+ * judges every request against the window that ceiling leaves).
  *
  * Nothing here reads a clock, a policy or the log: these are durations, and
  * every judgment made with them is made by a caller that already holds the
@@ -55,4 +58,87 @@ export const HOOK_RETRY_GRACE_MS = 5 * 60_000;
 export function abandonedAfterMs(waitMs, graceMs) {
     return Math.max(0, waitMs) + Math.max(0, graceMs);
 }
+/**
+ * How far below a harness's own timeout a hook-originated request must lapse
+ * (APRV-423).
+ *
+ * A harness bounds the hook process: Hermes caps a `pre_tool_call` entry at
+ * 300 s, Claude Code kills the hook at the `timeout` in its settings file, and
+ * every one of them treats the killed process as a NON-BLOCKING error and runs
+ * the tool call. So when the harness gives up first the hook is already gone,
+ * the request is still pending on somebody's phone, and the tap that arrives
+ * afterwards is recorded as a grant on a call nobody holds (APRV-410, observed
+ * 2026-09-20). The two records then disagree about the same moment: one says
+ * denied, the other says approved.
+ *
+ * The fix is to make the question end BEFORE the process that asked it does,
+ * and this is the distance between the two. It is 60 s because the daemon's
+ * TTL sweep runs on a 30 s interval (`daemon/daemon.ts`'s
+ * `DEFAULT_INTERVAL_MS`): a request that lapses one millisecond after a sweep
+ * waits a whole interval for the next one, so a margin of two intervals leaves
+ * the `approval.expired` append a full tick of room in the common case, and it
+ * lands inside the cap. Anything smaller would make the ordering this task is
+ * about depend on where in the sweep cycle the lapse fell.
+ *
+ * The common case, and not a guarantee. `Daemon.tick` skips a sweep when the
+ * previous tick is still running, and the request record's `ts` is stamped at
+ * the write boundary, some intake latency after the harness spawned the hook,
+ * so the cap runs from an instant slightly before the one the margin counts
+ * from. An overrunning tick plus a slow intake can put the `approval.expired`
+ * record after the kill. What keeps a late tap safe regardless is not this
+ * margin but the lazy refusal: `core/state.ts` judges the lapse by arithmetic
+ * whether or not the record exists, so `decide` refuses the tap `expired` and
+ * materialises the record then. The margin buys the ORDERING in the common
+ * case, so the two records agree without a human ever seeing the disagreement;
+ * the refusal is what makes the grant impossible in every case.
+ *
+ * It is a floor on the cap as well as a subtraction from it. A cap at or below
+ * the margin leaves no window in which a human could answer at all: `cli/hook.ts`
+ * refuses such a configuration rather than opening a question that is already
+ * dead, and `schema/event.schema.json` refuses a record carrying one at the
+ * write boundary (its `minimum` is this constant plus one, pinned equal by
+ * `tests/harness-cap-ttl.test.ts`).
+ */
+export const HARNESS_CAP_MARGIN_MS = 60_000;
+/**
+ * The deadline a hook-originated request is judged by: the SHORTER of the
+ * policy's TTL and the harness's cap minus {@link HARNESS_CAP_MARGIN_MS}
+ * (APRV-423).
+ *
+ * `null` means no deadline, exactly as `defaults.approval_ttl`'s absence means
+ * it (SPEC.md §6): nothing lapses, and no duration is invented for a policy
+ * that declared none.
+ *
+ * **The cap may only shorten.** It is a self-reported field (the hook states
+ * the ceiling its own harness runs it under), and SPEC.md §11.1 invariant 4
+ * says such a field never reduces scrutiny. Recording it raw and taking the
+ * minimum HERE is what makes that structural: a cap larger than the policy TTL
+ * changes nothing, a cap of an hour under a one-minute TTL changes nothing, and
+ * the only direction a requester can move its own deadline is earlier. The same
+ * shape as `core/gate-window.ts`'s `expires_at`, which clamps a claimed window
+ * against the derived one for the same reason.
+ *
+ * A cap that does not clear the margin yields `0`, which reads as lapsed from
+ * the instant the request is written. That is the fail-closed answer for a
+ * harness whose ceiling leaves no room for a human, and it is unreachable
+ * through the write path: the hook refuses the configuration before it
+ * appends, and the event schema refuses the record for any caller that did
+ * not come through the hook.
+ */
+export function harnessCappedTtlMs(policyTtlMs, capMs) {
+    if (capMs === null)
+        return policyTtlMs;
+    const fromCap = Math.max(0, capMs - HARNESS_CAP_MARGIN_MS);
+    return policyTtlMs === null ? fromCap : Math.min(policyTtlMs, fromCap);
+}
+/**
+ * Does `capMs` leave a window a human could answer in?
+ *
+ * The one question `cli/hook.ts` asks before it opens a request under a cap.
+ * Strictly greater: a cap EQUAL to the margin yields a zero-length window,
+ * which is a question that expires as it is asked.
+ */
+export function harnessCapFitsMargin(capMs) {
+    return capMs > HARNESS_CAP_MARGIN_MS;
+}
 //# sourceMappingURL=harness-wait.js.map

package/dist/src/core/harness-wait.js.map

@@ -1 +1 @@
-{"version":3,"file":"harness-wait.js","sourceRoot":"","sources":["../../../src/core/harness-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEvC,iDAAiD;AACjD,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAG,MAAM,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,OAAe;IAC9D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AACpD,CAAC"}
+{"version":3,"file":"harness-wait.js","sourceRoot":"","sources":["../../../src/core/harness-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEvC,iDAAiD;AACjD,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAG,MAAM,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,OAAe;IAC9D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,kBAAkB,CAChC,WAA0B,EAC1B,KAAoB;IAEpB,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,WAAW,CAAC;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,qBAAqB,CAAC,CAAC;IAC3D,OAAO,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AACzE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,OAAO,KAAK,GAAG,qBAAqB,CAAC;AACvC,CAAC"}

package/dist/src/core/instance.d.ts

@@ -47,7 +47,7 @@
  * secret and is not derived from one — it is a hash of a directory path, which
  * `.approval/env` already carries in the open.
  */
-import { type ResolvedVariable } from "./env-file.js";
+import { type ResolvedVariable, type SourceRunner } from "./env-file.js";
 import type { PolicyLoadResult } from "./policy-load.js";
 /**
  * The unscoped item names this project used before APRV-178.
@@ -59,6 +59,12 @@ import type { PolicyLoadResult } from "./policy-load.js";
 export declare const LEGACY_SERVICE_TELEGRAM_TOKEN = "approval-tg-token";
 export declare const LEGACY_SERVICE_VAULT_PASSPHRASE = "approval-vault-passphrase";
 export declare const LEGACY_SERVICE_SAMPLING_SECRET = "approval-sampling-secret";
+/**
+ * The sender key (APRV-370). Born scoped, so it has no legacy instance to be a
+ * fallback for; it sits in this list because the naming rule is the list's, and
+ * a name minted outside it is a name `approval env --check` reports as unknown.
+ */
+export declare const SERVICE_SENDER_KEY = "approval-sender-key";
 /** Every unscoped name, for the "is this the legacy one?" test. */
 export declare const LEGACY_SERVICES: readonly string[];
 /** How many hex digits of the digest a scoped name carries. */
@@ -196,8 +202,16 @@ export declare function parseEnvProvenance(raw: string | undefined): EnvProvenan
  *   half of the incident that survived fixing the file: the operator's rc
  *   exported the production token, so every fresh terminal kept using the
  *   production bot.
+ * - `stale-export` — the value in this shell is NOT what this instance's file
+ *   resolves to today (APRV-390). The name-only rules above cannot see this at
+ *   all, and it is the case that actually cost an evening: a token re-stored in
+ *   the keychain does not reach a shell that exported the old one, because
+ *   `approval env` never overrides a variable that is already set. The daemon
+ *   then answered 401 while the keychain item behind the same line passed
+ *   `getMe` by hand. Only {@link valueFindings} produces it, because only that
+ *   function is allowed to read a value.
  */
-export type InstanceFindingKind = "foreign-instance" | "legacy-shared" | "ambient-bleed";
+export type InstanceFindingKind = "foreign-instance" | "legacy-shared" | "ambient-bleed" | "stale-export";
 export interface InstanceFinding {
     kind: InstanceFindingKind;
     /** The environment variable the finding is about. */
@@ -249,5 +263,48 @@ export interface FindingsContext {
  * env --check` and `approval up` to say different things about one shell.
  */
 export declare function ownEnvExports(logPath: string, context?: FindingsContext): ReadonlySet<string>;
+/**
+ * The same question, answered by COMPARING VALUES (APRV-390).
+ *
+ * ## Why a second function, and why only start-up may call it
+ *
+ * Everything above answers from names, so that a diagnostic never blocks on a
+ * keystore-unlock dialog ({@link NON_RESOLVING_RUNNER}). That constraint is
+ * right for `approval doctor` and wrong for the thing `approval up` is about to
+ * do, which is USE the value. Two cases observed on 2026-09-19 are invisible to
+ * every name-only rule:
+ *
+ * 1. **A stale export.** `approval env` never overrides a variable already set
+ *    in the shell — that is invariant 7 working as designed — so a token
+ *    re-stored in the keychain never reaches a terminal that exported the old
+ *    one. The names agree, the file is this instance's, the provenance claim is
+ *    this instance's own, and the value is wrong. The daemon got 401 from a
+ *    token that passed `getMe` when read from the keychain by hand.
+ * 2. **A false positive on the correct ritual.** `APPROVAL_HUMAN` was reported
+ *    cross-instance when the export came from this instance's own `eval
+ *    "$(approval env)"` seconds earlier, because the provenance claim did not
+ *    match. A finding about a value that IS the file's value is noise, and
+ *    noise in a refusal is how a refusal gets overridden by habit.
+ *
+ * Comparing answers both: a value equal to what the file resolves to is
+ * correct however it got there, and a value that differs is wrong however
+ * honest its provenance looks.
+ *
+ * ## What it does with the values
+ *
+ * It compares them and drops them. Nothing is printed, returned, logged or put
+ * in a message on any path — every finding this produces carries a variable
+ * name, a file path and a line number, exactly like the name-only ones. The
+ * only new capability is answering "same or different".
+ *
+ * ## Where it fails soft, and in which direction
+ *
+ * A file entry that cannot be resolved (a locked keychain, a helper that is not
+ * installed, a `secret-tool` with no D-Bus) yields no comparison, and the
+ * name-only finding for that variable stands unchanged. That is the safe
+ * direction: an unverifiable value keeps whatever scrutiny it already had, and
+ * a caller that cannot resolve anything gets exactly the pre-APRV-390 report.
+ */
+export declare function valueFindings(logPath: string, load: PolicyLoadResult, runner: SourceRunner, ambientEnv?: NodeJS.ProcessEnv): InstanceFinding[];
 /** The name-only rules, over an already-resolved variable set. */
 export declare function findingsFor(logPath: string, variables: readonly ResolvedVariable[], context?: FindingsContext): InstanceFinding[];

package/dist/src/core/instance.js

@@ -60,11 +60,18 @@ import { NON_RESOLVING_RUNNER, envFilePathFor, resolveEnvironment, } from "./env
 export const LEGACY_SERVICE_TELEGRAM_TOKEN = "approval-tg-token";
 export const LEGACY_SERVICE_VAULT_PASSPHRASE = "approval-vault-passphrase";
 export const LEGACY_SERVICE_SAMPLING_SECRET = "approval-sampling-secret";
+/**
+ * The sender key (APRV-370). Born scoped, so it has no legacy instance to be a
+ * fallback for; it sits in this list because the naming rule is the list's, and
+ * a name minted outside it is a name `approval env --check` reports as unknown.
+ */
+export const SERVICE_SENDER_KEY = "approval-sender-key";
 /** Every unscoped name, for the "is this the legacy one?" test. */
 export const LEGACY_SERVICES = [
     LEGACY_SERVICE_TELEGRAM_TOKEN,
     LEGACY_SERVICE_VAULT_PASSPHRASE,
     LEGACY_SERVICE_SAMPLING_SECRET,
+    SERVICE_SENDER_KEY,
 ];
 /** How many hex digits of the digest a scoped name carries. */
 export const INSTANCE_ID_LENGTH = 8;
@@ -265,6 +272,112 @@ export function ownEnvExports(logPath, context = {}) {
     const view = provenanceView(logPath, context);
     return view.claimsThisFile ? view.names : new Set();
 }
+/**
+ * The same question, answered by COMPARING VALUES (APRV-390).
+ *
+ * ## Why a second function, and why only start-up may call it
+ *
+ * Everything above answers from names, so that a diagnostic never blocks on a
+ * keystore-unlock dialog ({@link NON_RESOLVING_RUNNER}). That constraint is
+ * right for `approval doctor` and wrong for the thing `approval up` is about to
+ * do, which is USE the value. Two cases observed on 2026-09-19 are invisible to
+ * every name-only rule:
+ *
+ * 1. **A stale export.** `approval env` never overrides a variable already set
+ *    in the shell — that is invariant 7 working as designed — so a token
+ *    re-stored in the keychain never reaches a terminal that exported the old
+ *    one. The names agree, the file is this instance's, the provenance claim is
+ *    this instance's own, and the value is wrong. The daemon got 401 from a
+ *    token that passed `getMe` when read from the keychain by hand.
+ * 2. **A false positive on the correct ritual.** `APPROVAL_HUMAN` was reported
+ *    cross-instance when the export came from this instance's own `eval
+ *    "$(approval env)"` seconds earlier, because the provenance claim did not
+ *    match. A finding about a value that IS the file's value is noise, and
+ *    noise in a refusal is how a refusal gets overridden by habit.
+ *
+ * Comparing answers both: a value equal to what the file resolves to is
+ * correct however it got there, and a value that differs is wrong however
+ * honest its provenance looks.
+ *
+ * ## What it does with the values
+ *
+ * It compares them and drops them. Nothing is printed, returned, logged or put
+ * in a message on any path — every finding this produces carries a variable
+ * name, a file path and a line number, exactly like the name-only ones. The
+ * only new capability is answering "same or different".
+ *
+ * ## Where it fails soft, and in which direction
+ *
+ * A file entry that cannot be resolved (a locked keychain, a helper that is not
+ * installed, a `secret-tool` with no D-Bus) yields no comparison, and the
+ * name-only finding for that variable stands unchanged. That is the safe
+ * direction: an unverifiable value keeps whatever scrutiny it already had, and
+ * a caller that cannot resolve anything gets exactly the pre-APRV-390 report.
+ */
+export function valueFindings(logPath, load, runner, ambientEnv = process.env) {
+    const envPath = envFilePathFor(logPath);
+    const named = instanceFindings(logPath, load, ambientEnv);
+    // EVERY variable whose value came from the shell and whose file has a line
+    // for it — not only the ones the name-only rule complained about.
+    //
+    // This is the correction that matters, and the reason the set is not taken
+    // from `named`. The provenance claim (APRV-278) vouches for an export by
+    // naming this instance, this file's DIGEST and this variable, and all three
+    // stay true when the file is untouched and the KEYSTORE ITEM behind one of
+    // its lines is re-stored. The claim is honest and the value is stale, so the
+    // vouched variables are exactly the ones this check must still look at.
+    const nameOnly = resolveEnvironment(load, envPath, NON_RESOLVING_RUNNER, ambientEnv);
+    if (!nameOnly.ok)
+        return named;
+    const ambientNames = new Set(nameOnly.variables
+        .filter((variable) => variable.status === "set-in-environment" && variable.fileSource !== undefined)
+        .map((variable) => variable.name));
+    if (ambientNames.size === 0)
+        return named;
+    // Resolve the FILE, by hiding exactly those names from the resolution: the
+    // ambient environment wins otherwise, and the answer would be the value we
+    // are trying to check. Nothing here is exported — this process's own
+    // environment is untouched, so invariant 7 is as true after this call as
+    // before it. The file cannot SET anything; it can only fail to match.
+    const hidden = { ...ambientEnv };
+    for (const name of ambientNames)
+        delete hidden[name];
+    const fromFile = resolveEnvironment(load, envPath, runner, hidden);
+    if (!fromFile.ok)
+        return named;
+    const fileValues = new Map();
+    for (const variable of fromFile.variables) {
+        if (variable.value !== undefined && variable.status !== "set-in-environment") {
+            fileValues.set(variable.name, variable.value);
+        }
+    }
+    // Everything the name-only rule found that is NOT about an ambient value: a
+    // foreign item name and a legacy shared one are facts about names, and no
+    // comparison of values can make either of them go away.
+    const findings = named.filter((finding) => finding.kind !== "ambient-bleed");
+    for (const name of ambientNames) {
+        const fileValue = fileValues.get(name);
+        const ambientValue = ambientEnv[name];
+        // Unresolvable (a locked keychain, a missing helper, a missing item): no
+        // comparison was made, so whatever the name-only rule said still stands.
+        if (fileValue === undefined) {
+            const bleed = named.find((finding) => finding.kind === "ambient-bleed" && finding.variable === name);
+            if (bleed !== undefined)
+                findings.push(bleed);
+            continue;
+        }
+        // The shell holds exactly what the file configures. Correct, however it got
+        // there, and whatever the provenance claim did or did not say.
+        if (ambientValue === fileValue)
+            continue;
+        findings.push({
+            kind: "stale-export",
+            variable: name,
+            detail: `${name} is exported in this shell with a value that is NOT what ${envPath} resolves to today, and an export always wins over the file, so this process would use the stale one`,
+        });
+    }
+    return findings;
+}
 /** The name-only rules, over an already-resolved variable set. */
 export function findingsFor(logPath, variables, context = {}) {
     const home = instanceHomeFor(logPath);

package/dist/src/core/instance.js.map

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

package/dist/src/core/log-subscribe.d.ts

@@ -25,6 +25,27 @@ export interface LogSubscriptionOptions {
     signal?: AbortSignal;
     /** Bounded fallback when filesystem notifications are missing. */
     pollIntervalMs?: number;
+    /**
+     * Drain the currently verified snapshot and RETURN, rather than waiting for
+     * appends (APRV-421).
+     *
+     * The streaming form is what `approval log follow` wants: a foreground
+     * process that stays. A PAGED reader wants the opposite and has nowhere to
+     * put a wait. `approval serve`'s `log/follow` answers one request with the
+     * records after a cursor and the cursor they end at, and the caller comes
+     * back with that cursor when it wants more. Expressing "we are caught up" as
+     * a race between the iterator and a timer is a timing heuristic; expressing
+     * it here is one flag, because this module already knows exactly when the
+     * verified snapshot is exhausted.
+     *
+     * It changes nothing about what is emitted or what is refused. The
+     * genesis-to-head verification, the cursor binding, the retained hash and
+     * every terminal failure are the ones below; this decides only whether the
+     * generator waits after the drain or ends. No watcher is established either,
+     * which matters for the caller this exists for: a server that left one file
+     * watcher behind per request would leak handles at the rate it is polled.
+     */
+    once?: boolean;
 }
 /**
  * Yield verified records after an exclusive cursor, then wait for appends.

package/dist/src/core/log-subscribe.js

@@ -86,12 +86,16 @@ export async function* subscribeVerifiedLog(logPath, options = {}) {
     options.signal?.addEventListener("abort", abort, { once: false });
     // Watch the directory so creation of an initially absent log is visible.
     // Failure to establish a watch is harmless: bounded polling remains active.
-    try {
-        watcher = watch(dirname(logPath), { persistent: false }, hint);
-        watcher.on("error", hint);
-    }
-    catch {
-        watcher = null;
+    // A `once` subscription never reaches the wait below, so it establishes no
+    // watch at all rather than opening and closing one per call.
+    if (options.once !== true) {
+        try {
+            watcher = watch(dirname(logPath), { persistent: false }, hint);
+            watcher.on("error", hint);
+        }
+        catch {
+            watcher = null;
+        }
     }
     try {
         while (!options.signal?.aborted) {
@@ -131,6 +135,12 @@ export async function* subscribeVerifiedLog(logPath, options = {}) {
             }
             if (options.signal?.aborted)
                 return;
+            // The verified snapshot is exhausted and this caller asked for exactly
+            // that much (APRV-421). Everything above ran unchanged: the chain was
+            // verified from genesis, the cursor was bound, and a mismatch already
+            // threw. What is skipped is only the waiting.
+            if (options.once === true)
+                return;
             // An append between watcher setup/read/drain and this point changes the
             // version and causes an immediate verification instead of a lost wakeup.
             if (wakeVersion !== versionBeforeRead)

package/dist/src/core/log-subscribe.js.map

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

package/dist/src/core/log-write-layer.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The filesystem calls that put durable bytes on disk: `core/log.ts`'s append
+ * (APRV-440) and `core/payload-store.ts`'s atomic write (APRV-457). They are
+ * kept in their own module so that `core/log.ts`'s public surface stays what
+ * `tests/log.test.ts` pins: no mutation, no reorder, no truncate, and no way to
+ * change how its bytes reach the disk.
+ *
+ * Why a seam at all. The durability claim is "fsync after the write and before
+ * ok", and a page cache that was flushed reads back exactly like one that was
+ * not until the machine dies. Only a layer that records the ORDER of the calls
+ * can prove the claim, so `tests/log-fsync.test.ts` and
+ * `tests/payload-fsync.test.ts` install one that records every call and then
+ * delegates to the real one, which keeps each log they build a real log built
+ * through the real append path.
+ *
+ * One seam for both writers, deliberately. A log record is only as durable as
+ * the payload it binds: a record that survives a crash while its payload comes
+ * back NUL-filled verifies and points at nothing (APRV-457). Proving the two
+ * through one layer keeps one model of "what reached the disk" for both.
+ *
+ * Nothing in `src/` calls {@link setAppendWriteLayerForTests}. It changes how
+ * the bytes reach the disk and nothing about which bytes, so every check before
+ * the write (lock, tail, compare-and-append, schema, payload hashing) runs as in
+ * production.
+ */
+export interface AppendWriteLayer {
+    /** `open(2)` with numeric flags; throws like `fs.openSync`. */
+    open(path: string, flags: number, mode: number): number;
+    /** One `write(2)` of the whole buffer; returns the bytes written. */
+    write(fd: number, data: Buffer): number;
+    /** `fsync(2)` of a file or directory descriptor; throws on failure. */
+    fsync(fd: number): void;
+    close(fd: number): void;
+    /**
+     * `rename(2)`; throws like `fs.renameSync`. Used by the payload store's
+     * temp-then-rename write (APRV-457); the log append never renames.
+     */
+    rename(from: string, to: string): void;
+}
+/** The layer the next append (or payload store write) uses. */
+export declare function appendWriteLayer(): AppendWriteLayer;
+/**
+ * Replace the append's write layer, or restore Node's with `null`. For tests
+ * and the opt-in benchmarks only.
+ */
+export declare function setAppendWriteLayerForTests(layer: AppendWriteLayer | null): void;
+/**
+ * fsync a directory through the current layer, so a name created or renamed
+ * into it survives a crash. Skipped on Windows (a directory cannot be opened
+ * for this there, and its filesystems journal names themselves) and tolerated
+ * where the filesystem reports directory fsync as unsupported; every other
+ * failure throws for the caller to report. The read-only handle is closed even
+ * when the fsync throws.
+ */
+export declare function fsyncDirectory(dir: string): void;