approval-md 0.1.0 → 0.3.0

package/dist/src/cli/git-scope.d.ts

@@ -0,0 +1,190 @@
+/**
+ * The bits of git the CLI needs, run the way `cli/amend.ts` has always run
+ * them: `spawnSync`, no shell, and every failure is a value rather than a throw.
+ *
+ * This module exists because APRV-125 gave a second and a third caller to the
+ * primary-checkout resolution APRV-101 wrote for the hook. `approval log sync`
+ * and `approval log advance` operate on the committed log, and the committed log
+ * has exactly one home: the primary checkout. A copy of `primaryRoot` per caller
+ * would be three chances for the three of them to disagree about where that is.
+ *
+ * Nothing here decides anything. It answers questions about a repository, and
+ * the verbs decide what the answers mean.
+ */
+import { GIT_OUTPUT_LIMIT_BYTES, gh, git, type GitRun } from "../core/git-run.js";
+/**
+ * The two runners moved to `core/git-run.ts` in APRV-245 and are re-exported
+ * here unchanged. The coverage sources are core code and shell out to git, and
+ * core reaching into `src/cli/` for the runner would invert the direction
+ * `tests/layering.test.ts` keeps. Every existing caller of `git-scope.ts` is
+ * untouched, and there is still one spelling of "run git" in the repository.
+ */
+export { GIT_OUTPUT_LIMIT_BYTES, gh, git, type GitRun };
+/** The repository root containing `dir`, or `null` when there is none. */
+export declare function repoRoot(dir: string): string | null;
+/**
+ * The primary checkout containing `cwd`, or `null` when git cannot say.
+ *
+ * `git rev-parse --git-common-dir` names the SHARED git directory: in a linked
+ * worktree it is the primary checkout's `.git`, in a plain checkout it is this
+ * checkout's own (printed as bare `.git` at the top level, absolute from a
+ * subdirectory). Either way the primary root is its parent, so a plain checkout
+ * resolves to itself.
+ *
+ * When git is absent, or `cwd` is not a repository at all, this returns `null`.
+ * What that means is the caller's business: the hook falls back to `cwd`
+ * (APRV-101), and the log verbs refuse, because a log ritual with no repository
+ * to run it in has nothing to synchronize.
+ */
+export declare function primaryRoot(cwd: string): string | null;
+/**
+ * The primary checkout, but only when `cwd` is standing in it.
+ *
+ * A linked worktree's toplevel is the worktree; its common git directory
+ * belongs to the primary. So the two agree in the primary checkout and differ
+ * in every linked one, which is the whole distinction. Symlinks are resolved on
+ * both sides, because `/tmp` is `/private/tmp` on macOS and a checkout reached
+ * through one spelling must not read as a different checkout from the other.
+ */
+export declare function primaryCheckout(cwd: string): {
+    ok: true;
+    root: string;
+} | {
+    ok: false;
+    reason: string;
+    worktreeRoot: string | null;
+    primary: string | null;
+};
+/**
+ * A repo-relative, forward-slashed path, as git spells one.
+ *
+ * BOTH sides are resolved through `realpath` first (APRV-210). `git rev-parse
+ * --show-toplevel` prints the physical path, so a checkout reached through a
+ * symlinked spelling (`/tmp/x` for `/private/tmp/x` on macOS, a symlinked home
+ * directory, a bind mount) hands this function a root and a path that live in
+ * different spellings of the same place. `relative()` on those two produces a
+ * path that climbs out of the repository (`../../private/tmp/…`), git has no
+ * blob at `HEAD:<that>`, and the caller concludes the file has never been
+ * committed. That is the misread APRV-210 recorded on a log with thousands of
+ * committed records.
+ */
+export declare function repoPath(root: string, path: string): string;
+/** The checked-out branch, or `null` on a detached HEAD. */
+export declare function currentBranch(root: string): string | null;
+/**
+ * One attempt at reading `<rev>:<relative>` out of the object store.
+ *
+ * The failure half carries the command and what the runner said, because the
+ * two ways this can fail need telling apart and neither is visible in a `null`:
+ * git answering "no such path in that rev" (ordinary, and the reason most
+ * callers move on to the next rev), and the read itself breaking — git absent,
+ * the object store unreadable, or output past
+ * {@link GIT_OUTPUT_LIMIT_BYTES}. A caller that reports "no committed copy"
+ * for the second case is telling an operator something false.
+ */
+export type BlobRead = {
+    ok: true;
+    bytes: Buffer;
+} | {
+    ok: false;
+    command: string;
+    status: number | null;
+    detail: string;
+};
+/**
+ * The bytes of `<rev>:<relative>`, with the reason when there are none.
+ *
+ * Read as a Buffer, never as text: callers hash and compare these bytes, and an
+ * encoding round-trip would silently change what is being compared. That is
+ * also why this is `spawnSync` directly rather than {@link git}, which decodes
+ * to a string — and why the buffer limit has to be repeated here rather than
+ * inherited from the runner.
+ */
+export declare function readBlob(root: string, rev: string, relative_: string): BlobRead;
+/**
+ * The bytes of `<rev>:<relative>`, or `null` when there are none.
+ *
+ * The shape every caller predating {@link readBlob} expects. Callers that owe
+ * an operator a diagnostic when the read fails should reach for `readBlob`.
+ */
+export declare function showBlob(root: string, rev: string, relative_: string): Buffer | null;
+/** Everything git said about a run, as trimmed non-empty lines. */
+export declare function outputLines(...texts: readonly string[]): string[];
+/**
+ * Fetch one branch from one remote and answer the sha it now points at.
+ *
+ * The ceremony verbs (`policy amend`, `log advance`) own this step rather than
+ * asking the operator to run it first (APRV-203). The failure that made it
+ * theirs: a ceremony run in a checkout whose local `main` was behind origin
+ * built its commit on the stale tip, so the pull request carried a parent that
+ * was missing everything main had merged since, and CI went red for reasons
+ * that had nothing to do with the amendment.
+ *
+ * `FETCH_HEAD` is read rather than `refs/remotes/<remote>/<branch>`, because a
+ * fetch of an explicit refspec always writes the former and a repository
+ * configured without remote-tracking refs would not have the latter.
+ */
+export declare function fetchBase(root: string, remote: string, branch: string): {
+    ok: true;
+    sha: string;
+} | {
+    ok: false;
+    message: string;
+    quote: readonly string[];
+};
+/** What {@link commitOnBase} is asked to build. */
+export interface CommitOnBase {
+    /** The commit the new one is parented on, as a sha. */
+    base: string;
+    /** Repo-relative paths taken from the WORKING TREE, laid over the base tree. */
+    paths: readonly string[];
+    message: string;
+    /**
+     * Blobs forced into the index after the working-tree paths are laid over it,
+     * as `{path, sha}` (APRV-233).
+     *
+     * For a caller whose file is being written to concurrently and that has
+     * already pinned the bytes it means. `approval log advance` hashes the log
+     * under the append lock and then releases it for the slow half of the verb,
+     * so the commit must carry the object it VERIFIED rather than whatever the
+     * file grew into while `git fetch` was talking to the network. The blob has
+     * to be in the object store already; `git hash-object -w` is how the caller
+     * puts it there.
+     */
+    blobs?: readonly {
+        path: string;
+        sha: string;
+    }[];
+}
+/**
+ * Build a commit on `base` carrying the working-tree state of `paths`, without
+ * checking anything out (APRV-203).
+ *
+ * The whole method is one scratch index: `GIT_INDEX_FILE` points at a temporary
+ * file, `read-tree` fills it from the base commit's tree, `add -A` lays the
+ * named working-tree paths over it, and `write-tree` plus `commit-tree` turn
+ * that into an object. HEAD never moves, the operator's index is never read or
+ * written, and no file in the working tree is touched — which is what lets a
+ * verb that MUST NOT check anything out (a branch switch rewinds `events.jsonl`
+ * underneath whatever holds it open) still base its commit on the remote.
+ *
+ * `unchanged` is the honest answer when the base tree already carries exactly
+ * these bytes: there is nothing to commit, and inventing an empty commit would
+ * be the verb narrating its own no-op.
+ */
+export declare function commitOnBase(root: string, request: CommitOnBase): {
+    ok: true;
+    sha: string;
+    unchanged: false;
+} | {
+    ok: true;
+    sha: null;
+    unchanged: true;
+} | {
+    ok: false;
+    step: string;
+    message: string;
+    quote: readonly string[];
+};
+/** The same, folded onto one line for a `--json` message string. */
+export declare function failureText(run: GitRun): string;

