approval-md 0.1.0 → 0.2.0

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

@@ -0,0 +1,1180 @@
+/**
+ * `approvald` — the daemon loop of SPEC.md §10.2 (APRV-39).
+ *
+ * > "`approvald` watches the backlog folder and the log: validates new/changed
+ * > envelopes, applies policy, dispatches channel notifications, expires TTLs,
+ * > samples supervised actions for audit, re-renders projections, and
+ * > (optionally) polls upstream sources."
+ *
+ * This module is the loop's core: watch, envelope drift, TTL sweep, projection
+ * write-back, queue regeneration, and loop-escalation surfacing. Channel dispatch
+ * belongs to the channel verbs (APRV-23/25/26), audit sampling to APRV-40, and
+ * payload-retention pruning to APRV-41; each is its own task and none of them is
+ * smuggled in here.
+ *
+ * ## Drift, then repair (SPEC.md §6.3, §10.2, APRV-62)
+ *
+ * A task file's `state:` is a projection and the log is the truth, so the two
+ * halves of that sentence are two steps of one tick. The drift scan runs first
+ * and appends `envelope.drift` for every file whose claim the log contradicts;
+ * the write-back pass runs after every append this tick could make and rewrites
+ * those files through `core/task-file.ts` so the projection matches the log
+ * again. Write-back never appends and never precedes an append: it only copies a
+ * fact the log already carries into a file that disagreed with it.
+ *
+ * So a drift record marks the moment a file was found wrong **and fixed**, not a
+ * standing disagreement. That reading is what makes the records worth watching:
+ * a file that keeps drifting after repair is a file some other writer is fighting
+ * the daemon over, and the repeated records are how an operator sees it. One
+ * record per transition is the healthy shape (the log moved, the file caught up);
+ * a run of identical records against an unmoving log is not.
+ *
+ * ## It decides nothing of its own
+ *
+ * Every judgement the daemon makes is one some other module already owns:
+ *
+ * - approval state per action is `core/state.ts`'s `requestState`, rolled up to
+ *   the task by `daemon/projection.ts` and never re-derived;
+ * - expiry is `core/gate.ts`'s `expire`, the system verb, which re-reads the log,
+ *   re-judges the TTL, and refuses anything that is not a live lapsed request;
+ * - the queue is `channels/render-queue.ts`'s `writeQueue`, the same renderer
+ *   `approval render` calls, writing the same file the same atomic way;
+ * - loop escalation is `core/loop.ts`'s projection, which the gate and the
+ *   executor already enforce. The daemon **surfaces** it and enforces nothing.
+ *
+ * What is new here is scheduling: when to look, how often, and how not to append
+ * the same fact twice.
+ *
+ * ## Watching, and why correctness never depends on it
+ *
+ * `fs.watch` is bursty, coalescing, and platform-dependent: one editor save can
+ * produce three events or one, a rename can arrive as a delete plus a create,
+ * and on some filesystems nothing arrives at all. So the watcher is treated as a
+ * **latency optimization and nothing else**. Every tick re-scans the task folder
+ * and re-derives everything from the verified log, and a periodic tick runs on
+ * `intervalMs` whether or not any watcher ever fires. A daemon whose watchers all
+ * failed to attach is a slower daemon, never a wrong one — which is also what
+ * makes the behavior testable without depending on any platform's watch
+ * semantics.
+ *
+ * Watch events are debounced (`debounceMs`) so a burst collapses into one tick.
+ * Ticks are synchronous end to end, so they cannot interleave.
+ *
+ * Which of those events are acted on, and which are dropped as this loop's own
+ * hand or as bookkeeping nobody reads, is {@link Daemon.attachWatchers}.
+ * `traceWatch` prints the decision for every event, and the `tick` line's
+ * `woke_by` names the one that opened the window it closed (APRV-230): a tick is
+ * the daemon's unit of work, and one nobody asked for costs exactly as much as
+ * one somebody did.
+ *
+ * ## Single writer, in intent only
+ *
+ * CLAUDE.md's rule is that the daemon is the sole writer while it runs. That is
+ * an operational stance, not a lock this module takes: the CLI verbs remain
+ * appendable at any moment, `core/log.ts`'s advisory lockfile serializes the
+ * writes, and every append here passes `expectedHead` so a check made against one
+ * log cannot land on another (compare-and-append, SPEC.md §11.1 invariant 5).
+ *
+ * The daemon therefore **tolerates external appends by re-reading**: a
+ * `head-moved` refusal is reported and dropped, never retried in place, because
+ * the next tick re-derives the whole question from the log as it now is. It holds
+ * no lock of its own and leaves no lockfile behind — the only lockfile in this
+ * system is the one `appendEvent` creates and releases inside a single call.
+ *
+ * ## Fail closed, loudly
+ *
+ * A log that does not verify stops the daemon rather than degrading it. Nothing
+ * may be appended onto a chain that does not verify, projections built from one
+ * would be screenshots of something nobody should read, and a daemon that kept
+ * running while reporting corruption would train an operator to ignore it.
+ */
+import { type Clock } from "../core/clock.js";
+import { type AutoMergeState } from "../cli/log-advance.js";
+import { type AdvanceAttempt, type AdvanceCadence, type AdvanceOutcome } from "./advance.js";
+import { type DarkSessionSweepOptions, type DarkSessionWatch } from "./dark-session.js";
+import type { DrawServeResult } from "./draw.js";
+import type { GitEvidenceRecorder } from "./git-evidence.js";
+import { type PruneReason } from "./prune.js";
+/**
+ * SPEC.md §8: runtime-originated events carry a `system:` actor. The daemon is
+ * the runtime, and `envelope.drift` is its own event — distinct from
+ * `system:gate`, which `core/gate.ts` stamps on the expiries it appends, so a
+ * reader can tell which part of the runtime spoke.
+ */
+export declare const DAEMON_ACTOR = "system:daemon";
+/** Backlog.md's conventional task folder, relative to the working directory. */
+export { DEFAULT_TASKS_DIR } from "../core/registration.js";
+/** How often the daemon looks, absent any watcher event. */
+export declare const DEFAULT_INTERVAL_MS = 30000;
+/** How long a burst of watcher events is allowed to settle before a tick. */
+export declare const DEFAULT_DEBOUNCE_MS = 250;
+/** The two directories this loop watches, as they are named in its output. */
+export type WatchSource = "tasks" | "log";
+/**
+ * Why a watcher event did not schedule a tick (APRV-230).
+ *
+ * Machine-readable and a closed union, for the reason {@link
+ * DAEMON_WARNING_CODES} is: an operator counting phantom ticks groups the trace
+ * by this field, and a free-text sentence would make that a grep instead of a
+ * count.
+ */
+export declare const WATCH_IGNORE_REASONS: readonly [
+/** A task file this daemon's own write-back pass placed (APRV-211). */
+"self-write", 
+/** The `.<name>.tmp-<pid>-<n>` file this process writes a task file through. */
+"own-temp", 
+/** A bookkeeping file: see {@link bookkeepingKind}. */
+"bookkeeping", 
+/** Something in the log's directory that is not the log (the snapshot). */
+"not-the-log"];
+export type WatchIgnoreReason = (typeof WATCH_IGNORE_REASONS)[number];
+/**
+ * What kind of bookkeeping file `name` is, or `null` when it is not one.
+ *
+ * The files that live in these two directories without ever being their
+ * subject: the append lockfile every writer in this runtime creates and removes
+ * (`<log>.lock`, `core/log.ts`), the swap, autosave, backup and lock files an
+ * editor scatters beside a file it is editing, and macOS's own `.DS_Store` and
+ * AppleDouble residue. Each of these is a filesystem event about how a change
+ * was made and never about the change; a tick scheduled for one re-derives an
+ * answer nothing has moved (APRV-230, and the lockfile pair is two events per
+ * append from every writer on the machine).
+ *
+ * Safe for exactly the reason {@link Daemon.attachWatchers} documents: the
+ * watcher is a latency optimization and correctness never depended on it
+ * (SPEC.md §10.2), so the worst an over-eager name here can cost is one
+ * `--interval` of latency. Nothing in this list can name a Backlog.md task file,
+ * which is `<id> - <slug>.md`.
+ */
+export declare function bookkeepingKind(name: string): string | null;
+/**
+ * One line of daemon output. **Frozen shape** in the same sense every `--json`
+ * shape in this CLI is frozen: an operator's log pipeline and an agent's
+ * supervisor branch on `event`, so entries may be added and none may be
+ * repurposed. Each is printed as one JSON object per line under `--json`, and as
+ * one human sentence otherwise.
+ */
+export type DaemonEvent = {
+    event: "started";
+    log: string;
+    tasks: string;
+    queue: string;
+    interval_ms: number;
+    debounce_ms: number;
+    watching: boolean;
+    /**
+     * Which prefix proof this run's verified reads run (APRV-217). Additive,
+     * like every other growth of this union. It is on the FIRST line the
+     * daemon prints because it is a configuration an operator has to be able
+     * to see without asking the process anything.
+     */
+    read_proof: "full" | "incremental";
+    /**
+     * The committed copy of the log this run is anchored against (APRV-219).
+     * Additive, like every other growth of this union, and on the first line
+     * for the reason `read_proof` is: which external witness a run holds
+     * itself to is not something an operator should have to ask the process
+     * about. `rev: null` is an honest "none was found", never a silent pass.
+     */
+    anchor: {
+        rev: string | null;
+        seq: number | null;
+        reason: string | null;
+    };
+    /**
+     * Where this run is answering live draws, or `null` when it is not
+     * (APRV-208). Additive, and on the first line for the reason `read_proof`
+     * is: whether `supervised-live` is actually live on this machine is a
+     * configuration an operator must be able to see without asking the process
+     * anything, and the difference between "sampled at 10%" and "gated at
+     * 100%" is exactly this field being a path rather than `null`.
+     */
+    draw?: string | null;
+    /**
+     * Advance cycles nobody closed that this checkout's refs cannot prove
+     * (APRV-264). Additive, like every other growth of this union.
+     *
+     * On the FIRST line because it is the one thing that will stop the
+     * cadence for the whole of this run and the one thing this process cannot
+     * fix: an operator who reads it here does not have to wait out a tick to
+     * find out that the advance is blocked, and they get the command that
+     * clears it. Empty on a healthy start, and empty when the startup sweep
+     * closed everything it found — what is here is precisely what is owed to
+     * a person.
+     */
+    dangling_advances?: string[];
+} | {
+    event: "drift";
+    task: string;
+    file: string;
+    declared_state: string | null;
+    derived_state: string;
+    seq: number;
+    /**
+     * Why (APRV-63). Present only for `envelope-missing`: a `state-mismatch`
+     * line is what every `drift` line has always been, and a field that
+     * appeared on all of them would change a shape supervisors already parse.
+     */
+    reason?: "envelope-missing";
+} | {
+    /**
+     * A task file's `state:` was rewritten to match the log (SPEC.md §6.3).
+     * Additive (APRV-62): the union grows, and no existing entry changes
+     * meaning. A rewritten file is a change to a human's working tree, so it
+     * gets a line of its own rather than hiding inside the drift record that
+     * preceded it.
+     */
+    event: "write_back";
+    task: string;
+    file: string;
+    /** The `state:` the file claimed, or `null` when it declared none. */
+    from: string | null;
+    /** The state the log implies, now on disk. */
+    to: string;
+    bytes: number;
+} | {
+    event: "expired";
+    action_key: string;
+    task: string | null;
+    seq: number;
+} | {
+    /**
+     * A supervised execution was drawn for retrospective review (APRV-40,
+     * SPEC.md §5.2). Additive (APRV-57): the union grows and no existing entry
+     * changes meaning. APRV-40 left successful samples visible only as a
+     * `rendered` backlog that grew, which tells an operator that *something*
+     * was sampled without telling them what; this names it.
+     */
+    event: "sampled";
+    action_key: string;
+    task: string | null;
+    /** `seq` of the appended `audit.sampled` record. */
+    seq: number;
+    /** `seq` of the `execution.started` record the sample named. */
+    subject_seq: number;
+} | {
+    /**
+     * A payload's bytes were removed under `payload_retention` (APRV-41,
+     * amended SPEC.md §5.2). Additive (APRV-57), and emitted only for a prune
+     * that both appended its `payload.pruned` and unlinked the file: a prune
+     * that appended and could not unlink is already a `prune-refused` warning,
+     * and a crash-window completion appends nothing, so it has no `seq` to
+     * name and stays out of this line.
+     *
+     * No byte count: `daemon/prune.ts` unlinks by hash and never stats the
+     * file, and a size read here would be a fresh filesystem question asked
+     * after the answer stopped existing.
+     */
+    event: "pruned";
+    payload_hash: string;
+    reason: PruneReason;
+    /** The action whose terminal state released the bytes; `null` for an orphan. */
+    action_key: string | null;
+    task: string | null;
+    /** `seq` of the appended `payload.pruned` record. */
+    seq: number;
+} | {
+    event: "rendered";
+    path: string;
+    bytes: number;
+    pending: number;
+    skipped: number;
+    audit_backlog: number;
+} | {
+    /**
+     * The log was advanced onto a records branch, or an attempt to advance it
+     * ended some other way (APRV-204). Additive: the union grows and no
+     * existing entry changes meaning.
+     *
+     * One line per ATTEMPT, including the refused and gated ones, because the
+     * thing an operator needs to see is that the cadence is running and what
+     * it met — an advance that silently did not happen is the failure mode
+     * this whole feature exists to remove.
+     */
+    event: "advance";
+    outcome: AdvanceOutcome;
+    /** Records not yet on a records branch, at the moment of the attempt. */
+    records_pending: number;
+    records_branch: string | null;
+    /** The seq range this attempt published, or `null` when it published none. */
+    range: {
+        from: number;
+        to: number;
+    } | null;
+    commit: string | null;
+    pr_url: string | null;
+    /** True when this attempt opened the day's pull request rather than updating it. */
+    pr_created: boolean;
+    /**
+     * What became of the auto-merge arm on that pull request (APRV-284), and
+     * why when it was not armed. `null` when no pull request step ran.
+     *
+     * Reported because "the records are pushed" and "the records will land"
+     * are different facts, and only the second one means nobody has anything
+     * left to do.
+     */
+    auto_merge: AutoMergeState | null;
+    auto_merge_note: string | null;
+    /**
+     * True when the day's records branch was REBUILT on the base rather than
+     * stacked on its own tip, and the ref it was rebuilt on (APRV-234).
+     *
+     * A branch the trunk has moved under cannot be fast-forwarded into it,
+     * and a daemon that kept stacking on it produced a pull request only a
+     * hand merge could land. Rebuilding is the repair, and an operator reading
+     * this stream should not have to infer that it happened from a sha.
+     */
+    rebuilt: boolean;
+    rebuilt_on: string | null;
+    /** The refusal or failure code, when the outcome carries one. */
+    code: string | null;
+    message: string;
+    /** True when this attempt was the graceful-shutdown flush. */
+    flush: boolean;
+} | {
+    /**
+     * One subject of a dark-session sweep (APRV-192). Additive: the union
+     * grows and no existing entry changes meaning.
+     *
+     * One line per subject that is NOT clean — dark, or undetermined —
+     * because the sweep's whole point is the thing nobody was told about, and
+     * a line per healthy worktree would bury it. A `dark` line names the
+     * `audit.dark_session` record it appended, or says the log already
+     * carried this observation; an `undetermined` line names what could not
+     * be established, which is never reported as a pass.
+     */
+    event: "dark_session";
+    verdict: "dark" | "undetermined";
+    /** The checkout: a worktree directory's name, or `primary`. */
+    subject: string;
+    branch: string | null;
+    code: string;
+    /** Commits observed on this subject inside the window. */
+    commits: number;
+    /** `seq` of the appended record, `null` when nothing was appended. */
+    seq: number | null;
+    /** True when a prior record already carried this observation key. */
+    already_recorded: boolean;
+    message: string;
+} | {
+    event: "escalated";
+    task: string;
+    consecutive_failures: number;
+} | {
+    event: "escalation_cleared";
+    task: string;
+} | {
+    /**
+     * One filesystem watcher event, as the platform delivered it (APRV-230).
+     *
+     * Emitted only under {@link DaemonOptions.traceWatch}, because a busy
+     * checkout produces several of these per second and they are a diagnostic
+     * rather than a narrative. It is what the phantom-tick investigation had
+     * no way to ask: which directory fired, what the platform called the
+     * event, which file it named, and whether this loop acted on it.
+     *
+     * Report-only in the strongest sense: nothing downstream reads it, and
+     * turning the trace on changes no verdict and no schedule.
+     */
+    event: "watch";
+    /** Which watcher fired: the task folder, or the log's directory. */
+    watcher: WatchSource;
+    /** The platform's own event name (`rename`, `change`). */
+    type: string;
+    /** The file the platform named, or `null` when it named none. */
+    file: string | null;
+    /** Whether this event scheduled a tick. */
+    action: "scheduled" | "ignored";
+    /** Why it was ignored, or `null` when it scheduled. */
+    reason: WatchIgnoreReason | null;
+} | {
+    event: "tick";
+    n: number;
+    head: number | null;
+    drift: number;
+    expired: number;
+    escalated: number;
+    /**
+     * What the tick cost (APRV-211). Additive, like every other growth of this
+     * union: the fields below were appended and nothing above them changed
+     * meaning. A tick is the daemon's unit of work and it was possible for one
+     * to pin a core for three seconds while every line it printed looked
+     * healthy; these three fields are how that is visible without a profiler.
+     */
+    /** Wall-clock duration of the whole tick, in milliseconds. */
+    ms: number;
+    /** Verified log reads this tick made. Bounded by structure, not by size. */
+    reads: number;
+    /**
+     * Which path this tick's reads took (APRV-217). Additive. `full` when any
+     * read this tick hashed the whole prefix — a full re-proof, a cadence
+     * boundary, a guard failure, or a cold walk — and `incremental` when
+     * every one of them was served from a carried hash state. Under
+     * `read_proof: full` it is `full` on every tick, which is the honest
+     * report: that is the path those reads took.
+     */
+    reproof: "full" | "incremental";
+    /**
+     * The anchor comparison this tick made, or `null` when it made none
+     * (APRV-219). Additive. The check rides the full re-proof cadence: a tick
+     * whose reads were all served from a carried hash state has re-proved
+     * nothing about the file's prefix and has nothing new to compare against
+     * a committed copy that cannot have changed since the last look.
+     */
+    anchor?: {
+        status: "pass" | "behind" | "skip";
+        rev: string | null;
+        seq: number | null;
+    };
+    /**
+     * The checkpoint check this tick made, or `null` when it made none
+     * (APRV-220). Additive, and on the same full re-proof cadence as the
+     * anchor for the same reason: a tick that re-proved nothing about the
+     * prefix has learned nothing new about the records inside it.
+     */
+    checkpoints?: {
+        status: "pass" | "skip";
+        verified: number;
+        keys: number;
+        /**
+         * Whether `audit.checkpoint_every` says one is DUE (APRV-257).
+         *
+         * The daemon's half of the cadence, and the same answer the channel
+         * prompt is enqueued from: both read `core/checkpoint.ts`'s one
+         * due-ness rule, so there is no arrangement in which this line says a
+         * checkpoint is owed and no prompt is offered, or the reverse. The
+         * ENQUEUE is the dispatch cycle's, which is where SPEC.md §10.2's
+         * dispatch job lives in this runtime (see `cli/channel-telegram.ts`'s
+         * module doc): the daemon holds no channel credential and reaches no
+         * network, and giving it either to send one prompt would undo that.
+         *
+         * Report-only, like everything else on this path. Nothing turns a
+         * `true` into a refusal; the outcome beside it is a `warn`, never a
+         * `fatal`.
+         */
+        due: boolean;
+    };
+    /**
+     * What woke this tick (APRV-230). Additive, and report-only.
+     *
+     * `log` and `tasks` name the watcher whose event opened the debounce
+     * window this tick closed; `interval` covers everything else (the
+     * periodic tick, the startup tick, and `--once`). The 2026-09-02 incident
+     * was diagnosed by counting ticks at an unchanged head, and this field is
+     * that count without a profiler: a tick that says `log` with no append
+     * behind it is a watcher event this daemon has not learned to attribute.
+     */
+    woke_by: WatchSource | "interval";
+    /**
+     * The file the waking event named, when it named one. Absent for an
+     * `interval` tick and for a platform event that named no file.
+     */
+    woke_file?: string;
+    /** Per-phase duration in milliseconds, in the order the tick runs them. */
+    phases: {
+        drift: number;
+        ttl: number;
+        audit: number;
+        dark: number;
+        prune: number;
+        write_back: number;
+        advance: number;
+        escalations: number;
+        render: number;
+    };
+} | {
+    event: "warning";
+    code: DaemonWarningCode;
+    message: string;
+} | {
+    event: "stopped";
+    reason: string;
+    ticks: number;
+    drift: number;
+    expired: number;
+    renders: number;
+};
+/**
+ * Why the daemon complained without stopping. Machine-readable and distinct, per
+ * SPEC.md §11.1 invariant 6, and a closed union for the same reason the gate's
+ * refusal codes are: a supervisor that branches on them needs them stable.
+ */
+export declare const DAEMON_WARNING_CODES: readonly [
+/** A task file could not be read (permissions, a vanished file). */
+"task-unreadable", 
+/** A task file's frontmatter does not parse. */
+"frontmatter-invalid", 
+/** The `approval:` envelope failed `envelope.schema.json`. */
+"envelope-invalid", 
+/** The frontmatter carries no usable `id`, so no drift can be keyed to it. */
+"task-id-missing", 
+/** The task folder could not be listed; the next tick tries again. */
+"tasks-dir-unreadable", 
+/** An append was refused. The next tick re-derives and may try again. */
+"append-refused", 
+/** The TTL sweep's `expire` refused for a reason other than a race. */
+"expire-refused", 
+/** The queue could not be written. The log is untouched. */
+"render-failed", 
+/** A watcher could not attach; the periodic tick covers the folder anyway. */
+"watch-unavailable", 
+/**
+ * A payload-retention prune did not complete (APRV-41). The store keeps the
+ * file, and the next tick re-derives; nothing is ever deleted unlogged.
+ */
+"prune-refused", 
+/**
+ * The projection write-back was refused by the writer, or the rewritten bytes
+ * could not be placed (APRV-62). The file is left exactly as it was and the
+ * log is untouched; the message carries `core/task-file.ts`'s own code.
+ */
+"write-back-refused", 
+/**
+ * A cadence advance did not publish (APRV-204): the gate sent it to a human,
+ * refused it, or the verb itself failed. Nothing was committed, the outcome
+ * is on the `advance` line beside this warning, and the next tick tries
+ * again — the cadence interval is the retry bound, so there is no hot loop.
+ */
+"advance-refused", 
+/**
+ * A dark-session sweep (APRV-192) found git activity it could not judge, or
+ * could not append the observation it did reach. Uncertainty is reported as
+ * uncertainty and never as a pass; nothing is escalated on it, because a
+ * detector reports and the gate decides.
+ */
+"dark-session-undetermined", 
+/**
+ * The working log is a strict PREFIX of its committed copy (APRV-219): the
+ * anchor carries records this file does not. Not a divergence — the two are
+ * one chain and this checkout is behind it — and not silence either, because
+ * an append onto the shorter chain forks it. `approval log sync` is the
+ * repair, and the next tick asks again.
+ */
+"anchor-behind", 
+/**
+ * `audit.checkpoint_every` says a human-signed checkpoint is due and the log
+ * carries none that recent (APRV-220). A WARNING and never a stop, at every
+ * layer: a human who has been away is not a forger, and a daemon that stopped
+ * for want of a tap is a daemon whose operator turns the check off.
+ */
+"checkpoint-due", 
+/**
+ * The live-draw socket could not be served (APRV-208). Nothing is degraded:
+ * every asker fails closed to a human decision, which is exactly what happens
+ * on a machine where no daemon runs at all. It is a warning rather than a
+ * silence because the operator's `supervised-live` classes are gating at 100%
+ * while it stands, and that is a thing to know rather than to discover from a
+ * month of taps.
+ */
+"draw-unavailable"];
+export type DaemonWarningCode = (typeof DAEMON_WARNING_CODES)[number];
+/** Where daemon output goes. Injected, so the loop itself writes to nothing. */
+export interface DaemonSink {
+    emit(event: DaemonEvent): void;
+}
+export interface DaemonOptions {
+    /** The append-only log (SPEC.md §9). Read every tick, appended rarely. */
+    logPath: string;
+    /** The Backlog.md task folder to watch. */
+    tasksDir: string;
+    /** Where `QUEUE.md` is regenerated (SPEC.md §9.1). */
+    queuePath: string;
+    /** Policy location, with `loadPolicy`'s semantics. */
+    policy: {
+        dir?: string;
+        file?: string;
+    };
+    /** Schema directory, passed to validation and to every append. */
+    schemaDir?: string;
+    /** Directory paths in output are reported relative to this. */
+    cwd: string;
+    /** Periodic tick, in milliseconds. Also the poll-assisted watcher fallback. */
+    intervalMs: number;
+    /** Watcher debounce, in milliseconds. */
+    debounceMs: number;
+    /** Run exactly one tick and stop. The cron-shaped invocation, and the tests'. */
+    once: boolean;
+    /**
+     * Emit a `watch` line for every filesystem watcher event (APRV-230), ignored
+     * ones included. Off by default: it is a diagnostic an operator turns on to
+     * find out what is waking their daemon, and on a busy checkout it is several
+     * lines per second. It changes nothing else about the run.
+     */
+    traceWatch?: boolean;
+    /** The write-boundary clock, injected by tests (amended SPEC.md §8). */
+    clock?: Clock;
+    /**
+     * SPEC.md §8's optional git hardening (APRV-42), off unless the operator asked
+     * for it. When present, it is handed the verified head at the end of each
+     * tick; it decides everything else, reports through its own sink, and cannot
+     * change any verdict this loop reaches. See `daemon/git-evidence.ts`.
+     */
+    gitEvidence?: GitEvidenceRecorder;
+    /**
+     * The cadence advance (APRV-204), off unless the operator asked for it.
+     *
+     * Opt-in for the reason `gitEvidence` is: it pushes commits and opens pull
+     * requests on a remote, and a daemon that started doing that on an upgrade
+     * because a default changed under it would be the surprise this project
+     * exists to prevent. `approval daemon run --advance` turns it on.
+     */
+    advance?: AdvanceCadence;
+    /**
+     * The child that runs a periodic tick's advance (APRV-211). A test seam;
+     * production spawns `daemon/advance-child.js`. See {@link AdvanceInput.runner}.
+     */
+    advanceRunner?: {
+        command: string;
+        args: readonly string[];
+    };
+    /**
+     * The dark-session sweep (APRV-192), off unless the operator asked for it.
+     *
+     * Opt-in for the reason `gitEvidence` and `advance` are, though a milder one:
+     * it runs `git log` over every worktree of the checkout on a cadence, which
+     * on a large repository is real work, and a daemon that started doing it
+     * because a default moved under an operator would be the surprise this
+     * project exists to prevent. `approval daemon run --dark-sessions` turns it
+     * on. It is READ-ONLY against git and appends only its own observations.
+     */
+    darkSessions?: DarkSessionWatch;
+    /**
+     * Test seam for the sweep's observer: an answer that does not run git. The
+     * daemon never sets it, exactly as it never sets `today`.
+     */
+    observeGit?: DarkSessionSweepOptions["observe"];
+    /** The day the records branch is named for. Injected by tests. */
+    today?: string;
+    /**
+     * Publish a verified-head snapshot beside the log on every clean read
+     * (APRV-188). On unless explicitly set to `false`.
+     *
+     * On by default, unlike `gitEvidence` and `advance`, because it changes
+     * nothing outside this machine: the file is derived, local, byte-endorsing
+     * state that every reader re-proves and any reader may ignore. Turning it off
+     * costs hook latency and nothing else.
+     */
+    snapshot?: boolean;
+    /**
+     * Which prefix proof this loop's verified reads run (APRV-217).
+     *
+     * Absent means `full`: every read re-hashes the whole proved prefix, which is
+     * the behaviour of every release before this one. The CLI resolves it from
+     * the `daemon` policy block and the `--read-proof` family, flag first, and
+     * hands the answer down here so the loop itself reads no policy for it and
+     * cannot drift from the mode its `started` line printed.
+     */
+    readProof?: {
+        mode: "full" | "incremental";
+        everyReads: number;
+        afterMs: number;
+    };
+    /**
+     * The log-anchoring check (APRV-219). On unless explicitly disabled.
+     *
+     * On by default, unlike `gitEvidence` and `advance`, for the reason
+     * `snapshot` is: it READS git's object store and changes nothing anywhere,
+     * on this machine or any other. `rev` pins the anchor to one rev instead of
+     * the default resolution, which is what a test and an operator debugging a
+     * divergence both want.
+     */
+    anchor?: {
+        enabled?: boolean;
+        rev?: string;
+        remote?: string;
+        base?: string | null;
+    };
+    /**
+     * The human-signed checkpoint check (APRV-220). On unless explicitly
+     * disabled, for the reason the anchor is: it reads the log this loop has
+     * already verified plus the policy, and writes nothing anywhere.
+     */
+    checkpoints?: {
+        enabled?: boolean;
+    };
+    /**
+     * The live-draw server (APRV-208), or absent when this run answers no draws.
+     *
+     * Constructed by the CALLER, not here, and the reason is the sampling secret:
+     * the CLI resolves it from the environment the operator established (the one
+     * `eval "$(approval env)"` writes) and hands down a server that has closed
+     * over it. `DaemonOptions` therefore never carries a secret, this loop never
+     * sees one, and a daemon started in a shell where the secret does not resolve
+     * simply gets no server and every supervised-live action keeps gating, which
+     * is the behaviour of every release before this one.
+     *
+     * Typed structurally rather than as `DrawServer` so a test can inject one.
+     */
+    draw?: {
+        start(): DrawServeResult;
+        close(): void;
+    };
+    sink: DaemonSink;
+}
+/**
+ * How the loop ended.
+ *
+ * `stopped` is a clean shutdown (a signal, or `once` completing). The four
+ * failures mirror the CLI's frozen exit table exactly, so the verb maps them
+ * without inventing a code: an unreadable log is I/O, a torn tail is a crashed
+ * write, and a chain that does not verify is an integrity failure.
+ *
+ * `anchor-diverged` (APRV-219) is the fourth, and it is an integrity failure
+ * for the same reason `log-corrupt` is: the log this loop would append to is
+ * not the log somebody else already holds a committed copy of, and appending
+ * onto it would extend the wrong chain. It is a DISTINCT kind rather than a
+ * flavour of `log-corrupt` because the two say different things to whoever
+ * reads the stopped line — one means the file contradicts itself, the other
+ * means the file contradicts the record of it.
+ *
+ * `checkpoint-invalid` (APRV-220) is the fifth, and it is distinct from both
+ * for the same kind of reason: it means the file contradicts a signature a
+ * human made over it. The three failures name three different witnesses, and
+ * flattening them would leave the operator's first question — which witness
+ * disagrees? — answerable only by reading a message.
+ */
+export type DaemonOutcome = {
+    kind: "stopped";
+    reason: string;
+} | {
+    kind: "log-unreadable";
+    message: string;
+} | {
+    kind: "log-torn-tail";
+    message: string;
+} | {
+    kind: "log-corrupt";
+    message: string;
+} | {
+    kind: "anchor-diverged";
+    message: string;
+} | {
+    kind: "checkpoint-invalid";
+    message: string;
+};
+/**
+ * The daemon.
+ *
+ * One instance owns one working set (a log, a task folder, a queue file) and one
+ * set of timers. {@link run} resolves when the loop stops; {@link stop} is what a
+ * signal handler calls.
+ */
+export declare class Daemon {
+    private readonly options;
+    private readonly watchers;
+    private watchAttempted;
+    private watching;
+    private interval;
+    private debounce;
+    private ticking;
+    private ticks;
+    private drifts;
+    private expiries;
+    private renders;
+    private lastRender;
+    /** Epoch ms of the last advance ATTEMPT, refusals included (APRV-204). */
+    private lastAdvanceAt;
+    private lastAdvance;
+    /** How many substantive records were owed at the last attempt. */
+    private lastAdvanceOwed;
+    /**
+     * Where the owed span ENDED at the last attempt (APRV-233).
+     *
+     * The count trigger measures against this inside the interval, so records an
+     * attempt has already tried to publish are not counted a second time towards
+     * publishing them again.
+     */
+    private lastAdvanceSpanEnd;
+    /**
+     * The advance whose git work is still running in a child (APRV-211).
+     *
+     * One slot, and a tick that finds it taken makes no attempt at all: two
+     * advances against one log would race for the append lock and for the records
+     * branch, and the second would have nothing to publish anyway.
+     */
+    private advanceInFlight;
+    /**
+     * An advance outcome this process observed and could not record (APRV-233).
+     *
+     * The 2026-09-02 residue: a hook's record landed between `recordFinish`'s
+     * read and its append, the bounded retry was spent, and the execution stayed
+     * open. The outcome is a fact this process holds and the log does not, so it
+     * is carried here and settled at the top of the next tick, before any trigger
+     * is looked at. Nothing else may advance while it stands.
+     */
+    private pendingAdvanceFinish;
+    /**
+     * The dangling advance cycles this process has already reported (APRV-264).
+     *
+     * A SET rather than one key: on 2026-09-05 five of them stood at once, and a
+     * single slot meant the operator was told about one, then about the next only
+     * after they had closed the first by hand. Reported once per key — the
+     * started line counts as the report for anything the startup listing found,
+     * so the first tick does not say it a second time — and never once per tick,
+     * because a warning printed every thirty seconds forever stops being read.
+     */
+    private reportedDangling;
+    /** Epoch ms of the last dark-session sweep (APRV-192); `null` before the first. */
+    private lastDarkSweepAt;
+    private reportedEscalations;
+    /** Verified reads made during the current tick (APRV-211). Reset at tick start. */
+    private reads;
+    /** Did any of this tick's own reads hash the whole prefix (APRV-217)? */
+    private fullReproofThisTick;
+    /** This tick's anchor comparison (APRV-219), or `null` when it made none. */
+    private anchorThisTick;
+    /** This tick's checkpoint check (APRV-220), or `null` when it made none. */
+    private checkpointsThisTick;
+    /**
+     * The watcher event that opened the current debounce window (APRV-230), or
+     * `null` when nothing has woken this daemon since the last tick consumed it.
+     * Read once at the top of a tick and cleared there, so a periodic tick that
+     * happens to run first takes the attribution with the work.
+     */
+    private pendingWake;
+    /** Basenames {@link writeBack} placed this tick, so the watcher can ignore them. */
+    private selfWrites;
+    /** The previous tick's, kept one generation: watch events arrive after the write. */
+    private previousSelfWrites;
+    private settle;
+    private finished;
+    /** Whether {@link DaemonOptions.draw} actually bound (APRV-208). */
+    private drawServing;
+    constructor(options: DaemonOptions);
+    /** Run until stopped (or, with `once`, for exactly one tick). */
+    run(): Promise<DaemonOutcome>;
+    /** Stop cleanly: timers cleared, watchers closed, nothing half-written. */
+    stop(reason: string): void;
+    private finish;
+    /**
+     * Attach watchers to the task folder and the log's directory.
+     *
+     * The log's *directory* rather than the log file: an append to a file is
+     * observable either way, but a log that does not exist yet cannot be watched at
+     * all, and a rename (which `writeQueue` and any future rotation perform) leaves
+     * a file watcher pointed at an inode nobody writes to again.
+     *
+     * Failure is a warning, never fatal — see the module header on why the periodic
+     * tick makes watching optional.
+     *
+     * ## Ignoring the daemon's own hand (APRV-211)
+     *
+     * Two of the files in these directories are written by this loop itself: the
+     * verified-head snapshot beside the log (`verified-head.json` and its temp
+     * file, published on every clean read) and the task files {@link writeBack}
+     * repairs. A watcher that fires on those schedules a tick whose only cause was
+     * the previous tick, and the daemon wakes itself forever: measured at 18 ticks
+     * in 45 seconds against a ten-minute interval, with no other writer.
+     *
+     * So the log-directory watcher schedules only for the log file itself (or for
+     * an event that names no file, which is the platform saying "something here
+     * changed" and must still be believed), and the tasks watcher ignores the
+     * basenames this daemon just placed.
+     *
+     * ## Bookkeeping, nobody's hand (APRV-230)
+     *
+     * The self-wake was not the whole of it. Both directories also carry files
+     * that no reader ever reads: the append lockfile every writer in this runtime
+     * creates and removes around each append, and the swap, autosave and backup
+     * files an editor scatters beside a task file. Those are events about how a
+     * change was made, and a tick scheduled for one re-derives an answer nothing
+     * has moved. {@link bookkeepingKind} names them and they are dropped here, in
+     * both directories.
+     *
+     * What is left unattributed on purpose is a platform event that names no file.
+     * That is the platform saying "something in this directory changed" and
+     * declining to say what, and the log itself is one of the things it might
+     * have been; believing it costs a tick and doubting it could cost an append's
+     * latency. {@link DaemonOptions.traceWatch} makes every one of these decisions
+     * visible, which is how the remaining wake sources get counted rather than
+     * guessed at.
+     *
+     * This is safe for exactly the reason stated in the module header: correctness
+     * never depended on the watcher. Every tick re-scans the folder and re-derives
+     * everything from the verified log, and the periodic tick runs regardless
+     * (SPEC.md §10.2). The worst an over-eager filter can cost is latency on a
+     * change that arrives inside the same window as one of the daemon's own
+     * writes, and the next periodic tick collects it.
+     */
+    private attachWatchers;
+    /**
+     * Whether one watcher event schedules a tick, and if not, why not (APRV-230).
+     *
+     * Pure, apart from reading the two sets of basenames this loop's own
+     * write-back placed. `null` means "schedule"; every other answer is a reason
+     * an operator can count.
+     */
+    private classifyWatchEvent;
+    /** Coalesce a burst of watcher events into one tick. */
+    private schedule;
+    /**
+     * One full pass: drift scan, TTL sweep, write-back, escalation surfacing,
+     * queue render.
+     *
+     * Returns `null` to continue, or the outcome that must stop the loop. Every
+     * step re-reads the verified log rather than sharing one snapshot across the
+     * pass, because each append invalidates the head the next one would build on
+     * and because an external writer may have moved the log in between. Reading is
+     * O(n) per call at v0.1 (`core/state.ts` documents the deferral); the head
+     * cache is APRV-43, and correctness comes first.
+     */
+    private tick;
+    /**
+     * Ask git what happened, and the log whether it was told.
+     *
+     * On its own interval rather than every tick: the tick is 30 seconds by
+     * default and a `git log` per worktree at that rate is work spent to re-read
+     * an unchanged answer. The interval is a floor and never a ceiling — a sweep
+     * missed because the daemon was down is simply made by the next one, since
+     * the sweep holds no cursor and re-derives its whole question from the window
+     * it is given.
+     *
+     * The daemon owns the SCHEDULING and nothing else, which is the division the
+     * drift scan, the TTL sweep and the audit sweep already keep.
+     */
+    private sweepDark;
+    /**
+     * Advance the log if the cadence says it is due, or if this is the flush.
+     *
+     * The trigger, in one place: enough SUBSTANTIVE records have accrued
+     * (`afterRecords`), or the interval has elapsed since the last attempt and at
+     * least one substantive record is owed. "Substantive" excludes the advance
+     * cycle's own bookkeeping — see `daemon/advance.ts` on why counting it would
+     * make an idle repository advance forever.
+     *
+     * The last-attempt clock is set for every attempt, successful or not, which
+     * is what keeps a refusal off the hot path: a gate that says no costs one
+     * attempt per interval and no more.
+     *
+     * The flush ignores the interval and the count, and only the interval and the
+     * count: it still asks the gate, and it still does nothing when nothing is
+     * owed.
+     */
+    /**
+     * The advance cycles the started line names, and nothing else (APRV-264).
+     *
+     * Reads and proves; appends nothing. The first tick runs a moment later and
+     * sweeps for real, so anything provable here is closed before an operator has
+     * finished reading the line — which is why the line carries only what is NOT
+     * provable, the part that needs a person. Every key it names is marked
+     * reported, so the sweep that follows does not warn about it again.
+     */
+    private listDanglingAdvancesAtStartup;
+    /** Everything `daemon/advance.ts` needs, built from this daemon's options. */
+    private advanceInputFor;
+    private advanceIfDue;
+    /** Record and report one finished attempt, from either runner. */
+    private reportAdvance;
+    /** The clock this loop reads, as the options every core writer takes it. */
+    private clockOptions;
+    /** The last attempt this process made, for a caller that wants to assert on it. */
+    lastAdvanceAttempt(): AdvanceAttempt | null;
+    /** Is the anchor check on for this run? On unless the operator turned it off. */
+    private anchorEnabled;
+    /** The anchor options this loop passes down, assembled once and identically. */
+    private anchorWhere;
+    /**
+     * Which committed copy this run is anchored against, for the `started` line.
+     *
+     * Resolution only: it asks git which revs carry a copy of the log and which
+     * of them reaches furthest, and compares nothing. The first tick, a line
+     * below the `started` emit, makes the comparison — and always in full, since
+     * a cold walk is a full re-proof by construction.
+     */
+    private resolveAnchorForReport;
+    /**
+     * Compare the verified working records against the committed copy.
+     *
+     * `null` when the check is off. Everything else — including "there is no
+     * committed copy" — comes back as an {@link AnchorCheck} the caller reports,
+     * because a check that could not look must never be read as a check that
+     * looked and was satisfied.
+     */
+    private compareToAnchor;
+    /**
+     * Demand every checkpoint inside the verified records.
+     *
+     * `null` when the check is off. Everything else — including "no key is
+     * configured" — comes back as a {@link CheckpointCheck} the caller reports,
+     * because a check that could not look must never be read as a check that
+     * looked and was satisfied.
+     *
+     * The policy is read here, once per comparison rather than once per run: the
+     * keys are the human's and the human may add one while this loop is running,
+     * and a daemon holding a key list from startup would keep refusing a
+     * checkpoint the operator had already authorized by editing the policy.
+     */
+    private checkCheckpoints;
+    private fatal;
+    /**
+     * The verified log, and — since APRV-188 — the publication of what was
+     * verified.
+     *
+     * The daemon holds a warm {@link VerifiedReadCache} and re-verifies only the
+     * appended tail on every tick. Every hook process, by contrast, starts with an
+     * empty cache and walks the whole chain before it may decide anything. So on
+     * each clean read this loop publishes a verified-head snapshot beside the log:
+     * an endorsement of the exact bytes it just walked, which the next hook
+     * process re-proves for itself (one SHA-256) instead of re-walking. See
+     * `core/verified-snapshot.ts` for what that endorsement claims and what a
+     * reader still checks.
+     *
+     * The publication rides on the read rather than following it, so the bytes
+     * endorsed are the bytes verified: a publisher that re-read the file to hash
+     * it could endorse a digest of bytes nobody walked.
+     */
+    private read;
+    private readOnce;
+    /** The TTL in force right now, re-read every pass: policy files change. */
+    private ttlMs;
+    private gateOptions;
+    /**
+     * Read every task file, compare its claimed `state:` against the log, and
+     * append `envelope.drift` for each file that contradicts it.
+     *
+     * §6.3: "`state` is a projection of log events; the file is updated by the
+     * daemon after the event is appended, never the reverse. A file edit that
+     * contradicts the log is itself logged (`envelope.drift`) and surfaced."
+     *
+     * This scan **only records**. The repair is {@link writeBack}, later in the
+     * same tick: the disagreement is written to the log first and copied into the
+     * file second, in that order, so nothing is ever corrected off the record. A
+     * drift record therefore names a moment, not a standing condition.
+     *
+     * A schema-invalid envelope is warned about and skipped, not logged as drift: a
+     * malformed file is not a *contradiction* of the log, it is a file the runtime
+     * cannot read a claim out of at all, and inventing a `declared_state` for it
+     * would put a fact in the log that nobody wrote.
+     */
+    private scanForDrift;
+    /** Every `*.md` under the task folder, sorted, non-recursive. */
+    private taskFiles;
+    private checkOneFile;
+    /**
+     * A task file with no envelope whose task the log registered: the envelope was
+     * lost (APRV-63, the defense half of APRV-60).
+     *
+     * Recorded as `envelope.drift` with `payload.reason: "envelope-missing"` —
+     * the same event type, because it is the same §6.3 question ("the file and
+     * the log disagree"), and a distinct reason, because the answer is different:
+     * a state mismatch is an edit to reconcile, a missing envelope is a deletion
+     * to restore. `declared_state` is `null` because the file makes no claim at
+     * all, and `envelope_sha256` is absent because there is no envelope to digest.
+     *
+     * **Nothing is repaired.** The registration in the log holds every action the
+     * envelope declared, so a writer *could* re-emit it — and that would turn a
+     * projection into a source, which is the one thing the log's authority rests
+     * on not happening. The daemon reports; a human restores by hand.
+     *
+     * `loose` says the id came from the file name rather than from frontmatter;
+     * it relaxes only the *matching*, and the record is written under the id the
+     * log itself holds.
+     */
+    private reportEnvelopeLoss;
+    /**
+     * Append `approval.expired` for every live request whose TTL has lapsed.
+     *
+     * The sweep changes no verdict. `core/gate.ts` already judges the TTL lazily at
+     * decision time, so a late grant is refused with or without an expiry record;
+     * what the sweep adds is *visibility* — the queue, the index, and anyone
+     * reading the log see a terminal fact rather than a request that looks live and
+     * is not.
+     *
+     * Idempotent three ways over, and none of them is a remembered flag:
+     *
+     * - with lazy expiry, because `expire` refuses `already-decided` for anything a
+     *   human (or the lazy path) already settled;
+     * - with itself, because the candidate list is re-derived from the verified log
+     *   each sweep and an expired request no longer appears in it;
+     * - across restarts, because the daemon carries no state between runs at all.
+     *
+     * A `head-moved` refusal is expected traffic, not a fault: a CLI verb decided
+     * the same request between this candidate list and this append. It is reported
+     * at `debug` weight (a single warning line) and the next tick re-derives.
+     */
+    private sweepTtl;
+    /**
+     * Hand one pass to `daemon/prune.ts` and surface whatever it could not do.
+     *
+     * The daemon adds nothing to the rule: with `payload_retention` absent the
+     * pass is a no-op, and with it present the pruner appends `payload.pruned`
+     * before every unlink and re-derives the whole question from the verified log.
+     * Warnings never stop the loop — a store that could not be pruned is a store
+     * holding more evidence than the policy asked it to, which is the safe side.
+     */
+    private prune;
+    /**
+     * Rewrite every task file whose `state:` disagrees with the log, so the
+     * projection says what the log says.
+     *
+     * §6.3: "`state` is a projection of log events; the file is updated by the
+     * daemon after the event is appended, never the reverse." Both halves are
+     * enforced structurally here. *After the event*: this runs at the end of the
+     * tick, when the drift scan and the TTL sweep have appended everything they
+     * are going to. *Never the reverse*: this method appends nothing at all, reads
+     * the state it writes from `daemon/projection.ts`'s rollup over the verified
+     * log, and produces bytes only through `core/task-file.ts`. A file can no more
+     * teach the log a state than a screenshot can teach a database a row.
+     *
+     * Four rules, each of which is a way of not making things worse:
+     *
+     * 1. **Only files that already have an envelope.** `set-state` refuses
+     *    `no-envelope`, and that refusal is honoured silently: a task with no
+     *    `approval:` key is a plain Backlog.md task (SPEC.md §6 requires tolerating
+     *    it), and a daemon that gave one an envelope would be enrolling a task
+     *    nobody enrolled. The register path is where an envelope comes from.
+     * 2. **No write when the bytes would not change.** The writer reports
+     *    `changed`, and the bytes are compared besides. An unnecessary write moves
+     *    an mtime, which wakes the watcher, which schedules a tick — a loop that
+     *    costs nothing but looks exactly like one that does not terminate.
+     * 3. **A refusal leaves the file alone.** Anything the round-trip writer will
+     *    not do — corrupt YAML, an `approval:` key that is not a mapping, a
+     *    self-check that failed — becomes one `write-back-refused` warning carrying
+     *    the writer's own code. Nothing partial is ever written, because
+     *    `rewriteTaskFile` produces bytes or a refusal and `writeTaskFileAtomic`
+     *    renames a complete temp file into place.
+     * 4. **Silence where the drift scan already spoke.** An unreadable file, a
+     *    frontmatter that does not parse, a missing `id`, a schema-invalid
+     *    envelope: each was warned about a few milliseconds ago by
+     *    {@link scanForDrift} over the same folder. Repeating it here would double
+     *    every line an operator reads without adding a fact.
+     *
+     * Loop safety comes from the comparison, not from a remembered flag: the next
+     * tick derives the same state from the same log, finds the file already
+     * declaring it, and does nothing — no drift, no write, no event. A file that
+     * *keeps* needing repair is being rewritten by something else, and the drift
+     * records are the trail of that fight.
+     */
+    private writeBack;
+    /**
+     * Report tasks that loop safety has escalated to manual, and tasks that have
+     * come back.
+     *
+     * The projection is `core/loop.ts`'s and the enforcement is the gate's and the
+     * executor's; this makes the state *visible* to whoever is watching the daemon,
+     * which is the one thing neither of them does. `approval status` reports the
+     * same set, from the same projection, for an operator who is not.
+     *
+     * Reported on change rather than every tick: a standing escalation restated
+     * every interval is noise that trains an operator to scroll past it.
+     */
+    private surfaceEscalations;
+    /**
+     * Regenerate `QUEUE.md` through the real renderer.
+     *
+     * Never partial: `writeQueue` writes a temp file and renames it, so a reader
+     * sees either the previous queue or the new one and never a half-written file,
+     * and a crashed daemon leaves no torn queue behind.
+     *
+     * The file is rewritten every tick, because TTL countdowns move even when the
+     * log does not. The *event* is emitted only when the summary changes, so a
+     * standing queue does not fill an operator's terminal with identical lines.
+     */
+    private render;
+    private emit;
+    private warn;
+    /** A path as the operator typed it: relative to cwd when it is inside it. */
+    private display;
+}
+/** Does this path exist and is it a directory? Used by the verb's preflight. */
+export declare function isDirectory(path: string): boolean;