@jawache/flow 0.1.1 → 0.2.1

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

@@ -1,6 +1,13 @@
 import type { LoadResult } from "../language/domain.ts";
 import { type Facts, type SelectOpts, type SpawnMeta, type TranscriptRef } from "./domain.ts";
-/** Where this harness keeps a working directory's conversations. */
+/**
+ * Where this harness keeps a working directory's conversations.
+ *
+ * Under the host's own folder, and `CLAUDE_CONFIG_DIR` moves that folder — the host honours it for
+ * the store as it does for settings.json, so a store read from `~/.claude` regardless would be
+ * somebody else's. A `home` passed in is taken as the user's home and wins: that is a test naming
+ * its own world.
+ */
 export declare function projectDir(cwd: string, home?: string): string;
 /** One conversation in the store, with everything findable about it without opening it twice. */
 export interface StoredTranscript {

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

@@ -1,5 +1,5 @@
 import { type ExecResult, type FlowConfig, type LoadResult, type Grammar, type Settings, type World } from "../language/domain.ts";
-import { type HookEvent, type HookPayload, type HookResult } from "./domain.ts";
+import { type CallRecord, type Change, type Delta, type HookEvent, type HookPayload, type HookResult } from "./domain.ts";
 /**
  * Run one command the way a check means it — through a shell, in the repo, hermetically.
  *
@@ -62,6 +62,45 @@ export declare function wearer(root: string): {
     readonly agent: string | null;
     readonly wearing: readonly string[];
 };
+/**
+ * RECORD THE TREE BEFORE A CALL, filed under the host's `tool_use_id`.
+ *
+ * A snapshot that cannot be taken is RECORDED as a fault rather than skipped, so the after-call rail
+ * reports it instead of finding nothing and calling the call clean. `who` is kept beside the tree so
+ * a snapshot with no after is readable as a call still in flight, per session and agent.
+ */
+export declare function takeSnapshot(root: string, key: string, include: readonly string[], who: {
+    readonly session: string;
+    readonly agent: string;
+    readonly tool: string;
+}): void;
+/**
+ * WHAT THE CALL CHANGED: the tree now against the tree its snapshot recorded, path by path, with
+ * the content either side. The before-snapshot is kept — a revert reads from it — until `forget`.
+ */
+export declare function observeDelta(root: string, key: string, include: readonly string[]): Delta & {
+    readonly before?: string;
+};
+/**
+ * PUT CHANGES BACK from the before-snapshot — a changed or removed file to its old content, a file
+ * the call created removed. Answers what could not be put back, never throws: a revert that failed
+ * is said to the model, loudly, rather than claimed.
+ */
+export declare function revertChanges(root: string, tree: string, changes: readonly Change[]): {
+    path: string;
+    why: string;
+}[];
+/**
+ * THE CALL LOG — every snapshot's record, read back: who made each call, when it started, and when
+ * it finished if it has. A record that cannot be read is left out; it is somebody's write racing
+ * this read, and the next diff reads it whole.
+ */
+export declare function callLog(root: string): CallRecord[];
+/**
+ * The call is over: its record says when it finished, so a diff still to come can tell it
+ * overlapped, and its throwaway indexes go. Records no diff still to come can overlap are dropped.
+ */
+export declare function finishSnapshot(root: string, key: string, now?: number): void;
 /**
  * The repo the session is standing in — the FOURTH question of §7.
  *
@@ -110,7 +149,7 @@ export declare function loadRegime(root: string): Promise<Regime>;
  *
  * The shape is deliberately flat rather than a hook function per event: the events differ in what
  * they CARRY (toEvent's job) and in how their answer is rendered (toResult's job), and the middle —
- * load, classify, run, log — is identical for all five. The old engine had five files here, and the
+ * load, classify, run, log — is identical for all of them. The old engine had five files here, and the
  * off switch, the session marker and the fault handling were each written out four or five times
  * with small differences nobody had chosen.
  */
@@ -157,9 +196,11 @@ export declare function readPayload(): PayloadRead;
  *
  * `pre-tool-use` is the rail that GUARDS, so it fails CLOSED — a payload it cannot read is a tool
  * call it cannot judge, and "I could not look" must never be spelled the same way as "I looked and
- * it was fine". The other four annotate, and breaking a session over a hook that only adds a
- * breadcrumb would be the cure killing the patient — so they SPEAK on stderr and allow, because
- * silence is precisely what let the old swallow go unnoticed.
+ * it was fine". The after-call rails JUDGE too — every change a call made reaches the rules there —
+ * so a payload they cannot read is a call whose changes nobody judged, and they report it with exit
+ * 2, which on those rails reaches the model beside the result and blocks nothing. The rest only add
+ * a breadcrumb, and breaking a session over one would be the cure killing the patient, so they SPEAK
+ * on stderr and allow. `readFault` next door is where that split is decided.
  *
  * Everything is wrapped: a hook that throws is a hook that wedges a session, and an unknown event
  * is silence rather than a usage message in front of the model.

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

@@ -18,10 +18,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
@@ -88,7 +100,7 @@ export declare function configImports(configText: string): readonly string[];
  * 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", "notification"];
 export type HookEvent = (typeof HOOK_EVENTS)[number];
 export declare function isHookEvent(word: string): word is HookEvent;
 /**
@@ -104,7 +116,9 @@ export declare function isHookEvent(word: string): word is HookEvent;
  *     perfectly. Reporting an entry that goes dark is `flow status`'s job (F6).
  *   · 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.
@@ -129,6 +143,12 @@ export type AdapterEvent = {
     readonly command?: string | undefined;
     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;
@@ -149,6 +169,13 @@ export interface EventWorld {
     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;
+    /** 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;
@@ -194,11 +221,37 @@ export declare function wouldBeFile(tool: string, input: Record<string, unknown>
  * aside. The command rail still sees the raw line either way.
  */
 export declare function deleteTargets(command: string): 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 — followed through `cd`, `VAR=`, `for` loops and `$(…)`. The repo root itself is not an
+ * area and is left out. Best-effort, failing open: see the section head.
+ */
+export declare function bashReads(command: string, 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.
  *
@@ -207,6 +260,94 @@ export declare function deleteTargets(command: string): string[];
 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;
+/**
+ * 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[];
+/**
+ * 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[];
+/** 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 +362,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,6 +427,8 @@ 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?
@@ -326,7 +523,16 @@ 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;
 /**
@@ -340,6 +546,16 @@ export declare function decision(hook: HookEvent, additionalContext: string): st
  * decision because it is a fact about what the event is FOR.
  */
 export declare function faultText(hook: HookEvent, why: "unreadable" | "unparseable", detail: string): string;
+/**
+ * The answer a rail gives when it could not read its payload — and which rails must be LOUD.
+ *
+ * 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 sentence 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.
+ */
+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. */
@@ -466,6 +682,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.
@@ -610,6 +856,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,7 +868,7 @@ 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. */
@@ -662,6 +910,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 +923,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 +936,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.
  *
@@ -832,6 +1095,51 @@ 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 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 +1172,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;
 }
@@ -943,6 +1255,15 @@ export declare const HOOK_REGISTRATIONS: readonly Registration[];
 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[];
+/**
+ * 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[];
 /**
  * A settings file with flow's registrations in it — a NEW object, and only ever added to.
  *
@@ -1092,13 +1413,52 @@ 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[];
 }
+/**
+ * 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;