package/dist/src/cli/gloss-attach.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Attaching the model gloss to a request, for every channel that renders one
+ * (APRV-144, APRV-164, APRV-197).
+ *
+ * `cli/gloss.ts` decides how a sentence is obtained; this decides which
+ * material is worth asking about and where the answer is hung. It lived inside
+ * `cli/channel-telegram.ts` until APRV-197, when a second surface needed it:
+ * Carter, deciding requests on the CLI channel, read the raw claimed summary
+ * and nothing else, because the only code that had ever attached a gloss was
+ * the Telegram listener. One reading aid implemented twice would be two reading
+ * aids that drift, so the listener and the terminal walker now call the same
+ * function over the same payload views.
+ *
+ * The safety argument is unchanged and belongs here rather than at either call
+ * site. This runs at RENDER time, on a `ChannelRequest` the tagger has already
+ * finished building: the gate resolved the class, the budgets and the payload
+ * binding without this field existing, the payload hash was computed over bytes
+ * that do not contain it, and the log will record a decision that never
+ * mentions it. Nothing anywhere branches on the content of a gloss; the only
+ * thing that turns on it is whether one more line appears.
+ *
+ * What APRV-197 adds is an {@link GlossOutcome}. Absence used to be silent by
+ * design, and that was right for one request and wrong for a thousand: with the
+ * timeout set where APRV-144 set it, the subprocess missed EVERY time and the
+ * result was indistinguishable from the feature never having shipped. The
+ * outcome is returned so a caller can count, and count is all it is for — no
+ * caller retries, waits longer, or renders anything different because of it.
+ */
+import { type ChannelRequest } from "../channels/contract.js";
+import { type GlossRunner } from "./gloss.js";
+/**
+ * What one attempt did. Counted by the caller, read by nobody else.
+ *
+ * `opaque` and `absent` are kept apart because they mean different things to an
+ * operator: a payload with no describable material was never going to get a
+ * sentence (there is nothing the canonical JSON does not already show), while
+ * `absent` means a model was asked and did not answer in time. Only the second
+ * is a fault, and a counter that added them together would report a fault every
+ * time an opaque payload went by.
+ */
+export type GlossOutcome = "attached" | "absent" | "opaque";
+export interface GlossAttachment {
+    /** The request, with a `gloss` field when there is one and unchanged otherwise. */
+    request: ChannelRequest;
+    outcome: GlossOutcome;
+}
+/**
+ * The request, plus a model's one-sentence gloss of its payload when one can be
+ * had.
+ *
+ * Every payload kind the renderer can read gets one (APRV-164): a command, a
+ * file change, an email. The kind is derived exactly as the WYSIWYS rendering
+ * derives it, from the structure of the bytes, so the sentence is about the
+ * material the approver is being shown and the two can never be about different
+ * payloads. An opaque payload gets none.
+ *
+ * Returns the request UNCHANGED for every flavour of "no answer". Losing the
+ * gloss costs one line on a prompt, which is why no failure here is allowed to
+ * cost anything more.
+ */
+export declare function attachGloss(request: ChannelRequest, run: GlossRunner): GlossAttachment;
+/**
+ * The instruction and the material for one payload, or `null` for an opaque one.
+ *
+ * The material is assembled from the same structural views the canonical
+ * rendering is built from, and it is deliberately plain: labelled lines and the
+ * text itself, in the order the prompt shows them. Nothing here reads a
+ * self-declared kind field, for the reason `core/wysiwys.ts` gives at length —
+ * a payload that chose its own presentation would have chosen its own gloss too.
+ */
+export declare function glossMaterial(value: unknown): {
+    instruction: string;
+    material: string;
+} | null;
+/**
+ * The stderr line that turns chronic silence into a visible fault (APRV-197 #3).
+ *
+ * One line, at the end of a walk or a dispatch cycle, and only when a model was
+ * actually asked and did not answer. It names the ceiling because that is the
+ * number an operator can act on, and it says the decision is unaffected because
+ * the first thing a reader of an approval tool's stderr needs to know is
+ * whether the thing they just approved was compromised by this. It was not:
+ * nothing downstream of a gloss exists.
+ */
+export declare function glossAbsenceLine(surface: string, absent: number, asked: number, timeoutMs: number): string;

