approval-md 0.1.0 → 0.2.0

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

@@ -0,0 +1,157 @@
+/**
+ * Which harness binary issued a hook-written record (APRV-227).
+ *
+ * ## The hole
+ *
+ * A harness upgrade — `claude update`, a global npm install, an unattended
+ * updater on a launchd timer — swaps the binary that hosts the PreToolUse hook
+ * without a line anywhere. A new harness release can change the hook envelope
+ * semantics and quietly stop the gate firing, and the first evidence would be
+ * an action nobody was asked about. The gate cannot stop a person upgrading
+ * their own machine, and should not. What it can do is notice the effect: the
+ * records the hook writes name the harness that issued them, and `approval
+ * doctor` says so when the installed binary no longer matches the last one the
+ * log saw.
+ *
+ * ## What this field is, and what it is emphatically not
+ *
+ * It is INFORMATIONAL. Nothing in the runtime reads it back as an input:
+ * no class resolution, no irreversibility floor, no loop-escalation streak, no
+ * budget arithmetic, no sampling draw. SPEC.md §11.1 invariant 4 says a
+ * self-reported field never reduces scrutiny, and the discipline that keeps
+ * that true here is that the value has exactly one reader — a doctor row that
+ * can only ADD a red line — and exactly one direction it can move a human's
+ * attention, which is toward the log rather than away from it. A harness that
+ * lies about its own version buys itself nothing: the row it defeats is a row
+ * that would have asked for a look.
+ *
+ * It is also OPTIONAL and additive. A record written before the field existed
+ * carries neither half and still validates and still verifies; a hook that
+ * cannot establish a version writes neither half rather than a guess.
+ *
+ * ## Where the value comes from, in order
+ *
+ * 1. The hook event's own version field, where the harness supplies one.
+ *    Claude Code's PreToolUse event may carry it; Cursor's does not.
+ * 2. `<binary> --version`, read at most ONCE per process ({@link
+ *    installedHarnessVersion} memoizes, including the failures) with a short
+ *    hard timeout.
+ * 3. Absent.
+ *
+ * Step 2 is why this module is careful about cost. A hook process exists per
+ * gated tool call, and APRV-186/188/212 each removed a term from what that
+ * process pays. So the probe is reached only on a path that is about to WRITE a
+ * record — a registration or a bypass — and never on the pass-through path that
+ * answers `cat README.md`. The memo makes a multi-class command pay once.
+ *
+ * ## Why the binary name is not configurable
+ *
+ * `cli/gloss.ts` already settled this: a runtime that let a policy or an
+ * environment variable name the executable it runs would have invented a new
+ * way to be told what to execute. The map below is the whole list, PATH is the
+ * only seam, and a test puts a stub binary in front of it.
+ */
+/** The harnesses this runtime speaks a hook protocol for. */
+export declare const HARNESS_KINDS: readonly ["claude-code", "cursor", "codex"];
+export type HarnessKind = (typeof HARNESS_KINDS)[number];
+/** Is `value` one of the harnesses this runtime knows? */
+export declare function isHarnessKind(value: unknown): value is HarnessKind;
+/**
+ * The executable each harness installs on PATH.
+ *
+ * Not configurable, deliberately (see the header). A harness whose binary is
+ * not one of these has no version to read here, and the field is simply absent.
+ */
+export declare const HARNESS_BINARY: Readonly<Record<HarnessKind, string>>;
+/**
+ * How long a version string may be, and the reason there is a cap at all.
+ *
+ * `<binary> --version` is the output of a third-party process, and this value
+ * is appended to an append-only log. SPEC.md §11.1 invariant 3 has no exception
+ * for provenance: a field that accepted arbitrary bytes is a field where a
+ * banner, a stack trace, or the credential quoted inside one arrives and stays
+ * forever. So the write boundary takes one line, printable ASCII only, capped.
+ */
+export declare const HARNESS_VERSION_LIMIT = 64;
+/**
+ * The one spelling of a harness version this runtime ever writes or compares.
+ *
+ * First line, trimmed, and nothing else: `claude --version` prints
+ * `2.0.14 (Claude Code)` and a future release may add a second line of banner.
+ * Both the hook (which records) and doctor (which compares) call this, so the
+ * comparison is between two values normalized identically — a row that failed
+ * because one side kept a trailing newline would be a false alarm, and a false
+ * alarm in a health check trains an operator to ignore it.
+ *
+ * Returns `null` for anything that is not a usable version: empty output, a
+ * line that is not printable ASCII, or one longer than the cap. Absence is
+ * always available and always honest.
+ */
+export declare function normalizeHarnessVersion(raw: unknown): string | null;
+/**
+ * How long the probe may take before it is killed and reported as absent.
+ *
+ * A bound against a HUNG binary, not a latency target: `<binary> --version`
+ * answers in milliseconds on any machine that is not already in trouble, and
+ * this number is only ever reached by one that is. It is generous for the same
+ * reason `cli/gloss.ts`'s is (20s there): a timeout tuned to a healthy machine
+ * turns a loaded one into a silent, intermittent absence, and an absence that
+ * appears under load is the least useful failure a provenance field could have.
+ * The cost is bounded by the fact that this runs only where a record is being
+ * written, and at most once per process.
+ */
+export declare const HARNESS_PROBE_TIMEOUT_MS = 10000;
+/**
+ * Run `<binary> --version` once, uncached, and normalize what came back.
+ *
+ * Every failure is a value rather than an exception, in the manner of
+ * {@link spawnGloss}: a missing binary, a non-zero exit and a timeout kill are
+ * all reported on the result object, and all of them are simply "no version".
+ *
+ * The child is STARVED, for the reason the gloss runner is: this is a
+ * third-party CLI spawned by a process that may be holding a bot token and a
+ * vault passphrase, and it has no use for either. Nothing is declared, because
+ * reading a version is not a granted action.
+ */
+export declare function probeHarnessVersion(kind: HarnessKind): string | null;
+/**
+ * The installed version of `kind`, read at most once per process.
+ *
+ * This is the only entry point callers should use. `probeHarnessVersion` is
+ * exported for the test that proves the memo is a memo.
+ */
+export declare function installedHarnessVersion(kind: HarnessKind): string | null;
+/** Drop the memo. TEST ONLY: a process reads a version once, by design. */
+export declare function resetHarnessVersionCache(): void;
+/**
+ * The provenance pair a hook-written record carries, or `null` when this
+ * process could not establish one.
+ *
+ * Both halves or neither. A version with no harness beside it is a string
+ * doctor cannot attribute to a binary — one log holds the records of every
+ * harness that ever wrote to it — and a harness with no version is a field that
+ * says nothing.
+ */
+export interface HarnessProvenance {
+    harness: HarnessKind;
+    harness_version: string;
+}
+/**
+ * Build the pair for `kind`, preferring the version the hook event supplied.
+ *
+ * `eventVersion` is whatever the harness put in its own event, unvalidated:
+ * it goes through {@link normalizeHarnessVersion} exactly as the probe's
+ * output does, because it arrives from the same untrusted side of the boundary
+ * and the write boundary does not have two standards.
+ */
+export declare function harnessProvenance(kind: HarnessKind, eventVersion?: unknown): HarnessProvenance | null;
+/**
+ * The provenance pair carried by an already-written record's payload, or
+ * `null` when it carries none (or carries half of one).
+ *
+ * The read side of the same contract, used by `approval doctor`. Strict on
+ * purpose: a record whose `harness` is a string this runtime does not know is a
+ * record from a harness this build cannot probe, so it is not evidence about
+ * any binary here and is skipped rather than guessed at.
+ */
+export declare function readHarnessProvenance(payload: unknown): HarnessProvenance | null;

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

