approval-md 0.0.1 → 0.2.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/git-scope.js

@@ -0,0 +1,295 @@
+/**
+ * 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 { spawnSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve as resolvePathSegments, sep, } from "node:path";
+import { GIT_OUTPUT_LIMIT_BYTES, gh, git } 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 };
+function absolute(value, cwd) {
+    return isAbsolute(value) ? value : resolvePathSegments(cwd, value);
+}
+/** The repository root containing `dir`, or `null` when there is none. */
+export function repoRoot(dir) {
+    const result = git(["rev-parse", "--show-toplevel"], dir);
+    if (!result.ok)
+        return null;
+    const root = result.stdout.trim();
+    return root.length === 0 ? null : root;
+}
+/**
+ * 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 function primaryRoot(cwd) {
+    const result = git(["rev-parse", "--git-common-dir"], cwd);
+    if (!result.ok)
+        return null;
+    const common = result.stdout.trim();
+    if (common.length === 0)
+        return null;
+    return dirname(absolute(common, cwd));
+}
+/** `realpathSync` that answers the path itself when the path cannot be resolved. */
+function real(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+/**
+ * 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 function primaryCheckout(cwd) {
+    const primary = primaryRoot(cwd);
+    const top = repoRoot(cwd);
+    if (primary === null || top === null) {
+        return {
+            ok: false,
+            reason: "git could not say which repository this directory belongs to",
+            worktreeRoot: top,
+            primary,
+        };
+    }
+    if (real(primary) !== real(top)) {
+        return {
+            ok: false,
+            reason: `this is the linked worktree ${top}, whose primary checkout is ${primary}`,
+            worktreeRoot: top,
+            primary,
+        };
+    }
+    return { ok: true, root: top };
+}
+/**
+ * `realpathSync` for a path that may not exist yet.
+ *
+ * The existing part of the path is resolved and the missing tail is appended.
+ * A log file that has not been created yet still has to produce the same
+ * repo-relative spelling as one that has, or a check would answer differently
+ * depending on whether it ran before or after the first append.
+ */
+function realish(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        const parent = dirname(path);
+        if (parent === path)
+            return path;
+        return join(realish(parent), basename(path));
+    }
+}
+/**
+ * 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 function repoPath(root, path) {
+    return relative(realish(root), realish(path)).split(sep).join("/");
+}
+/** The checked-out branch, or `null` on a detached HEAD. */
+export function currentBranch(root) {
+    const result = git(["symbolic-ref", "--quiet", "--short", "HEAD"], root);
+    if (!result.ok)
+        return null;
+    const name = result.stdout.trim();
+    return name.length === 0 ? null : name;
+}
+/**
+ * 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 function readBlob(root, rev, relative_) {
+    const spec = `${rev}:${relative_}`;
+    const result = spawnSync("git", ["show", spec], { cwd: root, maxBuffer: GIT_OUTPUT_LIMIT_BYTES });
+    const command = `git show ${spec}`;
+    if (result.error !== undefined || result.status === null) {
+        return {
+            ok: false,
+            command,
+            status: null,
+            detail: result.error === undefined
+                ? "git produced no exit status"
+                : `git did not complete: ${result.error.message}`,
+        };
+    }
+    if (result.status !== 0) {
+        const said = outputLines(result.stderr?.toString("utf8") ?? "").join(" | ");
+        return {
+            ok: false,
+            command,
+            status: result.status,
+            detail: `git exited ${String(result.status)}${said.length === 0 ? "" : `: ${said}`}`,
+        };
+    }
+    return { ok: true, bytes: result.stdout };
+}
+/**
+ * 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 function showBlob(root, rev, relative_) {
+    const read = readBlob(root, rev, relative_);
+    return read.ok ? read.bytes : null;
+}
+/** Everything git said about a run, as trimmed non-empty lines. */
+export function outputLines(...texts) {
+    return texts
+        .join("\n")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+// ---------------------------------------------------------------------------
+// Basing a ceremony commit on the remote, without checking anything out
+// ---------------------------------------------------------------------------
+/**
+ * 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 function fetchBase(root, remote, branch) {
+    const fetched = git(["fetch", remote, branch], root);
+    if (!fetched.ok) {
+        return {
+            ok: false,
+            message: `\`git fetch ${remote} ${branch}\` failed: ${failureText(fetched)}`,
+            quote: outputLines(fetched.stderr, fetched.stdout),
+        };
+    }
+    const resolved = git(["rev-parse", "--verify", "--quiet", "FETCH_HEAD^{commit}"], root);
+    const sha = resolved.stdout.trim();
+    if (!resolved.ok || sha.length === 0) {
+        return {
+            ok: false,
+            message: `\`git fetch ${remote} ${branch}\` succeeded and named no commit: ${failureText(resolved)}`,
+            quote: outputLines(resolved.stderr, resolved.stdout),
+        };
+    }
+    return { ok: true, sha };
+}
+/**
+ * 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 function commitOnBase(root, request) {
+    const scratch = mkdtempSync(join(tmpdir(), "approval-index-"));
+    const env = { GIT_INDEX_FILE: join(scratch, "index") };
+    const failed = (step, run) => ({
+        ok: false,
+        step,
+        message: `\`${step}\` failed: ${failureText(run)}`,
+        quote: outputLines(run.stderr, run.stdout),
+    });
+    try {
+        const read = git(["read-tree", request.base], root, env);
+        if (!read.ok)
+            return failed(`git read-tree ${request.base}`, read);
+        const added = git(["add", "-A", "--", ...request.paths], root, env);
+        if (!added.ok)
+            return failed("git add", added);
+        for (const blob of request.blobs ?? []) {
+            const pinned = git(["update-index", "--add", "--cacheinfo", `100644,${blob.sha},${blob.path}`], root, env);
+            if (!pinned.ok)
+                return failed(`git update-index ${blob.path}`, pinned);
+        }
+        const tree = git(["write-tree"], root, env);
+        if (!tree.ok)
+            return failed("git write-tree", tree);
+        const treeSha = tree.stdout.trim();
+        const baseTree = git(["rev-parse", `${request.base}^{tree}`], root);
+        if (baseTree.ok && baseTree.stdout.trim() === treeSha) {
+            return { ok: true, sha: null, unchanged: true };
+        }
+        const commit = git(["commit-tree", treeSha, "-p", request.base, "-m", request.message], root, env);
+        if (!commit.ok)
+            return failed("git commit-tree", commit);
+        const sha = commit.stdout.trim();
+        if (sha.length === 0) {
+            return { ok: false, step: "git commit-tree", message: "git commit-tree printed no sha", quote: [] };
+        }
+        return { ok: true, sha, unchanged: false };
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}
+/** The same, folded onto one line for a `--json` message string. */
+export function failureText(run) {
+    const lines = outputLines(run.stderr, run.stdout);
+    return lines.length === 0 ? "git printed nothing" : lines.join(" | ");
+}
+//# sourceMappingURL=git-scope.js.map

package/dist/src/cli/git-scope.js.map

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

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;