approval-md 0.1.0 → 0.2.0

package/dist/src/core/coverage.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Coverage of observed side effects (APRV-245, SPEC.md §10.1).
+ *
+ * ## Why a verb that witnesses rather than gates
+ *
+ * MCP use is voluntary. An agent connected to `approval mcp serve --http` can
+ * call `request`, `wait` and `run`, or it can simply act. Nothing in this
+ * runtime observes the act, because the runtime is not in the path: a gate an
+ * agent may route around reports only on the actions routed through it, and a
+ * report that counts only its own inputs is a report that cannot go down.
+ *
+ * What makes the arrangement honest is that side effects leave witnesses THIS
+ * PROJECT DOES NOT WRITE. Git history records commits, merges and tags. `gh`
+ * records pull requests. AgentMail records the messages an inbox actually sent.
+ * None of those are appended by approval.md, none of them are reachable by an
+ * agent editing its own log, and each of them can be read back and joined
+ * against the verified records to ask one question per effect: does the log say
+ * a human, or a policy, ever saw this?
+ *
+ * This module is that join, and nothing else. It performs no IO, reads no clock,
+ * spawns nothing and appends nothing. The sources under `coverage-sources/`
+ * gather the effects; `cli/coverage.ts` prints the answer.
+ *
+ * ## What counts as evidence, stated exactly
+ *
+ * The strongest answer first (APRV-251): an `execution.completed` may carry
+ * `payload.provider_ref`, the identifier the provider filed the effect under
+ * (SPEC.md §8), and an effect whose source and id match one is covered by that
+ * record, reported as `provider-ref`. No window is applied to it, because an id
+ * names one effect and a class in a span of time names a period. That is the
+ * whole difference the reference buys: without it, a gated send covers an
+ * ungated one of the same class sitting beside it in the window, and with it
+ * the log answers about the message actually in front of the reader.
+ *
+ * Otherwise, for one {@link ObservedEffect}, evidence is the EARLIEST record
+ * that is all three of:
+ *
+ * 1. one of `task.registered`, `approval.granted`, `execution.started`,
+ *    `execution.completed` — the four records that mean "this runtime was told
+ *    about an action of this class", from the declaration through the human's
+ *    decision to the spend;
+ * 2. of a matching class: EXACT first ({@link classesOf} against the effect's
+ *    class), and only if nothing matches exactly, a FAMILY match on the first
+ *    two dotted segments, reported distinctly as `family` so a reader is never
+ *    shown a weaker match dressed as a strong one;
+ * 3. inside the window `[at - 24h, at + 5m]`.
+ *
+ * The window is asymmetric on purpose and both halves are arguable, so both are
+ * written down. **24 hours back**, because the ordinary shape is register →
+ * request → grant → act, and the gap between the human's tap and the effect is
+ * a working day at worst; a week back would let one grant carry every later
+ * effect of its class, which is the laundering hole APRV-202 closed in the
+ * protected-path guard. **5 minutes forward**, because that is clock skew
+ * between git's author date (or a provider's timestamp) and this log, and not an
+ * ordering allowance: a record appended an hour after an effect is a record
+ * about some other action, whatever its class.
+ *
+ * The one place this rule is not used is a protected FILE path. Those already
+ * have a stronger answer: `core/protected-path-guard.ts` matches a change's
+ * BYTES against the material a grant bound, and its `attested` and
+ * `granted-file` verdicts are content-level rather than time-level. So an effect
+ * carrying a `path` takes the guard's verdict when the caller supplies a report
+ * that covers it, and the class-and-window rule is what everything else gets.
+ *
+ * ## Verified records only, and no writes
+ *
+ * The caller reads through `readVerifiedRecords` (SPEC.md §11.1 invariant 1);
+ * this function is handed records that already passed chain verification and has
+ * no way to read any others. It writes nothing anywhere, which is what lets it be
+ * informational: the whole report is derived, and running it changes no state
+ * that any later verdict depends on.
+ *
+ * ## What a green line does NOT say
+ *
+ * Coverage is a witness, not a control. An effect made with a credential the
+ * AGENT itself holds — an API key pasted into a chat surface, a token in a
+ * shell profile — leaves a witness only where the provider keeps one this verb
+ * can read. The remedy for that tier is custody (SPEC.md §10.4: adapters hold
+ * the credentials and answer only to a token), not a bigger report, and
+ * `docs/cli-reference.md#coverage` writes the three tiers out so that a green
+ * coverage line is never read as the claim that nothing else happened.
+ */
+import type { EventRecord } from "./log.js";
+import type { GuardReport } from "./protected-path-guard.js";
+/**
+ * One side effect a witness outside this runtime recorded.
+ *
+ * Every field is a FACT ABOUT THE WORLD, gathered from git, `gh` or a provider,
+ * and none of it is self-reported by the party under oversight. `actorHint` is
+ * named a hint deliberately: a commit author email is whatever the committer
+ * configured, so it is printed for a reader and never matched on (SPEC.md §11.1
+ * invariant 4 — a self-reported field never reduces scrutiny).
+ */
+export interface ObservedEffect {
+    /** Which source saw it: `git`, `gh`, `agentmail`. */
+    source: string;
+    /** The witness's own identifier: a commit sha, a PR number, a message id. */
+    id: string;
+    /** The side-effect class (SPEC.md §7) this effect would have been declared under. */
+    class: string;
+    /** When the witness says it happened, RFC 3339. */
+    at: string;
+    /** Who the witness says did it, or `null`. Printed, never matched on. */
+    actorHint: string | null;
+    /** One line a person can read. Never a message body, never a secret. */
+    detail: string;
+    /** For a file effect, the repository-relative path it changed. */
+    path?: string;
+}
+/**
+ * The span an observation covers, as two RFC 3339 instants.
+ *
+ * Both ends are supplied by the caller and neither is read from a clock here,
+ * so two runs over the same window ask every provider the same question.
+ */
+export interface ObservationWindow {
+    since: string;
+    until: string;
+}
+/**
+ * What the log says about one effect.
+ *
+ * `null` is a GAP: no record of a matching class sits in the window. The two
+ * shapes carry different kinds of proof, so they are different shapes rather
+ * than one object with optional halves — a record seq is something a reader can
+ * paste into `approval log tail`, and a guard verdict is a statement about
+ * bytes.
+ */
+export type Evidence = {
+    seq: number;
+    event: string;
+} | {
+    verdict: "attested" | "granted-file";
+} | null;
+/** How the evidence was found, so a weaker match is never read as a stronger one. */
+export type CoverageMatch = 
+/**
+ * An `execution.completed` names this exact effect by the provider's own
+ * identifier (APRV-251). The strongest answer this join can give: it is about
+ * one effect rather than about a class in a span of time.
+ */
+"provider-ref"
+/** The record's declared class equals the effect's class. */
+ | "exact"
+/** Only the class FAMILY matched (the first two dotted segments). */
+ | "family"
+/** The protected-path guard answered for this path, on bytes rather than time. */
+ | "protected-path"
+/** Nothing matched. `evidence` is `null`. */
+ | "none";
+/** One effect, and what the log had to say about it. */
+export interface CoverageEntry {
+    effect: ObservedEffect;
+    evidence: Evidence;
+    match: CoverageMatch;
+}
+/** Observed and covered counts for one grouping key. */
+export interface CoverageTotals {
+    key: string;
+    observed: number;
+    covered: number;
+}
+export interface CoverageReport {
+    entries: readonly CoverageEntry[];
+    /** Totals per source, sorted by source name. */
+    bySource: readonly CoverageTotals[];
+    /** Totals per class, sorted by class name. */
+    byClass: readonly CoverageTotals[];
+    observed: number;
+    covered: number;
+}
+/** How far BACK of an effect a record may sit and still be about it: 24 hours. */
+export declare const COVERAGE_LOOKBACK_MS: number;
+/**
+ * How far AHEAD of an effect a record may sit: five minutes.
+ *
+ * A skew allowance between two clocks, not an ordering allowance. See the
+ * module note for why the window is asymmetric.
+ */
+export declare const COVERAGE_AHEAD_MS: number;
+/** The record types that can be evidence, in the order they occur in a life. */
+export declare const EVIDENCE_EVENTS: readonly string[];
+export interface CoverageOptions {
+    /** Override {@link COVERAGE_LOOKBACK_MS}. */
+    lookbackMs?: number;
+    /** Override {@link COVERAGE_AHEAD_MS}. */
+    aheadMs?: number;
+    /**
+     * The protected-path guard's report for the same range, when the caller ran
+     * one. An effect whose `path` has a passing finding there takes that verdict
+     * instead of the class-and-window rule: it is content-level evidence, and
+     * content beats time.
+     */
+    guard?: GuardReport | null;
+}
+/**
+ * The family of a class: its first two dotted segments.
+ *
+ * `vcs.push.main` and `vcs.push.branch` are one family; `vcs.push.main` and
+ * `vcs.commit.branch` are not. Two segments rather than one, because a single
+ * segment would make every `vcs.*` record evidence for every other, and the
+ * pushes and the commits are different decisions. A class with fewer than two
+ * segments is its own family.
+ */
+export declare function classFamily(cls: string): string;
+/**
+ * Join observed effects against verified records.
+ *
+ * Deterministic and total: the same effects and the same records produce the
+ * same report, in the same order, every time. Entries come back in the order the
+ * effects were given, and the totals are sorted by key so that a `--json`
+ * consumer can pin the whole object with a `deepEqual`.
+ *
+ * @param effects what the witnesses outside this runtime saw
+ * @param records records that have ALREADY passed chain verification
+ */
+export declare function coverageReport(effects: readonly ObservedEffect[], records: readonly EventRecord[], options?: CoverageOptions): CoverageReport;

