approval-md 0.1.0 → 0.2.0

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

@@ -0,0 +1,120 @@
+/**
+ * `approval daemon run` — the foreground daemon verb (SPEC.md §10.2, APRV-39).
+ *
+ * As everywhere else in this CLI, **no logic lives here**. The loop, the drift
+ * comparison, the TTL sweep, and the queue regeneration are `daemon/daemon.ts`
+ * and `daemon/projection.ts`; every append they make goes through the same
+ * `core/gate.ts` and `core/log.ts` paths every other verb uses. This file
+ * resolves paths, validates two durations, renders the daemon's event stream as
+ * text or JSON, installs the signal handlers, and chooses an exit code.
+ *
+ * ## Foreground, deliberately
+ *
+ * `approval daemon run` runs in the foreground and stops on SIGINT/SIGTERM. It
+ * does not fork, write a pidfile, or manage its own lifecycle: in v0.1
+ * backgrounding is the operator's business, and `systemd`, `launchd`, `tmux`,
+ * and `&` all already do it better than a bespoke daemonizer would. That is
+ * stated in `--help` because an operator has to know it before they type it, and
+ * it is exactly the stance `approval channel telegram listen` takes for the same
+ * reason.
+ *
+ * ## What the exit code means
+ *
+ * A clean stop is 0 — a signal is how this verb is *supposed* to end. The three
+ * non-zero endings are the log's, mapped onto the frozen table exactly as every
+ * other verb maps them: 4 when the log cannot be read, 3 when its tail is torn,
+ * 1 when the chain does not verify. The daemon stops rather than degrades on all
+ * three, because nothing may be appended onto a log that does not verify and a
+ * projection of one would be a screenshot of something nobody should read.
+ */
+import { type DaemonEvent, type DaemonOutcome } from "../daemon/daemon.js";
+import { type AdvanceCadence } from "../daemon/advance.js";
+import { type GitEvidenceEvent } from "../daemon/git-evidence.js";
+import { type LoadPolicyOptions } from "../core/policy-load.js";
+import type { Streams } from "./main.js";
+/**
+ * A duration flag, in the policy's own `<n><unit>` vocabulary (SPEC.md §5.2).
+ *
+ * Exported for `approval up` (APRV-110), which accepts the same three durations
+ * and must refuse a typo in exactly the same words.
+ */
+export declare function durationFlag(flags: Record<string, string | boolean>, name: string, fallback: number): {
+    ok: true;
+    ms: number;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * The cadence-advance flags, as one cadence or none (APRV-204).
+ *
+ * Exported for `approval up`, which accepts every `daemon run` flag and must
+ * refuse a typo in exactly the same words — the reason {@link durationFlag} is
+ * exported, and the reason this parsing is not written twice.
+ *
+ * Every duration and count is judged HERE, before the first tick: a daemon that
+ * accepted `--advance-after twenty` and quietly advanced on the default would be
+ * lying about its own configuration for as long as it ran.
+ */
+export declare function advanceFlags(flags: Record<string, string | boolean>): {
+    ok: true;
+    cadence: AdvanceCadence | null;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * The prefix-proof flags, resolved against the policy (APRV-217).
+ *
+ * Precedence is the one every override in this CLI uses: the flag wins for this
+ * run, the policy governs when no flag was typed, and an unloadable policy
+ * yields the default — which here is `full`, the strictest and most expensive
+ * proof, so a policy nobody could read cannot buy a cheaper one.
+ *
+ * Exported for `approval up`, which accepts every `daemon run` flag and must
+ * refuse a typo in exactly the same words — the reason {@link durationFlag} and
+ * {@link advanceFlags} are exported.
+ */
+export declare function readProofFlags(flags: Record<string, string | boolean>, policy: LoadPolicyOptions): {
+    ok: true;
+    readProof: {
+        mode: "full" | "incremental";
+        everyReads: number;
+        afterMs: number;
+    };
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * One daemon event as a human sentence.
+ *
+ * Warnings go to stderr and everything else to stdout, so `approval daemon run >
+ * daemon.log` keeps the narrative and leaves the complaints on the terminal.
+ */
+export declare function describeDaemonEvent(event: DaemonEvent): {
+    text: string;
+    stderr: boolean;
+};
+/**
+ * One git-evidence line as a human sentence (APRV-42).
+ *
+ * Its own function rather than a branch of {@link describe}, because the
+ * hardening layer has its own frozen event shape and `daemon/daemon.ts`'s union
+ * is untouched by the opt-in. Failures go to stderr with everything else that
+ * complains.
+ */
+export declare function describeGitEvidence(event: GitEvidenceEvent): {
+    text: string;
+    stderr: boolean;
+};
+/** The outcome → frozen exit code mapping, drawn where every other verb draws it. */
+export declare function exitForDaemonOutcome(outcome: DaemonOutcome): number;
+/**
+ * `approval daemon run`. Returns a promise, so `main` treats `daemon` the way it
+ * treats `channel`: the CLI is synchronous by contract, and the two long-lived
+ * verbs report their eventual code through `process.exitCode`.
+ */
+export declare function commandDaemonRun(argv: string[], streams: Streams, cwd: string): number | Promise<number>;
+/** `approval daemon <subcommand>` — `run`, and nothing else at v0.1. */
+export declare function commandDaemon(argv: string[], streams: Streams, cwd: string): number | Promise<number>;

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

@@ -0,0 +1,129 @@
+/**
+ * `approval doctor` — environment sanity in one verb (APRV-31).
+ *
+ * ## Why this exists
+ *
+ * During the live policy-amendment ceremony the operator lost time twice to
+ * questions this command answers in a second. First they drove a **stale
+ * checkout**: `dist/` was older than the source tree, so verbs that existed in
+ * `src/` were simply absent from the built CLI and every invocation looked like
+ * a version confusion rather than a missing `npm run build`. Then they reached
+ * for what turned out to be an **unbuilt placeholder binary** — a `cli.js`
+ * loader with no `dist/` behind it, which fails with one line about a missing
+ * file and says nothing about which of the several checkouts on the machine is
+ * the real one. Only on the third try did they find the working install.
+ *
+ * Neither failure was a bug in the runtime. Both were facts about the
+ * environment that nothing was in a position to state out loud. `doctor` is
+ * that statement: eleven checks, in the order in which their failures cascade,
+ * each with a concrete repair.
+ *
+ * ## Every fix begins with a command (APRV-75)
+ *
+ * A `fix` string starts with something the operator can paste, and the prose
+ * comes after it. The reason is the reading order of a failed run: an operator
+ * scanning a wall of `fix:` lines is looking for the next thing to type, and a
+ * line that opens with "check that…" makes them read a sentence to discover
+ * there is nothing to type at all. {@link FIX_COMMAND_PREFIXES} is the pinned
+ * allowlist, and `tests/cli-doctor.test.ts` drives every failing verdict this
+ * command can produce and asserts the shape (never the wording).
+ *
+ * ## What it will not do
+ *
+ * **It appends nothing.** Not an event, not a marker, not a "doctor ran"
+ * breadcrumb. An operator reaching for a diagnostic while the log is in a state
+ * they do not understand must not have that state changed by looking at it; the
+ * test suite byte-compares the log across a run.
+ *
+ * **It sends no message.** The Telegram check calls `getMe` and only `getMe` —
+ * a pure identity read. It never calls `sendMessage` (a diagnostic that pings a
+ * human's phone is a diagnostic nobody runs twice) and it never calls
+ * `getUpdates`, because a running `channel telegram listen` owns that offset
+ * and a stray poll would consume an update the listener would then never see.
+ *
+ * **It repairs nothing.** Every failure yields a `fix` string the human runs
+ * themselves. A doctor that rebuilt, re-attested, or truncated on its own would
+ * be making exactly the decisions this project exists to keep human.
+ *
+ * ## Exit codes
+ *
+ * 0 when every check passed or skipped, 1 when any failed. {@link EXIT_IO} is
+ * reserved for doctor's own inability to look — the installation root cannot be
+ * stat'd for a reason other than "not there". An unreadable *log* or an
+ * unreadable *policy* is not that: those are environment facts, which is
+ * precisely what this command reports, so they are check failures (exit 1).
+ */
+import { type HarnessKind } from "../core/harness-version.js";
+import type { Streams } from "./main.js";
+import { type Style } from "./style.js";
+/** One check's verdict. `fix` is present only when there is something to do. */
+export interface DoctorCheck {
+    check: string;
+    status: "pass" | "fail" | "skip";
+    detail: string;
+    fix?: string;
+}
+/**
+ * Every `fix` string begins with one of these, and the prose follows (APRV-75).
+ *
+ * A closed, small list rather than "looks like a command": the point is that a
+ * reader can paste the head of the line, and a `fix` that opened with a verb
+ * nobody has installed would be no better than a sentence. `approval ` is by far
+ * the commonest — most repairs in this runtime are another verb of this CLI —
+ * and the shell builtins here are the ones an actual repair needs: a variable to
+ * export, a mode to set, an ignore line to append, a directory to move aside.
+ *
+ * Note what is NOT here: no `rm`, no `sudo`, no `git commit`. Doctor repairs
+ * nothing, and a fix line that told an operator to delete or to commit would be
+ * making the decision this project exists to keep human.
+ */
+export declare const FIX_COMMAND_PREFIXES: readonly string[];
+/**
+ * Report only project configuration visible on disk.
+ *
+ * Codex owns hook trust and runtime loading. Neither is inferable from a file,
+ * and no historical log record proves what the current desktop session loaded.
+ */
+export declare function checkCodexHookWiring(dir: string): DoctorCheck;
+/**
+ * Every harness this checkout registers an `approval hook` command for.
+ *
+ * Shape-agnostic on purpose: `.claude/settings.json` nests the command under
+ * `hooks.PreToolUse[].hooks[].command` and `.cursor/hooks.json` under
+ * `hooks.preToolUse[].command`, and a third harness would nest it somewhere
+ * else again. What all of them have in common is a STRING somewhere in the
+ * document that invokes this CLI, so the document is parsed as JSON (a file
+ * that is not JSON registers nothing this can read) and its string leaves are
+ * searched. The row this feeds can only SKIP when the answer is empty, so a
+ * miss costs a skip and never a false red.
+ */
+export declare function registeredHarnesses(dir: string): HarnessKind[];
+/**
+ * The human report: one aligned row per check, fixes indented under their row.
+ *
+ * The line contract is load-bearing and older than the table (APRV-91 #9): a
+ * check occupies exactly one line, and a `fix` exactly one indented line under
+ * it, so an operator scanning a failed run counts rows rather than paragraphs.
+ * What the table changed is alignment and colour, never that arithmetic.
+ *
+ * A detail is abbreviated only when a TERMINAL WIDTH IS KNOWN and the row would
+ * not fit it, and `--verbose` (APRV-102) turns even that off. The brief asked
+ * for truncation outright; this is the narrowed version of it, for two reasons.
+ * A pipe has no width, so piped output — which every other suite pins, and
+ * which is what a bug report contains — is never abbreviated at all. And a
+ * `fix:` line is never touched on any path: repair instructions cut off
+ * mid-command are worse than a wide line, which is what the truncation was
+ * supposed to prevent.
+ */
+export declare function renderDoctorHuman(checks: readonly DoctorCheck[], st?: Style, options?: {
+    verbose?: boolean;
+    width?: number | null;
+}): string;
+/**
+ * `approval doctor …` — run every check in order and report.
+ *
+ * Returns a number for the paths that are decided before any I/O (help, usage),
+ * and a promise otherwise, because two checks are asynchronous. `main`
+ * dispatches both shapes, as it already does for `channel`.
+ */
+export declare function commandDoctor(argv: string[], streams: Streams, cwd: string): number | Promise<number>;

package/dist/src/cli/doctor.js

@@ -55,7 +55,7 @@
  */
 import { createServer } from "node:net";
 import { closeSync, existsSync, openSync, readFileSync, readdirSync, statSync, unlinkSync, } from "node:fs";
-import { dirname, isAbsolute, join, resolve as resolvePathSegments } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve as resolvePathSegments } from "node:path";
 import { WEB_DEFAULT_PORT } from "../channels/web.js";
 import { TELEGRAM_DEFAULT_API_BASE, telegramChatEnvFor, telegramTokenEnvFor, } from "../channels/telegram.js";
 import { HUMAN_ACTOR_ENV, checkAttestation, findOrganAttestation, latestOrganAttestation, policyBytesHash, resolveHumanActor, } from "../core/attest.js";
@@ -1947,15 +1947,123 @@ function checkHarnessWiring(dir) {
         detail: `WIRED on disk: ${path} registers \`approval hook\` for PreToolUse over ${GATED_TOOLS.join(", ")}. This is the file being present, NOT proof this session loaded it — the APRV-151 bypasses happened in worktrees carrying exactly this entry. The check that does not trust session wiring is the CI-side grant cross-check over the committed log, which asks whether the CHANGE was granted rather than whether the path ever was (APRV-202).`,
     };
 }
+/** The project-local Codex hook files doctor can observe without asking Codex. */
+const CODEX_HOOKS = join(".codex", "hooks.json");
+const CODEX_CONFIG = join(".codex", "config.toml");
+const CODEX_MATCHER = "Bash|apply_patch";
+const CODEX_HOOK_TIMEOUT_SECONDS = 600;
+function isDirectCodexHookCommand(command) {
+    const match = command.match(/^(?:"([^"$`\\\r\n;&|<>]+)"|'([^'\\\r\n;&|<>]+)'|([^\s"'$`\\\r\n;&|<>]+)) hook codex --dir (?:"([^"$`\\\r\n;&|<>]+)"|'([^'\\\r\n;&|<>]+)'|([^\s"'$`\\\r\n;&|<>]+)) --as agent:codex --timeout 9m$/u);
+    if (match === null)
+        return false;
+    const executable = match[1] ?? match[2] ?? match[3] ?? "";
+    const primaryDir = match[4] ?? match[5] ?? match[6] ?? "";
+    return isAbsolute(executable) && basename(executable) === "approval" && isAbsolute(primaryDir);
+}
+function codexEventConfigured(hooks, event) {
+    if (typeof hooks !== "object" || hooks === null || Array.isArray(hooks))
+        return false;
+    const groups = hooks[event];
+    if (!Array.isArray(groups))
+        return false;
+    return groups.some((group) => {
+        if (typeof group !== "object" || group === null || Array.isArray(group))
+            return false;
+        const fields = group;
+        if (fields["matcher"] !== CODEX_MATCHER || !Array.isArray(fields["hooks"]))
+            return false;
+        return fields["hooks"].some((handler) => {
+            if (typeof handler !== "object" || handler === null || Array.isArray(handler))
+                return false;
+            const entry = handler;
+            return (entry["type"] === "command" &&
+                typeof entry["command"] === "string" &&
+                isDirectCodexHookCommand(entry["command"]) &&
+                entry["timeout"] === CODEX_HOOK_TIMEOUT_SECONDS &&
+                (entry["async"] === undefined || entry["async"] === false));
+        });
+    });
+}
+/**
+ * Report only project configuration visible on disk.
+ *
+ * Codex owns hook trust and runtime loading. Neither is inferable from a file,
+ * and no historical log record proves what the current desktop session loaded.
+ */
+export function checkCodexHookWiring(dir) {
+    const check = "codex-hook-wiring";
+    const root = repoRoot(dir);
+    const where = root ?? dir;
+    const hooksPath = join(where, CODEX_HOOKS);
+    const configPath = join(where, CODEX_CONFIG);
+    const hasHooks = existsSync(hooksPath);
+    const hasConfig = existsSync(configPath);
+    if (!hasHooks && !hasConfig) {
+        return {
+            check,
+            status: "skip",
+            detail: `NOT CONFIGURED on disk: ${where} carries neither ${CODEX_HOOKS} nor ${CODEX_CONFIG}. Codex hook trust and observed execution are separate and remain unknown.`,
+        };
+    }
+    if (!hasHooks) {
+        return {
+            check,
+            status: "skip",
+            detail: `${configPath} exists. Doctor does not interpret inline TOML hook tables, so Codex hook configuration, trust and observed execution are undetermined.`,
+            fix: "approval hook codex --help — compare the documented PreToolUse and PostToolUse entries with .codex/config.toml",
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(hooksPath, "utf8"));
+    }
+    catch (cause) {
+        return {
+            check,
+            status: "fail",
+            detail: `${hooksPath} cannot be read as JSON (${oneLine(detailOf(cause))}); configured wiring cannot be established, and trust or execution cannot be inferred.`,
+            fix: "approval hook codex --help — compare and repair the project-local hook JSON after human review",
+        };
+    }
+    const hooks = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+        ? parsed["hooks"]
+        : null;
+    const pre = codexEventConfigured(hooks, "PreToolUse");
+    const post = codexEventConfigured(hooks, "PostToolUse");
+    if (!pre || !post) {
+        const missing = [!pre ? "PreToolUse" : null, !post ? "PostToolUse" : null]
+            .filter((value) => value !== null)
+            .join(" and ");
+        return {
+            check,
+            status: "skip",
+            detail: `${hooksPath} is present but does not match the expected APRV-313 profile for ${missing}: synchronous command hooks with matcher ${JSON.stringify(CODEX_MATCHER)}, command \`approval hook codex\`, and timeout ${String(CODEX_HOOK_TIMEOUT_SECONDS)} seconds. Other Codex hook configurations may be valid; this integration's coverage is undetermined. File presence proves neither trust nor observed execution.`,
+            fix: "approval hook codex --help — install the documented pair only after human review",
+        };
+    }
+    if (hasConfig) {
+        return {
+            check,
+            status: "skip",
+            detail: `CONFIGURED in ${hooksPath}: the required PreToolUse and PostToolUse entries are present. ${configPath} also exists and Codex merges hook sources; doctor does not interpret its TOML tables, so the effective configuration is not fully established. Trust and observed execution remain unknown.`,
+            fix: "approval hook codex --help — compare .codex/config.toml with the reviewed hooks.json and keep one representation per layer",
+        };
+    }
+    return {
+        check,
+        status: "pass",
+        detail: `CONFIGURED on disk: ${hooksPath} carries synchronous PreToolUse and PostToolUse \`approval hook codex\` entries for ${CODEX_MATCHER}, each with a ${String(CODEX_HOOK_TIMEOUT_SECONDS)} second outer timeout. This does not establish Codex trust, loading, or observed execution; inspect and trust the exact hook with \`/hooks\`, then run the bounded smoke test.`,
+    };
+}
 // ---------------------------------------------------------------------------
 // harness version provenance (APRV-227)
 // ---------------------------------------------------------------------------
 /** The Cursor counterpart of {@link CLAUDE_SETTINGS}. */
 const CURSOR_HOOKS = join(".cursor", "hooks.json");
 /** Where a harness hook registration can be written, one file per harness. */
