approval-md 0.1.0 → 0.3.0

package/dist/src/cli/policy.js

@@ -30,9 +30,11 @@ import { isAbsolute, join, resolve as resolvePathSegments } from "node:path";
 import { explain, isActionClass } from "../core/policy-explain.js";
 import { loadPolicy, POLICY_FILENAMES } from "../core/policy-load.js";
 import { commandPolicyAmend } from "./amend.js";
+import { commandPolicyApply } from "./policy-apply.js";
 import { boolFlag, parseFlags, stringFlag } from "./args.js";
 import { commandPolicyAttest } from "./attest.js";
 import { EXIT_IO, EXIT_OK, EXIT_USAGE } from "./exit-codes.js";
+import { resolveScratchRoots } from "./hook.js";
 import { POLICY_CHECK_HELP, POLICY_HELP, POLICY_TEST_HELP } from "./help.js";
 import { relPath, style } from "./style.js";
 import { usageErrorText } from "./usage.js";
@@ -189,7 +191,13 @@ function runVerb(argv, streams, cwd, helpText) {
         if (!check.ok)
             return ioError(streams, json, check.message);
     }
-    const explanation = explain(loadPolicy(options), actionClass, reversibleFlag === null ? {} : { reversible: reversibleFlag === "true" });
+    const explanation = explain(loadPolicy(options), actionClass, {
+        ...(reversibleFlag === null ? {} : { reversible: reversibleFlag === "true" }),
+        // APRV-347. Resolved HERE, where the process may touch a disk, so the read
+        // scope a reader is shown is the one this machine would actually enforce
+        // rather than a description of the key.
+        systemReadRoots: resolveScratchRoots(cwd),
+    });
     if (json) {
         streams.out(`${JSON.stringify(explanation)}\n`);
     }
@@ -222,6 +230,11 @@ export function commandPolicy(argv, streams, cwd) {
         // It writes too, and for the same reason it lives in its own file.
         case "amend":
             return commandPolicyAmend(rest, streams, cwd);
+        // APRV-343. It writes the policy FILE, which nothing else in this CLI does,
+        // and then hands over to the amendment above so the edit and its
+        // attestation stay one act.
+        case "apply":
+            return commandPolicyApply(rest, streams, cwd);
         default:
             return usageError(streams, wantsJson(argv), `unknown subcommand ${JSON.stringify(sub)} for \`approval policy\``, POLICY_HELP);
     }

package/dist/src/cli/policy.js.map

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

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