package/dist/src/cli/gloss-codex-child.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Process-group supervisor for the synchronous Codex gloss runner (APRV-254).
+ *
+ * The public runner waits synchronously because GlossRunner is synchronous.
+ * This small child can still supervise Codex asynchronously, which lets it
+ * terminate the complete detached process group when the CLI times out or
+ * exceeds its output allowance. It never prints stderr or process errors.
+ */
+export {};

package/dist/src/cli/gloss-codex.d.ts

@@ -0,0 +1,24 @@
+/** Provider-specific Codex CLI runner for optional model glosses (APRV-254). */
+import { type GlossRunner } from "./gloss.js";
+export type CodexGlossUnavailableReason = "invalid-model" | "invalid-prompt" | "unsupported-platform" | "spawn-error" | "timeout" | "output-too-large" | "nonzero-exit" | "invalid-output" | "unsafe-output" | "cleanup-failed";
+export interface CodexGlossRunnerOptions {
+    /** Test seam. Production callers omit this and run the installed `codex`. */
+    readonly executable?: string;
+    /** Test seam. Production callers always receive the shared 20-second cap. */
+    readonly timeoutMs?: number;
+    /** Receives only a fixed reason code, never subprocess output. */
+    readonly diagnostic?: (reason: CodexGlossUnavailableReason) => void;
+}
+/**
+ * Build a synchronous Codex gloss runner using the CLI's saved authentication.
+ *
+ * The invocation starts in a new empty directory with a named read-only
+ * permission profile, command network disabled, project instructions
+ * suppressed, host skill discovery skipped, and selected known
+ * tool/integration features disabled.
+ * Codex 0.152.1 has no universal deny-all tool switch: host-managed and global
+ * base instructions still apply, the under-development discovery switch is
+ * version-specific, and the CLI owns any auth-state maintenance.
+ * The caller must present that practical isolation boundary to the operator.
+ */
+export declare function codexGlossRunnerFor(model: string, passphraseEnv?: string | null, options?: CodexGlossRunnerOptions): GlossRunner;

