approval-md 0.1.0 → 0.2.0

package/dist/src/cli/exit-codes.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Process exit codes for the `approval` CLI — **frozen public API**.
+ *
+ * SPEC.md §10.1 makes the CLI the primary interface for humans *and* agents.
+ * An agent branches on the exit code before it ever looks at stdout, so these
+ * five numbers are part of the contract: they are defined once, here, and every
+ * `--help` text prints them. Adding a code is a spec change; changing the
+ * meaning of an existing one is a breaking change.
+ *
+ * The distinction that matters most is {@link EXIT_INTEGRITY} vs
+ * {@link EXIT_IO}. "I could not read the file" and "the file has been tampered
+ * with" are different facts about the world, and conflating them either cries
+ * wolf over a permission bit or — far worse — lets real tampering read as a
+ * transient filesystem hiccup. The core `verify()` reports a non-ENOENT read
+ * failure as `corrupt`, because from inside the chain walker an unreadable log
+ * is indistinguishable from a broken one; the CLI boundary therefore checks
+ * readability *itself* before calling core, and reports I/O as I/O. Messages on
+ * this path must never use the word "corrupt".
+ */
+/**
+ * Success. `verify`: the chain is clean. `tail`/`export`: the requested records
+ * were produced — including the torn-tail case, where the intact prefix is
+ * printed and the tear is a stderr warning. `reindex`: the index was built.
+ */
+export declare const EXIT_OK = 0;
+/**
+ * Integrity failure. `verify`: the log is corrupt. `tail`/`export`: refused to
+ * print records from a corrupt log. `reindex`: refused to index one
+ * (`not-clean`).
+ */
+export declare const EXIT_INTEGRITY = 1;
+/** Usage error: unknown command, unknown flag, missing or invalid value. */
+export declare const EXIT_USAGE = 2;
+/**
+ * Torn tail — the log's final line is unterminated, the signature of a crashed
+ * write rather than of tampering. `verify` reports it; `reindex` refuses
+ * without `--force`. Nothing is ever repaired: truncating a torn line is a
+ * human decision.
+ */
+export declare const EXIT_TORN_TAIL = 3;
+/**
+ * I/O error: the log or the index path could not be read, created, or
+ * replaced. Never used for anything the log itself says about its own
+ * contents.
+ */
+export declare const EXIT_IO = 4;
+/**
+ * No valid execution token — **`approval run` only** (APRV-18, human-settled
+ * 2026-08-06: "refuses without a valid token at a distinct exit code").
+ *
+ * An addition to the table above, not a redefinition of anything in it: every
+ * command that existed before APRV-18 still uses 0–4 and none of them can emit
+ * 5. It is distinct from {@link EXIT_INTEGRITY} because the repair is distinct.
+ * A generic gate refusal means "ask a human what to do"; a 5 means "you are
+ * holding no key to this door" — request the action, get it granted, and pass
+ * the token that grant printed. An agent that could not tell those apart would
+ * escalate when it should retry with a token, or retry forever when it should
+ * escalate.
+ */
+export declare const EXIT_NO_TOKEN = 5;
+/**
+ * Timeout — **`approval wait` only** (APRV-18). The wait elapsed with the
+ * task's requests still undecided. Nothing was appended and nothing is implied
+ * about the request: it is still live, and waiting again is legitimate.
+ *
+ * Distinct from every decision code, because "no answer yet" is not an answer.
+ * `wait` is the one verb whose exit code encodes a *decision* rather than a
+ * runtime outcome (SPEC.md §10.1: "exit code = decision"), so its mapping is
+ * documented in full in its own `--help`.
+ */
+export declare const EXIT_TIMEOUT = 6;
+/** The frozen table, for help text and for tests that pin it. */
+export declare const EXIT_CODE_TABLE: ReadonlyArray<readonly [number, string]>;

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

