@jawache/flow 0.1.2 → 0.3.0

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

@@ -1,5 +1,5 @@
-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";
+import { type BreadcrumbMoment, type Ctx, type EntrySpec, type LoadedEntry, type ExecResult, type GuardrailMoment, type LoadResult, type Moment, type Refusal, type SessionFacts, type ShellCommand, type ShellStep, type TurnAction } from "../language/domain.ts";
+import { type AgentOf, 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.
  *
@@ -10,7 +10,13 @@ import { type Block, type Bound, type Cause, type Metrics, type MomentsView, typ
  */
 export interface HookPayload {
     readonly session_id?: string;
+    /** Present on every call a SUBAGENT makes, and only then: the host's id for that one spawn. */
     readonly agent_id?: string;
+    /**
+     * The agent type the host started this subagent as, sent beside `agent_id` on its every call.
+     * Host-written: the session cannot change the message, which is why a category may key on it.
+     */
+    readonly agent_type?: string;
     readonly hook_event_name?: string;
     readonly transcript_path?: string;
     readonly stop_hook_active?: boolean;
@@ -18,10 +24,22 @@ export interface HookPayload {
     readonly tool_input?: Record<string, unknown>;
     /** SessionStart's reason: `startup` · `resume` · `clear` · `compact` — the compaction announcement. */
     readonly source?: string;
+    /**
+     * The host's id for one tool call, the same on its PreToolUse and its PostToolUse. It is the key
+     * the snapshot taken before the call is filed under and looked up by after it.
+     */
+    readonly tool_use_id?: string;
+    /**
+     * The permission mode the session runs under (`default` · `acceptEdits` · `plan` · `auto` · …),
+     * as the host states it on every call. Recorded and reported; never a category key.
+     */
+    readonly permission_mode?: string;
+    /** What the tool answered, on the after-call rails. Read for the host's own changed-file list. */
+    readonly tool_response?: unknown;
     readonly [key: string]: unknown;
 }
 /**
- * The five events flow registers for, named by the EVENT and never by the job.
+ * The events flow answers, 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
@@ -41,54 +59,25 @@ 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
+ * about a file that may 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.
+ * published — and a package is not this repo's source. A `..` segment climbs out of the root, so
+ * those are dropped too: the config sits at the repo root and `guardPaths` 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
+ * spells an import line puts that path among the guard's files 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.
+ * the list only ever WIDENS, so the worst it does is report one extra path as a guard file.
  */
 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 declare const HOOK_EVENTS: readonly ["session-start", "pre-tool-use", "post-tool-use", "post-tool-use-failure", "stop", "subagent-stop", "notification"];
 export type HookEvent = (typeof HOOK_EVENTS)[number];
 export declare function isHookEvent(word: string): word is HookEvent;
 /**
@@ -97,38 +86,56 @@ export declare function isHookEvent(word: string): word is HookEvent;
  *
  * 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).
+ *   · `commit` is delivered, but not by the harness — git's pre-commit hook calls `flow hook
+ *     commit`, which is why every harness gets the gates for free and why it is in this list at all.
+ *   · turn-end BRIEFING is delivered, on the `Stop` and `SubagentStop` answers'
+ *     `additionalContext`: the host labels it hook feedback rather than an error, and the agent
+ *     takes one more turn to read it. A refusal at the same hand-back carries the note beside it
+ *     (`toResult`), so the agent is held and told at once rather than held, then told on the next.
  *   · command BRIEFING is delivered, on the same PreToolUse answer the command guardrails use: when
  *     nothing blocks, the hook's `additionalContext` carries the note, and when something does, the
- *     refusal wins — which is the right order, since a blocked command is not about to run.
+ *     refusal wins — which is the right order, since a blocked command is not about to run. The
+ *     files a Bash command reads ride that same answer as touches (`bashReads`), so an area's note
+ *     arrives before the output does.
  *
- * 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.
+ * It is two lists rather than one because a moment is delivered for a KIND of entry: `command` and
+ * `turn-end` are words in both vocabularies, and another harness may carry one rail there and not
+ * the other — a single flat list could only lie about one of them.
  */
 export declare const DELIVERS: {
     guard: readonly GuardrailMoment[];
     brief: readonly BreadcrumbMoment[];
 };
+/**
+ * Does a note at this moment ride a refusal, rather than wait for the call that runs?
+ *
+ * Before a call, a refusal means the call never runs, so a note about it is held back until the
+ * retry that does — and is not marked shown, or it would stay silent until drift. A held turn is
+ * different: the agent is about to act on the refusal anyway, and the note is about that same
+ * turn, so both go to it together.
+ */
+export declare function ridesRefusal(moment: BreadcrumbMoment): boolean;
 /**
  * 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
+ * and this file cannot know: who the session is (`wearing`, which needs the transcript 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 file?: Ctx["file"];
     readonly command?: string | undefined;
+    /** command: the line's parse, made once here and handed to the engine with the line. */
+    readonly commands?: Ctx["commands"];
     readonly staged?: readonly string[] | undefined;
     readonly turn?: readonly TurnAction[] | undefined;
+    /**
+     * The change has already LANDED: the file came out of the delta after the call, not out of a
+     * tool's input before it. A refusal of an observed write is undone from the snapshot, and it
+     * is refused under its own banner.
+     */
+    readonly observed?: boolean | undefined;
 } | {
     readonly rail: "brief";
     readonly moment: BreadcrumbMoment;
@@ -147,8 +154,21 @@ export interface EventWorld {
     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. */
+    /** What the actor did this turn. Only the two turn-end rails ask, so only they pay for it. */
     readonly turn?: (() => readonly TurnAction[]) | undefined;
+    /**
+     * The agent the SESSION itself runs as (`--agent`, or the `agent` setting), or null when it runs
+     * as none. Only `subagent-stop` asks, and only of a payload that names an agent type, because it
+     * costs the parent's transcript: it is how an internal agent's hand-back is told from a subagent's.
+     */
+    readonly sessionAgent?: (() => string | null) | undefined;
+    /** The home directory, for a Bash read through `~`. Absent, such a path is simply not named. */
+    readonly home?: string | undefined;
+    /**
+     * What the call changed in the tree, from the snapshot taken before it. Only the after-call
+     * rails carry it; absent, the call changed nothing flow could see.
+     */
+    readonly changes?: readonly Change[] | 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;
@@ -183,30 +203,211 @@ export declare function wouldBeFile(tool: string, input: Record<string, unknown>
     content: string;
 } | null;
 /**
- * The paths a Bash line would remove — `rm`, `git rm`, and the SOURCE side of `mv` / `git mv`.
+ * The paths a Bash line would remove — `rm`, `git rm`, and the SOURCE side of `mv` / `git mv` —
+ * read from those commands' arguments in the parse.
  *
  * 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.
+ * assembled here or it does not exist at all. The parse decides what is a command, so a commit
+ * message mentioning `rm`, a heredoc body that names a file, or an `echo 'rm a.ts'` is not a
+ * removal, while an `rm` inside a `$( … )` or a `bash -c` string, which runs, is.
  *
- * 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.
+ * A line that does not parse yields NOTHING, deliberately: the parse's `null` 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(commands: readonly ShellCommand[] | null): string[];
+/** Where a Bash call ran, and the two directories its paths are judged against. */
+export interface BashWhere {
+    /** The shell's working directory when the call started. */
+    readonly cwd: string;
+    /** The repo root. Paths outside it are not an area of this repo and are dropped. */
+    readonly root: string;
+    /** What `~` and `$HOME` mean; absent, a path through them is not known. */
+    readonly home?: string | undefined;
+}
+/** What a Bash command reads in the repo, repo-relative, in order, each once. */
+export interface BashReads {
+    /** Files it reads by name — `cat`, `head`, `sed -n`, `grep` on a file, a `<` redirect. */
+    readonly reads: readonly string[];
+    /**
+     * Paths a search walks or lists — `rg`, `find`, `ls`, `grep -r`, a `git` pathspec — which may be
+     * directories. They touch an area; they are not a file the session read.
+     */
+    readonly searched: readonly string[];
+}
+/**
+ * The repo paths a Bash command reads or searches — the `READERS` table, a `<` redirect, a `git`
+ * pathspec — read from the parse's steps, and followed through `cd`, `VAR=`, `for` loops and the
+ * commands a `$(…)` runs. The repo root itself is not an area and is left out. Best-effort, failing
+ * open: see the section head. A line that does not parse names nothing.
  */
-export declare function deleteTargets(command: string): string[];
+export declare function bashReads(steps: readonly ShellStep[] | null, where: BashWhere): BashReads;
 /**
  * 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.
+ * One Bash call is genuinely several moments — the command about to run, each file an `rm` in it
+ * would remove, and each file it reads — 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[];
+/**
+ * Does this hook have nothing to run for this config — so the shell can answer before it reads a
+ * thing?
+ *
+ * A subagent's hand-back costs the parent's transcript (whose agent the session runs as) and the
+ * subagent's own (its turn), and it comes at every hand-back of every subagent. A config that binds
+ * no entry at turn-end, guardrail or breadcrumb, has nothing either read could feed, so neither is
+ * made. A disabled entry binds nothing.
+ *
+ * A repo that is RECORDING never answers early: the tape is for replaying a session against rules
+ * written later, so it keeps every hand-back whatever is bound today.
+ */
+export declare function nothingBound(hook: HookEvent, entries: readonly LoadedEntry[], recording: boolean): boolean;
 /** 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;
+/**
+ * One path a call changed. `before` is null for a file the call created, `after` for one it
+ * removed; a path with both is a file it changed.
+ */
+export interface Change {
+    readonly path: string;
+    readonly before: string | null;
+    readonly after: string | null;
+}
+/**
+ * What the shell could see of one call — the changes, or why it could not see them.
+ *
+ * A FAULT IS NOT AN EMPTY DELTA, and the difference is the guard's whole doctrine: "I looked and
+ * nothing changed" and "I could not look" must never be spelled the same way, or a snapshot that
+ * failed would let every write through as clean.
+ */
+export type Delta = {
+    readonly ok: true;
+    readonly changes: readonly Change[];
+} | {
+    readonly ok: false;
+    readonly fault: string;
+};
+/**
+ * Where git should look for the ignored paths `snapshotInclude` names: each glob's literal head,
+ * so git walks `config/` for `config/*.local.json` and not the whole repo. A glob with no literal
+ * head (`**` + `/.env`) has to be looked for everywhere.
+ */
+export declare function snapshotPathspecs(include: readonly string[]): string[];
+/** Of the ignored paths git listed under those heads, the ones a `snapshotInclude` glob matches. */
+export declare function included(listed: readonly string[], include: readonly string[]): string[];
+/**
+ * Of the paths a call changed, the ones the AGENT changed. The rest are git's — a checkout, a reset
+ * or a fast-forward put them there, from a commit the repo already had, and the commit gate judged
+ * that content when it was committed — so they leave the diff before anything reads them: no rule,
+ * no write-back, no breadcrumb, no shell-write row. CONTENT, never the command line: git run by a
+ * recipe is caught the same way, and the `sed` in `git switch x && sed -i … f` is still judged.
+ *
+ * - A file on disk after the call is git's when it is identical to its copy in HEAD after the call.
+ * - A file the call removed is git's when HEAD held it BEFORE the call and does not hold it after:
+ *   git removed it by moving HEAD. A file no commit holds — an untracked file, an included `.env` —
+ *   is the agent's to answer for when it goes.
+ *
+ * `nameStatus` is the call's own diff, `git diff-tree -r -z --name-status --no-renames`, in git's
+ * order. `differsAfter` and `differsBefore` are every path where HEAD's tree after the call, and
+ * before it, disagree with the tree after the call. `differsAfter` is null when HEAD after the call
+ * is no commit the repo had before it — none yet, or one the call made, whose content no gate is
+ * known to have judged — and then nothing is git's. `differsBefore` is null where there was no HEAD
+ * before; for a path gone from disk, being in it is exactly "HEAD held it before".
+ */
+export declare function authored(nameStatus: string, differsAfter: readonly string[] | null, differsBefore: readonly string[] | null): string[];
+/**
+ * Git's answer as paths, one per line — the plainest shape git has, and the only one flow parses.
+ *
+ * ONE reader for it in the adapter: `flow status` asks git what it ignores and the realWorld asks
+ * for the staged set, and both used to split, trim and drop blank lines under two names. `null` is
+ * a command that never ran, and it is no paths.
+ */
+export declare function pathLines(stdout: string | null): string[];
+/**
+ * What a commit changes, in the shape the commit gate judges: the files it will hold, which of
+ * those the last commit does not have, and the files it removes. A rename is a removal of the old
+ * path plus an add of the new one, so it needs no shape of its own.
+ */
+export interface StagedChanges {
+    /** Every path the commit will hold that it changes — the subjects of a file rule. */
+    readonly files: readonly string[];
+    /** The `files` the last commit does not have. Undefined when git could not say. */
+    readonly added: readonly string[] | undefined;
+    /** The paths the last commit has and this one will not. */
+    readonly deleted: readonly string[];
+}
+/** NUL-separated paths, as git prints them under `-z` — no quoting, so a path is a path. */
+export declare function nulPaths(stdout: string): string[];
+/**
+ * The staged changes, read from `git diff --cached --name-status --no-renames -z`.
+ *
+ * ONE question to git, and every staged change comes back with what it is: `A` added, `D` deleted,
+ * anything else changed in place. `--no-renames` splits a rename into the delete and the add it is.
+ */
+export declare function stagedChanges(nameStatus: string): StagedChanges;
+/**
+ * The whole tree as one commit — `flow hook commit --all` — against the last commit's own list.
+ *
+ * `present` is every file git can see that is on disk; `tree` is `git ls-tree -r --name-only -z
+ * HEAD`. It fails in two ways that answer differently. Before the first commit there is no HEAD, so
+ * every file is new and nothing is removed. Any other failure is unknown: `added` stays undefined,
+ * so a check asks the disk and refuses rather than allows.
+ */
+export declare function treeChanges(present: readonly string[], tree: ExecResult, hasHead: () => boolean): StagedChanges;
+/** The key one call's snapshot is filed under — the host's `tool_use_id` — or null when it sent none. */
+export declare function callKey(payload: HookPayload): string | null;
+/**
+ * The paths the PreToolUse rail already judged for this call, repo-relative, BY RAIL.
+ *
+ * An Edit, a Write or a MultiEdit was judged as a write, on the file it would produce; an `rm` or
+ * an `mv` source was judged as a delete, on the file it was about to remove. Both were allowed there
+ * or the call would not have run, and judging them again after it would log every such decision
+ * twice. The rail matters: a path judged only as a delete says nothing about content written to it
+ * afterwards in the same call.
+ */
+export declare function preJudged(payload: HookPayload, root: string): {
+    readonly writes: string[];
+    readonly deletes: string[];
+};
+/**
+ * One tool call as flow's own log holds it: who made it, when its snapshot was taken, and when its
+ * diff was, once it has been. A record with no `done` is a call still in flight.
+ */
+export interface CallRecord {
+    /** The host's `tool_use_id`. */
+    readonly key: string;
+    readonly session: string;
+    readonly agent: string;
+    readonly tool: string;
+    /** When the snapshot before the call was taken, in epoch milliseconds. */
+    readonly at: number;
+    /** When the diff after it was taken. Absent while the call is in flight. */
+    readonly done?: number | undefined;
+}
+/** A call record read back off disk, or null when the file is not one. */
+export declare function callRecord(key: string, raw: unknown): CallRecord | null;
+/**
+ * The calls of OTHER actors that overlapped this one in time: started before this diff, and
+ * finished after this snapshot or not finished at all.
+ *
+ * A call that finished inside this one's window counts as well as one still in flight: its write
+ * landed between this snapshot and this diff just the same. Calls of the same session and agent
+ * never count — the host does not run an agent's writing calls side by side.
+ */
+export declare function overlapping(me: CallRecord, log: readonly CallRecord[]): CallRecord[];
+/**
+ * The finished calls the log can forget: no call still in flight started before one finished, so no
+ * diff still to come can overlap it. Keeping every record for a day would make every diff read a
+ * day of records.
+ */
+export declare function forgettable(log: readonly CallRecord[]): string[];
+/** How a call is named in a message: the tool, the host's id, and whose it was. */
+export declare function callName(call: CallRecord): string;
 /** 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. */
@@ -221,7 +422,61 @@ export declare const ALLOW: HookResult;
 export interface Refused {
     readonly moment: GuardrailMoment;
     readonly block: Block;
+    /** The path of a change that had already landed when this refused it — the one to put back. */
+    readonly observed?: string | undefined;
+}
+/**
+ * What putting refused changes back came to — written by the shell, which did the writing.
+ *
+ * `failed` is the loud half: a file flow could not write back still holds what the call wrote, and
+ * the message must say so rather than claim a revert that did not happen.
+ */
+export interface Undone {
+    /** The changes written back to what they were before the call. */
+    readonly restored: readonly Change[];
+    /** Paths the call changed that no rule refused — left as the call wrote them. */
+    readonly kept: readonly string[];
+    readonly failed: readonly {
+        readonly path: string;
+        readonly why: string;
+    }[];
+    /** What the refusal was allowed to undo — what the message explains when it was not everything. */
+    readonly scope?: RevertScope | undefined;
 }
+/** Which of a call's changes are put back, and which stay as the call left them. */
+export interface Reversal {
+    readonly revert: readonly Change[];
+    readonly kept: readonly string[];
+}
+/**
+ * What a refusal is allowed to undo, beside the refusals themselves: the repo's `revert` setting,
+ * and the other calls that overlapped this one.
+ *
+ * A command started in the background gets nothing here, by ruling: what it writes after its call
+ * returns lands in some later call's diff and is judged and put back there like anything else.
+ * The harness runs no hook when the process ends, so any mark saying "not this call's" would have
+ * to outlive the process by a guess — and a guess that let `sleep 1` buy one unreverted write.
+ */
+export interface RevertScope {
+    /** The config's `revert` setting: the refused files alone, or every file the call changed. */
+    readonly revert: "refused" | "all";
+    /** Other actors' calls that overlapped this one. Any of them, and `"all"` is not honoured. */
+    readonly overlap: readonly CallRecord[];
+}
+/** The default scope: the refused files, and no overlap. */
+export declare const REFUSED_ONLY: RevertScope;
+/**
+ * THE REVERT SCOPE: the files a rule refused, or every file the call changed when the repo asked
+ * for that, and never more than the refused files while another actor's call overlapped this one
+ * — a diff taken then can hold that call's writes, and "all" would put back work that was not this
+ * call's to lose.
+ *
+ * Most writing calls touch one file, and the other files a multi-file command wrote are not wrong
+ * because one of them is — they are listed as kept, so the agent knows they stand. A refusal that
+ * names no landed path (a fault on a pre-emptive rail) reverts nothing: a revert is only ever of a
+ * change flow saw land, never a guess.
+ */
+export declare function reversal(changes: readonly Change[], refusals: readonly Refused[], scope?: RevertScope): Reversal;
 /** A note with its prose resolved: a `file:` breadcrumb is read by the shell, never here. */
 export interface Shown {
     readonly entry: string | null;
@@ -232,59 +487,60 @@ export interface Shown {
 export interface Answer {
     readonly refused: readonly Refused[];
     readonly shown: readonly Shown[];
+    /** What was put back, when a refusal was of changes that had already landed. */
+    readonly undone?: Undone | undefined;
 }
 /**
- * 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.
+ * What the agent is told beside the load error, on every answer it rides: what that error means.
  *
- * 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.
+ * The load error says what broke; this says what flow is doing about it. Without it, a call that
+ * went through reads like a guard that judged it and passed.
  */
-export declare function repairs(event: AdapterEvent, surface: readonly string[]): boolean;
+export declare const FLOW_OFF = "flow is OFF until flow.config.ts loads: every write, delete and command goes through unchecked, and every commit is refused.";
 /**
  * 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.
+ * A config has two ways of not loading. 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. To everyone who meets them the two are the same fact, "the guard is entirely
+ * off", so they get the same answer.
+ *
+ * NOTHING IS REFUSED HERE (docs/user/explanation/fail-loud.md). A guard that refused every call
+ * would refuse the repair too — the fix for a missing package is `npm ci`, a command — and a write
+ * made now reaches the commit gate anyway, which stays shut until the config loads and then checks
+ * the staged files against every guardrail. The cost is the guardrails on commands, which nothing
+ * later can check; the agent is told on every call that they are off.
+ *
+ * TOLD BEFORE THE CALL, ONCE. The load error rides the answer to a session start and to every
+ * write, delete or command about to run — one notice per answer, however many events the payload
+ * carried. A touch never carries it, on either rail: a Read is not told, and a Bash call is told by
+ * its command, not by the files it reads. So the after-call rail, whose events are observed changes
+ * and touches, stays silent: the agent was told when the call was asked for, and saying it again
+ * with the result is the same sentence twice.
+ *
+ * TURN-END IS TOLD, NOT REFUSED. Holding a turn open on a broken config prevents nothing — 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. Not as a note either: a turn-end note keeps the
+ * agent working for one more turn, which is the same hold by a softer name.
  *
  * 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.
+ * is nothing to run, say so", for the two callers that have no call to let through and no turn to
+ * end, namely `replay` and the commit gate. `flow replay` over a config the grammar refuses reaches
+ * `brief()`'s branch and emits the fault notice, so that branch is live. What IS shared is the
+ * shape — `Outage extends Answer`, so the hook rail's answer and every other answer are one type.
  */
 export interface Outage extends Answer {
     /**
-     * The sentence turn-end is TOLD instead of being refused with, or null when no turn ended here.
+     * The sentence turn-end is TOLD 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.
+     * It is not `shown`: a note at turn-end keeps the agent working for one more turn, and this
+     * sentence is for the human the turn hands back to, so the shell writes it to stderr and answers 0.
      */
     readonly told: string | null;
 }
-export declare function whileBroken(events: readonly AdapterEvent[], surface: readonly string[], message: string): Outage;
+export declare function whileBroken(events: readonly AdapterEvent[], message: string): Outage;
 /**
  * The one code `flow status` answers with.
  *
@@ -315,7 +571,11 @@ export declare function briefBlock(shown: readonly Shown[]): string;
  * 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.
+ * Injection stays the decision object, because there is no other channel for it — with one
+ * exception. Notes beside a refusal go on stderr after it: the host reads that stderr as the
+ * agent's next instruction, and its hooks reference says no JSON field on stdout can override an
+ * exit 2, so stderr is the one place both are sure to arrive. Only a held turn has any: before a
+ * call, the shell judges no notes once something refused (`ridesRefusal`).
  */
 export declare function toResult(hook: HookEvent, answer: Answer): HookResult;
 /**
@@ -326,20 +586,43 @@ export declare function toResult(hook: HookEvent, answer: Answer): HookResult;
  * 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;
+export declare function refused(refusals: readonly Refused[], undone?: Undone): HookResult | null;
+/**
+ * What the after-call rail says when it could not see what the call changed.
+ *
+ * FAIL LOUD, NEVER FAIL CLEAN. A snapshot that could not be taken, or a diff that could not be
+ * read, is not an empty delta: the call is not waved through as having changed nothing, and nothing
+ * is put back on a guess. Exit 2 on this rail cannot block — the call has run — so it is a report,
+ * and it goes where the model reads the tool's result.
+ */
+export declare function deltaFault(fault: string): HookResult;
 /** Hand the agent some context and allow — the one shape every steering rail emits. */
 export declare function decision(hook: HookEvent, additionalContext: string): string;
+/** The rails that run once a tool call has landed: their exit 2 reports, it cannot block. */
+export declare const AFTER_CALL: ReadonlySet<HookEvent>;
 /**
- * What the guard says when it could not read its own payload.
+ * The answer a rail gives when it could not read its payload — and which rails must be LOUD.
  *
  * 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.
+ * holding an unreadable payload found no tool call, allowed, and told nobody. So every rail says one
+ * fault line, and it keeps READ apart from PARSE: a payload that never arrived and one that arrived
+ * and was not JSON are different faults. The line names the hook and the cause, never "the guard",
+ * because on an after-call rail the call has already run and must not read as refused (#12).
+ *
+ * The three rails that judge a tool call answer exit 2: PreToolUse, where it refuses the call it
+ * could not see, and the two after-call rails, where every change the call made is judged — there
+ * exit 2 blocks nothing (the call has run) and puts the line in front of the model beside the
+ * result, so a call whose changes went unjudged is never passed as clean. The rest only add a
+ * breadcrumb or end a turn, and say it on stderr with exit 0.
+ *
+ * PreToolUse and the annotating rails print the line bare; an after-call rail wraps it in
+ * `deltaFault`, the one message for "flow could not see what this call changed", because the host
+ * labels its exit 2 a "blocking error" and the bare line read as a refusal of a call that had
+ * already landed (#12).
  */
-export declare function faultText(hook: HookEvent, why: "unreadable" | "unparseable", detail: string): string;
+export declare function readFault(hook: HookEvent, why: "unreadable" | "unparseable", detail: string): HookResult;
 /** 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. */
@@ -435,28 +718,31 @@ export declare function briefHead(jsonl: string, cap?: number): string;
  * 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.
+ * The payload's `agent_id` is what makes a call a subagent's, whether or not any file exists for
+ * it, and its `agent_type` is the type that subagent was started as. Both are in the message the
+ * host writes, which the session cannot change. A subagent whose message carries no type is
+ * spawned as something unknown: `subagent` stays true and `agentType` is left undefined, so a
+ * category keyed on a specific type declines rather than the parent category wrongly claiming it.
+ * The parent is recognised by ABSENCE — there is no positive marker for being the top-level
+ * session, only the absence of having been spawned.
+ *
+ * `transcript` is this agent's own transcript, a subagent's included, and its head is the brief.
  */
 export declare function sessionFactsFrom(args: {
     readonly payload: HookPayload;
     readonly transcript: string | null;
-    readonly sidecar: string | null;
 }): SessionFacts;
+/**
+ * Which agent one hook message came from — the one reading of it, for its state, its classification
+ * and its log rows alike.
+ *
+ * The type is read only beside an `agent_id`: the host also sends `agent_type` on a top-level
+ * session started with `--agent`, and that session is still the parent.
+ */
+export declare function agentOf(payload: HookPayload): AgentOf;
 /**
  * A tool call → the row that records it, or null when the payload names no tool at all.
  *
@@ -466,6 +752,36 @@ export declare function sessionFactsFrom(args: {
  * 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 files a Bash call reads by name, one `read` row each — written beside its tool row, so the
+ * record counts a `cat` of a file as a touch of it the way it counts a Read.
+ *
+ * Files only. A directory a search walks is an area, not a file anybody read, and counted as one it
+ * would name a folder as a node of the tree the rows are drawn into.
+ */
+export declare function shellReadRows(payload: HookPayload, root: string, home?: string): Row[];
+/**
+ * The files one call changed that its own tool row does not already say, one `write` row each —
+ * what a heredoc, a `sed -i`, a script or a recipe wrote, and what an Edit's call changed besides
+ * the file it named.
+ *
+ * A SPAWN writes none of its own. The Agent call's diff holds everything its subagent wrote through
+ * calls that are logged under their own rows, and counted again here every edit a builder made would
+ * be in the record twice.
+ */
+export declare function writeRows(payload: HookPayload, changes: readonly Change[], root: string): Row[];
+/**
+ * Claude Code's own list of the files a command changed, where the host sent one, set against
+ * flow's diff — a `mismatch` row when they disagree, and nothing when they agree or the host said
+ * nothing.
+ *
+ * A CROSS-CHECK, NEVER AN INPUT. The host's list (`bashEditDiff`, a public beta, on by default only
+ * in some permission modes) decides nothing here: it is recorded so a reader of `flow facts` can see
+ * where the two views of one call differ. A host path outside the repo is not a file flow could
+ * have seen, so it is left out rather than reported; and when the host says its list was cut short
+ * (`moreFiles`), a file only flow saw is not a disagreement anybody can claim.
+ */
+export declare function mismatchRow(payload: HookPayload, changes: readonly Change[], 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.
@@ -520,14 +836,24 @@ export declare function classifyStore(paths: readonly string[]): {
     transcripts: TranscriptRef[];
     ignored: string[];
 };
+/**
+ * The path of THIS agent's own transcript, from a live payload — null when the payload names none.
+ *
+ * On a subagent's call the host sends the PARENT's `transcript_path`, and keeps the subagent's own
+ * transcript under it, in the store's layout: `…/<session>.jsonl` →
+ * `…/<session>/subagents/agent-<agent_id>.jsonl`. The parent's path is the parent's transcript.
+ * Null too when a subagent's half is not what that layout needs — an id that could step out of the
+ * folder included, since it becomes part of a path that is then read.
+ */
+export declare function ownTranscriptPath(payload: HookPayload): string | null;
 /**
  * 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.
+ * `Agent` tool call, so a sidecar and the block that spawned it join exactly. That join names an
+ * actor for cost attribution, after the fact — 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. A live
+ * session is not classified from it: that reads the agent type in its hook message.
  */
 export interface SpawnMeta {
     readonly agentType: string | null;
@@ -577,9 +903,10 @@ export interface Spawn {
  * 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.
+ * being classified, while the sidecar is host-written and unforgeable, and so outranks it here.
+ * Neither decides who a live session is: classification (engine, `spawnedAs`) reads the agent type
+ * in the hook message. 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. */
@@ -610,6 +937,8 @@ export type TranscriptEvent = {
     readonly input: Record<string, unknown>;
     /** The file the call names, repo-relative. Empty when it names none. */
     readonly path: string;
+    /** The repo files a Bash call reads by name (`bashReads`), when it reads any. */
+    readonly reads?: readonly string[];
 };
 /**
  * A transcript → the narrative events in it: typed prompts, tool calls, and their results.
@@ -620,10 +949,16 @@ export type TranscriptEvent = {
  * 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[];
+export declare function parseEvents(jsonl: string, root?: string, home?: 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. */
+/**
+ * The tools a repo's justfile actually drives — what a direct invocation would be bypassing.
+ *
+ * Each recipe's body is read through the parse as one script, so a loop or an `if` that spans its
+ * lines is read whole; a body that does not parse whole is read line by line, and a line that does
+ * not parse names nothing. Just's own `@` and `-` line prefixes are dropped first.
+ */
 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 {
@@ -631,7 +966,12 @@ export interface BashClass {
     readonly bypasses: readonly string[];
     readonly commits: boolean;
 }
-/** Read one command line against the repo's own recipe tools. HEURISTIC, like everything below. */
+/**
+ * Read one command line against the repo's own recipe tools, from its parse. A heredoc's body is
+ * text the command is fed, so a file being written that names a tool is not a run of it — while
+ * the line around the heredoc is judged like any other, and so is a body a shell runs. A line that
+ * does not parse is nothing: no recipe, no bypass, no commit.
+ */
 export declare function classifyBash(command: unknown, tools: readonly string[]): BashClass;
 /** A pointer into a transcript — the shape every heuristic finding takes. */
 export interface Pointer {
@@ -662,6 +1002,10 @@ export interface Narrative {
     readonly stats: {
         readonly edits: number;
         readonly writes: number;
+        /** Files changed round the edit tools — a heredoc, a `sed -i`, a script — from flow's own diff. */
+        readonly shellWrites: number;
+        /** Files a Bash command read by name. */
+        readonly shellReads: number;
         readonly commits: number;
         readonly recipes: Readonly<Record<string, number>>;
         readonly bypasses: Readonly<Record<string, number>>;
@@ -671,6 +1015,11 @@ export interface Narrative {
     readonly bypassSites: readonly Bypass[];
     readonly loops: readonly EditLoop[];
     readonly retries: readonly Retry[];
+    /** The paths behind the two shell counts, with how often each. */
+    readonly shell: {
+        readonly writes: Readonly<Record<string, number>>;
+        readonly reads: Readonly<Record<string, number>>;
+    };
     /** Every in-repo file the session touched, with how often. The facts layer scores coverage. */
     readonly touched: Readonly<Record<string, number>>;
 }
@@ -679,8 +1028,14 @@ export interface Narrative {
  *
  * `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.
+ *
+ * `rows` is the conversation's own stream, when it has one, and it is where a SHELL WRITE comes
+ * from: a transcript says what command ran, never what it changed, and only flow's diff knows that.
+ * A conversation with no stream has no shell writes to count, which is why the count reads zero
+ * there rather than a guess. Shell READS come from the transcript, like every Read does, so they are
+ * counted in every conversation.
  */
-export declare function narrative(events: readonly TranscriptEvent[], tools?: readonly string[]): Narrative;
+export declare function narrative(events: readonly TranscriptEvent[], tools?: readonly string[], rows?: readonly Row[]): Narrative;
 /**
  * Every narrative reading merged into one, each pointer tagged with the transcript it came from.
  *
@@ -692,12 +1047,16 @@ export declare function mergeNarratives(each: readonly {
     session: string;
     read: Narrative;
 }[]): Narrative;
+/**
+ * The repo's own Claude Code settings file, relative to the repo root: guarded here, and where
+ * `settingsFileFor` registers a dev dependency's hooks, and `flow uninstall` takes them out.
+ */
+export declare const REPO_SETTINGS = ".claude/settings.json";
 /**
  * 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.
+ * repo's half, which `guardPaths` reads out of the config's imports.
  *
  * 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
@@ -717,7 +1076,18 @@ export declare function mergeNarratives(each: readonly {
  *     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. */
+/**
+ * Every file that decides what the guard does here: the config and the packs it imports, then the
+ * host's half. `weakenedAfterBlock` reads it — "a rail refused, and then somebody edited the guard".
+ *
+ * The repo's half is READ OUT OF THE CONFIG'S TEXT (`configImports`) rather than resolved, so it
+ * answers the same whether or not the config loads, and it follows whatever a repo called its pack
+ * folder — no folder name is spelled into the engine.
+ *
+ * The FOLDER of each imported pack comes with the file, which is the one deliberate widening. A
+ * pack imports its own helpers, and those the config never names. The import graph cannot be
+ * walked from text, so the folder is the honest approximation.
+ */
 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;
@@ -791,9 +1161,9 @@ export declare function health({ armed, rows, withRecord, analysed }: HealthArgs
  *
  * 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.
+ * `toolUseId` names an actor for cost attribution, after the fact: 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. A live session is classified from its hook message instead.
  */
 export interface SpawnRecord {
     /** The conversation that spawned it. */
@@ -832,6 +1202,59 @@ export interface Uncovered {
  * know whether the entries it just bound point anywhere near it.
  */
 export declare function uncoveredAreas(touched: Readonly<Record<string, number>>, entries: readonly Bound[]): Uncovered[];
+/**
+ * Whether Claude Code's auto mode is steering the session towards shell edits — `bashFirst` on the
+ * host's auto-mode attachment, which tells the model to read with `cat` and change files with `sed`,
+ * heredocs and scripts rather than Read, Edit and Write. `variant` is the host's own word for how hard
+ * (`strict` · `relaxed`), when it gave one.
+ */
+export interface Steer {
+    readonly shellFirst: boolean;
+    readonly variant: string | null;
+}
+/**
+ * The auto-mode steer a conversation is under, from the LAST auto-mode attachment in its transcript
+ * — or null when it has none, or the last one is the host leaving auto mode.
+ *
+ * Read from the END, and only lines that name the attachment are parsed: a transcript is a couple
+ * of megabytes and the answer is one record.
+ */
+export declare function steerOf(jsonl: string): Steer | null;
+/**
+ * The agent a session runs as (`--agent`, or the `agent` setting), from its own transcript — or
+ * null when it runs as none.
+ *
+ * The host writes it as an `agent-setting` record, again as the session goes on. Read from the END,
+ * and only lines that name the record are parsed, as `steerOf` does: the answer is one record.
+ */
+export declare function agentSettingOf(jsonl: string): string | null;
+/** The permission mode the last recorded call was made under, or null when no row states one. */
+export declare function lastMode(rows: readonly Row[]): string | null;
+/** The permission modes the read conversations ran under, and how many of them auto mode steered. */
+export interface Modes {
+    /** Recorded calls per permission mode. */
+    readonly calls: Readonly<Record<string, number>>;
+    /** Conversations whose transcript last stood in auto mode. */
+    readonly auto: number;
+    /** Of those, the ones steered towards shell edits, and by which variant. */
+    readonly steered: number;
+    readonly variants: Readonly<Record<string, number>>;
+}
+/** Each conversation's rows and steer, added up. */
+export declare function modesOf(each: readonly {
+    readonly rows: readonly Row[];
+    readonly steer: Steer | null;
+}[]): Modes;
+/** Where Claude Code's changed-file list and flow's diff disagreed, over the read conversations. */
+export interface Mismatches {
+    readonly calls: number;
+    /** Paths only the host listed, and how often. */
+    readonly hostOnly: Readonly<Record<string, number>>;
+    /** Paths only flow's diff held, and how often. */
+    readonly flowOnly: Readonly<Record<string, number>>;
+}
+/** The `mismatch` rows, added up. */
+export declare function mismatchesIn(rows: readonly Row[]): Mismatches;
 export interface Facts {
     readonly root: string;
     readonly store: {
@@ -864,6 +1287,10 @@ export interface Facts {
     readonly actors: readonly SpawnRecord[];
     /** A rail refused, and then somebody edited the guard. A pointer, never an accusation. */
     readonly weakened: readonly Weakening[];
+    /** The permission modes the read conversations ran under, and the auto-mode steer. */
+    readonly modes: Modes;
+    /** Where the host's changed-file list disagreed with flow's diff. */
+    readonly mismatches: Mismatches;
     /** How many conversations were marked read, when asked for. Null when not asked. */
     readonly marked: number | null;
 }
@@ -930,7 +1357,39 @@ export interface Registration {
     /** The host's `matcher`. Absent means every occurrence of the event. */
     readonly matcher?: string;
 }
+/**
+ * The repo's bin folder, relative to the repo root. flow never runs a `flow` from here: any package
+ * can install one (Facebook's `flow-bin` does), and nothing guards the folder. `hostPath` drops it
+ * from the PATH npm hands one run.
+ */
+export declare const LOCAL_BIN = "node_modules/.bin";
+/** Where the repo's own `@jawache/flow` is, relative to the repo root: a dev dependency, or init's link. */
+export declare const PACKAGE_DIR = "node_modules/@jawache/flow";
+/** That package's own binary — the file its `bin` names. */
+export declare const PACKAGE_BIN = "node_modules/@jawache/flow/dist/flow.mjs";
+/**
+ * The command each registration runs: the repo's own `@jawache/flow` first, then the PATH's.
+ *
+ * The host runs it through a shell with `$CLAUDE_PROJECT_DIR` set to the repo, so a repo with flow
+ * only as a dev dependency answers its hooks, and its lockfile's version wins over a global one. It
+ * runs the package's own file, by path, never a `flow` in node_modules/.bin, which any package can
+ * put there. The same command goes in either settings file, so the host, which merges identical
+ * commands, runs it once when it is in both.
+ */
+export declare function hookCommand(hook: HookEvent): string;
 export declare const HOOK_REGISTRATIONS: readonly Registration[];
+/**
+ * WHICH SETTINGS FILE holds flow's hooks: the repo's own `.claude/settings.json` when the repo's
+ * `package.json` lists `@jawache/flow` as a dependency or a dev dependency, and the machine-wide
+ * file otherwise.
+ *
+ * A dev dependency guards that one repo: the repo's file is committed, so a fresh clone is guarded
+ * after `npm install`, and a machine with no global flow is not handed a hook that fails in every
+ * other repo it opens. A `package.json` that is missing, or will not parse, lists nothing.
+ */
+export declare function settingsFileFor(manifest: string | null, machine: string): string;
+/** Does this `package.json` list `@jawache/flow` as a dependency or a dev dependency? */
+export declare function listsFlow(manifest: string | null): boolean;
 /**
  * Is this registration OURS?
  *
@@ -944,17 +1403,63 @@ 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.
+ * The events flow IS registered for, but with a matcher narrower than this build asks for.
+ *
+ * An older flow registered PostToolUse for six tools, because an after-call hook could only show a
+ * breadcrumb then. Now it is where every change a tool makes is judged, so a registration on six
+ * tools leaves a shell edit through any other tool unjudged — and it LOOKS registered. It is its own
+ * red line for that reason, rather than disappearing inside "registered".
+ */
+export declare function staleRegistrations(settings: unknown): string[];
+/**
+ * flow's own registration in the OLD shape, the bare `flow hook <event>`: the word it answers to, or
+ * null when the command is anything else. It finds flow on the PATH alone, so a repo with flow only
+ * as a dev dependency answers none of its hooks. A command with a path to the binary is not this
+ * shape: it names the copy it runs, and that is somebody's choice.
+ */
+export declare function bareHook(command: string): HookEvent | null;
+/** The events this settings file calls flow for in the old shape — see `bareHook`. */
+export declare function bareRegistrations(settings: unknown): string[];
+/**
+ * THE MACHINE-WIDE FILE, when a dev dependency's hooks are in the repo's own: flow's old-shape
+ * commands there (`bareHook`) rewritten to today's, and nothing else touched — no registration
+ * added, no matcher widened, no other key or hook changed. A NEW object; `rewritten` names the
+ * events, empty when there was nothing to do.
+ *
+ * The host merges only IDENTICAL commands across its settings files. An old `flow hook stop` in the
+ * machine-wide file beside today's command in the repo's would run flow twice for every event, so
+ * every rule would fire twice and every refusal print twice. Made the same command, it runs once.
+ */
+export declare function withMachineCommandsUpToDate(settings: unknown): {
+    settings: unknown;
+    rewritten: string[];
+};
+/**
+ * A settings file with flow's registrations in it — a NEW object, added to, and with flow's own
+ * entries brought up to date.
  *
- * 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.
+ * It is somebody's file and holds far more than us, so nothing of anyone else's 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[];
 };
+/**
+ * A settings file with flow's registrations taken out — a NEW object, and the reverse of
+ * `withRegistrations`.
+ *
+ * On the events flow registers, each hook whose command is flow's (`ourHookCommand`, so an older
+ * flow's bare `flow hook <event>` goes too) is removed; an entry left with no hook goes, an event left
+ * with no entry goes, and a `hooks` key left empty goes. Every other key, event and hook is kept as
+ * it was. `removed` names the events, in registration order, empty when there was nothing of flow's.
+ */
+export declare function withoutRegistrations(settings: unknown): {
+    settings: unknown;
+    removed: string[];
+};
 /**
  * WHERE THE GATE LIVES, spelled once for everyone who names it.
  *
@@ -968,24 +1473,139 @@ 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.
+ * The gate's line that runs the repo's own `@jawache/flow` first: git runs the hook from the repo's
+ * root, so `$PWD` is the repo. Written by `init`, looked for by `status`, and named in its fixes.
+ */
+export declare const GATE_LOCAL_LINE: string;
+/** The gate's line that runs flow, last, so its exit code is the hook's. */
+export declare const GATE_RUN_LINE = "exec flow hook commit";
+/**
+ * How to arm a gate flow will not write over, in the ONE wording both readers use. Both of the
+ * gate's lines: the run line alone finds flow on the PATH alone, and a repo with flow only as a dev
+ * dependency then fails every commit.
  *
  * `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";
+export declare const ADD_THE_GATE_LINE: string;
+/**
+ * How to bring a gate written for the old verb up to date, in the ONE wording both readers use.
+ *
+ * The old hook still runs the gate, which is why it is not simply broken: it hands flow a list that
+ * leaves out deletions, and exits before calling flow at all when a commit only deletes files.
+ * `status` says that much; this is the instruction alone, so it ends `init`'s sentence cleanly.
+ */
+export declare const UPDATE_THE_GATE_LINE: string;
 /**
  * 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.
+ * `flow hook commit` — git's hook under the same verb as the harness's hooks. It passes nothing:
+ * flow asks git what the commit adds, changes and deletes, so there is one source of the staged set
+ * whoever calls the gate, and nothing in this file to filter it or to skip flow when it is empty.
  */
-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 const PRE_COMMIT: string;
+/** Does this pre-commit hook call flow's gate? Asked by `init` before writing, and by `status` after. */
 export declare function armsFlow(text: string | null): boolean;
+/** Does it call the gate's OLD verb, `flow commit` — a gate that runs, and misses deletions? */
+export declare function armsOldFlow(text: string | null): boolean;
+/**
+ * The pre-commit hook with flow taken out: `delete` when every command in it is one a `flow init`
+ * wrote, the hook less the lines that run flow when it holds commands of its own, and null when no
+ * line of it is flow's. A line is flow's only when it is, trimmed, exactly one flow wrote: a line
+ * somebody spelled themselves is theirs to remove.
+ */
+export declare function gateWithoutFlow(text: string | null): {
+    readonly delete: true;
+} | {
+    readonly delete: false;
+    readonly body: string;
+} | null;
+/**
+ * The lines of a hook that call flow, trimmed, in order: each line a `flow init` wrote into a gate
+ * or told a person to add, today's and every older release's, and any other line that runs
+ * `flow hook commit` or `flow commit`. Comments call nothing. What uninstall names for a person to
+ * delete from a hook that is not flow's to edit.
+ */
+export declare function flowLinesOf(text: string | null): string[];
+/** What the gate judges: the staged changes, or the whole tree as if all of it were staged. */
+export type CommitScope = "staged" | "all";
+/**
+ * `flow hook commit [--all]`, read. Null is a refusal: a file list here would be a second source of
+ * the staged set. `legacy` is the old `flow commit <files…>`, whose list an older hook still passes,
+ * and it is dropped rather than refused so that hook keeps running the gate.
+ */
+export declare function commitScope(args: readonly string[], legacy: boolean): CommitScope | null;
+/** The folder git runs hooks from, as the shell found it. One reading, for init and status alike. */
+export interface HooksFolder {
+    /** As git names it (`git rev-parse --git-path hooks`), spelled by `hooksDirOf`. */
+    readonly dir: string;
+    /** The name of every file in it, `.sample` files included: which of them count is decided here. */
+    readonly files: readonly string[];
+    /** The text of the pre-commit hook a person edits for that folder (`preCommitOf(dir)`), or null. */
+    readonly preCommitText: string | null;
+    /** That file has the execute bit this user needs to run it. False when there is no file. */
+    readonly preCommitExecutable: boolean;
+}
+/**
+ * What the pre-commit hook git runs lacks before it runs flow's gate: `add` flow's two lines;
+ * `create` the hook, which is not there; `chmod` a hook that calls flow but that git ignores,
+ * because it lacks the execute bit; or `add-and-chmod`, both.
+ */
+export type HookFix = "add" | "create" | "chmod" | "add-and-chmod";
+/** Git runs other hooks, and whether the pre-commit hook it runs calls flow. */
+export interface OtherHooks {
+    /** The folder git runs hooks from. */
+    readonly dir: string;
+    /** The pre-commit hook a person edits to call flow. */
+    readonly preCommit: string;
+    /** The first fix, or null when that hook calls flow's gate and git runs it: flow is installed. */
+    readonly fix: HookFix | null;
+}
+/** Other hooks that do not run flow's gate yet, so flow is not installed. */
+export type UnwiredHooks = OtherHooks & {
+    readonly fix: HookFix;
+};
+/** Does git run other hooks without flow's gate among them? */
+export declare function unwired(other: OtherHooks | null): other is UnwiredHooks;
+/**
+ * The pre-commit hook a person edits for this hooks folder.
+ *
+ * Usually the folder's own `pre-commit`. Husky is the exception: it points git at `.husky/_`, a
+ * folder of stubs it rewrites on every install, and each stub runs the hook of the same name one
+ * folder up, so the file a person edits is `.husky/pre-commit`. Any folder named `_` is read that way.
+ */
+export declare function preCommitOf(dir: string): string;
+/**
+ * The hooks folder as a person would type it, from git's answer to `git rev-parse --git-path hooks`
+ * run at the repo root: repo-relative when it is inside the repo, absolute when it is not, such as
+ * a worktree's shared `.git/hooks`. Resolved, so `.githooks/` and `./.githooks` both read `.githooks`.
+ */
+export declare function hooksDirOf(root: string, said: string): string;
+/**
+ * Does git run hooks other than flow's here? Null when it does not: `core.hooksPath` is flow's own
+ * folder, or it is unset and `.git/hooks` holds nothing but git's own `.sample` files. A
+ * `core.hooksPath` anywhere else counts whatever is in it, and any other file in `.git/hooks` counts,
+ * not only a `pre-commit`: Git LFS installs `pre-push` and `post-checkout` there.
+ */
+export declare function otherHooks(hooksPath: string | null, folder: HooksFolder): OtherHooks | null;
+/** The words the block opens with, fixed by the docs, for every reader that looks for them. */
+export declare const NOT_INSTALLED = "FLOW IS NOT INSTALLED";
+/**
+ * Git could not name the folder it runs hooks from, in the ONE wording init's report and status's
+ * line share. No advice: telling a husky repo to set `core.hooksPath` is what turns husky off.
+ */
+export declare const HOOKS_UNKNOWN = "git could not name the folder it runs hooks from, so flow cannot tell whether a commit runs its gate. Run `git rev-parse --git-path hooks` here to see why.";
+/** Other hooks whose pre-commit calls flow, in the ONE wording init's note and status's line share. */
+export declare function wiredLine(other: OtherHooks): string;
+/**
+ * The message for other hooks that do not run flow, in the ONE wording init's block and status's
+ * line share: the folder git runs hooks from, why its pre-commit hook does not run flow's gate, and
+ * the two ways to finish. The first fix is whatever that hook lacks: flow's two lines, the hook
+ * itself, or the execute bit. Init never takes either fix itself: editing or creating another
+ * tool's hook, or moving its hooks, is the person's call.
+ */
+export declare function notInstalledLines(other: UnwiredHooks): string[];
 /** 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. */
@@ -1000,8 +1620,11 @@ export interface InitFacts {
     readonly hasFlowDir: boolean;
     /** `git config core.hooksPath` as it stands. */
     readonly hooksPath: string | null;
+    /** The folder git runs hooks from, or null outside git or when git could not say. */
+    readonly hooksFolder: HooksFolder | null;
+    /** The settings file flow's hooks go in: the repo's own, repo-relative, or the machine-wide one. */
     readonly settingsPath: string;
-    /** The parsed host settings file. */
+    /** That file, parsed. */
     readonly settings: unknown;
     /**
      * The settings file is THERE and would not parse.
@@ -1013,6 +1636,15 @@ export interface InitFacts {
      * settings.json holding JSONC comments: the write was one branch away.
      */
     readonly settingsUnreadable: boolean;
+    /**
+     * The machine-wide settings file, read, when flow's hooks go in the repo's own file — a dev
+     * dependency's — and null when they go in the machine-wide file itself.
+     */
+    readonly machine: {
+        readonly path: string;
+        readonly settings: unknown;
+        readonly unreadable: boolean;
+    } | null;
     /** Does `@jawache/flow` already resolve from this repo? */
     readonly resolves: boolean;
     /**
@@ -1036,17 +1668,36 @@ export interface InitPlan {
     readonly gate: Write | null;
     /** A pre-commit hook that is somebody else's. Never overwritten — reported, with the line to add. */
     readonly gateKept: boolean;
+    /** …and it is flow's own, from before `flow hook commit` — reported with the line to replace. */
+    readonly gateOld: 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;
+    /** Point git at `.githooks`: a git repo whose git runs no other hooks, and not already there. */
     readonly hooksPath: boolean;
+    /** Git runs other hooks, so `core.hooksPath` is left alone. Flow is not installed unless it is wired. */
+    readonly otherHooks: OtherHooks | null;
+    /**
+     * A git repo whose git could not name the folder it runs hooks from, so `core.hooksPath` is left
+     * alone too: that folder may hold another tool's hooks, and setting it would turn them off.
+     */
+    readonly hooksUnknown: 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 machine-wide file with flow's old commands brought up to date, for a dev dependency whose
+     * hooks are in the repo's own file — or null when it has none, or could not be read.
+     */
+    readonly machine: {
+        readonly path: string;
+        readonly value: unknown;
+        readonly rewritten: readonly string[];
+    } | null;
     /** The settings file was there and would not parse, so nothing was registered. Said out loud. */
     readonly settingsUnreadable: string | null;
 }
@@ -1057,9 +1708,125 @@ export declare function planInit(facts: InitFacts): InitPlan;
  *
  * 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.
+ * was read-only, and the person needs to know exactly that. `colour` is `wantsColour`'s answer for
+ * the output this is written to.
  */
-export declare function initLines(plan: InitPlan, failures: readonly string[]): string[];
+export declare function initLines(plan: InitPlan, failures: readonly string[], colour?: boolean): string[];
+/**
+ * Does this output get colour? Only in a terminal, and never with `NO_COLOR` set to anything but an
+ * empty string, which is the convention at no-color.org. A pipe, a file and a test harness get the
+ * plain text, so nothing that reads the output has escape codes to strip.
+ */
+export declare function wantsColour(terminal: boolean, noColor: string | undefined): boolean;
+/**
+ * Init's exit code. 1 when it could not finish, and 1 when flow is not installed or cannot tell: a
+ * script chaining `flow init && …` is asking whether the repo is guarded, and a gate git never runs
+ * is not.
+ */
+export declare function initCode(plan: InitPlan, failures: readonly string[]): 0 | 1;
+/** What the shell found before anything was removed. Every one is a stat, not a judgement. */
+export interface UninstallFacts {
+    readonly hasConfig: boolean;
+    /** The gate as it stands, or null when there is none. */
+    readonly gateText: string | null;
+    /** `git config core.hooksPath` as it stands. */
+    readonly hooksPath: string | null;
+    /** The repo's top folder when the run is in a folder below it, else null. */
+    readonly subfolderOf: string | null;
+    /** The names in `.githooks/`, or null when there is no such folder. */
+    readonly hooksDir: readonly string[] | null;
+    /**
+     * The folder git runs hooks from, read at the repo's top folder as init and status read it, or
+     * null outside git or when git could not say.
+     */
+    readonly hooksFolder: HooksFolder | null;
+    readonly hasFlowDir: boolean;
+    /** `node_modules/@jawache/flow` is a symlink: the link `flow init` makes. A real folder is an install. */
+    readonly linked: boolean;
+    /** Does the repo's `package.json` list `@jawache/flow`? Then flow's hooks are in the repo's own settings file. */
+    readonly listed: boolean;
+    /** The repo's `.claude/settings.json`, parsed; null when there is none. */
+    readonly settings: unknown;
+    /** …it is there and would not parse. */
+    readonly settingsUnreadable: boolean;
+    /** `--machine` was given: the machine-wide settings file is flow's to clean too. */
+    readonly machineFlag: boolean;
+    /** The machine-wide settings file: its absolute path, its JSON (null when there is none), and whether it would not parse. */
+    readonly machineFile: {
+        readonly path: string;
+        readonly settings: unknown;
+        readonly unreadable: boolean;
+    };
+}
+/** A settings file with flow's registrations taken out: where it is, what to write, and the events that went. */
+export interface SettingsWithout {
+    readonly path: string;
+    readonly value: unknown;
+    readonly removed: readonly string[];
+}
+/** Everything `flow uninstall` will do, decided before a byte is removed. */
+export interface UninstallPlan {
+    /** The gate: deleted, rewritten without flow's lines, or null when nothing in it is flow's. */
+    readonly gate: {
+        readonly path: string;
+        readonly body: string | null;
+    } | null;
+    /**
+     * A pre-commit hook that still calls flow after the run, in lines flow did not write there: that
+     * hook, as the report names it, and those lines, for a person to delete before `npm uninstall`.
+     * The hook git runs from another folder, such as husky's `.husky/pre-commit`, which uninstall
+     * never edits, as `flow init` never does; else what is left of `.githooks/pre-commit`. Null when
+     * neither calls flow.
+     */
+    readonly hookCallsFlow: {
+        readonly path: string;
+        readonly lines: readonly string[];
+    } | null;
+    /** Unset `core.hooksPath`: it is `.githooks`, the run is at the repo's top folder, and the folder holds no other hook. */
+    readonly hooksPath: boolean;
+    /**
+     * `core.hooksPath` is `.githooks` but the run is in a subfolder: the repo's top folder, where
+     * `flow uninstall` removes it, or null.
+     */
+    readonly hooksPathFrom: string | null;
+    /** The hooks that keep `core.hooksPath` at `.githooks`, named for the report. */
+    readonly hooksKept: readonly string[];
+    /** Remove `.githooks/`, which nothing else is in. */
+    readonly hooksDir: boolean;
+    readonly flowDir: boolean;
+    readonly link: boolean;
+    /** The repo's settings file without flow's registrations, or null when it holds none. */
+    readonly settings: SettingsWithout | null;
+    /** With `--machine`: the machine-wide settings file without flow's registrations, or null when it holds none. */
+    readonly machine: SettingsWithout | null;
+    /** The settings files flow's to clean that would not parse: nothing written to them, each said out loud. */
+    readonly unreadable: readonly string[];
+    /** How this run was typed, so a failure's report says what to run again. */
+    readonly command: string;
+    readonly keptConfig: boolean;
+    /**
+     * The machine-wide file this repo's hooks are in still holds them, because `--machine` was not
+     * given: its path, said beside the report and in its last line, or null. Without it, a plain run
+     * reports success while every Claude Code session on the machine still calls `flow`.
+     */
+    readonly machineHolds: string | null;
+    /** The command that removes the package, the report's last line. */
+    readonly next: string;
+}
+/** What uninstall will remove from this repo. Pure: every branch reads a fact the shell already gathered. */
+export declare function planUninstall(facts: UninstallFacts): UninstallPlan;
+/** The one argument `flow uninstall` takes: clean the machine-wide settings file too. */
+export declare const MACHINE_FLAG = "--machine";
+/**
+ * `flow uninstall`'s arguments, read: null when they are fine, else the refusal to print. An argument
+ * it does not know is refused rather than ignored, because this verb deletes files and a `--dry-run`
+ * or a `--help` that went ahead would delete them too.
+ */
+export declare function uninstallRefusal(args: readonly string[]): string | null;
+/** A step that could not be done answers 1, whether the shell hit it or the plan did. */
+export declare function uninstallCode(plan: UninstallPlan, failures: readonly string[]): 0 | 1;
+/** The report: every removal named, what was kept and why, each failure, and the command to run next. */
+export declare function uninstallLines(plan: UninstallPlan, 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;
@@ -1077,8 +1844,18 @@ export interface StatusFacts {
     readonly load: LoadResult | null;
     readonly gateText: string | null;
     readonly hooksPath: string | null;
+    /** The folder git runs hooks from, read as init reads it, or null outside git or when git could not say. */
+    readonly hooksFolder: HooksFolder | null;
     readonly settingsPath: string;
     readonly settings: unknown;
+    /**
+     * The machine-wide settings file, parsed, when flow's hooks are in the repo's own file — a dev
+     * dependency's — and null when `settingsPath` is the machine-wide file itself.
+     */
+    readonly machine: {
+        readonly path: string;
+        readonly settings: unknown;
+    } | null;
     /**
      * The grammars the config declared, each with its library path made absolute and a straight
      * answer about whether that file is there.
@@ -1092,13 +1869,64 @@ export interface StatusFacts {
         readonly libraryPath: string;
         readonly present: boolean;
     }[];
-    /** Who last worked in this worktree, from the marker the write rail leaves. Null when nobody has. */
+    /**
+     * Who last worked in this worktree, from the marker the write rail leaves. Null when nobody has.
+     * `mode` is the permission mode its last recorded call stated, null when none did; `steer` is auto
+     * mode's steer as its transcript last stated it, asked only under auto mode.
+     */
     readonly session: {
         readonly id: string;
         readonly agent: string | null;
         readonly wearing: readonly string[];
+        readonly mode?: string | null | undefined;
+        readonly steer?: Steer | null | undefined;
     } | null;
+    /**
+     * What git ignores here, one path per entry, a directory with its trailing `/` — plus any literal
+     * path a write or delete rule names that git would ignore though it does not exist yet (`.env`).
+     */
+    readonly ignored: readonly string[];
+    /** The config's `snapshotInclude` globs: the ignored paths the snapshot records anyway. */
+    readonly snapshotInclude: readonly string[];
+    /**
+     * Where the flow the hooks and the gate run is, as three stats. `listed`: the repo's
+     * `package.json` lists `@jawache/flow`. `copy`: its package's binary, `PACKAGE_BIN`, is there —
+     * a dev dependency's, or the link `flow init` made to the flow that ran it. `path`: a `flow` on
+     * the PATH this command was run with, less what npm added for this run (`hostPath`) — the nearest
+     * reading there is of the PATH git and the host hand their hooks. `binaryFitting` judges them.
+     */
+    readonly binary: {
+        readonly listed: boolean;
+        readonly copy: boolean;
+        readonly path: boolean;
+    };
 }
+/**
+ * The literal head of a glob, cut back to a whole segment: `src/gen/**` → `src/gen/`, `.env` →
+ * `.env`, `**` + `/*.ts` → nothing. A glob with no wildcard is all head.
+ */
+export declare function staticPrefix(glob: string): string;
+/**
+ * The paths those rules name OUTRIGHT — a glob with no wildcard, such as `.env`. A file that does
+ * not exist yet is in no listing of ignored files, so status asks git about these by name.
+ */
+export declare function literalScopes(load: LoadResult | null): string[];
+/**
+ * THE SNAPSHOT'S BLIND SPOTS, as red lines: a write or delete rule whose scope reaches a path git
+ * ignores, where `snapshotInclude` does not bring it back.
+ *
+ * The snapshot is git's view, so a shell write to an ignored file is never in the diff and never
+ * judged — and a rule guarding `.env` would load green and watch nothing. So the gap is said where a
+ * person looks, naming the rule and the setting.
+ *
+ * WHAT "REACHES" MEANS, and why it is not "the glob could match something in there". An ignored
+ * FILE is reached when the rule's globs match it. An ignored DIRECTORY is reached when a glob names
+ * it — its literal head lies inside the directory (`dist/**` over an ignored `dist/`), or sits above
+ * it and continues with `**` (`src/**` over an ignored `src/gen/`). A glob that is all wildcard,
+ * `**` + `/*.ts`, does not reach `node_modules/` by this measure, though strictly it matches files in
+ * there: every repo with such a rule would be red over a folder no rule was written about.
+ */
+export declare function snapshotGaps(entries: readonly Bound[], ignored: readonly string[], include: readonly string[]): Fitting[];
 /** The whole answer. */
 export interface Status {
     readonly root: string;
@@ -1115,6 +1943,15 @@ export interface Status {
     readonly refusals: readonly Refusal[];
     readonly green: boolean;
 }
+/**
+ * THE PATH GIT AND THE HOST HAND THEIR HOOKS, read off the PATH this command was run with: every
+ * folder of it but a `node_modules/.bin` that npm put there for this one run — the repo's own or an
+ * ancestor's, which `npx flow` and `npm run` add, and npx's cache of a package it fetched. Counted,
+ * `npx flow status` would find a dev dependency's copy "on the PATH" that git never sees.
+ *
+ * Another repo's node_modules/.bin stays: it is on the PATH because someone put it there.
+ */
+export declare function hostPath(dirs: readonly string[], root: string): string[];
 /** 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. */