package/dist/src/cli/gloss-options.d.ts

@@ -0,0 +1,42 @@
+/** Shared provider selection for the three optional gloss surfaces (APRV-255). */
+import { type ParsedFlags } from "./args.js";
+import { codexGlossRunnerFor, type CodexGlossUnavailableReason } from "./gloss-codex.js";
+import { type GlossProvider, type GlossRunner } from "./gloss.js";
+/** A validated operator selection. It is safe to hand directly to a runner factory. */
+export interface GlossOptions {
+    readonly enabled: boolean;
+    readonly provider: GlossProvider;
+    readonly model: string;
+}
+export type GlossOptionsResult = {
+    readonly ok: true;
+    readonly options: GlossOptions;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Resolve the flags shared by `up`, Telegram listen and the terminal channel.
+ *
+ * The caller supplies its historical default: Telegram and `up` pass `true`,
+ * while the terminal channel passes `false`. `--no-gloss` wins a tie so an
+ * explicit request to remove a model from the path can never accidentally
+ * spawn one. Provider and model values are validated even when disabled;
+ * otherwise a typo could wait unnoticed until a later invocation adds
+ * `--gloss`.
+ */
+export declare function parseGlossOptions(flags: ParsedFlags, enabledByDefault: boolean): GlossOptionsResult;
+type ClaudeRunnerFactory = (passphraseEnv: string | null, model: string) => GlossRunner;
+type CodexRunnerFactory = typeof codexGlossRunnerFor;
+/** Fixed reason codes only; subprocess output must never reach this callback. */
+export type GlossDiagnostic = (reason: CodexGlossUnavailableReason) => void;
+export interface GlossRunnerFactoryOptions {
+    readonly passphraseEnv?: string | null;
+    readonly diagnostic?: GlossDiagnostic;
+    /** Test seams. Production callers use the provider implementations above. */
+    readonly claudeRunnerFor?: ClaudeRunnerFactory;
+    readonly codexRunnerFor?: CodexRunnerFactory;
+}
+/** Construct exactly the selected runner, or no runner when glossing is disabled. */
+export declare function glossRunnerFromOptions(selection: GlossOptions, factoryOptions?: GlossRunnerFactoryOptions): GlossRunner | undefined;
+export {};

package/dist/src/cli/gloss.d.ts

@@ -0,0 +1,265 @@
+/**
+ * The model gloss: one sentence saying what a payload does, attached to a
+ * prompt at render time and to nothing else (APRV-144, APRV-164).
+ *
+ * The observed complaint (Carter, 2026-08-25): "the claimed isn't very useful —
+ * I mostly see the path, not a readable claim of what is happening". The
+ * deterministic half of the answer is `channels/payload-view.ts`'s command
+ * breakdown, which is derived from the classifier's own parse and is COMPUTED.
+ * This is the other half, and it is the opposite kind of thing: a sentence from
+ * a language model, which no party vouches for and which the runtime must
+ * therefore treat as decoration.
+ *
+ * Four properties hold the design together, and every one of them is about
+ * keeping a model out of the decision.
+ *
+ * **The gate never sees it.** This runs in the LISTENER, at the moment a
+ * message is about to be sent, on a `ChannelRequest` the tagger has already
+ * finished building. The payload hash covers the bytes and not this; the log
+ * records the approval lifecycle and not this; a restart forgets it. Nothing
+ * here writes anything anywhere.
+ *
+ * **It is never load-bearing.** No code path branches on the content of a
+ * gloss. The only thing that turns on it at all is whether one more line
+ * appears in the CLAIMED block, which is why every failure mode below resolves
+ * to ABSENCE rather than to a placeholder, an error line, or a retry: a prompt
+ * with no gloss is the prompt approval.md shipped for its whole life so far,
+ * and a listener that waited on a model would have made a language model part
+ * of the availability of the gate.
+ *
+ * **It fails toward absence, fast.** A hard timeout (default
+ * {@link GLOSS_TIMEOUT_MS}), a non-zero exit, empty output, a binary that is
+ * not installed, a spawn that throws: all `null`. The timeout is bounded on
+ * purpose — this sits in a dispatch cycle that an approver is waiting on — and
+ * since APRV-197 it is bounded by a MEASUREMENT rather than by a guess, because
+ * a ceiling the model cannot meet is not a fast failure, it is a feature that
+ * never runs. See {@link GLOSS_TIMEOUT_MS}. Absences are counted and reported
+ * by the caller (`cli/gloss-attach.ts`), so a ceiling that is wrong again
+ * announces itself instead of looking like silence.
+ *
+ * **Its output is untrusted text.** Whatever comes back is collapsed to a
+ * single line, capped at {@link GLOSS_MAX_CHARS}, and handed to the channel as
+ * a CLAIMED field, which means it goes through the same `escapeHtml` every
+ * other claimed value does. It is treated exactly like a summary an agent
+ * wrote, because that is precisely what it is a cousin of.
+ *
+ * The subprocess is injectable ({@link GlossRunner}) so the tests drive both
+ * branches without a model ever being invoked: the suite never spawns
+ * anything, and the default runner below is exercised only in production.
+ */
+/**
+ * How long the subprocess gets before it is killed and the gloss is dropped.
+ *
+ * **Measured, not guessed (APRV-197).** APRV-144 chose 2s on the reasoning that
+ * "a slow reading aid is worse than no reading aid", which is true and was the
+ * wrong number: five fresh `claude -p --model haiku` spawns of this module's
+ * own command instruction, timed on the author's machine on 2026-09-01, came
+ * back in 10.2s, 11.3s, 13.5s, 14.6s and 14.9s. Every one of them would have
+ * been killed. The gloss was therefore not "occasionally absent"; it was
+ * absent every single time, and because absence is silent by design that was
+ * indistinguishable from the feature never having shipped — which is exactly
+ * how it was reported (Carter, 2026-09-01: "i thought we implemented a change
+ * so that the claim would be an llm summary").
+ *
+ * A pre-warm was the other option on the table and the measurement rules it
+ * out: the runs above were consecutive, so runs two through five were warm in
+ * every sense a second process can be (page cache, module cache), and they took
+ * 10s to 15s all the same. What is being waited on is inference, not start-up,
+ * and nothing a listener does once at boot shortens it.
+ *
+ * So the ceiling is set above the slowest observed run with headroom, and the
+ * price of that honesty is made explicit rather than hidden. A gloss is now
+ * asked for only under `--gloss` (on `channel cli`, `channel telegram listen`
+ * and `up` alike): an operator who wants the sentence spends the seconds
+ * knowingly, one who does not is never made to wait, and the reading aid that
+ * is always present is the deterministic `command_breakdown` the classifier
+ * derives from the same bytes for free.
+ */
+export declare const GLOSS_TIMEOUT_MS = 20000;
+/** The most characters a gloss may occupy on the prompt. */
+export declare const GLOSS_MAX_CHARS = 200;
+/** Maximum length of an exact provider-supplied model identifier. */
+export declare const GLOSS_MODEL_ID_MAX_CHARS = 100;
+/**
+ * The model tier this spends: the cheap one.
+ *
+ * CLAUDE.md's model tiers put "cheap classification" on a `claude -p` haiku
+ * subprocess, and a one-sentence paraphrase of a command line is the cheapest
+ * kind of language task there is. Nothing about the prompt or the gate changes
+ * if the flag is unrecognised by the installed CLI: an unusable invocation
+ * exits non-zero and the gloss is absent.
+ */
+export declare const GLOSS_MODEL = "haiku";
+/**
+ * The historical author label for legacy string-valued test runners.
+ *
+ * Production runners return explicit provenance. Keeping this constant is a
+ * compatibility bridge for callers whose injected seam predates APRV-253; it
+ * must never be used to guess the provenance of a typed production result.
+ */
+export declare const GLOSS_AUTHOR = "model:haiku";
+/**
+ * The instruction the model is given.
+ *
+ * Deliberately narrow: describe, do not judge. A model asked whether a command
+ * is safe would produce a sentence an approver could read as a recommendation,
+ * and a recommendation from an unverified party sitting beside an Approve
+ * button is the failure this whole codebase is arranged to prevent. It is
+ * asked what the command DOES, and the answer is labelled as a model's on the
+ * line where it appears.
+ */
+export declare const GLOSS_INSTRUCTION: string;
+/**
+ * The same instruction for a file change (APRV-164).
+ *
+ * A payload kind gets its own wording because "what this shell command does" is
+ * the wrong question to ask about a diff, and a model handed the wrong question
+ * answers a question nobody asked. The discipline is identical: describe the
+ * change, do not rate it, and above all do not say whether the edit looks
+ * correct — a judgement of a diff sitting beside an Approve button is the same
+ * failure as a judgement of a command.
+ */
+export declare const GLOSS_EDIT_INSTRUCTION: string;
+/** The same instruction for an email (APRV-164): what it says, and to whom. */
+export declare const GLOSS_EMAIL_INSTRUCTION: string;
+/**
+ * The most material a gloss may hand the subprocess.
+ *
+ * A whole-file `Write` payload is megabytes, and a reading aid must not turn a
+ * dispatch cycle into a megabyte of argv and a model reading it. The cap is on
+ * the INPUT only: {@link GLOSS_MAX_CHARS} still bounds what comes back.
+ */
+export declare const GLOSS_MAX_INPUT_CHARS = 8192;
+/**
+ * What the model is told when the cap bit.
+ *
+ * Announced rather than silent, for the reason every other fold in this
+ * codebase is announced: a model describing a prefix as if it were the whole
+ * would produce a confident sentence about a change the approver is not being
+ * shown. The line is for the model; the approver's own evidence is the PAYLOAD
+ * block, which is never folded.
+ */
+export declare const GLOSS_TRUNCATION_NOTE = "(input truncated; describe what is shown)";
+/** A summarizer implementation the listener may explicitly select. */
+export type GlossProvider = "claude" | "codex";
+/**
+ * The model identity a runner can honestly establish.
+ *
+ * `requestedModel` is always present because it is controlled by the
+ * invocation. `confirmedModel` is present only when machine-readable process
+ * output identifies the model that actually served the request. A successful
+ * process exit alone does not confirm that identity.
+ */
+export interface GlossProvenance {
+    provider: GlossProvider;
+    requestedModel: string;
+    confirmedModel?: string;
+}
+/** One raw model answer together with runner-supplied provenance. */
+export interface GlossResult {
+    text: string;
+    provenance: GlossProvenance;
+    /** Compatibility marker for the pre-APRV-253 injected string seam. */
+    legacy?: true;
+}
+/**
+ * How a gloss is obtained.
+ *
+ * New runners return a {@link GlossResult}. A raw string remains accepted only
+ * so existing injected stubs keep working; it is explicitly interpreted as
+ * the historical Claude/Haiku seam. Every flavour of "no answer" is `null`.
+ *
+ * MUST NOT throw: a runner that raised would put a language model on the
+ * failure path of the listener's dispatch cycle.
+ */
+export type GlossRunnerOutput = GlossResult | string | null;
+export type GlossRunner = (prompt: string) => GlossRunnerOutput;
+/**
+ * One line, capped, or `null`.
+ *
+ * Newlines are stripped rather than escaped because the prompt renders this as
+ * a single bullet, and a multi-line value would break the one-fact-per-line
+ * shape the whole COMPUTED/CLAIMED split relies on to stay legible. Truncation
+ * is marked, for the same reason every other fold in this codebase is.
+ */
+export declare function tidyGloss(raw: string | null): string | null;
+/**
+ * Normalize a runner answer without inventing provenance.
+ *
+ * Objects with incomplete metadata fail toward absence. Raw strings take the
+ * one narrowly documented legacy path and retain the historical Haiku label.
+ */
+export declare function tidyGlossResult(raw: unknown): GlossResult | null;
+/** A bounded, single-line identifier, or `null` rather than a misleading fold. */
+export declare function normalizeGlossModelId(raw: unknown): string | null;
+/**
+ * The claimed author rendered beside one gloss.
+ *
+ * Requested and confirmed identities are deliberately distinct. The default
+ * subprocess knows what it asked Claude for, but its plain stdout does not
+ * prove which model served the request, so it renders as requested.
+ */
+export declare function glossAuthor(result: GlossResult): string;
+/**
+ * The production runner: `claude -p --model haiku`, with a hard timeout.
+ *
+ * `spawnSync` with no shell, in the manner of `cli/hook.ts`'s git calls: the
+ * prompt is an argument and never a string a shell re-parses. Every failure is
+ * a value rather than an exception — `spawnSync` reports a missing binary and a
+ * timeout kill on the result object, and both are simply "no gloss".
+ *
+ * **Starved, like a granted child (APRV-207).** The environment is built by
+ * APRV-205's scrub rather than inherited: this is a third-party CLI that talks
+ * to the network on every prompt render, spawned by the listener, which is the
+ * process holding the Telegram bot token and the vault passphrase. It has no
+ * use for either, and a gate that hands its own credentials to a convenience is
+ * a gate whose custody claim is decorative. No credential is DECLARED here,
+ * because a gloss is not a granted action and no adapter asked for one.
+ *
+ * What passes is what the scrub does not take: the model's own auth
+ * (`ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`,
+ * `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL` and kin), `PATH`, `HOME`, `TMPDIR`
+ * and the locale. None of them is under the gate's credential-bearing prefixes,
+ * so none of them needs a list of its own: a second list here is a second list
+ * to drift, and the CLI's ability to reach its own model is not this gate's
+ * secret to keep.
+ *
+ * `passphraseEnv` is the name the policy's `vault.passphrase_env` gives, for
+ * the deployment that renamed it out from under the prefixes. Omitted, the
+ * default (`APPROVAL_VAULT_PASSPHRASE`) is removed by the prefix rule anyway.
+ */
+export declare function spawnGloss(prompt: string, passphraseEnv?: string | null, model?: string): GlossResult | null;
+/**
+ * {@link spawnGloss} bound to one policy's passphrase variable (APRV-207).
+ *
+ * The verbs that wire a runner (`channel cli`, `channel telegram listen`, `up`)
+ * have a policy load in hand already, and this is the only thing the scrub
+ * needs from it. A runner is still a `(prompt) => string | null`, so nothing
+ * downstream learns that a policy exists.
+ */
+export declare function glossRunnerFor(passphraseEnv: string | null, model?: string): GlossRunner;
+/**
+ * `material`, capped at {@link GLOSS_MAX_INPUT_CHARS} and marked when it was.
+ *
+ * The marker precedes the material rather than trailing it, so a model reading
+ * a long prefix meets the caveat before the text it is about to describe.
+ */
+export declare function glossPrompt(instruction: string, material: string): string;
+/**
+ * A gloss for one payload's material, or `null`.
+ *
+ * The material is passed to the model as data inside the prompt. It is
+ * agent-authored text, and it is worth being explicit about what that does and
+ * does not mean here: a command (or a diff, or a body) crafted to talk the
+ * model into writing "harmless cleanup" gets that sentence onto the prompt,
+ * labelled `(model, unverified)`, next to a COMPUTED breakdown derived from the
+ * same bytes by code and a PAYLOAD block carrying the canonical rendering verbatim. It
+ * cannot change the class, the autonomy, the budget verdicts or the payload
+ * hash, because nothing downstream reads it. That is the whole reason this is
+ * allowed to exist on the prompt at all.
+ *
+ * The caller chooses the instruction, which is the only thing that varies by
+ * payload kind: the bounds, the failure modes and the author label are one
+ * pipeline for every kind (APRV-164).
+ */
+export declare function glossFor(instruction: string, material: string, run?: GlossRunner): GlossResult | null;