@@ -0,0 +1,60 @@
+/**
+ * `approval feedback` (APRV-239) — what the operator thought, read back.
+ *
+ * The HUMAN-TO-AGENT direction of the log, at the CLI. Two records can carry a
+ * human's own words about an action: `approval.granted`, where a person answered
+ * the gate, and `audit.reviewed`, where a person looked at a sampled action
+ * afterwards. Both may carry a graded `reaction` and both may carry a `note`.
+ * This verb collects them, joins each to the class, the task, the action key and
+ * the AGENT whose work it was, and prints them behind a banner.
+ *
+ * Three properties are the whole design, and each is enforced somewhere in this
+ * file rather than asserted in prose:
+ *
+ * - **It is guidance, and it says so on every output form.** {@link FEEDBACK_BANNER}
+ *   leads the human rendering and rides in the `note` field of the JSON. A
+ *   surface that printed reactions without labelling them would be handing an
+ *   agent free-text human prose in the shape of a rule (SPEC.md §11.1
+ *   invariant 10 requires the label; the invariant's substance is that nothing
+ *   in the runtime reads any of this).
+ * - **It is symmetric with `journal`, deliberately.** `journal read` is the
+ *   operator reading what the agents said; this is the agents reading what the
+ *   operator said. Same shape of entry, same delimiters, same `--since` and
+ *   `--limit`. The one difference is that no entry here is marked `[claimed]`:
+ *   these are the overseer's words, appended under a `human:` actor to a
+ *   hash-chained log, which is precisely the thing `[claimed]` exists to
+ *   distinguish journal text FROM.
+ * - **It reads verified records and nothing else.** No policy is resolved, no
+ *   clock is read, nothing is appended. A log that does not verify refuses with
+ *   the log-* exit codes rather than showing a partial list, because a reaction
+ *   read out of an unverifiable log is a sentence attributed to a person who may
+ *   not have written it.
+ *
+ * `--actor` filters on the AGENT the feedback is about, not on the human who
+ * wrote it. That is the question an agent reading this actually has ("what has
+ * the operator said about my work"), and the human side is a small closed set
+ * that a `--source` filter already separates usefully.
+ */
+import type { Streams } from "./main.js";
+/**
+ * The one line every output form carries.
+ *
+ * Exported because the guard tests assert it is on both renderings. A surface
+ * that stopped saying what these words are would be offering an agent a
+ * human's after-the-fact opinion in the same register as a policy rule, and the
+ * agent's correct reading of a policy rule is "this binds me". Nothing here
+ * binds anything: SPEC.md §11.1 invariant 10 says no enforcement path reads a
+ * reaction, and this sentence is how a reader learns that without going to the
+ * spec.
+ */
+export declare const FEEDBACK_BANNER = "HUMAN-AUTHORED GUIDANCE, not policy. A reaction records what the operator thought of an action after the fact; it grants nothing, forbids nothing, and changes no verdict, sampling probability or budget.";
+/**
+ * `approval feedback [filters] [--log <path>] [--json]`.
+ *
+ * Reads and prints. There is no write half and there will not be one: the two
+ * verbs that record a reaction are `approval grant` and `approval audit review`,
+ * both human-only, and a third path into the same field that was not one of
+ * those would be a way for the party under oversight to author the operator's
+ * opinion of it.
+ */
+export declare function commandFeedback(argv: string[], streams: Streams, cwd: string): number;

package/dist/src/cli/gate-window.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `approval gate open|close|status` — the open window's CLI (APRV-214, amended
+ * SPEC.md §5.2).
+ *
+ * As everywhere else in this CLI, no logic lives here. Deriving the window,
+ * checking the actor, the cap and the window state, and every append are
+ * `core/gate-window.ts`; this file resolves paths and identity, runs the
+ * ceremony, chooses an exit code, and formats output.
+ *
+ * ## The ceremony, and why it is shaped like this
+ *
+ * `open` suspends the harness gate's policy for every tool call under the root.
+ * Three locks stand between an agent and that, and they are independent:
+ *
+ *  1. **The class.** `approval gate open` classifies `policy.core`
+ *     (`core/command-class.ts`), which APPROVAL.md holds human-only, so the
+ *     harness hook denies the command before it ever runs.
+ *  2. **The terminal.** `createPrompter` returns `null` unless `process.stdin`
+ *     is a TTY, and a harness shell tool has no TTY. `--json` refuses for the
+ *     same reason: a machine-readable answer implies a machine asking.
+ *  3. **The word.** One line is read and only exactly `understood` proceeds.
+ *     There is deliberately NO `--yes` and no `--force`: a flag that answers
+ *     the question is a way for something that cannot type to type.
+ *
+ * `close` has none of it beyond the human actor, because closing only ever
+ * tightens, and a ceremony guarding the safe direction is one people learn to
+ * type past. `status` decides nothing and writes nothing.
+ */
+import type { Streams } from "./main.js";
+import { type Prompter } from "./prompt.js";
+/**
+ * Injected seams. `prompter` is the terminal, exactly as `commandSetup`'s is:
+ * a test passes a scripted one and asserts on what was asked as well as on what
+ * was done, and passing `null` is how "there is no terminal" becomes a test
+ * rather than a claim.
+ */
+export interface GateWindowDeps {
+    prompter?: Prompter | null;
+}
+export declare function commandGate(argv: string[], streams: Streams, cwd: string, deps?: GateWindowDeps): number;

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