package/dist/src/core/credential-spec.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The credential manifest type (SPEC.md §10.4; APRV-78).
+ *
+ * An adapter reads named values out of the vault, and until this file existed
+ * the only place those names were written down was the adapter's own `act`,
+ * where a human setting the vault up cannot read them. A manifest moves that
+ * knowledge one level out: the adapter DECLARES what it needs, and a generic
+ * interactive writer (`cli/setup-flow.ts`) asks for it, validates it, stores it
+ * and reports on it without knowing anything about email or SMTP.
+ *
+ * **This module is a type and nothing else.** No I/O, no imports, no runtime
+ * values, deliberately: it is imported by `src/adapters/*` (which must not
+ * depend on the CLI) and by `src/cli/*` (which must not depend on a particular
+ * adapter), so anything with behaviour in it would make one of those two edges
+ * a dependency on the other. The behaviour lives at both ends; the vocabulary
+ * lives here.
+ *
+ * A spec carries no default for a `secret`, and it never carries a VALUE of any
+ * kind: the manifest is printed, in checklists and in non-interactive hints, and
+ * a field that could hold a credential would be a credential in a terminal.
+ */
+/**
+ * What kind of thing a credential is, from the operator's point of view.
+ *
+ * Three, not two, because the collection differs for each: a `config` value is
+ * typed in the clear with its default shown, a `choice` is picked from a
+ * numbered list so a typo cannot become a silently wrong transport, and a
+ * `secret` is read with no echo. The vault stores all three identically — it
+ * has no notion of a non-secret entry — so this distinction exists purely to
+ * decide what the human is asked and what may be echoed back at them.
+ */
+export type CredentialKind = "secret" | "config" | "choice";
+/** One value an adapter reads from the vault, described well enough to ask for. */
+export interface CredentialSpec {
+    /** The vault name, exactly as the adapter's `act` asks for it. */
+    name: string;
+    kind: CredentialKind;
+    /** A short label for a prompt: `SMTP host`. */
+    label: string;
+    /** One sentence for the checklist: what this is and why the adapter wants it. */
+    describe: string;
+    /**
+     * Must the vault hold this before the adapter can work?
+     *
+     * `false` does not mean "unimportant": the email adapter's user and password
+     * are both optional and both-or-neither, which no per-field flag can express.
+     * That is what {@link CredentialSpec.validate}'s cross-field companion (the
+     * flow's `check` hook) is for.
+     */
+    required: boolean;
+    /** Offered as `[default]` at the prompt. Never present on a `secret`. */
+    default?: string;
+    /** For `kind: "choice"`: the closed set, each with a one-line explanation. */
+    choices?: readonly {
+        value: string;
+        describe: string;
+    }[];
+    /**
+     * Per-field validation, run on the value the operator typed.
+     *
+     * Returns the refusal SENTENCE rather than a code, because the sentence is
+     * the whole point: it must be the same one the adapter's own `act` would
+     * print later, so an operator does not learn at send time that the port they
+     * typed at setup time was never a port.
+     */
+    validate?(value: string): {
+        ok: true;
+    } | {
+        ok: false;
+        message: string;
+    };
+}