@@ -0,0 +1,501 @@
+/**
+ * The startup preflight (APRV-215): is the code about to run the code that is
+ * on origin, and is the build behind it the one the sources describe?
+ *
+ * ## The four manual steps this replaces
+ *
+ * Deploying the APRV-212 fix in the primary checkout took `git fetch`, a
+ * judgment call about whether the ten upstream commits touched
+ * `.approval/log/events.jsonl` while the working log was dirty, `git pull
+ * --ff-only`, and `npm run build`. Three of those are typing; the second is the
+ * one a human cannot make from `git status` alone, because `git status` does not
+ * say what the *upstream range* changed. Carter's standing view is that manual
+ * git steps for the human are a defect rather than a runbook, so the judgment
+ * moves here and the typing moves with it.
+ *
+ * ## What it is allowed to do
+ *
+ * Read git, and at most four writes: a `--ff-only` merge, `npm run build`,
+ * when the merge refused over an untracked file under `backlog/tasks/`
+ * that main already contains, clearing that file out of the way (APRV-300, and
+ * the rules it obeys are in {@link reconcileUntrackedTaskFiles}), and the one
+ * `approval log sync` performs on its behalf (APRV-346, below).
+ *
+ * It never resets, never stashes, never checks anything out, and never touches
+ * the working log ITSELF. That list is not conservatism for its own sake — it is
+ * fork 2 of 2026-08-20 (APRV-104's notes, and the reason `approval log sync`
+ * exists at all): a working `events.jsonl` rewound through git underneath a live
+ * appender is two chains where there was one. `--ff-only` cannot rewind a file
+ * that upstream did not change, and when upstream DID change it while the
+ * working copy is dirty, the file is moved by `cli/log-sync.ts` and by nothing
+ * here.
+ *
+ * ## The routine collision, and the one that is not (APRV-346)
+ *
+ * Every records advance moves `origin/main`'s `.approval/log/events.jsonl`
+ * while the hook keeps appending locally, so "upstream changed the log and so
+ * did this working copy" is the NORMAL state of the primary checkout after a
+ * merge rather than an edge case. Refusing it sent the operator to `approval log
+ * sync` and then back to `approval up` every single time, which is a two-step
+ * ritual for a state the preflight can already tell apart from a fork.
+ *
+ * So the collision is now a question rather than a verdict: is the working log a
+ * byte-for-byte EXTENSION of the committed one (main's records 1..N unchanged,
+ * local N+1.. following) or are they two chains that share a prefix and then
+ * differ? {@link planLogSync} asks `core/log-reconcile.ts` — the same comparison
+ * `log sync` and doctor's `log-drift` ask — and answers a plan or `null`:
+ *
+ * - a plan, and {@link runPreflight} calls `logSync` itself. Not a
+ *   reimplementation of it: the APRV-215 ceremony (one hold of the append lock,
+ *   snapshot, baseline, fast-forward, reconcile, rebuild the projections,
+ *   post-verify) stays the single implementation, and this module supplies a
+ *   caller rather than a copy;
+ * - `null`, and the old `up-preflight-log-diverged` refusal stands unchanged.
+ *   A fork, a log that does not verify, a log at some path other than the
+ *   repository's own, or any OTHER upstream-touched path locally modified all
+ *   answer `null`. Every one of those is a judgment, and this module makes none.
+ *
+ * ## Refusals, not repairs
+ *
+ * Four codes, each firing for exactly one condition. The first three are
+ * evaluated in this order, before anything is written:
+ *
+ * - `up-preflight-behind-ahead` — `origin/<branch>..HEAD` is non-empty. Local
+ *   commits exist that the remote does not have. A fast-forward is not the
+ *   operation for that state, and guessing which side to keep is a decision.
+ * - `up-preflight-log-diverged` — the upstream range changes the working log or
+ *   the queue projection, the working copy has uncommitted changes to them, AND
+ *   the two chains are not in a prefix relationship (or cannot be compared at
+ *   all). This is the case the human could not judge by eye, and it is `approval
+ *   log sync`'s whole subject. The routine case — a working log that merely
+ *   extends the committed one — is reconciled rather than refused (APRV-346).
+ * - `up-preflight-dirty-protected` — some OTHER path the upstream range changes
+ *   is locally modified, so `git merge --ff-only` would refuse to overwrite it.
+ *   Named separately because the repair is different: look at the edit and
+ *   decide, or start on the current build with `--no-preflight`.
+ *
+ * The fourth is answered after the merge has already refused, and only for the
+ * one path shape where two checkouts routinely author one file (APRV-300):
+ *
+ * - `up-preflight-task-file-conflict` — an untracked file under
+ *   `backlog/tasks/` stopped the fast-forward, and it holds lines the incoming
+ *   copy does not. See {@link reconcileUntrackedTaskFiles} for what happens
+ *   when it holds none, and why that is a claim rather than an assumption.
+ *
+ * `git reset --hard` appears in none of them, and never will: it is the command
+ * that turns "your checkout is confusing" into "your work is gone".
+ *
+ * A fourth refusal reports a write that failed rather than a judgment:
+ * `up-preflight-failed` carries the step and, for the build, the exit code
+ * `npm run build` came back with. The runtime does not start after it, because the whole point
+ * of the rebuild is that a daemon and a hook running compiled-away code is the
+ * defect being fixed (APRV-301); `--no-build` is how an operator says they
+ * meant to run the stale build anyway.
+ *
+ * ## A fetch that fails is weather
+ *
+ * A laptop on a train has no origin to compare against. That is not a reason to
+ * refuse to run a gate — the log is local, the policy is local, and the human is
+ * holding the phone. A failed fetch is reported as a warning and the runtime
+ * starts on the build it has, saying so.
+ *
+ * ## Two callers, one judgment
+ *
+ * `approval up` (and therefore `approval daemon run --with-channels`) acts on
+ * it; `approval doctor`'s `main-behind-origin` row reports it. Doctor passes
+ * `fetch: false`, because a report is not allowed to make a network call the
+ * operator did not ask for, and says out loud that its answer is only as fresh
+ * as the last fetch.
+ */
+import type { EventRecord } from "../core/log.js";
+import { type LogRelation } from "../core/log-reconcile.js";
+import type { DoctorCheck } from "./doctor.js";
+import { type RunbookStep } from "./style.js";
+/**
+ * The installation root: the directory holding `cli.js`, `src/`, `dist/`.
+ *
+ * Derived from this module's own location rather than from `cwd`, because the
+ * question is "is the code I am running stale", and the answer must not change
+ * when the operator runs the CLI from somewhere else. Compiled, this file is
+ * `<root>/dist/src/cli/preflight.js`, hence three levels up.
+ */
+export declare function installationRoot(): string;
+/** Thrown out of the source walk so a real I/O denial can become exit 4. */
+export declare class ScanError extends Error {
+}
+/**
+ * Is the built CLI at least as new as the sources it was built from?
+ *
+ * The marker is `dist/src/cli/main.js` — the exact file `cli.js` loads, so the
+ * thing being timestamped is the thing that will actually run. It is compared
+ * against the newest mtime under `src/` and of `tsconfig.json` (a compiler
+ * option change invalidates a build as surely as an edit does).
+ *
+ * Three shapes are distinguished because their repairs differ:
+ *
+ * - `cli.js` present, `dist/` absent — the placeholder-binary shape from the
+ *   ceremony. The loader exists, so the checkout *looks* installed; nothing
+ *   behind it does.
+ * - marker older than sources — the stale-checkout shape. Verbs that exist in
+ *   `src/` are missing from the binary.
+ * - no `src/` at all — a published install, where freshness is not a question
+ *   that can be asked. `skip`, not a silent pass.
+ *
+ * Note the self-reference: doctor itself runs *from* `dist`, so a completely
+ * absent `dist` means `cli.js` already refused and this code never ran. The
+ * check is still implemented for that shape because `--root` can point it at
+ * another tree, and because "the binary you ran is not the tree you edited" is
+ * exactly the confusion it exists to name.
+ */
+export declare function checkBuildFreshness(root: string): DoctorCheck;
+/**
+ * Is `root`'s build older than `root`'s sources?
+ *
+ * `null` when the question does not apply — a published install with no `src/`,
+ * or a tree that is not an installation at all. A caller that wants the full
+ * three-way answer asks {@link checkBuildFreshness}; this is the boolean the
+ * preflight acts on, and "cannot tell" must not read as "stale" or the preflight
+ * would rebuild a tree it has no business compiling.
+ */
+export declare function distStale(root: string): boolean | null;
+/** What the preflight did, or would have done. Frozen: it is a `--json` field. */
+export type PreflightAction = 
+/** Already at the remote tip with a build no older than the sources. */
+"none"
+/** Only the build was behind. */
+ | "rebuild"
+/** Only the checkout was behind. */
+ | "fast-forward"
+/** Both. The ordinary shape after a few days away. */
+ | "fast-forward+rebuild"
+/** The build was older than the sources and `--no-build` said to leave it. */
+ | "build-skipped"
+/** The checkout was behind, the build is now stale, and `--no-build` said so. */
+ | "fast-forward+build-skipped"
+/** A refusal: nothing was touched. */
+ | "refused"
+/** `--no-preflight`, or a checkout git cannot answer questions about. */
+ | "skipped"
+/** The fetch did not reach the remote. Weather, not a fault. */
+ | "fetch-failed";
+/** The machine-readable refusal codes. Frozen public API, distinct by repair. */
+export declare const PREFLIGHT_REFUSAL_CODES: readonly ["up-preflight-behind-ahead", "up-preflight-log-diverged", "up-preflight-dirty-protected", "up-preflight-task-file-conflict"];
+export type PreflightRefusalCode = (typeof PREFLIGHT_REFUSAL_CODES)[number];
+/** The facts, exactly as they are carried on the `--json` stream. */
+export interface PreflightFacts {
+    behind_by: number;
+    ahead_by: number;
+    log_touched: boolean;
+    dist_stale: boolean;
+    action: PreflightAction;
+    /**
+     * True when the preflight rebuilt and the runtime therefore re-executed into
+     * the fresh build rather than carrying on in the process that dated it.
+     *
+     * Always false from {@link inspectPreflight}: inspection builds nothing, so
+     * it can never be the reason a process was replaced. Doctor's row reads that
+     * answer and never this one.
+     */
+    reexec: boolean;
+    /**
+     * True when `approval log sync`'s reconcile ran on this preflight's behalf
+     * (APRV-346), which is the one write here that touches the working log.
+     *
+     * Always false from {@link inspectPreflight}, for the same reason `reexec` is:
+     * inspection performs nothing, so it can never be the thing that did this.
+     * What inspection answers instead is {@link PreflightReport}'s `sync`, which
+     * is the plan rather than the deed.
+     */
+    log_synced: boolean;
+}
+/**
+ * The reconcile the preflight would hand to `approval log sync`, or has.
+ *
+ * Present on a report only when the protected-path collision is the routine one
+ * (APRV-346): the working chain and the committed chain stand in a prefix
+ * relationship, so adopting the longer one extends and never rewinds. A fork,
+ * or a chain that cannot be verified, has no plan — it has a refusal.
+ */
+export interface PreflightSyncPlan {
+    /** How the working chain stands relative to the committed one at the target. */
+    relation: LogRelation;
+    /** Records the working chain holds beyond the committed one: what is kept. */
+    kept: number;
+}
+/** A refusal, in the APRV-129 runbook's own vocabulary. */
+export interface PreflightRefusal {
+    code: PreflightRefusalCode;
+    headline: string;
+    state: string[];
+    steps: RunbookStep[];
+    footer: string[];
+    /** The one command a machine caller should run next, unadorned. */
+    next: string;
+}
+/** What {@link inspectPreflight} answers. */
+export type PreflightReport = {
+    ok: true;
+    facts: PreflightFacts;
+    /** One sentence, for the human line and for doctor's `detail`. */
+    detail: string;
+    /** A fetch that did not reach the remote, or `null`. */
+    warning: string | null;
+    /** The commit a fast-forward would move to, when there is one. */
+    target: string | null;
+    /** Where the judgment was made. `null` when there was no repository. */
+    root: string | null;
+    /**
+     * The reconcile this preflight would ask `approval log sync` for, or
+     * `null` when the working log needs nothing (APRV-346).
+     */
+    sync: PreflightSyncPlan | null;
+} | {
+    ok: false;
+    facts: PreflightFacts;
+    refusal: PreflightRefusal;
+    root: string;
+};
+export interface PreflightInput {
+    /** The working log, which also names the repository (as doctor's log-drift does). */
+    logPath: string;
+    /** The queue projection, the second path a fast-forward must not clobber. */
+    queuePath: string;
+    /** The installation whose `dist/` is dated against its `src/`. */
+    root: string;
+    /** Ask the remote, or judge against the last fetch. Doctor passes `false`. */
+    fetch: boolean;
+    /** Defaults to `origin`. */
+    remote?: string;
+    /** Defaults to the checked-out branch, or `main` on a detached HEAD. */
+    branch?: string;
+    /**
+     * Run the package's build when `dist/` is older than the sources. Defaults to
+     * `true`, which is the whole point of the preflight; `false` is `--no-build`.
+     *
+     * Opting out changes what the preflight DOES, never what it SAYS: the
+     * fast-forward still happens, `dist_stale` still reports the truth, and the
+     * action settles on `build-skipped` so neither the human line nor a machine
+     * caller can read "started" as "started on the code that was merged".
+     *
+     * {@link inspectPreflight} ignores it, because inspection builds nothing.
+     */
+    build?: boolean;
+}
+/**
+ * The whole judgment, and not one byte of action.
+ *
+ * Every write the preflight is allowed to make lives in {@link runPreflight};
+ * this function reads. That split is what lets doctor report the same facts
+ * without any risk of doctor repairing something, which doctor has never done.
+ */
+export declare function inspectPreflight(input: PreflightInput): PreflightReport;
+/** What the reconcile actually did, once `approval log sync` had run it. */
+export interface PreflightSynced {
+    /** The commit the checkout ended on. */
+    commit: string;
+    /** Local records the reconcile put back on top of it. */
+    kept: number;
+    relation: LogRelation;
+    remote: string;
+    branch: string;
+}
+/** What {@link runPreflight} did, with the facts as they ended up. */
+export type PreflightOutcome = {
+    ok: true;
+    facts: PreflightFacts;
+    detail: string;
+    warning: string | null;
+    /** Present when a rebuild happened: the caller must become this child. */
+    reexec?: ReexecPlan;
+    /** Present when the reconcile ran: what it fast-forwarded and kept. */
+    synced?: PreflightSynced;
+} | {
+    ok: false;
+    facts: PreflightFacts;
+    refusal: PreflightRefusal;
+}
+/** A write the preflight attempted and could not complete. Also a refusal. */
+ | {
+    ok: false;
+    facts: PreflightFacts;
+    failed: {
+        step: string;
+        message: string;
+    };
+};
+/**
+ * Inspect, then perform at most a fast-forward and a build.
+ *
+ * `npm run build` is spawned rather than shelled, with the checkout as its cwd,
+ * so nothing here depends on the operator's shell or on `npm` being on a
+ * particular PATH entry. Its output is discarded and its exit status is the
+ * whole answer: a build that fails is a failed preflight, and the runtime does
+ * not start on a half-compiled tree.
+ */
+export declare function runPreflight(input: PreflightInput, spawnBuild?: (root: string) => {
+    ok: boolean;
+    message: string;
+}): PreflightOutcome;
+/** Where the fresh build lives, and what to run it with. */
+export interface ReexecPlan {
+    /** `<root>/dist/src/cli/main.js` — resolved from the CHECKOUT, never from `import.meta`. */
+    entry: string;
+    /** This process's own argv, plus `--no-preflight` so the child cannot loop. */
+    argv: string[];
+}
+/**
+ * Run the fresh build in a child process and become its exit code.
+ *
+ * `stdio: "inherit"` so the child owns the terminal exactly as the parent would
+ * have: the daemon's lines, the token panel, a channel's prompts and an
+ * operator's ctrl-c all behave as though no re-exec happened. SIGINT and
+ * SIGTERM are forwarded rather than handled, because the child is the writer
+ * and the shutdown sequence that matters is its own.
+ *
+ * A child killed by the signal we forwarded exits 0: the operator asked the
+ * runtime to stop and it stopped, which is a clean stop under any spelling.
+ * Any other signal is reported as an I/O failure, because a writer that
+ * vanished is a fact about the machine rather than a decision of the runtime.
+ */
+export declare function reexecFreshBuild(plan: ReexecPlan, cwd: string): Promise<number>;
+/**
+ * The preflight's two lines on the event stream.
+ *
+ * They live here rather than in `cli/up.ts` because `approval daemon run` runs
+ * the same preflight and must print the same lines, and `daemon.ts` cannot
+ * import `up.ts` (the cycle APRV-110 already routes around with a dynamic
+ * import). `UpEvent` includes this union, so the `--json` stream stays one union
+ * of additive shapes with no field added to any shape that already existed.
+ */
+export type PreflightEvent = ({
+    event: "preflight";
+    commit: string | null;
+    detail: string;
+} & PreflightFacts) | {
+    event: "preflight_warning";
+    message: string;
+}
+/**
+ * The reconcile, when there was one (APRV-346). A third additive shape rather
+ * than a field on `preflight`: a consumer that already parses that line must
+ * not have to learn a key to keep working, and this is a different fact —
+ * what `approval log sync` did, not what the preflight found.
+ */
+ | ({
+    event: "preflight_sync";
+} & PreflightSynced)
+/**
+ * The attested policy is not on the remote yet (APRV-342). Emitted only when
+ * that is TRUE: `up` reports the interregnum and never refuses on it, because
+ * a policy amendment waiting on a pull request is a normal state of a
+ * repository and not a reason to refuse to run the gate.
+ */
+ | {
+    event: "preflight_policy";
+    detail: string;
+    fix: string | null;
+};
+/** One preflight line as a human sentence, and where it belongs. */
+export declare function describePreflightEvent(event: PreflightEvent): {
+    text: string;
+    stderr: boolean;
+};
+/** How a caller emits one line. `up` and `daemon run` route theirs identically. */
+export type PreflightEmit = (event: PreflightEvent) => void;
+/**
+ * The policy file `--policy` names, or the one `--dir` (else `cwd`) holds.
+ *
+ * Discovery, not a load: this answers WHICH FILE, so the preflight can compare
+ * its attested hash against the remote's copy (APRV-342) before either caller
+ * has loaded a policy. The order is `core/policy-load.ts`'s own, so the file
+ * named here is the file the runtime will go on to enforce. `null` when there is
+ * no such file, which is not a finding — `approval doctor`'s `policy` rows are
+ * where an absent policy is somebody's problem.
+ */
+export declare function preflightPolicyPath(policyFlag: string | null, dirFlag: string | null, cwd: string): string | null;
+export interface StartupPreflightInput {
+    logPath: string;
+    queuePath: string;
+    /**
+     * The policy file, for the `attested-policy-on-main` line (APRV-342). `null`
+     * where the caller could not name one, and the line is then not emitted:
+     * there is nothing to compare, which is not a finding.
+     */
+    policyPath?: string | null;
+    /** The installation whose `dist/` is dated. `null` means "ask this build". */
+    root: string | null;
+    remote: string | null;
+    branch: string | null;
+    /** `false` is `--no-build`: fast-forward, but leave a stale `dist/` alone. */
+    build: boolean;
+    emit: PreflightEmit;
+    /** Where a refusal is written. One line under `--json`, a runbook otherwise. */
+    refuse: (text: string) => void;
+    json: boolean;
+}
+/**
+ * Run the preflight, print what it did, and answer whether the caller may start.
+ *
+ * `ok: false` carries nothing but the fact: everything a human or a machine
+ * needs has already been written by `refuse`, and the caller's only remaining
+ * job is to return the exit code.
+ */
+export declare function startupPreflight(input: StartupPreflightInput): {
+    ok: boolean;
+    reexec: ReexecPlan | null;
+};
+/**
+ * A preflight refusal, on both surfaces (APRV-129).
+ *
+ * The human surface is the runbook: the code, the state, one runnable command
+ * per numbered line, and the rationale compressed into the footer. The machine
+ * surface is one object carrying the stable code and the same facts the success
+ * path carries, so a supervisor can branch on `error.code` without reading a
+ * word of it.
+ */
+export declare function renderPreflightRefusal(outcome: PreflightOutcome & {
+    ok: false;
+}, json: boolean): string;
+/**
+ * `main-behind-origin`, doctor's twenty-first row.
+ *
+ * It makes no network call (`fetch: false`), for the reason every doctor row
+ * makes none it was not asked for: doctor is a report, and a report that reached
+ * the network to be more accurate would be doing something on its own account.
+ * So the answer is as fresh as the last fetch, and the detail says so.
+ *
+ * `fix` strings stay inside `FIX_COMMAND_PREFIXES`: they name `approval` verbs,
+ * never `git`. That constraint predates this row and is the right one — a repair
+ * line telling an operator to reset a branch would be doctor making a decision.
+ */
+/**
+ * `attested-policy-on-main`, doctor's row for the interregnum (APRV-342).
+ *
+ * Between a policy amendment and its pull request merging there is a window
+ * where the attestation is in the log and the amended `APPROVAL.md` is in the
+ * working tree, and `origin/main` carries neither. A fresh checkout of main in
+ * that window has the OLD policy with no attestation covering it, and every
+ * gate operation there refuses `policy-not-attested`.
+ *
+ * Nothing said so. On 2026-09-16 `approval up` ran its preflight in exactly that
+ * state and reported "already at the remote tip"; doctor's `attestation` row
+ * passed, because the LOCAL file is attested and that row asks a different
+ * question. This row asks the missing one: is the policy the log vouches for the
+ * policy `origin/<branch>` carries?
+ *
+ * Read-only, and networkless. The remote tip is read from the last fetch, like
+ * every other answer doctor gives about a remote, and the `policy-amend-<seq>`
+ * branch is looked for among the remote-tracking refs rather than asked of
+ * GitHub: a report that reached the network to be more accurate would be doing
+ * something on its own account.
+ */
+export declare function checkAttestedPolicyOnMain(input: {
+    policyPath: string;
+    /** The log, verified, in append order. Doctor's own records; `up` re-reads. */
+    records: readonly EventRecord[];
+    /** The repository the policy lives in, or `null` when it is not in one. */
+    root: string | null;
+    remote?: string;
+    branch?: string;
+}): DoctorCheck;
+export declare function checkMainBehindOrigin(logPath: string, queuePath: string, root: string): DoctorCheck;