@@ -0,0 +1,68 @@
+/**
+ * The gate verbs of SPEC.md §10.1: `approval register`, `approval request`,
+ * `approval grant|reject|revoke`, and `approval expire`.
+ *
+ * As everywhere else in this CLI, **no logic lives here.** State derivation,
+ * transition legality, TTL arithmetic, attestation, and budgets are all
+ * `core/gate.ts`; frontmatter reading is `core/frontmatter.ts`; the append is
+ * `core/log.ts`. This file resolves paths and identity, chooses an exit code,
+ * and formats output.
+ *
+ * Four choices are load-bearing enough to state plainly.
+ *
+ * **A gate refusal is exit 1, not exit 2.** "You may not do that" is not a
+ * usage error — the command was well-formed, the runtime understood it, and the
+ * answer is no. Grouping refusals with typos would train agents to retry with
+ * different flags when the correct response is to ask a human. Exit 2 stays what
+ * it has always been: an unknown flag, a missing argument, an unresolvable
+ * identity. The frozen `error.code` inside `--json` is what a caller branches on
+ * to tell *which* refusal it was.
+ *
+ * **The log supplies the action's declaration, not flags.** `approval request
+ * <task> --action <key>` reads the action's class, cost, reversibility and
+ * summary from the `task.registered` record in the log — the same record
+ * `approval register` wrote from the envelope. There are no `--class` /
+ * `--cost` flags, deliberately: an agent that could name its own class at
+ * request time could declare `read.web` for an action registered as
+ * `financial.spend`, and SPEC.md §7's "class MUST be declared before a token can
+ * be requested" would mean nothing. Register once from the file; request against
+ * what was registered. A task file edited after registration is `envelope.drift`
+ * (M5), not a silent re-declaration.
+ *
+ * **`register` reads task files but never writes them.** Unknown frontmatter
+ * keys are preserved trivially here because nothing is rewritten at all;
+ * round-trip rewriting is M6.
+ *
+ * **grant / reject / revoke are human-only**, via `resolveHumanActor` — `--as
+ * human:<id>` or `APPROVAL_HUMAN`, refused at exit 2 when absent or when it
+ * names an agent. `expire` takes no identity at all: it is the system verb, and
+ * `core/gate.ts` stamps `system:gate`.
+ *
+ * **This layer no longer reads the clock.** It used to pass `new Date()` into
+ * every gate call; under amended SPEC.md §8 (A2) a gate-typed event's `ts` is
+ * assigned inside core at the write boundary, and there is no parameter here to
+ * pass one through. Nothing about determinism is lost — core reads an injected
+ * clock — and one caller-supplied-timestamp seam is gone.
+ */
+import { type Decision } from "../core/gate.js";
+import type { Streams } from "./main.js";
+export declare function commandRegister(argv: string[], streams: Streams, cwd: string): number;
+export declare function commandRequest(argv: string[], streams: Streams, cwd: string): number;
+export declare function commandDecide(decision: Decision, argv: string[], streams: Streams, cwd: string): number;
+/**
+ * `approval withdraw <task> --action <key>` — the requester takes its own
+ * pending request back (APRV-106).
+ *
+ * Agent-facing, unlike every other terminal verb here: the whole point is that
+ * the party who asked can stop asking, and the party who asks is usually an
+ * agent. Identity resolves through {@link resolvePrincipalActor}, and the gate
+ * then checks it against the actor on the `approval.requested` record — so
+ * passing `--as` does not let a caller withdraw someone else's request, it only
+ * lets the caller say who it is.
+ *
+ * The task id is positional and the action key is a flag, matching
+ * `approval request` exactly: the two verbs are the open and the close of one
+ * gesture, and an agent that can spell one can spell the other.
+ */
+export declare function commandWithdraw(argv: string[], streams: Streams, cwd: string): number;
+export declare function commandExpire(argv: string[], streams: Streams, cwd: string): number;

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 {};