@@ -54,7 +54,7 @@
 import { spawnSync } from "node:child_process";
 import { childEnvironment } from "./child-env.js";
 /** The harnesses this runtime speaks a hook protocol for. */
-export const HARNESS_KINDS = ["claude-code", "cursor"];
+export const HARNESS_KINDS = ["claude-code", "cursor", "codex"];
 /** Is `value` one of the harnesses this runtime knows? */
 export function isHarnessKind(value) {
     return typeof value === "string" && HARNESS_KINDS.includes(value);
@@ -68,6 +68,7 @@ export function isHarnessKind(value) {
 export const HARNESS_BINARY = {
     "claude-code": "claude",
     cursor: "cursor-agent",
+    codex: "codex",
 };
 /**
  * How long a version string may be, and the reason there is a cap at all.

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

@@ -1 +1 @@
-{"version":3,"file":"harness-version.js","sourceRoot":"","sources":["../../../src/core/harness-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,6DAA6D;AAC7D,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,aAAa,EAAE,QAAQ,CAAU,CAAC;AAIhE,0DAA0D;AAC1D,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,aAAmC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC3F,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAA0C;IACnE,aAAa,EAAE,QAAQ;IACvB,MAAM,EAAE,cAAc;CACvB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAExC,oFAAoF;AACpF,MAAM,SAAS,GAAG,iBAAiB,CAAC;AAEpC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAY;IAClD,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1C,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC1B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,qBAAqB;QAAE,OAAO,IAAI,CAAC;IAC1E,OAAO,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5C,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAiB;IACnD,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,EAAE;YACtD,QAAQ,EAAE,MAAM;YAChB,GAAG,EAAE,gBAAgB,EAAE,CAAC,GAAG;YAC3B,OAAO,EAAE,wBAAwB;YACjC,UAAU,EAAE,SAAS;YACrB,wEAAwE;YACxE,4DAA4D;YAC5D,SAAS,EAAE,EAAE,GAAG,IAAI;SACrB,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACnE,OAAO,uBAAuB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,MAAM,GAAG,IAAI,GAAG,EAA8B,CAAC;AAErD;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAiB;IACvD,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACxB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,wBAAwB;IACtC,MAAM,CAAC,KAAK,EAAE,CAAC;AACjB,CAAC;AAgBD;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAiB,EACjB,YAAY,GAAY,IAAI;IAE5B,MAAM,MAAM,GAAG,uBAAuB,CAAC,YAAY,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,MAAM,IAAI,uBAAuB,CAAC,IAAI,CAAC,CAAC;IACxD,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC;AAC/E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAgB;IACpD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3F,MAAM,MAAM,GAAG,OAAkC,CAAC;IAClD,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IAC/B,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,OAAO,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAC1C,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,uBAAuB,CAAC,OAAO,CAAC,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IAC7F,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC;AACrD,CAAC"}
+{"version":3,"file":"harness-version.js","sourceRoot":"","sources":["../../../src/core/harness-version.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,55 @@
+/**
+ * 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
+ * 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.
+ *
+ * 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
+ * instant it is judging against.
+ */
+/**
+ * The hook's default wait, chosen to sit inside Claude Code's own 60s hook
+ * default. The string form is what the flag parser takes; the millisecond form
+ * is what a comparison takes.
+ */
+export declare const HOOK_DEFAULT_WAIT = "55s";
+/** {@link HOOK_DEFAULT_WAIT} in milliseconds. */
+export declare const HOOK_DEFAULT_WAIT_MS = 55000;
+/**
+ * How long a request outlives the wait that opened it, before the hook takes it
+ * back (APRV-287).
+ *
+ * The window exists for exactly one thing: the retry. A hook whose wait expires
+ * leaves its question open because a decision inside the policy's TTL still
+ * authorizes an identical retry of the identical command (APRV-117), and the
+ * agent that was denied usually retries within a minute or two. So the question
+ * stays live for that long and no longer.
+ *
+ * Past it, nobody is coming back for the answer. The request was accruing on an
+ * approver's phone as one more message a restarted listener would re-deliver,
+ * and on 2026-09-06 a dozen of those arrived at once behind a dead daemon. A
+ * request nothing will adopt is withdrawn (reason `timeout`), which authorizes
+ * nothing, refuses a late tap in the approver's own words, and leaves the log
+ * saying exactly what happened: the asker gave up.
+ *
+ * Five minutes because it is longer than any retry loop this runtime has been
+ * observed to take and shorter than the shortest TTL an operator is likely to
+ * write. It is a default: `--retry-grace` moves it per invocation, and `0`
+ * withdraws at the moment the wait expires.
+ */
+export declare const HOOK_RETRY_GRACE_MS: number;
+/**
+ * How old a request opened under `waitMs` must be before the grace has run out.
+ *
+ * Measured from the `approval.requested` record's own timestamp, which is the
+ * instant the runtime wrote at the write boundary, and never from anything a
+ * caller states about when it started waiting.
+ */
+export declare function abandonedAfterMs(waitMs: number, graceMs: number): number;

package/dist/src/core/head-retry.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The bounded head-moved retry, in one place (APRV-150, APRV-236).
+ *
+ * ## The fact this module is about
+ *
+ * `core/log.ts` takes a compare-and-append precondition: a writer states the
+ * `(seq, hash)` its checks were made against, and the append is refused under
+ * the lock when the tail is something else. That refusal is `append-failed`
+ * with `append.code === "head-moved"`, and it is correct: every read-dependent
+ * check that authorized the write is stale.
+ *
+ * Stale is not the same as wrong. A moved head says the verdict must be
+ * computed again; it does not say what the verdict is. Treating the two as the
+ * same is what turned a busy log into a lottery, twice:
+ *
+ *  - 2026-08-29 (APRV-150): a session's first `git status` — class `read.shell`,
+ *    autonomous, no human anywhere near it — was denied by the Claude Code hook
+ *    because an unrelated record landed a few milliseconds earlier.
+ *  - 2026-09-02 (APRV-236): `approval grant` refused a human's decision with
+ *    `head moved: expected seq 14218, found 14219` while two lanes and the
+ *    daemon were appending. The human ran it again. Twice more.
+ *
+ * The second one is the worse of the two, because the caller it handed the
+ * retry to was a person. A compare-and-append refusal is a fact about timing
+ * rather than about authority, and asking a human to retype is the wrong party
+ * to hand it to.
+ *
+ * ## What a retry is here, and what it is not
+ *
+ * The unit of retry is the WHOLE read-check-append cycle: a new read of the
+ * verified log, a new read of the policy, a fresh attestation, a fresh
+ * derivation of the request's state, fresh escalation, single-use, intake and
+ * budget checks, and a new append against the head that the new read observed.
+ * Nothing crosses an attempt except the caller's own inputs.
+ *
+ * The append is never retried on its own. That distinction is the whole safety
+ * argument, and it is worth stating as three properties:
+ *
+ *  - **compare-and-append is untouched.** Every attempt supplies the head it
+ *    read, and a stale write is still refused under the lock. SPEC.md §11.1
+ *    invariant 5 holds per attempt, which is where it has to hold.
+ *  - **A changed verdict is the new verdict.** If the record that moved the head
+ *    decided the request, spent the key, exhausted the budget, lapsed the TTL or
+ *    re-attested a different policy, the next attempt derives that and refuses
+ *    it with the code those fresh facts produce — `already-decided`,
+ *    `request-withdrawn`, `already-executed`, `budget-exceeded`, `expired`,
+ *    `policy-drift` — never `append-failed`. A retry cannot launder a denial
+ *    into an allow, because it never replays the earlier conclusion.
+ *  - **Only `head-moved` retries.** Every other refusal, a real verdict included,
+ *    is returned on the first attempt. So is a lock timeout, a corrupt log and a
+ *    schema refusal at the write boundary: retrying those would be either
+ *    pointless or a second write.
+ *
+ * The bound is what keeps a busy log from turning one call into an unbounded
+ * write loop. When it is spent the last `head-moved` refusal is returned with
+ * its code and its `append` error unchanged, and with the attempt count added to
+ * its message so a reader can tell one lost race from a log under sustained
+ * contention. The caller fails closed on it exactly as it always did.
+ */
+import type { AppendError } from "./log.js";
+/**
+ * How many times a gate writer re-derives its verdict against a moved head
+ * before it gives up. Small, fixed, and not configurable upward.
+ *
+ * APRV-150 chose three for the hook's writers; APRV-236 gives the same three to
+ * every other writer a human or a session drives, rather than inventing a
+ * second number for the same fact.
+ */
+export declare const HEAD_MOVED_ATTEMPTS = 3;
+/**
+ * The shape this module needs of a writer's result: an `ok` discriminator, and
+ * on the refusal side a code and the append error beneath it.
+ *
+ * Deliberately structural. `GateRefusal`, `ExecuteRefusal`, `TokenRefusal` and
+ * `GateWindowRefusal` are four frozen unions in four modules that must not
+ * learn about each other; what they share is this, and this is all the helper
+ * reads.
+ */
+export interface HeadRetryable {
+    ok: boolean;
+    code?: string;
+    message?: string;
+    append?: AppendError;
+}
+/** Did this refusal come from the compare-and-append precondition alone? */
+export declare function isHeadMoved(result: HeadRetryable): boolean;
+/**
+ * The attempt budget for one operation: `ceiling` unless the caller asked for
+ * fewer.
+ *
+ * Clamped rather than trusted, and clamped in the one direction that matters: a
+ * caller may ask for LESS tolerance of a moved head (a test pinning the
+ * unretried behaviour, a caller that would rather fail fast), never for more.
+ * Ambiguity — a non-integer, a zero, a negative — resolves to the value the
+ * runtime chose, not the caller's.
+ */
+export declare function attemptsOf(asked: number | undefined, ceiling?: number): number;
+/**
+ * Run one whole read-check-append cycle, and run it again from the top while it
+ * loses the race, up to `attempts` times.
+ *
+ * `cycle` MUST be the entire operation: it re-reads, re-runs every check on the
+ * head it just read, and returns either the append it attempted or the refusal
+ * those fresh facts produced. A `cycle` that closes over a stale read would
+ * defeat the only property that makes this safe.
+ */
+export declare function withHeadRetry<T extends HeadRetryable>(attempts: number, cycle: () => T): T;

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

@@ -0,0 +1,253 @@
+/**
+ * Which gate instance this process is talking about (APRV-178).
+ *
+ * Everything else in this runtime is directory-scoped already: the policy is
+ * the `APPROVAL.md` beside the working directory, the log is that directory's
+ * `.approval/log/events.jsonl`, the vault and `.approval/env` sit next to it.
+ * Two checkouts on one machine are two gates, and nothing they hold is shared.
+ *
+ * The OS keystore was the exception, and it cost a live incident: the item
+ * names were three fixed strings, so a demo instance provisioned in another
+ * directory stored its bot token over the production instance's item and then
+ * read the production token back. Both gates then long-polled ONE bot, the
+ * `getUpdates` offsets fought, and a human's approval tap was consumed by the
+ * listener that had not asked for it. A keystore is machine-global; the names
+ * put into it have to carry the scoping the filesystem gave everything else.
+ *
+ * ## What the identity is
+ *
+ * The absolute path of the instance's `.approval` directory, hashed. Not the
+ * repository root (a gate may be configured with `--log` somewhere else), not
+ * a random id written into a file (a file the operator can copy is an identity
+ * that travels, which is the bug), and not the log path itself (a `--log` that
+ * names the same instance's log by a different but equivalent spelling should
+ * not mint a second identity, and `envFilePathFor` already normalises the two
+ * spellings this runtime supports).
+ *
+ * Symlinks are deliberately NOT resolved. `realpathSync` would touch the
+ * filesystem, so the identity of an instance would depend on whether its
+ * directory currently exists — and `approval setup` must be able to name the
+ * item it is about to create before anything is on disk. Two paths that reach
+ * one directory by different routes are therefore two identities; that is the
+ * safe direction of the error (two names, no sharing) rather than the unsafe
+ * one.
+ *
+ * ## What the names look like
+ *
+ * ```
+ * approval-tg-token-3f2a9c11
+ * approval-vault-passphrase-3f2a9c11
+ * approval-sampling-secret-3f2a9c11
+ * ```
+ *
+ * Eight hex digits: long enough that two instances on one machine will not
+ * collide by accident, short enough that an operator reading
+ * `keychain:approval-tg-token-3f2a9c11` in `.approval/env` and the same suffix
+ * in `approval doctor` can compare them at a glance. The suffix is not a
+ * 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 { PolicyLoadResult } from "./policy-load.js";
+/**
+ * The unscoped item names this project used before APRV-178.
+ *
+ * Kept, and kept named, for two reasons: an instance provisioned before the
+ * change still has its token under one of them, and the migration path is to
+ * READ them as a fallback and say so out loud, never to silently adopt them.
+ */
+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";
+/** 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. */
+export declare const INSTANCE_ID_LENGTH = 8;
+/**
+ * The `.approval` directory this log path belongs to, absolute as given.
+ *
+ * `envFilePathFor` already answers "which instance is this log in", by walking
+ * up out of `log/` when it is there; the env file's own directory IS the
+ * instance home, so this is that answer with the filename removed rather than
+ * a second rule that could disagree with it.
+ */
+export declare function instanceHomeFor(logPath: string): string;
+/** The instance's short identity: {@link INSTANCE_ID_LENGTH} hex digits. */
+export declare function instanceIdFor(logPath: string): string;
+/** The keystore item name `base` takes in the instance owning `logPath`. */
+export declare function scopedService(base: string, logPath: string): string;
+/**
+ * How a service name relates to the instance owning `logPath`.
+ *
+ * Answered from the NAME alone, with no keystore lookup: `approval doctor`
+ * reports on this and a diagnostic may not pop a keychain-unlock prompt (see
+ * `cli/doctor.ts`'s `NON_RESOLVING_RUNNER`). The name is enough, because the
+ * name is what decides which item a lookup would find.
+ *
+ * - `mine` — the scoped name this instance writes.
+ * - `legacy` — one of the unscoped pre-APRV-178 names, which every instance on
+ *   the machine resolves to the same item.
+ * - `other-instance` — a scoped name whose suffix is some other instance's.
+ * - `unknown` — a name this runtime never wrote; the operator chose it, and
+ *   nothing here can say whose it is.
+ */
+export type ServiceScope = "mine" | "legacy" | "other-instance" | "unknown";
+export declare function scopeOfService(service: string, logPath: string): ServiceScope;
+/**
+ * The variable `approval env`'s export block uses to say what it exported.
+ *
+ * ## The bug this exists to close
+ *
+ * The bleed rule below reads no values, on purpose: it runs inside `approval
+ * doctor` and `approval up`, neither of which may pop a keystore-unlock dialog
+ * to produce a diagnostic (`NON_RESOLVING_RUNNER`). So it saw "this variable is
+ * exported, and the file has a line for it" and reported that the value in use
+ * was not the one the instance configured. It could not know that. The
+ * documented start ritual is
+ *
+ * ```sh
+ * eval "$(approval env)"
+ * ```
+ *
+ * which exports THIS instance's own values from THIS instance's own file, and
+ * leaves behind exactly the state the rule was calling an incident: exported,
+ * with a file line naming a source. Observed on 2026-09-06 in the primary,
+ * where `unset APPROVAL_SAMPLING_SECRET && eval "$(approval env)" && approval
+ * up` printed the finding for the variable the eval had just resolved from the
+ * gate's own keychain item. A check that asserts a fact it never tested is
+ * worse than no check: it teaches the operator to skip the line.
+ *
+ * ## What is exported, and why it is value-free
+ *
+ * ```
+ * APPROVAL_ENV_PROVENANCE=1:3f2a9c11:<64 hex>:APPROVAL_TG_TOKEN,APPROVAL_TG_CHAT
+ *                         │ │        │        └ the NAMES it exported from the file
+ *                         │ │        └ sha256 of the env file bytes it read
+ *                         │ └ the instance whose file that was
+ *                         └ the format version
+ * ```
+ *
+ * Four colon-separated fields; the names are shell variable names, which cannot
+ * contain a colon or a comma, so the shape needs no escaping. Every field is a
+ * NAME, an id or a digest: the same three kinds of thing `.approval/env` already
+ * carries in the open, and none of them is a value. The rule stays as value-free
+ * after this change as it was before it, which is the point — a check that had
+ * to read the secret to decide whether to complain about the secret would be a
+ * worse trade than the false positive.
+ *
+ * ## What it does NOT weaken
+ *
+ * Invariant 7 (no verb loads `.approval/env` implicitly) is untouched: this
+ * variable reaches a shell only when a human evaluates `approval env`'s output,
+ * exactly like every other line in that block, and no verb gains the ability to
+ * read the file for its values. And it cannot launder a foreign export, because
+ * `approval env` lists only the names it resolved FROM THE FILE. A value that
+ * was already in the environment is re-exported by that block for fidelity, and
+ * deliberately left out of this list, so a bled variable stays reported however
+ * many times the ritual is run over it.
+ *
+ * Trusting the variable is safe in the only direction that matters. Anything
+ * able to set it in this process's environment could already set the credential
+ * variables themselves, so it buys an attacker nothing; and being wrong here
+ * silences a WARNING rather than opening a gate. The reverse default — believing
+ * the exported value is foreign — is the bug being fixed.
+ */
+export declare const ENV_PROVENANCE_VAR = "APPROVAL_ENV_PROVENANCE";
+/** The only format version this build writes, and the only one it reads. */
+export declare const ENV_PROVENANCE_VERSION = "1";
+/** What one `approval env` export block claims about itself. */
+export interface EnvProvenance {
+    /** The instance whose env file it resolved from. */
+    instanceId: string;
+    /** `envFileDigest` of the bytes it resolved from (`core/env-file.ts`). */
+    digest: string;
+    /** The names it exported FROM that file. Never the ones it passed through. */
+    names: ReadonlySet<string>;
+}
+/**
+ * The value for {@link ENV_PROVENANCE_VAR}, for an export block that resolved
+ * `names` out of the file `digest` identifies.
+ */
+export declare function formatEnvProvenance(logPath: string, digest: string, names: readonly string[]): string;
+/**
+ * Read the claim back, or `null` for anything this build does not recognise.
+ *
+ * Strict on every field, and `null` rather than a partial answer: a malformed
+ * claim is an unverified one, an unverified one earns no credit, and no credit
+ * means the finding is still reported. That is the fail-closed direction (the
+ * check stays loud) for a value whose whole job is to make the check quieter.
+ */
+export declare function parseEnvProvenance(raw: string | undefined): EnvProvenance | null;
+/**
+ * One way this instance's credentials can belong to somebody else.
+ *
+ * - `foreign-instance` — `.approval/env` names a keystore item whose scope
+ *   suffix is another instance's. Two gates then hold one credential, which is
+ *   the incident: one bot, two long pollers, and a human's tap consumed by the
+ *   listener that did not ask the question. This is WRONG, not a state.
+ * - `legacy-shared` — the file names one of the unscoped pre-APRV-178 items.
+ *   Correct on a machine with one gate and a trap on a machine with two, so it
+ *   is reported and not failed: it is what every existing installation looks
+ *   like, and the repair is one re-run of `approval setup channel telegram`.
+ * - `ambient-bleed` — the value was exported before this process started, the
+ *   file names a source of its own, and the export is NOT one this instance's
+ *   `approval env` made (see {@link ENV_PROVENANCE_VAR}). The shell wins on
+ *   purpose (invariant 7); what was missing is anyone saying so. This is the
+ *   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.
+ */
+export type InstanceFindingKind = "foreign-instance" | "legacy-shared" | "ambient-bleed";
+export interface InstanceFinding {
+    kind: InstanceFindingKind;
+    /** The environment variable the finding is about. */
+    variable: string;
+    /** The item name, for the two name-shaped findings. */
+    service?: string;
+    /** One sentence, and never a value. */
+    detail: string;
+}
+/**
+ * What is wrong with WHOSE credentials this instance is using (APRV-178).
+ *
+ * Answered from names alone. No keystore is consulted ({@link
+ * NON_RESOLVING_RUNNER}), so this may be called from `approval doctor` and from
+ * `approval up`'s start-up without either of them blocking on an unlock dialog.
+ * No value is read, compared or printed on any path: the inputs are a service
+ * name, a scheme, a variable name, and (since APRV-278) an instance id, a file
+ * digest and a list of variable names out of {@link ENV_PROVENANCE_VAR} — all of
+ * which `.approval/env` and `approval env --check` carry in the open. The
+ * exported VALUES this reports on are still never read, compared or printed.
+ *
+ * A file this runtime cannot read at all produces no findings rather than a
+ * guess; `approval env --check` and doctor's `environment` row are what report
+ * an unreadable or wrong-moded file, and saying it twice in different words is
+ * how two commands come to disagree.
+ */
+export declare function instanceFindings(logPath: string, load: PolicyLoadResult, ambientEnv?: NodeJS.ProcessEnv): InstanceFinding[];
+/**
+ * What the rule may consult beyond the names (APRV-278).
+ *
+ * Both fields are optional and an absent one only ever makes the report LOUDER:
+ * a caller that supplies neither gets the pre-APRV-278 behaviour, where every
+ * exported variable with a file line is reported.
+ */
+export interface FindingsContext {
+    /** The environment the report is about. Read for {@link ENV_PROVENANCE_VAR}. */
+    ambientEnv?: NodeJS.ProcessEnv;
+    /** `envFileDigest` of this instance's env file as it now reads. */
+    envFileDigest?: string;
+}
+/**
+ * The exported names this instance's OWN current `approval env` vouches for
+ * (APRV-278).
+ *
+ * Empty unless {@link ENV_PROVENANCE_VAR} parses, names this instance, and
+ * matches the env file as it now reads. `approval env --check` and the finding
+ * rule below both answer "is this export the documented ritual's?" from this one
+ * function, because two spellings of that question are two chances for `approval
+ * env --check` and `approval up` to say different things about one shell.
+ */
+export declare function ownEnvExports(logPath: string, context?: FindingsContext): ReadonlySet<string>;
+/** The name-only rules, over an already-resolved variable set. */
+export declare function findingsFor(logPath: string, variables: readonly ResolvedVariable[], context?: FindingsContext): InstanceFinding[];