-const HARNESS_SETTINGS = [CLAUDE_SETTINGS, CURSOR_HOOKS];
+const HARNESS_SETTINGS = [CLAUDE_SETTINGS, CURSOR_HOOKS, CODEX_HOOKS];
 /** `approval hook <kind>` inside a command string, whichever file shape holds it. */
-const HOOK_COMMAND = /\bapproval\s+hook\s+(claude-code|cursor)\b/u;
+const HOOK_COMMAND = /\bapproval["']?\s+hook\s+(claude-code|cursor|codex)\b/u;
 /**
  * Every harness this checkout registers an `approval hook` command for.
  *
@@ -1968,7 +2076,7 @@ const HOOK_COMMAND = /\bapproval\s+hook\s+(claude-code|cursor)\b/u;
  * searched. The row this feeds can only SKIP when the answer is empty, so a
  * miss costs a skip and never a false red.
  */
-function registeredHarnesses(dir) {
+export function registeredHarnesses(dir) {
     const found = new Set();
     for (const relative of HARNESS_SETTINGS) {
         const path = join(dir, relative);
@@ -1986,8 +2094,11 @@ function registeredHarnesses(dir) {
             const node = stack.pop();
             if (typeof node === "string") {
                 const match = HOOK_COMMAND.exec(node);
-                if (match !== null && isHarnessKind(match[1]))
+                if (match !== null &&
+                    isHarnessKind(match[1]) &&
+                    (match[1] !== "codex" || isDirectCodexHookCommand(node))) {
                     found.add(match[1]);
+                }
                 continue;
             }
             if (Array.isArray(node)) {
@@ -2631,6 +2742,9 @@ export function commandDoctor(argv, streams, cwd) {
             // `.approval/` is a directory people `git add` from, and the key store had
             // nothing telling them it must not come along.
             checkSealedKeys(logPath, dir),
+            // APRV-313: appended, nineteenth time, same reason. Configuration on
+            // disk is distinct from Codex trust, loading and observed execution.
+            checkCodexHookWiring(dir),
         ];
         const ok = checks.every((entry) => entry.status !== "fail");
         if (json)