package/dist/src/core/dark-session.d.ts

@@ -0,0 +1,331 @@
+/**
+ * The dark-session detector (APRV-192): the log is asked what git already knows.
+ *
+ * ## The hole this closes
+ *
+ * APRV-151 built the CI-side grant cross-check, and its root cause is the thing
+ * that check cannot reach. A session whose harness never invoked the hook writes
+ * NO records at all: not a grant, not a refusal, not a request. Nothing inside
+ * such a session is in a position to notice, because the component that would
+ * have written the record is the component that did not run, and asking a
+ * session whether it is hooked asks the party under oversight to report its own
+ * oversight (SPEC.md §11). The CI guard sees only the diffs that reach a pull
+ * request; a session that ran dark and pushed nothing, or pushed to a branch
+ * nobody opened a pull request for, leaves the guard with nothing to read.
+ *
+ * So the direction is reversed. APRV-42's git evidence asks "does every log
+ * entry match git?"; this asks **"does every piece of git activity match a log
+ * entry?"** Git is the artifact a session cannot help producing: a commit has an
+ * author, a date and a tree, a linked worktree has a root and a birth, and none
+ * of those is authored by the runtime's hook. The absence of a record beside
+ * them is the signal.
+ *
+ * ## Two arms, because there are two questions
+ *
+ * **Arm A, evidence.** For each commit in the window, every guarded path it
+ * changed must carry evidence in the verified log that a human decided it. This
+ * is not reimplemented: it is {@link evaluateProtectedPaths}, APRV-151's own
+ * evaluator, called per commit, so the verdict vocabulary (`attested`,
+ * `granted-file`, `granted-command`), the recency bound, the exempt evidence
+ * surface and the `no-evidence` code are one implementation with two callers.
+ * Arm A runs over EVERY checkout, the primary included, because a guarded-path
+ * commit with no evidence is dark wherever it was made.
+ *
+ * **Arm B, silence.** A linked worktree that produced commits in the window (or
+ * that came into existence in it) and to which NOT ONE record in the window can
+ * be attributed is a dark session, whatever it touched. This is the arm that
+ * catches the APRV-151 root cause on paths the CI guard never sees, and it is
+ * the arm that needs an attribution rule.
+ *
+ * ## How a record is attributed to a worktree
+ *
+ * Hook task ids are `hook:<session>:<tool-use>` and carry no checkout, so the
+ * id is not the key. The bound material is. Every gated file-tool call binds
+ * `{tool, rule, file, …}` with `file` ABSOLUTE (`cli/hook.ts`), and every gated
+ * shell call binds `{command, cwd}` with `cwd` absolute. A record whose bound
+ * material names a path inside a worktree root was written by a session working
+ * in that worktree. That is PR #169's checkout-root anchoring, which APRV-151's
+ * notes recorded as the stronger answer to the two-checkouts problem and did not
+ * have a caller for; it has one now.
+ *
+ * The branch name is the second key, and a weak one: a branch `aprv-192-…`
+ * names task `APRV-192`, and a `task.registered` for that id in the window is
+ * attribution. Weak because a branch name is chosen by the party under
+ * oversight, so it may only ever ADD attribution (SPEC.md §11.1 invariant 4:
+ * a self-reported field may raise scrutiny and never lower it) — which is
+ * exactly what it does here, since attribution is what stops an alarm. Stated
+ * plainly rather than hidden: a session that names its branch after a task some
+ * other session registered escapes arm B. It does not escape arm A, and the
+ * cost of the alternative (no branch key at all) is an alarm on every worktree
+ * whose session worked entirely outside the payload store's reach.
+ *
+ * ## Fail closed in the report
+ *
+ * Uncertainty is never "fine". A log that does not verify, a payload whose
+ * bytes will not resolve, a commit git could not date, a worktree whose root
+ * cannot be placed: each is its own `undetermined` verdict with its own code,
+ * counted separately from the clean ones, and the renderer never folds an
+ * undetermined subject into the pass count. What this module does NOT do is
+ * escalate on uncertainty, because a detector is not an enforcement path: it
+ * reports, a human reads, and nothing here changes what the gate authorizes.
+ *
+ * ## What keeps the human's own commits quiet (AC4)
+ *
+ * Three exemptions, narrow and documented, and each of them fails NOISY when it
+ * does not apply:
+ *
+ * 1. A commit that touches only the daemon's own append surface
+ *    ({@link EXEMPT_PREFIXES}) is a records advance carrying evidence, not a
+ *    session doing work. Requiring evidence for the evidence is circular.
+ * 2. A commit authored by the git-evidence identity is the daemon's own
+ *    (`daemon/git-evidence.ts`), and the daemon is not a session.
+ * 3. Arm B's subject is LINKED WORKTREES ONLY. The agent-session artifact is
+ *    the worktree; the human commits in the primary checkout, where the policy
+ *    ceremony and the genesis events are made. The primary is not thereby
+ *    passed: it stays wholly subject to arm A, so a ceremony commit passes on
+ *    its attestation and an unevidenced guarded-path commit there is still
+ *    reported. And the limit is stated on every report as its own coverage
+ *    line, so an agent session that ran in the primary checkout shows up as a
+ *    gap in the report rather than as silence.
+ *
+ * ## Layout
+ *
+ * The evaluator ({@link evaluateDarkSessions}) is PURE: no IO, no clock, no
+ * git, so a fixture is enough to test it and a repository is never required.
+ * The observing half below the fold does run git and read the payload store,
+ * and it lives here rather than under `daemon/` because `approval doctor`
+ * reports the same findings and `src/cli/` may not import `src/daemon/`
+ * (APRV-59). The one thing that stays in `daemon/dark-session.ts` is the
+ * append, which is the one thing a reader must never do.
+ */
+import type { ProtectedPathEntry } from "./command-class.js";
+import { type Clock } from "./clock.js";
+import type { EventRecord } from "./log.js";
+/**
+ * The events a hooked session cannot avoid writing.
+ *
+ * A registration opens the question, a request puts it to a human, and a start
+ * records that something ran. A session that made any gated tool call at all
+ * wrote at least one of these; a session that wrote none of them made no gated
+ * call the runtime ever saw, which is the definition of dark.
+ */
+export declare const SESSION_EVENTS: readonly string[];
+/**
+ * How a subject came out. **Frozen union**, additive-only, in the same sense as
+ * every other verdict vocabulary here (SPEC.md §11.1 invariant 6).
+ */
+export declare const DARK_SESSION_VERDICTS: readonly ["hooked", "dark", "exempt", "undetermined"];
+export type DarkSessionVerdict = (typeof DARK_SESSION_VERDICTS)[number];
+/**
+ * Why a subject got the verdict it got. **Frozen union**, additive-only.
+ *
+ * `no-evidence` is spelled exactly as APRV-151 spells it, because it IS
+ * APRV-151's finding, arrived at through the same evaluator.
+ */
+export declare const DARK_SESSION_CODES: readonly [
+/** Arm B: git activity in the window, and not one attributable record. */
+"no-records", 
+/** Arm A: a guarded path changed and the log carries no evidence for it. */
+"no-evidence", 
+/** Exempt: the commits touch only the daemon's own append surface. */
+"evidence-surface", 
+/** Exempt: authored by the daemon's own git identity. */
+"daemon-authored", 
+/** Exempt from arm B (never from arm A): the primary checkout. */
+"primary-checkout", 
+/** Undetermined: the log did not verify, so nothing may be read from it. */
+"log-unverified", 
+/** Undetermined: git could not be run, or answered nothing. */
+"git-unavailable", 
+/** Undetermined: bound material would not resolve, so records cannot be placed. */
+"payload-unresolvable", 
+/** Undetermined: git named no usable date for the activity. */
+"activity-undated"];
+export type DarkSessionCode = (typeof DARK_SESSION_CODES)[number];
+/** One commit the observer saw, as git reported it. */
+export interface ObservedCommit {
+    /** The full sha. */
+    sha: string;
+    /** Author instant, ISO-8601, or `null` when git would not say. */
+    ts: string | null;
+    /** `Name <email>`, verbatim from git. */
+    author: string;
+    /** The author's email alone, lowercased, or `""` when git named none. */
+    authorEmail: string;
+    /** Repository-relative, `/`-separated paths this commit changed. */
+    changedPaths: readonly string[];
+    /** The branch or worktree this commit was observed on, for the message. */
+    ref: string;
+}
+/** One checkout the observer saw: the primary, or a linked worktree. */
+export interface ObservedCheckout {
+    /** Absolute, symlink-resolved root. */
+    root: string;
+    /** How it is named in the report (the worktree directory's base name). */
+    name: string;
+    /** True for the primary checkout, false for a linked worktree. */
+    primary: boolean;
+    /** The checked-out branch, or `null` on a detached HEAD. */
+    branch: string | null;
+    /** Its birth instant, when the observer could stat it; else `null`. */
+    born: string | null;
+    /** Commits observed on it inside the window. */
+    commits: readonly ObservedCommit[];
+}
+/** What the observer gathered, and what it could not. */
+export interface GitActivity {
+    checkouts: readonly ObservedCheckout[];
+    /**
+     * Why git could not be asked, when it could not. A non-null value makes every
+     * subject `undetermined` rather than passing them for lack of evidence.
+     */
+    unavailable: string | null;
+}
+/** The window the sweep judged, as instants. */
+export interface DarkSessionWindow {
+    from: string;
+    to: string;
+}
+export interface DarkSessionInput {
+    activity: GitActivity;
+    /**
+     * Records from the log that have passed chain verification, or `null` when it
+     * did not verify. `null` makes every subject `undetermined`; nothing here
+     * reads an unverified record (SPEC.md §11.1 invariant 1).
+     */
+    records: readonly EventRecord[] | null;
+    /** Why the log could not be used, when `records` is `null`. */
+    logDetail?: string;
+    /** `policy.protected_paths`, widening the built-in guarded set. */
+    policyProtectedPaths: readonly ProtectedPathEntry[];
+    /** The policy file's repository-relative path, e.g. `APPROVAL.md`. */
+    policyPath: string;
+    /** SHA-256 of the policy bytes now on disk, for the `attested` verdict. */
+    policySha256: string | null;
+    /** Resolve bound material by hash from the live payload store. */
+    payloadFor: (hash: string) => unknown | null;
+    /** Author emails whose commits are the daemon's own, lowercased. */
+    daemonEmails: readonly string[];
+    /** The instants the observer swept between. */
+    window: DarkSessionWindow;
+    /** Override the recency bound `evaluateProtectedPaths` applies. */
+    lookbackMs?: number;
+}
+/** One subject's verdict. A subject is one checkout. */
+export interface DarkSessionFinding {
+    /** The checkout's name — the worktree directory, or `primary`. */
+    subject: string;
+    root: string;
+    primary: boolean;
+    branch: string | null;
+    verdict: DarkSessionVerdict;
+    code: DarkSessionCode | null;
+    /** Commits observed on this subject in the window. */
+    commits: number;
+    /** Guarded paths this subject changed in the window. */
+    guardedPaths: readonly string[];
+    /** Records in the window attributed to this subject. */
+    attributed: readonly number[];
+    /**
+     * The newest sha observed on this subject, or `null` when it produced no
+     * commit. Half of the observation key: an alarm is about a state of the
+     * world, and the same state must not be recorded twice.
+     */
+    newestSha: string | null;
+    /** Stable across ticks for one observation; see {@link observationKey}. */
+    key: string;
+    /** Prose a reader can act on, on every verdict. */
+    detail: string;
+}
+export interface DarkSessionReport {
+    /** True when no subject came out `dark`. Says nothing about what was seen. */
+    ok: boolean;
+    /**
+     * True when every subject was ESTABLISHED, one way or the other.
+     *
+     * Kept separate from {@link DarkSessionReport.ok} on purpose. A report with
+     * no dark subject and three undetermined ones is not a clean sweep, and a
+     * single boolean would have to lie about one of the two facts: either it
+     * alarms on uncertainty (and an operator learns to ignore the alarm) or it
+     * calls uncertainty fine (and the detector reports a pass it did not earn).
+     * Two booleans say both things, and every surface reads the one it means.
+     */
+    settled: boolean;
+    findings: readonly DarkSessionFinding[];
+    window: DarkSessionWindow;
+    /**
+     * What this sweep could not see, always stated. Arm B covers linked worktrees
+     * only, so a session that ran in the primary checkout is outside it, and a
+     * report that did not say so would be claiming coverage it does not have.
+     */
+    coverage: string;
+}
+/** The observation key: one subject, one state of the world. */
+export declare function observationKey(subject: string, newestSha: string | null, born: string | null): string;
+/** The Backlog.md task id a branch name begins with, upper-cased (`aprv-192-x`). */
+export declare function taskIdFromBranch(branch: string | null): string | null;
+/**
+ * Evaluate what git showed against what the log carries. Pure: no IO, no clock.
+ */
+export declare function evaluateDarkSessions(input: DarkSessionInput): DarkSessionReport;
+/** The report as lines an operator reads. Pure. */
+export declare function renderDarkSessionReport(report: DarkSessionReport): string;
+/**
+ * Everything below this line does IO, and it lives here rather than in
+ * `daemon/` for one reason: `approval doctor` reports the same findings and
+ * `src/cli/` may not import `src/daemon/` (APRV-59, `tests/layering.test.ts`).
+ * Two observers would be two answers to one question, so there is one, and the
+ * daemon's module keeps only the thing a reader must never do — the append.
+ */
+/** How far back a sweep looks, absent an operator saying otherwise. */
+export declare const DEFAULT_DARK_WINDOW_MS: number;
+/** How often the sweep runs, absent an operator saying otherwise. */
+export declare const DEFAULT_DARK_INTERVAL_MS: number;
+/**
+ * The git identities whose commits are the runtime's own.
+ *
+ * Spelled here rather than imported from `daemon/git-evidence.ts`, which is
+ * where the daemon's commit identity is defined: core must not depend on the
+ * daemon. `tests/dark-session.test.ts` pins the two against each other so they
+ * cannot drift apart, the same device `APPROVALD_VERSION` uses for its own
+ * duplicate of the package version.
+ */
+export declare const DAEMON_EVIDENCE_EMAILS: readonly string[];
+/** The opt-in, as the daemon carries it. */
+export interface DarkSessionWatch {
+    /** How far back each sweep looks. */
+    windowMs: number;
+    /** How often a sweep runs. The tick interval is the floor. */
+    intervalMs: number;
+}
+/** Everything git could tell the sweep about a repository in one window. */
+export declare function observeGitActivity(root: string, from: string, to: string): GitActivity;
+export interface DarkSessionSweepOptions {
+    logPath: string;
+    /** The checkout to observe. The daemon's own `cwd`; never an agent worktree. */
+    root: string;
+    /** Policy location, with `loadPolicy`'s semantics. */
+    policy: {
+        dir?: string;
+        file?: string;
+    };
+    schemaDir?: string;
+    /** The write-boundary clock (amended SPEC.md §8). */
+    clock?: Clock;
+    windowMs: number;
+    /** Verified records. The caller has already read them; nothing re-reads. */
+    records: readonly EventRecord[] | null;
+    logDetail?: string;
+    /** Test seam: an observer that answers without running git. */
+    observe?: (root: string, from: string, to: string) => GitActivity;
+}
+/**
+ * Observe and judge, appending nothing.
+ *
+ * The read-only half, which is the half `approval doctor` calls: doctor reports
+ * and the daemon writes, so two processes never become two writers of one fact.
+ */
+export declare function reportDarkSessions(options: DarkSessionSweepOptions): {
+    report: DarkSessionReport;
+    window: DarkSessionWindow;
+};