@jawache/flow 0.1.0

package/dist/types/adapter/domain.d.ts

@@ -0,0 +1,1112 @@
+import { type BreadcrumbMoment, type EntrySpec, type GuardrailMoment, type LoadResult, type Moment, type Refusal, type SessionFacts, type TurnAction } from "../language/domain.ts";
+import { type Block, type Bound, type Cause, type Metrics, type MomentsView, type Row, type TerrainNode } from "../engine/domain.ts";
+/**
+ * One hook payload, as Claude Code writes it on stdin.
+ *
+ * Deliberately loose, every field optional: it is JSON from another program, so a shape this file
+ * DEMANDS is a shape that breaks the day the host adds a field or omits one. The index signature is
+ * not laziness either — F5's archival side reads keys this phase has no use for, and a payload
+ * narrowed on the way in cannot grow them back.
+ */
+export interface HookPayload {
+    readonly session_id?: string;
+    readonly agent_id?: string;
+    readonly hook_event_name?: string;
+    readonly transcript_path?: string;
+    readonly stop_hook_active?: boolean;
+    readonly tool_name?: string;
+    readonly tool_input?: Record<string, unknown>;
+    /** SessionStart's reason: `startup` · `resume` · `clear` · `compact` — the compaction announcement. */
+    readonly source?: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * The five events flow registers for, named by the EVENT and never by the job.
+ *
+ * Carried from the old engine unchanged, and the naming rule with it: call a hook
+ * `flow hook plan-drift` and the day a second concern wants the same host event you register a
+ * second hook beside the first, which is the duplicate-firing problem the grammar exists to make
+ * impossible. One command per event; a second concern extends the function.
+ */
+/**
+ * The one file that turns anything on, spelled ONCE.
+ *
+ * It lives in the pure home rather than in the shell that opens it because three things name it
+ * and only one of them is a read: the shell looks for it, the CLI defaults to it, and the list of
+ * files that ARE the guard here has to include it. A second spelling in that list would leave a
+ * renamed config's old name watched and its new one not.
+ */
+export declare const CONFIG_FILE = "flow.config.ts";
+/**
+ * Every relative module the config names, READ OUT OF ITS TEXT.
+ *
+ * A regex over source, deliberately, and it is the only reader that can work here: this is asked
+ * about a file that will not import, so anything that had to resolve, parse or evaluate it would
+ * be asking the broken thing to answer for itself. A line like `import { house } from
+ * "./guards/house.ts";` survives almost every way a config breaks, because what breaks a config is
+ * a missing `.message(…)` or a stray brace two hundred lines below its imports.
+ *
+ * Only `./…` and `../…` count. A bare specifier is a package — `@jawache/flow`, or a pack somebody
+ * published — and a package is not this repo's source to repair. A `..` segment climbs out of the
+ * root, so those are dropped too: the config sits at the repo root and the surface is
+ * repo-relative or it is nothing. A leading dot in a FOLDER name is ordinary and is kept —
+ * `./.guard/house.ts` is a pack like any other.
+ *
+ * A `from '…'` phrase inside a QUOTED STRING is harvested as well — a rule whose `.message(…)`
+ * spells an import line puts that path on the surface though no import named it. ACCEPTED, not
+ * overlooked: telling a real import from a sentence quoting one takes a parser, and a parser is
+ * the one thing a file that will not parse cannot give. The cost is bounded and one-directional —
+ * the surface only ever WIDENS, it widens only while the config is already refusing every other
+ * write, and the commit gate goes on refusing until the config loads green.
+ */
+export declare function configImports(configText: string): readonly string[];
+/**
+ * THE CONFIG SURFACE — the files a write may target while the guard is broken, and nothing else.
+ *
+ * Fail-loud says a config that will not load refuses every gated moment, and it is right: a guard
+ * that quietly carries on with yesterday's rules is a guard that lies about being there. But taken
+ * without exception it also refuses the ONE write that can end the outage, and then the doctrine's
+ * own instruction — "adjust the change so it passes, then retry" — is impossible to obey. A human
+ * in an editor never meets this (no hooks sit in front of them, so they just undo); an agent that
+ * broke the config is locked out of repairing it, and the repo stays broken until a human arrives.
+ * Measured twice on the crossing that introduced it, once for real.
+ *
+ * So the exception is exactly as wide as the repair and no wider: a write whose target is the
+ * config or a pack it imports. Everything else still refuses — every other path, every command,
+ * and the commit gate, which goes on refusing until the config loads green, so nothing written
+ * under the exception can reach a commit unreviewed by a working guard.
+ *
+ * DERIVED FROM THE CONFIG'S OWN TEXT, and it used to be a two-line constant: the config file, plus
+ * one repo's pack folder spelled into the engine. Every other repo got a repair exception over a
+ * folder it does not have, and an agent that broke the config there could not reach the pack it
+ * broke. The text is readable when the module is not, so nothing is given up by asking it — and the
+ * answer now follows whatever a repo actually called the folder.
+ *
+ * The FOLDER of each imported pack comes with the file, which is the one deliberate widening. A
+ * repair is rarely one file: a pack imports its own helpers, and those the config never names. The
+ * import graph cannot be walked (walking it means resolving, and resolving is what is broken), so
+ * the folder is the honest approximation — and it is exactly the width the old constant had.
+ */
+export declare function configSurface(configText: string | null): readonly string[];
+export declare const HOOK_EVENTS: readonly ["session-start", "pre-tool-use", "post-tool-use", "stop", "notification"];
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+export declare function isHookEvent(word: string): word is HookEvent;
+/**
+ * WHAT THIS HARNESS CAN HONESTLY SUPPLY — the seventh question, and the one that keeps the seam
+ * from rotting quietly. An adapter never fakes a moment it cannot deliver.
+ *
+ * Two facts are stated here rather than discovered by somebody whose rule never fires:
+ *
+ *   · `commit` is delivered, but not by the harness — git's pre-commit hook calls `flow commit`,
+ *     which is why every harness gets the gates for free and why it is in this list at all.
+ *   · turn-end BRIEFING is not delivered. Stop's decision object carries no context channel, so a
+ *     `breadcrumb().at(turnEnd)` has nowhere to be shown; the guardrail rail at that moment works
+ *     perfectly. Reporting an entry that goes dark is `flow status`'s job (F6).
+ *
+ * It is two lists rather than one because "turn-end" is a word in both vocabularies and the answer
+ * differs between them — a single flat list could only lie about one of them.
+ */
+export declare const DELIVERS: {
+    guard: readonly GuardrailMoment[];
+    brief: readonly BreadcrumbMoment[];
+};
+/**
+ * One event in the engine's vocabulary, minus the two things the engine's own event types demand
+ * and this file cannot know: who the session is (`wearing`, which needs the sidecar and the stored
+ * verdict) and how far it has drifted (`tokens`, which needs the transcript). The shell adds both,
+ * because both come off disk.
+ */
+export type AdapterEvent = {
+    readonly rail: "guard";
+    readonly moment: GuardrailMoment;
+    readonly file?: {
+        readonly path: string;
+        readonly content: string;
+    } | undefined;
+    readonly command?: string | undefined;
+    readonly staged?: readonly string[] | undefined;
+    readonly turn?: readonly TurnAction[] | undefined;
+} | {
+    readonly rail: "brief";
+    readonly moment: BreadcrumbMoment;
+    readonly path?: string | undefined;
+};
+/**
+ * What a payload needs from the world before it can become an event. Injected, never reached for.
+ *
+ * Every answer is a FUNCTION rather than a value, and that is not ceremony: a hook fires on every
+ * tool call, and the turn's actions cost a whole transcript to work out. Asking only when the
+ * moment needs it means the write rail — by far the most frequent — never opens the file at all.
+ */
+export interface EventWorld {
+    /** The repo root. Event paths are repo-relative, because that is how every `on` glob is written. */
+    readonly root: string;
+    /** A file as it stands right now, or null when it is not there — an Edit is a diff against it. */
+    readonly read: (path: string) => string | null;
+    /** What the actor did this turn. Only `stop` asks, so only `stop` pays for it. */
+    readonly turn?: (() => readonly TurnAction[]) | undefined;
+}
+/** An absolute path inside the repo → the repo-relative spelling every glob is written against. */
+export declare function relativise(path: string, root: string): string;
+/** One edit operation, as the Edit tool states it. */
+export interface EditOp {
+    readonly old_string?: string;
+    readonly new_string?: string;
+    readonly replace_all?: boolean;
+}
+/**
+ * Fold one Edit into the text it would produce — the delicate half of the pre-emptive rail.
+ *
+ * The whole capability rests on reconstructing the would-be file EXACTLY as the Edit tool would
+ * write it: get this wrong and the guard judges a file that never existed, which is worse than not
+ * guarding at all. Null when the anchor is not in the base text — the caller must then stand aside
+ * rather than judge a guess.
+ *
+ * Lifted from the old engine with its behaviour intact, including the empty-anchor case:
+ * `old_string: ""` is a Write wearing an Edit's clothes, and the new text is the whole file.
+ */
+export declare function applyEdit(base: string, { old_string, new_string, replace_all }: EditOp): string | null;
+/**
+ * The file as it WOULD be on disk after this tool call, disk untouched — J2.2, and the whole reason
+ * to guard at PreToolUse rather than after the write.
+ *
+ * Write carries the content outright; Edit is a diff against what is there; MultiEdit is a fold of
+ * several, and one unlocatable anchor abandons the whole reconstruction rather than judging a
+ * half-applied file. A tool that names no path is not a write at all.
+ */
+export declare function wouldBeFile(tool: string, input: Record<string, unknown>, world: EventWorld): {
+    path: string;
+    content: string;
+} | null;
+/**
+ * The paths a Bash line would remove — `rm`, `git rm`, and the SOURCE side of `mv` / `git mv`.
+ *
+ * Deletion has no tool of its own: it is a side effect of a shell command, so the delete moment is
+ * assembled here or it does not exist at all. `git mv` was the old engine's blind spot; it is
+ * covered, and quoting is respected, so a commit message mentioning `rm` is not a removal.
+ *
+ * A line that cannot be tokenised yields NOTHING, deliberately: `null` from the tokeniser means "I
+ * cannot tell", and a guard that guesses at a line it could not parse is worse than one that stands
+ * aside. The command rail still sees the raw line either way.
+ */
+export declare function deleteTargets(command: string): string[];
+/**
+ * A payload → every event it carries. ZERO OR MORE, and the plural is not hedging.
+ *
+ * One Bash call is genuinely two moments — the command about to run, and each file an `rm` in it
+ * would remove — and the old engine ran two evaluations off that one hook for exactly this reason.
+ * A signature returning one event would push the second rail back into the shell, where it could
+ * not be tested as a decision.
+ *
+ * An event flow was not asked for answers with an empty list, never with an invented moment.
+ */
+export declare function toEvent(hook: HookEvent, payload: HookPayload, world: EventWorld): AdapterEvent[];
+/** What a post-tool-use call was about, repo-relative: a path, or nothing this rail can steer on. */
+export declare function touchedPath(payload: HookPayload, root: string): string | null;
+/** What the binary prints and exits with. The three IO edges as data, so a test can read them. */
+export interface HookResult {
+    /** stdout — a JSON decision the host reads. Empty means nothing to say. */
+    readonly stdout: string;
+    /** stderr — the refusal, shown to the model on exit 2 and to the human otherwise. */
+    readonly stderr: string;
+    /** 0 allows; 2 blocks. Never anything else — those are the host's two codes. */
+    readonly exitCode: 0 | 2;
+}
+export declare const ALLOW: HookResult;
+/** One refusal, with the rail that made it — the banner is the moment's, not the hook's. */
+export interface Refused {
+    readonly moment: GuardrailMoment;
+    readonly block: Block;
+}
+/** A note with its prose resolved: a `file:` breadcrumb is read by the shell, never here. */
+export interface Shown {
+    readonly entry: string | null;
+    readonly cause: Cause;
+    readonly body: string;
+}
+/** Everything one payload produced, ready to become something the host understands. */
+export interface Answer {
+    readonly refused: readonly Refused[];
+    readonly shown: readonly Shown[];
+}
+/**
+ * Is this event the WRITE that could fix a config that will not load?
+ *
+ * The one exception to fail-loud, and it is deliberately the narrowest shape that works: a write
+ * (or a delete) whose target is the guard's own source. `configSurface` above says why that surface
+ * is read out of the config's own text rather than resolved.
+ *
+ * A COMMAND is never a repair, however plausible it looks. `sed -i` on the config would qualify by
+ * intent and there is no way to tell it from `rm -rf` before it runs — a command rail sees a string,
+ * not a target — so the command rail stays fully closed in the broken state, and the agent's route
+ * back is the edit tools, which name the file they are about to write.
+ *
+ * It lives HERE rather than in the shell beside its caller because it decides and reads nothing.
+ * The coverage gate over this file is what keeps the exception's exact width asserted.
+ */
+export declare function repairs(event: AdapterEvent, surface: readonly string[]): boolean;
+/**
+ * WHAT EVERY RAIL ANSWERS WHILE THE CONFIG WILL NOT LOAD — one decision for both ways it can break.
+ *
+ * A config has two ways of not loading, and they used to get two different answers. One will not
+ * IMPORT — a missing module, a syntax error — which the shell catches as a thrown error. The other
+ * imports fine and the GRAMMAR refuses it: a missing `.message(…)`, an override naming an entry the
+ * pack does not have, a mandatory parameter nobody supplied. Only the first ever reached the repair
+ * exception, because the second was refused a layer deeper inside `guard()` — so the break the
+ * README and the guidebook both tell a reader to make was the one break an agent could not repair
+ * itself out of. To everyone who meets them the two are the same fact, "the guard is entirely off",
+ * and now they are the same answer as well.
+ *
+ * TURN-END IS TOLD, NOT REFUSED. Holding a turn open on a broken config prevents nothing risky —
+ * every write, command and commit is already refused and the commit gate stays shut — while it does
+ * stop the agent handing back to the one person who can fix it. So the fault is reported and the
+ * turn ends.
+ *
+ * THE ENGINE HAS ITS OWN PAIR OF `!load.ok` BRANCHES — `guard()` blocks with the fault, `brief()`
+ * notices it — and they are NOT this rule written twice. They answer a different question: "there
+ * is nothing to run, say so", for the two callers that have no repair to make and no turn to end,
+ * namely `replay` and the commit gate. Deleting them was considered at F3.B3 and measured first:
+ * `flow replay` over a config the grammar refuses reaches `brief()`'s branch and emits the fault
+ * notice, so the branch is live and its deletion would have dropped that notice silently. What IS
+ * shared is the shape — `Outage extends Answer`, so the hook rail's answer and every other answer
+ * are one type rather than two that happen to match.
+ */
+export interface Outage extends Answer {
+    /**
+     * The sentence turn-end is TOLD instead of being refused with, or null when no turn ended here.
+     *
+     * It is not `shown`: the Stop rail has no context channel to inject prose into, which is what
+     * `DELIVERS` already says, so the shell writes this one to stderr and answers 0.
+     */
+    readonly told: string | null;
+}
+export declare function whileBroken(events: readonly AdapterEvent[], surface: readonly string[], message: string): Outage;
+/**
+ * The one code `flow status` answers with.
+ *
+ * THE 1/2 SPLIT IS THE WHOLE POINT of there being two non-zero codes: "your guard caught something
+ * or is not fully wired" and "your guard cannot run at all" are different facts and a setup script,
+ * a hook or a CI step has to tell them apart. Status used to break that itself — a config that would
+ * not IMPORT answered 2 while a config the grammar REFUSED answered 1, which is the same fact under
+ * two codes. A refusal list means the document was refused whole and every rail is off, so it is 2
+ * however it broke; anything else that is not green is 1.
+ */
+export declare function statusCode(answer: Status): 0 | 1 | 2;
+/**
+ * The block of prose a set of notes is injected as.
+ *
+ * The header says `breadcrumb` because that is the mechanism's name everywhere else — in the
+ * config, in the log, in `flow status`. The injected block was the last place the old system spoke
+ * one word to the agent and printed another to the human, and a mechanism you hear one name for and
+ * read another about is one you cannot look up.
+ */
+export declare function briefBlock(shown: readonly Shown[]): string;
+/**
+ * Effects → the three IO edges. The SECOND and THIRD of the seven questions, answered once.
+ *
+ * BLOCKING IS EXIT 2 WITH THE TEXT ON STDERR, at every rail, and that is a deliberate narrowing of
+ * what the old engine did. It had three spellings — a PreToolUse `permissionDecision: "deny"`
+ * object for a write, exit 2 for a command, a `decision: "block"` object at Stop — three shapes for
+ * one answer, each with its own way of being subtly wrong, and only one of them works at every
+ * moment. Exit 2 is the host's documented refusal channel and the model reads stderr on all three
+ * rails, so flow has one refusal and one place to look when it fails to arrive.
+ *
+ * Injection stays the decision object, because there is no other channel for it.
+ */
+export declare function toResult(hook: HookEvent, answer: Answer): HookResult;
+/**
+ * Every refusal as the one thing a refusal is, or null when nothing refused.
+ *
+ * It takes NO hook, and that is the point of it existing beside `toResult`: the commit gate is not
+ * a hook at all — git spawns it — so rendering its refusals through a hook-shaped function meant
+ * naming an event that never happened. The banner comes off the MOMENT, which every rail has,
+ * rather than off the event, which only the harness ones do.
+ */
+export declare function refused(refusals: readonly Refused[]): HookResult | null;
+/** Hand the agent some context and allow — the one shape every steering rail emits. */
+export declare function decision(hook: HookEvent, additionalContext: string): string;
+/**
+ * What the guard says when it could not read its own payload.
+ *
+ * The three outcomes of a read are not one outcome. "There was nothing to guard" is safe and common
+ * — a hand-run, an empty stdin — and silence is the right answer to it. "I could not SEE what I was
+ * guarding" is the old engine's invisible swallow: both were folded into `{}`, so a PreToolUse rail
+ * holding an unreadable payload found no tool call, allowed, and told nobody. The sentence is the
+ * same on every rail; what differs is whether the rail blocks with it, and that is the caller's
+ * decision because it is a fact about what the event is FOR.
+ */
+export declare function faultText(hook: HookEvent, why: "unreadable" | "unparseable", detail: string): string;
+/** One line of a transcript, parsed. `record` is the raw object — this file reads it, nobody else. */
+export interface TranscriptLine {
+    /** The record's `type`: `user`, `assistant`, or whatever else the host writes. */
+    readonly kind: string;
+    readonly record: Record<string, unknown>;
+    /**
+     * 1-based position in the FILE, counting blank and unreadable lines.
+     *
+     * Ground truth about the file rather than narrative, and the reason it is counted here rather
+     * than by a consumer: the facts layer cites a transcript line back to a person, and a number
+     * derived from a filtered list points at the wrong line the moment anything is skipped.
+     */
+    readonly line: number;
+    /** ISO-8601 UTC, exactly as the host wrote it. Null when the line carries none. */
+    readonly ts: string | null;
+}
+/**
+ * Every readable line of a transcript, in order.
+ *
+ * The two questions that can stop early do NOT come through here, and the reason is size: a real
+ * transcript is a couple of megabytes and a hook fires on every tool call, so parsing twenty
+ * thousand records to read one number is a cost paid on every keystroke. They walk the raw lines
+ * from whichever end answers first, through the same `parseLine` — one rule about what a line is,
+ * three ways of arriving at it.
+ */
+export declare function transcriptLines(jsonl: string): TranscriptLine[];
+/** The token counts one `usage` record carries. */
+export interface Usage {
+    readonly input_tokens?: number;
+    readonly cache_read_input_tokens?: number;
+    readonly cache_creation_input_tokens?: number;
+}
+/**
+ * The context size a `usage` record represents — input plus BOTH cache buckets.
+ *
+ * Verified on a real transcript, and the reason the sum is spelled out: `input_tokens` alone is
+ * about nil, because the context lives in `cache_read_input_tokens`. A counter that summed the
+ * obvious field read ~0 forever, which looks exactly like a session that never drifts.
+ */
+export declare function contextTokens(usage: Usage | undefined): number;
+/**
+ * How far this session has drifted, in context tokens — the FOURTH question, and drift's one input.
+ *
+ * The LAST message carrying usage, because that is the current size; an earlier one describes a
+ * context that no longer exists. Unreadable or absent is 0, which the engine reads as "no drift
+ * yet": a note then shows on first touch and not again, which is the harmless direction.
+ */
+export declare function tokensFromTranscript(jsonl: string): number;
+/**
+ * The tools that CHANGE a file — which names count as an edit is harness knowledge, and this is the
+ * one set.
+ *
+ * There were two in the old engine and they had already drifted: the recorder's knew about
+ * `NotebookEdit` and the turn-end rule's did not, so a notebook edit was work for the log and not
+ * work for the rule watching for work. A fact about the host's tool names belongs in one place.
+ */
+export declare const EDIT_TOOLS: ReadonlySet<string>;
+export declare function isInjected(prose: string): boolean;
+/**
+ * What the actor did THIS TURN, in order — the fact a turn-end check is handed.
+ *
+ * The turn starts at the last thing the human typed. That is a real narrowing of the rule this
+ * replaces, which walked the whole file: over one turn the two agree (the check compares the last
+ * edit against the last run), but over a resumed session of forty turns the old one was answering
+ * about work from hours ago while its message said "this turn".
+ *
+ * And what comes back is a NARROW, harness-neutral answer — an ordered list of edits and runs —
+ * rather than the transcript itself. The rule this replaces read `$WORK_TURN_TRANSCRIPT` from the
+ * environment, opened the file and parsed this JSONL inside the check: three reads of the world in
+ * the one place the design forbids them, and it made that rule the only core rule no case could
+ * drive.
+ */
+export declare function turnActions(jsonl: string, root?: string): TurnAction[];
+/**
+ * The brief a session was started with, verbatim — the first thing the human, or the spawning
+ * agent, said.
+ *
+ * It is rung 2 of the settled classification order, and only rung 2: a brief is consulted for
+ * generic spawn buckets and never for a specifically-typed one, because a brief QUOTES — four
+ * verifier briefs in the 335-transcript probe matched builder patterns, since a verifier is briefed
+ * with what the builder claimed to have done. That rule is enforced in the engine's `spawnedAs`;
+ * what this owes is the text, honestly and whole, capped only so a runaway paste cannot become the
+ * thing every classifier scans.
+ */
+export declare function briefHead(jsonl: string, cap?: number): string;
+/**
+ * The branch a worktree has out, from the text of its own `HEAD` — the session marker's key.
+ *
+ * A ref name, or the short sha when HEAD is detached, or null when there is nothing there. It is
+ * read as a FILE rather than asked of `git`, and at this frequency that matters: the marker is
+ * written on every tool call, and a subprocess per keystroke is a cost this answer does not justify.
+ * It is also the only form that answers on an unborn branch, where `git rev-parse HEAD` fails
+ * outright — which is every repo's own first commit.
+ */
+export declare function branchFromHead(head: string): string | null;
+/**
+ * The sidecar beside a subagent's transcript: `…/agent-<id>.jsonl` → `…/agent-<id>.meta.json`.
+ *
+ * The host writes one for every spawn — present 335/335 in the probe — and it is the strongest
+ * evidence in the system precisely because the session did not write it. A session could claim to
+ * be anything, and permissions resting on the claim would rest on a lie.
+ */
+export declare function sidecarPath(transcriptPath: string): string | null;
+/**
+ * Host-written evidence about one session × agent, assembled — the shape a classifier sees.
+ *
+ * The sidecar's absence is itself the evidence for the top-level session: there is no positive
+ * marker for being the parent, only the absence of having been spawned. A sidecar that will not
+ * parse is NOT the same as none — the session was spawned, we simply cannot say as what — so
+ * `subagent` stays true and `agentType` is left undefined, and a category keyed on a specific type
+ * declines rather than the parent category wrongly claiming it.
+ */
+export declare function sessionFactsFrom(args: {
+    readonly payload: HookPayload;
+    readonly transcript: string | null;
+    readonly sidecar: string | null;
+}): SessionFacts;
+/**
+ * A tool call → the row that records it, or null when the payload names no tool at all.
+ *
+ * EVERY call, including the ones no rule watches and no breadcrumb covers. The subject is whatever
+ * the call had — a path (repo-relative, so it matches the globs an entry is written with), a
+ * command line, a search pattern and its scope — and a call with no subject is still recorded by
+ * name, because "the session ran fifty greps here" is a fact about the area.
+ */
+export declare function toolRow(payload: HookPayload, root?: string): Row | null;
+/**
+ * The variables git exports into a hook's environment, which REDIRECT any nested `git` command back
+ * at the parent repo — a `git init` in a temp directory would suddenly write the real index.
+ *
+ * The commit gate runs inside git's pre-commit hook and inherits every one of them, so a check that
+ * shells out (a test suite, a type-checker, dependency-cruiser writing a temp config) would run
+ * inside the in-progress commit unless they are stripped. It was one rule script's own business in
+ * the old engine; it is the adapter's now, because `ctx.exec` is the one door and this is a fact
+ * about the world on the other side of it.
+ */
+export declare const GIT_HOOK_ENV: readonly string[];
+/** The environment a check's command should see: this one, minus git's hook plumbing. */
+export declare function hermeticEnv(env: Readonly<Record<string, string | undefined>>): Record<string, string | undefined>;
+/**
+ * The folder a working directory's transcripts live in.
+ *
+ * Every character that is not a letter or a digit becomes a dash — verified against all 63 folders
+ * on this machine carrying a readable cwd, with zero mismatches, rather than taken from a summary.
+ * A dot is not special: `/Users/x/.work/y` yields a doubled dash, and that doubling is the check
+ * that this is the real rule rather than a hand-written approximation (the old signposts spelling
+ * was `[/.]` and was wrong for an underscore or a space).
+ *
+ * THE RULE IS NOT INVERTIBLE, and that matters more here than anywhere else it is used: a folder
+ * named `…-workbench-workflow-flow` is `workbench.workflow-flow` and `workbench/workflow/flow` and
+ * `workbench_workflow_flow`, all three. Which worktree a transcript belongs to is answered by the
+ * `cwd` field the host writes INSIDE the records — see `cwdOf` — never by reading the name back.
+ */
+export declare function projectFolderName(cwd: string): string;
+/** One transcript file worth reading, and the sidecar beside it. */
+export interface TranscriptRef {
+    /** Relative to the project folder. */
+    readonly path: string;
+    /** The sidecar's path, only when the listing actually held it — never a probe. */
+    readonly meta: string | null;
+    readonly session: string;
+    /** Null for a top-level session; the `agent-…` stem for a subagent. */
+    readonly agent: string | null;
+}
+/**
+ * A flat listing of a project folder, sorted into the transcripts worth reading.
+ *
+ * Two shapes count and nothing else does: `<session>.jsonl` at the top (a conversation somebody
+ * sat in front of) and `<session>/subagents/<agent>.jsonl` (a child it spawned). A worktree holds
+ * several sessions — a chat resumed on another day is a second file — so every one is enumerated
+ * rather than a newest being picked.
+ *
+ * Anything else comes back as IGNORED rather than being silently skipped, because "the folder held
+ * something I did not understand" is a fact a reader should be able to see. A `.meta.json` is the
+ * one exception: it is read through the transcript it belongs to, so naming it would be noise.
+ */
+export declare function classifyStore(paths: readonly string[]): {
+    transcripts: TranscriptRef[];
+    ignored: string[];
+};
+/**
+ * The sidecar the host writes beside every subagent transcript, read.
+ *
+ * `toolUseId` is the field that makes this more than a label: it is the id of the parent's own
+ * `Agent` tool call, so a sidecar and the block that spawned it join exactly. That join is what
+ * lets cost attribution and classification agree about who an actor was — the sidecar says what a
+ * spawn WAS, the parent's block says when it happened and what it was asked for, and neither
+ * alone answers both.
+ */
+export interface SpawnMeta {
+    readonly agentType: string | null;
+    readonly description: string | null;
+    /** The parent's tool_use id. Null on a sidecar written before the field existed. */
+    readonly toolUseId: string | null;
+    /** The model the spawn asked for — an alias like `opus`, never the served model id. */
+    readonly model: string | null;
+    readonly spawnDepth: number | null;
+}
+/** A sidecar's text → what it says. Null when it is absent or will not parse. */
+export declare function spawnMeta(raw: string | null): SpawnMeta | null;
+/** The three things knowable about a conversation without reading what was said in it. */
+export interface TranscriptHead {
+    /**
+     * The working directory it was recorded in — THE ONLY HONEST ANSWER to "which worktree is this".
+     *
+     * `projectFolderName` collapses dots, slashes and underscores into one character, so two
+     * worktrees of one repo — `workbench` and `workbench.workflow-flow` — share a folder name and a
+     * reader that inverted it would attribute one checkout's conversations to the other.
+     */
+    readonly cwd: string | null;
+    readonly branch: string | null;
+    /** When it started, as the host stamped it. */
+    readonly started: string | null;
+}
+/**
+ * A conversation's opening facts, in ONE pass, stopping as soon as all three are known.
+ *
+ * It was three functions and therefore three parses of the same multi-megabyte file, once per
+ * conversation in the store — a cost paid on every `flow facts` run for an answer that is in the
+ * first few records. The file opens with stub records (last-prompt, mode, permission-mode) that
+ * carry no fields at all, so a literal first line is never enough and the walk has to be able to
+ * continue; what it must not do is start over twice.
+ */
+export declare function transcriptHead(jsonl: string): TranscriptHead;
+/** One spawn as the PARENT recorded it: the tool call, joined to the sidecar by its id. */
+export interface Spawn {
+    readonly toolUseId: string;
+    /** What the parent asked for — its own claim, which the sidecar's `agentType` outranks. */
+    readonly asked: string | null;
+    readonly description: string | null;
+    readonly ts: string | null;
+    readonly line: number;
+}
+/**
+ * Every spawn a parent transcript made, by tool_use id — the parent's half of the join.
+ *
+ * It is the WEAKER half and is read as such: what the parent asked for is a claim by the session
+ * being classified, while the sidecar is host-written and unforgeable. The classification order
+ * (engine, `spawnedAs`) reads the sidecar and never this. What this is for is everything the
+ * sidecar cannot say — when the spawn happened, and where in the parent's own transcript to look.
+ */
+export declare function spawnsIn(jsonl: string): Map<string, Spawn>;
+/** Text with terminal colour codes taken out — a recorded command line is full of them. */
+export declare function strip(value: unknown): string;
+/**
+ * ONE definition of "make this printable and short": strip ANSI, collapse whitespace, cut to `n`
+ * — and MARK the cut, because a truncated command with no ellipsis reads as a whole one, and every
+ * surface that shows these strings claims to be showing what really happened.
+ */
+export declare function snip(value: unknown, n?: number): string;
+/** One thing that happened in a conversation, with the line it happened on. */
+export type TranscriptEvent = {
+    readonly line: number;
+    readonly kind: "prompt";
+    readonly text: string;
+} | {
+    readonly line: number;
+    readonly kind: "result";
+    readonly id: string;
+    readonly content: string;
+    readonly failed: boolean;
+} | {
+    readonly line: number;
+    readonly kind: "use";
+    readonly ts: string | null;
+    readonly id: string;
+    readonly name: string;
+    readonly input: Record<string, unknown>;
+    /** The file the call names, repo-relative. Empty when it names none. */
+    readonly path: string;
+};
+/**
+ * A transcript → the narrative events in it: typed prompts, tool calls, and their results.
+ *
+ * The PAIRING is this function's own — a `tool_use` block carries the id its `tool_result` answers
+ * to, and matching them is what turns a flat file into "the agent tried X and got back Y". The
+ * old engine did this over its own `JSON.parse` and its own type switch, beside the corpus reader
+ * doing the same over the same files, so "what is an assistant line" had two answers free to
+ * drift. It reads through `transcriptLines` now, and owns only the pairing.
+ */
+export declare function parseEvents(jsonl: string, root?: string): TranscriptEvent[];
+/** Does this prompt read as the human pushing back? */
+export declare function isCorrection(prose: string): boolean;
+/** The tools a repo's justfile actually drives — what a direct invocation would be bypassing. */
+export declare function recipeTools(justfile: string): string[];
+/** What one Bash line was: the recipes it drove, the tools it went round, and whether it committed. */
+export interface BashClass {
+    readonly recipes: readonly string[];
+    readonly bypasses: readonly string[];
+    readonly commits: boolean;
+}
+/** Read one command line against the repo's own recipe tools. HEURISTIC, like everything below. */
+export declare function classifyBash(command: unknown, tools: readonly string[]): BashClass;
+/** A pointer into a transcript — the shape every heuristic finding takes. */
+export interface Pointer {
+    readonly line: number;
+    readonly text: string;
+    /** Which transcript, once several are merged into one report. */
+    readonly session?: string;
+}
+export interface Bypass extends Pointer {
+    readonly tool: string;
+}
+/** The same file edited over and over — a loop somebody was stuck in. */
+export interface EditLoop {
+    readonly path: string;
+    readonly count: number;
+    readonly from: number;
+    readonly to: number;
+    readonly session?: string;
+}
+/** The same command run again and again — something that would not come right. */
+export interface Retry {
+    readonly command: string;
+    readonly count: number;
+    readonly lines: readonly number[];
+    readonly session?: string;
+}
+export interface Narrative {
+    readonly stats: {
+        readonly edits: number;
+        readonly writes: number;
+        readonly commits: number;
+        readonly recipes: Readonly<Record<string, number>>;
+        readonly bypasses: Readonly<Record<string, number>>;
+    };
+    readonly prompts: readonly Pointer[];
+    readonly corrections: readonly Pointer[];
+    readonly bypassSites: readonly Bypass[];
+    readonly loops: readonly EditLoop[];
+    readonly retries: readonly Retry[];
+    /** Every in-repo file the session touched, with how often. The facts layer scores coverage. */
+    readonly touched: Readonly<Record<string, number>>;
+}
+/**
+ * The narrative reading of one conversation. Everything here is a guess with a citation.
+ *
+ * `tools` is INJECTED — the shell reads the justfile — so the same call is reproducible from a
+ * fixture, which is the same discipline the guard itself is built on.
+ */
+export declare function narrative(events: readonly TranscriptEvent[], tools?: readonly string[]): Narrative;
+/**
+ * Every narrative reading merged into one, each pointer tagged with the transcript it came from.
+ *
+ * The report is ONE aggregate whether it read one conversation or a hundred — the flags only
+ * re-scope which sessions it covers, never its shape — so this is where the per-session readings
+ * stop being chapters and become one list somebody can work down.
+ */
+export declare function mergeNarratives(each: readonly {
+    session: string;
+    read: Narrative;
+}[]): Narrative;
+/**
+ * The HOST's half of the guard: where the hooks that invoke any of it are registered.
+ *
+ * Fixed, because these are the harness's own file names and not a repo's choice — unlike the
+ * repo's half, which is `configSurface` reading the config's imports. The old list spelled the two
+ * halves as one constant, with one repo's pack folder standing in for every repo's.
+ *
+ * THE GUARD PACK KEEPS ITS OWN, WIDER LIST, and the difference is deliberate — this is the one
+ * place that says so, because two lists that look like copies are read as drift until somebody
+ * checks. Two things separate them:
+ *
+ *   · They answer different questions. This list feeds `weakenedAfterBlock`, which reports "a rail
+ *     refused, and then somebody edited the guard" — so it holds only files that can WEAKEN a
+ *     rule the engine enforces. The pack's `editingTheGuardrails` is a nudge before you type, and
+ *     it adds `.claude/skills/**`: a skill is prose an agent reads, so editing one is worth a
+ *     word of caution and is not evidence that a guardrail was loosened. Merged, every skill edit
+ *     after any block would be reported as a possible weakening, and the report earns its keep
+ *     only while every line in it is worth reading.
+ *   · Neither may import the other, and the shared home would be worse than the duplication.
+ *     `flow-packs → flow-adapter` is fenced (a pack must not be able to tell which harness is
+ *     running it) and so is the way back, so a shared constant could only live in the public
+ *     door — which would put one harness's file names into the GRAMMAR every config is written
+ *     in, and that is the coupling the fence exists to prevent.
+ */
+export declare const HOST_SURFACE: readonly string[];
+/** Every file that decides what the guard does here — the config and its packs, plus the host's. */
+export declare function guardPaths(configText: string | null): readonly string[];
+/** Is this one of the files that decides what the guard does? */
+export declare function isGuardPath(path: string, paths: readonly string[]): boolean;
+/** A block, and the guardrail edit that followed it. A POINTER, never an accusation. */
+export interface Weakening {
+    readonly entry: string | null;
+    readonly line: number;
+    readonly path: string;
+    readonly gapSeconds: number;
+}
+/**
+ * A rail refused, and then somebody edited the guard — flagged, with both ends cited.
+ *
+ * The edit may be perfectly legitimate authoring, which is exactly why this reports a POINTER and
+ * lets a person read the two spots. What it cannot do is stay quiet: "the rule blocked me, so I
+ * changed the rule" is the one failure mode a guard cannot catch itself.
+ */
+export declare function weakenedAfterBlock(rows: readonly Row[], events: readonly TranscriptEvent[], paths: readonly string[]): Weakening[];
+/** One transcript, as the selector needs it: enough to order by, and nothing it has to open. */
+export interface Candidate {
+    readonly id: string;
+    readonly bytes: number;
+    readonly mtimeMs: number;
+    /** When the conversation began, as the host stamped it. Preferred over the file's mtime. */
+    readonly started: string | null;
+    readonly branch: string | null;
+}
+export interface SelectOpts {
+    /** Analyse only the first N in order. The rest resurface next time. */
+    readonly limit?: number | null | undefined;
+    /** Ignore the limit. */
+    readonly all?: boolean | undefined;
+    /** Order heaviest-first — wasted effort concentrates in the token-heavy conversations. */
+    readonly largest?: boolean | undefined;
+    /** A date floor, in ms. */
+    readonly since?: number | null | undefined;
+}
+export interface Selection {
+    readonly analyse: readonly Candidate[];
+    readonly excluded: readonly {
+        readonly id: string;
+        readonly reason: "limit" | "since";
+    }[];
+    readonly counts: {
+        readonly backlog: number;
+        readonly analysed: number;
+        readonly excluded: number;
+    };
+}
+/** The backlog, ordered and narrowed — and an honest account of what was left out, and why. */
+export declare function selectSessions(candidates: readonly Candidate[], done: ReadonlySet<string>, opts?: SelectOpts): Selection;
+export interface Health {
+    /** The record cannot be believed at all, and this says why. Nothing below it should be read. */
+    readonly blocked: string | null;
+    /** It can be believed with a caveat, and here they are. */
+    readonly warn: readonly string[];
+}
+export interface HealthArgs {
+    /** Does this repo have a recorded history at all? */
+    readonly armed: boolean;
+    /** Did the sessions being read record anything? */
+    readonly rows: number;
+    /** How many of the conversations being read had a stream of their own. */
+    readonly withRecord: number;
+    readonly analysed: number;
+}
+/** What a reader must know before believing anything under it. */
+export declare function health({ armed, rows, withRecord, analysed }: HealthArgs): Health;
+/**
+ * One spawned actor, as the two host-written records agree on it — THE join, at its consumer.
+ *
+ * The sidecar says what a spawn WAS (`agentType`, unforgeable, written by the host) and the
+ * parent's own `Agent` block says when it happened and what was asked for. Joining them on
+ * `toolUseId` is what lets classification and cost attribution name the same actor: a builder
+ * spawned under a generic bucket is `general-purpose` in the parent's claim and `builder` in the
+ * host's record, and only one of those is evidence.
+ */
+export interface SpawnRecord {
+    /** The conversation that spawned it. */
+    readonly session: string;
+    /** The `agent-…` stem — its own transcript's name. */
+    readonly agent: string;
+    /** The host's answer. Null when the sidecar was absent or would not parse: spawned, as what unknown. */
+    readonly agentType: string | null;
+    readonly description: string | null;
+    readonly model: string | null;
+    /** What the PARENT asked for. Null when the two records could not be joined. */
+    readonly asked: string | null;
+    readonly at: string | null;
+    /** Where in the parent's transcript to look. Null when unjoined. */
+    readonly line: number | null;
+}
+/** One subagent's two records, joined. An unjoinable sidecar still yields what it alone knows. */
+export declare function joinSpawn(args: {
+    readonly session: string;
+    readonly agent: string;
+    readonly meta: SpawnMeta | null;
+    readonly spawns: ReadonlyMap<string, Spawn>;
+}): SpawnRecord;
+/** An area the conversations worked in that no entry's globs reach. */
+export interface Uncovered {
+    readonly path: string;
+    readonly touches: number;
+}
+/**
+ * The files a conversation touched that nothing was watching — coverage read from the TRANSCRIPT.
+ *
+ * It is not a duplicate of the record's own gap list and the difference is the whole point: the
+ * rows can only answer for sessions flow was installed for, and the store holds every conversation
+ * this repo has ever had. A session with no record at all still says where the work went, which is
+ * exactly the reading a repo wants on the day it adopts flow — and the day after, when it wants to
+ * know whether the entries it just bound point anywhere near it.
+ */
+export declare function uncoveredAreas(touched: Readonly<Record<string, number>>, entries: readonly Bound[]): Uncovered[];
+export interface Facts {
+    readonly root: string;
+    readonly store: {
+        readonly dir: string;
+        readonly exists: boolean;
+        readonly ignored: readonly string[];
+    };
+    /** Which conversations this run covers, and which it deliberately deferred. */
+    readonly selection: Selection;
+    readonly coverage: {
+        readonly analysed: number;
+        readonly withRecord: number;
+        readonly narrativeOnly: number;
+    };
+    /** The fail-loud header. Read it before believing anything else here. */
+    readonly health: Health;
+    /**
+     * The numbers, over the repo's WHOLE recorded history — deliberately not narrowed to the
+     * selection. A dead scope and a lead distribution are lifetime questions, and scoping them to
+     * one backlog would make a quiet week look like a retirement case.
+     */
+    readonly metrics: Metrics;
+    readonly moments: MomentsView;
+    readonly terrain: readonly TerrainNode[];
+    /** The heuristic pointers, one list, each row tagged with the conversation it came from. */
+    readonly narrative: Narrative;
+    /** Where the conversations worked that nothing watches — the transcript's own coverage answer. */
+    readonly uncovered: readonly Uncovered[];
+    /** Every actor the read conversations spawned, both host-written records joined. */
+    readonly actors: readonly SpawnRecord[];
+    /** A rail refused, and then somebody edited the guard. A pointer, never an accusation. */
+    readonly weakened: readonly Weakening[];
+    /** How many conversations were marked read, when asked for. Null when not asked. */
+    readonly marked: number | null;
+}
+/**
+ * The reading, as the lines a person reads. The whole of what `flow facts` prints.
+ *
+ * It is here rather than in the CLI shell on this repo's own standing precedent (927ca62, the
+ * guard status report): a report's text is a pile of branches — is it armed, is the history ample,
+ * did anything go quiet, was the guard edited after it refused — and every one of those branches
+ * is a judgement about what a reader most needs to know. In a shell they are untestable, and the
+ * one that matters most is the one that fires least.
+ */
+export declare function formatFacts(facts: Facts): string[];
+/**
+ * The node version flow's config loader needs, and why it is a floor rather than a preference.
+ *
+ * A `flow.config.ts` is TypeScript and is loaded by node's own type stripping — there is no
+ * transpile step and there will not be one, because a guard that compiles its own config is a guard
+ * with a build to go wrong. Stripping is flag-free from node 24 (the Active LTS), so that is the
+ * floor `engines` states and the number this sentence names.
+ */
+export declare const NODE_FLOOR = 24;
+/**
+ * Is this module one of the GUARDED REPO'S OWN TypeScript files — the config, and whatever it
+ * imports — which flow has to evaluate itself?
+ *
+ * Node decides a `.ts` file's module system from the nearest `package.json`: `type: "module"` makes
+ * it ESM, anything else makes it CommonJS, and there is no syntax detection for `.ts` the way there
+ * is for an extensionless-type `.js`. A config is written in `import` statements, so in a repo whose
+ * package.json says `commonjs` — or says nothing, which is what `npm init` writes, and is the
+ * ordinary JS repo — the config flow's own `init` just scaffolded cannot be loaded at all. Measured
+ * at 0.1.0's pre-flight over all four shapes: absent green (no package.json, so node falls back to
+ * syntax detection), `module` green, NO TYPE FIELD red, `commonjs` red. Every suite had missed it
+ * because the harness's throwaway repos carry no package.json.
+ *
+ * So flow loads its own config the way eslint and vitest load theirs: it reads the file, strips the
+ * types and hands node ESM, and the repo's package.json never enters into it. This is the pure half
+ * — WHICH urls that treatment is for — and `loadConsumerTypeScript` in the shell is the doing.
+ *
+ * THREE EXCLUSIONS, each a case that must keep node's own answer:
+ *
+ * · not a `file:` url — an http or data specifier is nothing flow put there.
+ * · `.d.ts` — declarations, which are types all the way down and evaluate to nothing.
+ * · anything under `node_modules` — node REFUSES to strip types there
+ *   (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), on the grounds that a dependency ships built
+ *   files. Stripping them here because a config happened to import one would quietly overrule that,
+ *   for every package in the tree, from a guard. flow's own bundles are `.mjs` and never reach here.
+ */
+export declare function loadsAsStrippedModule(url: string): boolean;
+/**
+ * The one sentence for "this config would not load", and the one place a version floor is named.
+ *
+ * A node too old to strip types fails on the IMPORT, with a syntax error about a colon. That is a
+ * machine fact arriving as a parse error — the least actionable shape a true statement can take —
+ * so it is rewritten here, once, for both readers: the `flow test` verb and the live hook rail,
+ * which would otherwise describe one breakage two ways.
+ */
+export declare function configLoadFault(file: string, message: string, nodeVersion: string): string;
+/** One entry in a settings file's hook array: the command, and what it fires on. */
+export interface Registration {
+    /** The host's own name for the event — `SessionStart`, `PreToolUse`, … */
+    readonly event: string;
+    readonly command: string;
+    /** The host's `matcher`. Absent means every occurrence of the event. */
+    readonly matcher?: string;
+}
+export declare const HOOK_REGISTRATIONS: readonly Registration[];
+/**
+ * Is this registration OURS?
+ *
+ * The rule that says "this is ours" is the rule that would say "this may be removed", so it is
+ * narrow on purpose: the flow binary — by either name it legitimately goes by, with any path in
+ * front — invoking `hook <event>` for an event this build actually answers. A `work hook stop` from
+ * the engine flow replaces is NOT ours; sweeping those is the crossing's job, with that engine's own
+ * recogniser.
+ */
+export declare function ourHookCommand(command: string): boolean;
+/** The events this settings file already calls flow for. What makes init idempotent and status honest. */
+export declare function registeredEvents(settings: unknown): string[];
+/**
+ * A settings file with flow's registrations in it — a NEW object, and only ever added to.
+ *
+ * It is somebody's file and holds far more than us, so nothing is rewritten and nothing is removed:
+ * a registration on our event that belongs to another tool keeps its place and flow stands beside
+ * it. Adding what is already there is skipped, which is the whole of what makes `flow init`
+ * idempotent — a second run has nothing to say.
+ */
+export declare function withRegistrations(settings: unknown): {
+    settings: unknown;
+    added: string[];
+};
+/**
+ * WHERE THE GATE LIVES, spelled once for everyone who names it.
+ *
+ * Four readers say these two paths — the hook `init` writes, the report that names the write, the
+ * fitting `status` checks, and the shell next door that stats the file. Spelled four times, a rename
+ * would leave one reader writing a path another never looks at, and the failure is the silent kind:
+ * a green report over a gate git is not running.
+ */
+export declare const HOOKS_DIR = ".githooks";
+export declare const GATE_PATH = ".githooks/pre-commit";
+/** What arms git, said the way a person types it — the report's line and the fitting's fix. */
+export declare const SET_HOOKS_PATH = "git config core.hooksPath .githooks";
+/**
+ * How to arm a gate flow will not write over, in the ONE wording both readers use.
+ *
+ * `init` says it about the hook it just declined to overwrite; `status` says it about the hook it
+ * found unarmed. The same instruction, at the two moments a person can meet it — and two spellings
+ * of an instruction are two instructions the day one of them is edited.
+ */
+export declare const ADD_THE_GATE_LINE = "add `flow commit $(git diff --cached --name-only)` to it";
+/**
+ * The pre-commit hook, verbatim.
+ *
+ * `flow commit <files…>` rather than a sixth hook, because the commit moment is not delivered by any
+ * harness — git's own hook is what fires it, which is why every harness gets the gates for free. The
+ * staged set is computed here rather than inside flow: it is git's own question, and this file is
+ * already a git hook.
+ */
+export declare const PRE_COMMIT = "#!/bin/sh\n# The flow commit gate. Written by `flow init`; `git config core.hooksPath .githooks` arms it.\n#\n# Every at(commit) guardrail runs over the staged set and a block exits non-zero, which is how git\n# refuses the commit. This is the half of the promise the PreToolUse rail cannot make: it fires for\n# a human's commit, a merge and CI, with no session in the room.\nstaged=$(git diff --cached --name-only --diff-filter=ACMR)\n[ -z \"$staged\" ] && exit 0\n# shellcheck disable=SC2086\nexec flow commit $staged\n";
+/** Does this pre-commit hook call flow? Asked by `init` before writing, and by `status` after. */
+export declare function armsFlow(text: string | null): boolean;
+/** The config file init writes: the demo, or the bare one `--empty` asks for. */
+export declare function scaffold(empty: boolean): string;
+/** What the shell found before anything was written. Every one is a stat, not a judgement. */
+export interface InitFacts {
+    readonly root: string;
+    /** `--empty`: the wiring, with no demo. */
+    readonly empty: boolean;
+    readonly isGit: boolean;
+    readonly hasConfig: boolean;
+    /** The gate as it stands, or null when there is none. */
+    readonly gateText: string | null;
+    readonly hasFlowDir: boolean;
+    /** `git config core.hooksPath` as it stands. */
+    readonly hooksPath: string | null;
+    readonly settingsPath: string;
+    /** The parsed host settings file. */
+    readonly settings: unknown;
+    /**
+     * The settings file is THERE and would not parse.
+     *
+     * Distinct from `settings: null`, which means there is none — and the distinction is the whole
+     * reason this field exists. Both read as "no registrations found", so an init that acted on the
+     * absence would answer an unreadable file by writing a NEW one over it, taking the reader's
+     * permissions, model and every other key with it. Measured at the crossing, against a real
+     * settings.json holding JSONC comments: the write was one branch away.
+     */
+    readonly settingsUnreadable: boolean;
+    /** Does `@jawache/flow` already resolve from this repo? */
+    readonly resolves: boolean;
+    /**
+     * Where the running binary's own package lives — what a link would point at, and NULL when the
+     * walk up never found it. Null rather than an empty string on purpose: an empty string is a path
+     * as far as the shell is concerned, and it would go on to attempt a symlink to nowhere and report
+     * the failure of a step that should never have been planned.
+     */
+    readonly packageRoot: string | null;
+}
+/** One file to write, repo-relative so the report reads the way a person would say it. */
+export interface Write {
+    readonly path: string;
+    readonly body: string;
+    /** Set on the gate, which git will not run unless it is executable. */
+    readonly mode?: number;
+}
+/** Everything `flow init` will do, decided before a byte is written. A null means "already there". */
+export interface InitPlan {
+    readonly config: Write | null;
+    readonly gate: Write | null;
+    /** A pre-commit hook that is somebody else's. Never overwritten — reported, with the line to add. */
+    readonly gateKept: boolean;
+    readonly notGit: boolean;
+    readonly flowDir: boolean;
+    /** The package to link into `node_modules/@jawache/flow`, or null when flow already resolves. */
+    readonly link: string | null;
+    readonly hooksPath: boolean;
+    /** The rewritten settings, or null when they already call flow — or could not be read. */
+    readonly settings: {
+        readonly path: string;
+        readonly value: unknown;
+    } | null;
+    readonly registered: readonly string[];
+    /** The settings file was there and would not parse, so nothing was registered. Said out loud. */
+    readonly settingsUnreadable: string | null;
+}
+/** What init will do to this repo. Pure: every branch reads a fact the shell already gathered. */
+export declare function planInit(facts: InitFacts): InitPlan;
+/**
+ * The report — every write named, and everything NOT done said out loud with what to do instead.
+ *
+ * A setup command that prints "done" is a command nobody can check. Failures are handed in rather
+ * than thrown because a PARTIAL init is the interesting case: the config landed, the settings file
+ * was read-only, and the person needs to know exactly that.
+ */
+export declare function initLines(plan: InitPlan, failures: readonly string[]): string[];
+/** One thing the world around the config has to be, and whether it is. A red line carries its fix. */
+export interface Fitting {
+    readonly id: string;
+    readonly ok: boolean;
+    readonly detail: string;
+}
+/** Everything status was able to read. Gathering it is the shell's job; judging it is not. */
+export interface StatusFacts {
+    readonly root: string;
+    readonly version: string;
+    readonly off: boolean;
+    readonly configPath: string;
+    readonly hasConfig: boolean;
+    /** The load, or null when there is no config to load. */
+    readonly load: LoadResult | null;
+    readonly gateText: string | null;
+    readonly hooksPath: string | null;
+    readonly settingsPath: string;
+    readonly settings: unknown;
+    /** Who last worked in this worktree, from the marker the write rail leaves. Null when nobody has. */
+    readonly session: {
+        readonly id: string;
+        readonly agent: string | null;
+        readonly wearing: readonly string[];
+    } | null;
+}
+/** The whole answer. */
+export interface Status {
+    readonly root: string;
+    readonly version: string;
+    readonly armed: boolean;
+    readonly configPath: string;
+    readonly moments: MomentsView;
+    /** Every category a bound entry names — the vocabulary this repo actually classifies by. */
+    readonly categories: readonly string[];
+    readonly session: StatusFacts["session"];
+    /** Entries bound only at moments this harness cannot deliver. Loaded, counted, and dark. */
+    readonly dark: readonly string[];
+    readonly fittings: readonly Fitting[];
+    readonly refusals: readonly Refusal[];
+    readonly green: boolean;
+}
+/** Does this adapter carry that moment, for that KIND of entry? */
+export declare function delivers(kind: EntrySpec["kind"], moment: Moment): boolean;
+/** The gathered facts, judged. Never throws: a broken config is a red line, not an exception. */
+export declare function status(facts: StatusFacts): Status;
+/**
+ * The whole answer as lines — the headline, what meets you and when, then everything not true yet.
+ *
+ * The branching is here rather than in the CLI shell for the reason every report in this package is:
+ * which headline, whether a moment table is printable at all, when the close goes red — each of
+ * those is a judgement about what a reader most needs to know, and in a shell not one has a test.
+ */
+export declare function statusLines(s: Status): string[];