@manyoars/oars 0.2.0 → 0.3.0

package/dist/gate/record.js

@@ -0,0 +1,125 @@
+// The shape of `crossings.jsonl`, in closed vocabulary. Field classes are in `docs/gate.md` and `docs/sessions-store.md`: a name and a stated
+// version are class A because a private package's name can identify private work, and no path, working folder, or command text is kept at all.
+import { createHash } from 'node:crypto';
+import { CROSSING_CLASSES, CROSSING_FORMS } from './checks.js';
+export const GATE_VERSION = 1;
+/** Where a row came from. A replay row is read from a transcript, a hook row was written as the call crossed, and `both` is a hook row a replay then filled in. */
+export const VIAS = ['hook', 'replay', 'both'];
+/** `not-read` on a field says no one has read it for this row yet: a hook row has no transcript, so the fields a transcript gives read `not-read` until a replay fills them. */
+export const NOT_READ = 'not-read';
+/** Every program a crossing can name: the package managers and runners the gate reads, their `python -m` forms, and the `mcp` and `skill` tools. */
+export const PROGRAMS = ['npm', 'pnpm', 'yarn', 'bun', 'npx', 'pnpx', 'bunx', 'pip', 'python -m pip', 'python -m pipx', 'python -m uv', 'uv', 'uvx', 'pipx', 'poetry', 'pdm', 'rye', 'pipenv', 'conda', 'mamba', 'micromamba', 'mcp', 'skill'];
+export const ORIGINS = ['prompt', 'repo-file', 'web', 'tool-output', 'skill', 'harness', 'none-seen', 'not-read'];
+export const NOVELTIES = ['fleet', 'repository', 'session', 'none', 'not-read'];
+export const DECIDERS = ['operator', 'agent', 'not-read'];
+export const PERMISSIONS = ['default', 'acceptEdits', 'plan', 'bypassPermissions', 'dontAsk', 'auto', 'other', 'unknown'];
+export const STATUSES = ['ok', 'error', 'refused', 'none', 'not-read'];
+export const NEXTS = ['proceeded', 'retried', 'routed-around', 'changed-name', 'stopped', 'no-result', 'not-read'];
+export const MISSES = ['none', 'not-found', 'not-read'];
+export const AGAINST_LATEST = ['not-read', 'latest', 'not-latest', 'range', 'unstated', 'unknown'];
+export const REGISTRY_STATES = ['not-read', 'found', 'not-found', 'unreachable'];
+export const REGISTRY_AGES = ['not-read', 'after-crossing', 'under-7-days', 'under-30-days', 'under-1-year', 'older', 'unknown'];
+export const DEPTHS = ['main', 'subagent'];
+/** Whether a note that would show did (`shown`), was held back by the policy's holdback (`held`), or there was none to show or the line was a block (`none`). A replay shows nothing, so it reads `none`. */
+export const ARMS = ['none', 'shown', 'held'];
+/** The fixed ids of the lines the hook can show; the words are in `notes.ts`. `none` is no line shown, a held note included. */
+export const LINE_IDS = ['none', 'young-name-note', 'not-found-note', 'not-found-block'];
+/** A truncated SHA-256 of the folder an ask ran in, so a kept answer names its folder without storing the path. */
+export const folderKey = (cwd) => createHash('sha256').update(cwd).digest('hex').slice(0, 16);
+/** The harness's permission mode, in the closed vocabulary: a mode this version does not know reads `other`. */
+export const permissionOf = (value) => PERMISSIONS.find((known) => known === value) ?? 'other';
+const isRow = (value) => {
+    const kind = typeof value === 'object' && value !== null ? Reflect.get(value, 'kind') : undefined;
+    return kind === 'crossing' || kind === 'run' || kind === 'registry';
+};
+/** A line this version cannot read is skipped: a torn tail or a newer row kind says nothing about the rest. */
+export const parseRows = (text) => text.split('\n').flatMap((line) => {
+    if (line === '')
+        return [];
+    try {
+        const parsed = JSON.parse(line);
+        return isRow(parsed) ? [parsed] : [];
+    }
+    catch {
+        return [];
+    }
+});
+export { CROSSING_CLASSES, CROSSING_FORMS };
+const isLive = (row) => row.via === 'hook' || row.via === 'both';
+/** A hook never saw these, so a hook row says them as `not-read`, `null`, or `unknown`: then the replay's value stands. */
+const unsaid = (value) => value === undefined || value === NOT_READ || value === null || value === 'unknown';
+const pick = (key, live, replayed) => (unsaid(live[key]) ? replayed[key] : live[key]);
+/**
+ * One crossing seen twice. The hook's fields from the time of the crossing win: its clock, its permission mode, the registry as it stood, and what was new. A replay's
+ * fields from the transcript fill in what the hook could not read. A row that came out of an earlier merge is a hook row again here, so a second replay refreshes
+ * only the transcript fields and keeps what the hook saw.
+ */
+const merged = (live, replayed) => ({
+    ...replayed,
+    via: 'both',
+    // The folder as it was at the crossing: a bin installed or removed since must not turn a fetch into a local run, or the reverse.
+    form: live.form,
+    day: pick('day', live, replayed),
+    ts: pick('ts', live, replayed),
+    version: pick('version', live, replayed),
+    permission: pick('permission', live, replayed),
+    novelty: pick('novelty', live, replayed),
+    // One reading, so all three come from one side: the registry as it stood at the crossing when the hook read it, else the replay's. Picked field by field, a hook's
+    // `unreachable` (with `unknown` beside it) would take a later replay's `not-latest`, a row that contradicts itself.
+    // A local bin run was never asked of the registry (docs/gate.md), so a replay that saw no bin and asked cannot give it a reading.
+    ...(live.registryState === NOT_READ && live.form !== 'local-bin-run'
+        ? { againstLatest: replayed.againstLatest, registryState: replayed.registryState, registryAge: replayed.registryAge }
+        : live.form === 'local-bin-run'
+            ? { againstLatest: NOT_READ, registryState: NOT_READ, registryAge: NOT_READ }
+            : { againstLatest: live.againstLatest, registryState: live.registryState, registryAge: live.registryAge }),
+    ...(live.policy === undefined ? {} : { policy: live.policy }),
+    arm: pick('arm', live, replayed),
+    lineShown: pick('lineShown', live, replayed),
+    // A hook row from an earlier build has no `lineHeld`: `unsaid` reads it as nothing said, so the replay's `none` stands.
+    lineHeld: pick('lineHeld', live, replayed),
+});
+/** The key a call crossing is counted by: nothing counts twice when a row has a tool use id and another row has the same one. */
+const crossingKey = (row) => (row.toolUseId === null ? null : [row.session, row.toolUseId, row.class, row.name].join('\0'));
+/** The first row of each key; a row with no key cannot repeat, so it stays. */
+const once = (rows) => {
+    const seen = new Set();
+    return rows.filter((row) => {
+        const key = crossingKey(row);
+        if (key === null)
+            return true;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+};
+/**
+ * Every crossing once. The rows of `replayed` are replay rows and the rows of `live` are hook rows (or merged ones); rows with the same session, tool use id, class, and
+ * name are one row, whether two sources saw it or one wrote it twice, so the same name twice in one call counts once. A row with no tool use id cannot be paired and stays.
+ */
+export const mergeCrossings = (replayed, live) => {
+    const hooked = once(live);
+    const waiting = new Map();
+    for (const row of hooked) {
+        const key = crossingKey(row);
+        if (key !== null)
+            waiting.set(key, row);
+    }
+    const paired = new Set();
+    const result = once(replayed).map((row) => {
+        const key = crossingKey(row);
+        const mate = key === null ? undefined : waiting.get(key);
+        if (mate === undefined)
+            return row;
+        paired.add(mate);
+        return merged(mate, row);
+    });
+    return [...result, ...hooked.filter((row) => !paired.has(row))];
+};
+/** The crossings of a file's rows with each counted once: replay rows and hook rows of the same call become one. */
+export const crossingsOf = (rows) => {
+    const crossings = rows.filter((row) => row.kind === 'crossing');
+    return mergeCrossings(crossings.filter((row) => !isLive(row)), crossings.filter(isLive));
+};
+/** The hook-written rows (and merged ones) of a file, which a replay keeps when it rewrites the rest. */
+export const liveCrossings = (rows) => rows.filter((row) => row.kind === 'crossing' && isLive(row));

package/dist/gate/registry-state.d.ts

@@ -0,0 +1,10 @@
+import type { Crossing } from './checks.js';
+import type { AgainstLatest, RegistryAge } from './record.js';
+import type { RegistryAnswer } from './registry.js';
+export declare const DAY_MS = 86400000;
+/** Only these managers read the registry the `npm view` and `pip index` asks reach. A `pnpm` (its own global `rc`), `poetry`, `uv`, `yarn`, or `conda` install may use one they do not. */
+export declare const ASKED_PROGRAMS: ReadonlySet<string>;
+export declare const ageOf: (answer: RegistryAnswer, ts: string | null) => RegistryAge;
+export declare const againstLatestOf: (crossing: Crossing, answer: RegistryAnswer) => AgainstLatest;
+/** An answer reaches a row only when that row's own program was asked and its command left the registry to the default: the same name can cross twice. */
+export declare const askedOf: (crossing: Crossing) => boolean;

package/dist/gate/registry-state.js

@@ -0,0 +1,30 @@
+export const DAY_MS = 86_400_000;
+/** Only these managers read the registry the `npm view` and `pip index` asks reach. A `pnpm` (its own global `rc`), `poetry`, `uv`, `yarn`, or `conda` install may use one they do not. */
+export const ASKED_PROGRAMS = new Set(['npm', 'npx', 'pip', 'python -m pip']);
+export const ageOf = (answer, ts) => {
+    if (answer.created === null || ts === null)
+        return 'unknown';
+    const days = (Date.parse(ts) - Date.parse(answer.created)) / DAY_MS;
+    if (Number.isNaN(days))
+        return 'unknown';
+    if (days < 0)
+        return 'after-crossing';
+    if (days < 7)
+        return 'under-7-days';
+    if (days < 30)
+        return 'under-30-days';
+    return days < 365 ? 'under-1-year' : 'older';
+};
+export const againstLatestOf = (crossing, answer) => {
+    if (answer.state !== 'found')
+        return 'unknown';
+    if (crossing.versionForm === 'unstated')
+        return 'unstated';
+    if (crossing.versionForm === 'range')
+        return 'range';
+    if (crossing.version === 'latest' || crossing.version === answer.latest)
+        return 'latest';
+    return crossing.versionForm === 'pinned' ? 'not-latest' : 'unknown';
+};
+/** An answer reaches a row only when that row's own program was asked and its command left the registry to the default: the same name can cross twice. */
+export const askedOf = (crossing) => crossing.registryAsked && crossing.form !== 'local-bin-run' && ASKED_PROGRAMS.has(crossing.program);

package/dist/gate/registry.d.ts

@@ -0,0 +1,56 @@
+import { type ChildProcess, type SpawnOptions } from 'node:child_process';
+import type { CrossingClass } from './checks.js';
+export interface RegistryAsk {
+    class: CrossingClass;
+    name: string;
+    cwd: string;
+    /** Aborting it stops the manager the ask started, and the processes that manager started (the hook does so before it hands the name to a helper). */
+    signal?: AbortSignal;
+}
+export interface RegistryAnswer {
+    state: 'found' | 'not-found' | 'unreachable';
+    latest: string | null;
+    created: string | null;
+}
+export type RegistryReader = (ask: RegistryAsk) => Promise<RegistryAnswer>;
+/** What a manager's run came back with: the exit code, null when it could not be started or ran out of time. */
+export interface ManagerRun {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+export type ManagerRunner = (program: string, args: readonly string[], cwd: string, signal?: AbortSignal) => Promise<ManagerRun>;
+/** Whether a name can be asked about: a package class, spelled as a registry could hold it. */
+export declare const askable: (cls: CrossingClass, name: string) => boolean;
+/** `npm view <name> dist-tags.latest time.created --json`, as an object or a one-element array. A not-found answer is an `E404` on either stream. */
+export declare const readNpmView: (run: ManagerRun) => RegistryAnswer;
+/**
+ * `pip index versions <name>` prints `name (latest)` first. It states no dates, so a Python name's age stays unknown. A Python name never reads
+ * `not-found`: pip prints "No matching distribution" for a missing name and for a down index alike, so the line cannot tell them apart.
+ */
+export declare const readPipIndex: (run: ManagerRun) => RegistryAnswer;
+/**
+ * How a manager is started. `cwd` comes from a transcript, and `cmd.exe` searches the current directory before PATH, so `NoDefaultCurrentDirectoryInExePath`
+ * keeps an `npm.cmd` left there from running: nothing here runs package code.
+ */
+export declare const managerOptions: (cwd: string, platform?: NodeJS.Platform, timeout?: number) => {
+    cwd: string;
+    timeout: number;
+    shell: boolean;
+    windowsHide: boolean;
+    encoding: "utf8";
+    env: {
+        NoDefaultCurrentDirectoryInExePath: string;
+    };
+};
+/** What `stopTree` needs of `spawn`: a program, its arguments, and a child to hear an error from. */
+export type StartProcess = (program: string, args: readonly string[], options: SpawnOptions) => {
+    on: (event: 'error', listener: () => void) => unknown;
+};
+/**
+ * Stops a manager and what it started. On Windows `shell: true` puts `cmd.exe` first, and killing it leaves the manager running, so the whole tree goes (`taskkill /T`); elsewhere
+ * the manager is the child itself.
+ */
+export declare const stopTree: (child: Pick<ChildProcess, "pid" | "kill">, platform?: NodeJS.Platform, start?: StartProcess) => void;
+/** The reader the option uses. `npm view` and `pip index` run no package code; the manager's own cache is the manager's. */
+export declare const managerReader: (given?: ManagerRunner, timeout?: number) => RegistryReader;

package/dist/gate/registry.js

@@ -0,0 +1,94 @@
+// The `--registry-state` option: what a registry says about a name, asked through `npm` or `pip` in the folder the call ran in. For a crossing made
+// with npm, npx, or pip whose command left the registry, the config, and the folder to their defaults (the replay asks for no other crossing),
+// that is the registry the manager would contact, because those read the same project and user config; so a private name does not go to a public
+// registry on the gate's account. Off by default; nothing here runs unless the operator asks.
+import { execFile, spawn } from 'node:child_process';
+const TIMEOUT_MS = 20_000;
+const UNREACHABLE = { state: 'unreachable', latest: null, created: null };
+const NOT_FOUND = { state: 'not-found', latest: null, created: null };
+// On Windows the managers are `.cmd` shims, which run only through a shell, so a name reaches a command line. These accept only what a registry
+// can hold, which has no shell character, and nothing that a manager would read as a flag.
+const NPM_NAME = /^(?:@[a-z0-9~][a-z0-9._~-]*\/)?[a-z0-9~][a-z0-9._~-]*$/i;
+const PYTHON_NAME = /^[a-z0-9][a-z0-9._-]*$/i;
+/** Whether a name can be asked about: a package class, spelled as a registry could hold it. */
+export const askable = (cls, name) => (cls === 'npm-package' ? NPM_NAME.test(name) : cls === 'python-package' && PYTHON_NAME.test(name));
+const textField = (value, key) => {
+    const field = typeof value === 'object' && value !== null ? Reflect.get(value, key) : undefined;
+    return typeof field === 'string' && field !== '' ? field : null;
+};
+/** `npm view <name> dist-tags.latest time.created --json`, as an object or a one-element array. A not-found answer is an `E404` on either stream. */
+export const readNpmView = (run) => {
+    if (/\bE404\b/.test(run.stdout) || /\bE404\b/.test(run.stderr))
+        return NOT_FOUND;
+    if (run.code !== 0)
+        return UNREACHABLE;
+    try {
+        const answer = JSON.parse(run.stdout);
+        // npm 12 wraps the two-field answer in a one-element array; older npm prints the object itself.
+        const parsed = Array.isArray(answer) ? answer[0] : answer;
+        const latest = textField(parsed, 'dist-tags.latest');
+        return latest === null ? UNREACHABLE : { state: 'found', latest, created: textField(parsed, 'time.created') };
+    }
+    catch {
+        return UNREACHABLE;
+    }
+};
+/**
+ * `pip index versions <name>` prints `name (latest)` first. It states no dates, so a Python name's age stays unknown. A Python name never reads
+ * `not-found`: pip prints "No matching distribution" for a missing name and for a down index alike, so the line cannot tell them apart.
+ */
+export const readPipIndex = (run) => {
+    if (run.code !== 0)
+        return UNREACHABLE;
+    const latest = /^\S+ \(([^)]+)\)/m.exec(run.stdout)?.[1];
+    return latest === undefined ? UNREACHABLE : { state: 'found', latest, created: null };
+};
+/**
+ * How a manager is started. `cwd` comes from a transcript, and `cmd.exe` searches the current directory before PATH, so `NoDefaultCurrentDirectoryInExePath`
+ * keeps an `npm.cmd` left there from running: nothing here runs package code.
+ */
+export const managerOptions = (cwd, platform = process.platform, timeout = TIMEOUT_MS) => ({
+    cwd,
+    timeout,
+    shell: platform === 'win32',
+    windowsHide: true,
+    encoding: 'utf8',
+    env: { ...process.env, NoDefaultCurrentDirectoryInExePath: '1' },
+});
+/**
+ * Stops a manager and what it started. On Windows `shell: true` puts `cmd.exe` first, and killing it leaves the manager running, so the whole tree goes (`taskkill /T`); elsewhere
+ * the manager is the child itself.
+ */
+export const stopTree = (child, platform = process.platform, start = spawn) => {
+    if (platform === 'win32' && child.pid !== undefined) {
+        start('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true }).on('error', () => undefined);
+        return;
+    }
+    child.kill();
+};
+const runnerWith = (timeout) => (program, args, cwd, signal) => new Promise((resolve) => {
+    const child = execFile(program, [...args], managerOptions(cwd, process.platform, timeout), (error, stdout, stderr) => {
+        const code = error === null ? 0 : typeof error.code === 'number' ? error.code : null;
+        resolve({ code, stdout, stderr });
+    });
+    if (signal?.aborted === true)
+        stopTree(child);
+    else
+        signal?.addEventListener('abort', () => { stopTree(child); }, { once: true });
+});
+/**
+ * With a deadline the child gets its own: the kill `execFile`'s timeout sends never comes when the caller's process exits first, and npm's default fetch retries run
+ * for minutes against an unreachable registry. Without one (a replay) the manager keeps its defaults.
+ */
+const npmLimits = (timeout) => (timeout === undefined ? [] : [`--fetch-timeout=${String(timeout)}`, '--fetch-retries=0']);
+/** pip counts its socket timeout in whole seconds. */
+const pipLimits = (timeout) => (timeout === undefined ? [] : ['--timeout', String(Math.ceil(timeout / 1000)), '--retries', '0']);
+/** The reader the option uses. `npm view` and `pip index` run no package code; the manager's own cache is the manager's. */
+export const managerReader = (given, timeout) => async ({ class: cls, name, cwd, signal }) => {
+    const run = given ?? runnerWith(timeout ?? TIMEOUT_MS);
+    if (!askable(cls, name))
+        return UNREACHABLE;
+    if (cls === 'npm-package')
+        return readNpmView(await run('npm', ['view', name, 'dist-tags.latest', 'time.created', '--json', '--logs-max=0', ...npmLimits(timeout)], cwd, signal));
+    return readPipIndex(await run('pip', ['index', 'versions', name, '--disable-pip-version-check', ...pipLimits(timeout)], cwd, signal));
+};

package/dist/gate/replay.d.ts

@@ -0,0 +1,20 @@
+import { type SessionsRuntime } from '../sessions/store.js';
+import { type RunRow } from './record.js';
+import { type RegistryReader } from './registry.js';
+export declare const crossingsFile: (storeDir: string) => string;
+export declare const REGISTRY_NOT_READ = "registry state not read";
+export interface ReplayOptions {
+    /** Project folders to read; empty means the saved allowlist. */
+    allow: readonly string[];
+    /** Only with `--registry-state`. Absent, nothing leaves this machine. */
+    registry?: RegistryReader;
+    now: () => number;
+}
+export interface ReplayResult {
+    run: RunRow;
+    file: string;
+    text: string;
+}
+/** A kept registry answer older than this many days is asked again: a `latest` goes stale, and a row would otherwise read "as of this run" forever. */
+export declare const REGISTRY_MAX_DAYS = 30;
+export declare const replay: (runtime: Pick<SessionsRuntime, "storeDir" | "projectsRoot">, options: ReplayOptions) => Promise<ReplayResult>;

package/dist/gate/replay.js

@@ -0,0 +1,257 @@
+// `oars gate replay`: the crossing checks over logs already on disk. It reads raw transcripts under the allowlist and writes one file, `crossings.jsonl`.
+// It never calls `localSalt` or the step log, both of which write, and it holds no store lock, since a replay touches nothing a deposit reads.
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CliError, ExitCode } from '../errors.js';
+import { compileAllow } from '../sessions/allow.js';
+import { makeRedactor } from '../sessions/redact.js';
+import { paths, readState, writeAtomic } from '../sessions/store.js';
+import { GATE_VERSION, liveCrossings, mergeCrossings, parseRows } from './record.js';
+import { askable } from './registry.js';
+import { withLocalBin } from './local-bin.js';
+import { ageOf, againstLatestOf, askedOf, DAY_MS } from './registry-state.js';
+import { scopesOf, seedIndex } from './novelty.js';
+import { repositoryOf } from './scope.js';
+import { discover, readCalls, readOrigins } from './transcripts.js';
+export const crossingsFile = (storeDir) => join(storeDir, 'crossings.jsonl');
+export const REGISTRY_NOT_READ = 'registry state not read';
+/** A failed install is looked at for this many calls after it. */
+const NEXT_WINDOW = 10;
+const REGISTRY_WORKERS = 4;
+/** A kept registry answer older than this many days is asked again: a `latest` goes stale, and a row would otherwise read "as of this run" forever. */
+export const REGISTRY_MAX_DAYS = 30;
+const keyOf = (crossing) => `${crossing.class}\0${crossing.name}`;
+const PACKAGE_CLASSES = new Set(['npm-package', 'python-package']);
+const nextOf = (found, read) => {
+    if (found.status === 'ok')
+        return 'proceeded';
+    if (found.status === 'none')
+        return 'no-result';
+    const end = found.call + NEXT_WINDOW;
+    const { crossing } = found;
+    const later = read.found.find((one) => one.call > found.call && one.call <= end && one.crossing.class === crossing.class && (one.crossing.name === crossing.name || PACKAGE_CLASSES.has(crossing.class)));
+    if (read.pipes.some((call) => call > found.call && call <= end && (later === undefined || call < later.call)))
+        return 'routed-around';
+    if (later === undefined)
+        return 'stopped';
+    if (later.crossing.name !== crossing.name)
+        return 'changed-name';
+    return later.crossing.program === crossing.program && later.crossing.form === crossing.form ? 'retried' : 'routed-around';
+};
+const originsOf = async (transcript, read) => {
+    const firstLines = new Map();
+    const servers = new Set();
+    for (const { crossing, line } of read.found) {
+        if (!firstLines.has(crossing.name))
+            firstLines.set(crossing.name, line);
+        if (crossing.class === 'mcp-server')
+            servers.add(crossing.name);
+    }
+    return firstLines.size === 0 ? { origins: new Map(), prompted: new Set() } : readOrigins(transcript.file, firstLines, servers);
+};
+const byTime = (one, two) => {
+    if (one.ts === two.ts)
+        return 0;
+    if (one.ts === null)
+        return 1;
+    if (two.ts === null)
+        return -1;
+    return one.ts < two.ts ? -1 : 1;
+};
+/** The widest scope in which this is the first use, read in time order so a run's result does not depend on the order folders list in. */
+const noveltyWalker = () => {
+    const fleet = new Set();
+    const repositories = new Set();
+    const sessions = new Set();
+    return (held) => {
+        const key = keyOf(held.found.crossing);
+        const inRepository = `${repositoryOf(held.transcript.project)}\0${key}`;
+        const inSession = `${held.transcript.session}\0${key}`;
+        let novelty = 'none';
+        if (!fleet.has(key))
+            novelty = 'fleet';
+        else if (!repositories.has(inRepository))
+            novelty = 'repository';
+        else if (!sessions.has(inSession))
+            novelty = 'session';
+        fleet.add(key);
+        repositories.add(inRepository);
+        sessions.add(inSession);
+        return novelty;
+    };
+};
+const lastRemovals = (removals) => {
+    const last = new Map();
+    for (const { removal, transcript } of removals) {
+        if (removal.status === 'error' || removal.status === 'refused' || removal.ts === null)
+            continue;
+        const key = `${repositoryOf(transcript.project)}\0${keyOf(removal.removal)}`;
+        if ((last.get(key) ?? '') < removal.ts)
+            last.set(key, removal.ts);
+    }
+    return last;
+};
+const asAnswer = (row) => ({ state: row.state, latest: row.latest, created: row.created });
+const isFolder = (path) => stat(path).then((found) => found.isDirectory(), () => false);
+/** A command, its environment, or an earlier `cd` chose that call's registry or config: the gate cannot read it from here, so the name is not asked, kept answers included. */
+const unaskedKeys = (rows) => new Set(rows.filter(({ found }) => !found.crossing.registryAsked).map(({ found }) => keyOf(found.crossing)));
+/** One question per name, from the first call whose folder still exists: the manager reads its registry from there, and a guess at another folder could ask the wrong one. */
+const askRegistry = async (rows, reader, cached) => {
+    const unasked = unaskedKeys(rows);
+    const answers = new Map([...cached].filter(([key]) => !unasked.has(key)).map(([key, row]) => [key, asAnswer(row)]));
+    const folders = new Map();
+    const asks = new Map();
+    for (const { found } of rows) {
+        const { crossing, cwd } = found;
+        const key = keyOf(crossing);
+        if (cwd === null || unasked.has(key) || answers.has(key) || asks.has(key) || crossing.versionForm === 'url' || !askedOf(crossing) || !askable(crossing.class, crossing.name))
+            continue;
+        const exists = folders.get(cwd) ?? (await isFolder(cwd));
+        folders.set(cwd, exists);
+        if (exists)
+            asks.set(key, { class: crossing.class, name: crossing.name, cwd });
+    }
+    const queue = [...asks];
+    const worker = async () => {
+        for (let item = queue.shift(); item !== undefined; item = queue.shift()) {
+            const [key, ask] = item;
+            answers.set(key, await reader(ask).catch(() => ({ state: 'unreachable', latest: null, created: null })));
+        }
+    };
+    await Promise.all(Array.from({ length: REGISTRY_WORKERS }, worker));
+    return answers;
+};
+const recordOf = (held, novelty, removedAt, answers) => {
+    const { found, transcript, origin, prompted, next } = held;
+    const { crossing, ts, side } = found;
+    // An answer reaches a row only when that row's own program was asked and its command left the registry to the default: the same name can cross twice.
+    const answer = askedOf(crossing) ? answers?.get(keyOf(crossing)) : undefined;
+    return {
+        kind: 'crossing',
+        v: GATE_VERSION,
+        via: 'replay',
+        day: ts === null ? null : ts.slice(0, 10),
+        class: crossing.class,
+        form: crossing.form,
+        program: crossing.program,
+        versionForm: crossing.versionForm,
+        statusReports: crossing.statusReports,
+        origin,
+        novelty,
+        // The operator named it only on the main line: a subagent's prompt is another model's words.
+        decidedBy: prompted && !side ? 'operator' : 'agent',
+        permission: found.permission,
+        status: found.status,
+        next,
+        removedLater: removedAt !== undefined && ts !== null && ts < removedAt,
+        depth: side ? 'subagent' : 'main',
+        miss: found.miss,
+        againstLatest: answer === undefined ? 'not-read' : againstLatestOf(crossing, answer),
+        registryState: answer?.state ?? 'not-read',
+        registryAge: answer === undefined ? 'not-read' : ageOf(answer, ts),
+        arm: 'none',
+        lineShown: 'none',
+        lineHeld: 'none',
+        session: transcript.session,
+        agent: transcript.agent,
+        toolUseId: found.toolUseId,
+        ts,
+        name: crossing.name,
+        version: crossing.version,
+    };
+};
+const cachedAnswers = async (file, now) => {
+    const text = await readFile(file, 'utf8').catch(() => '');
+    return new Map(parseRows(text)
+        .filter((row) => row.kind === 'registry' && (now - Date.parse(row.day)) / DAY_MS <= REGISTRY_MAX_DAYS)
+        .map((row) => [keyOf(row), row]));
+};
+const registryRows = (answers, rows, cached, day) => {
+    const added = new Map();
+    const unasked = unaskedKeys(rows);
+    for (const { found } of rows) {
+        const key = keyOf(found.crossing);
+        const answer = answers.get(key);
+        // An unreachable registry says nothing about the name, so a later run asks again.
+        if (cached.has(key) || added.has(key) || answer === undefined || answer.state === 'unreachable')
+            continue;
+        added.set(key, { kind: 'registry', v: GATE_VERSION, day, class: found.crossing.class, state: answer.state, created: answer.created, name: found.crossing.name, latest: answer.latest });
+    }
+    return [...[...cached].filter(([key]) => !unasked.has(key)).map(([, row]) => row), ...added.values()];
+};
+const summaryText = (run, file) => [
+    `Read ${String(run.transcripts)} transcripts (${String(run.unreadable)} unreadable, ${String(run.badLines)} torn lines) and ${String(run.calls)} tool calls.`,
+    `Crossings: ${String(run.crossings)}. Written to ${file}.`,
+    run.registryRead ? 'Registry state read through the package manager, as of this run, not as of each crossing.' : REGISTRY_NOT_READ,
+    'Counts: oars gate report',
+].join('\n');
+const readAll = async (runtime, entries, domains) => {
+    const redact = makeRedactor(domains);
+    const { files, unreadable: unlisted } = await discover([runtime.projectsRoot, paths(runtime.storeDir).raw], compileAllow(entries));
+    const seen = new Map();
+    const reads = [];
+    let unreadable = unlisted;
+    for (const transcript of files) {
+        try {
+            reads.push({ transcript, read: await readCalls(transcript.file, transcript.agent, redact, seen) });
+        }
+        catch {
+            unreadable += 1;
+        }
+    }
+    // A folder's own bin is read once the whole record is in, so `nextOf` below sees the form the row will carry.
+    const memo = new Map();
+    for (const { read } of reads) {
+        for (const [at, found] of read.found.entries())
+            read.found[at] = { ...found, crossing: await withLocalBin(found.crossing, found.cwd, memo) };
+    }
+    return { reads, transcripts: files.length, unreadable };
+};
+export const replay = async (runtime, options) => {
+    const state = await readState(runtime.storeDir);
+    const entries = options.allow.length > 0 ? options.allow : state.allow;
+    if (entries.length === 0)
+        throw new CliError('Name a folder with --allow: nothing is read from a folder you have not named, and no deposit has saved an allowlist.', ExitCode.USAGE, 'usage');
+    const { reads, transcripts, unreadable } = await readAll(runtime, entries, state.redactDomains);
+    const held = [];
+    for (const { transcript, read } of reads) {
+        const { origins, prompted } = await originsOf(transcript, read).catch(() => ({ origins: new Map(), prompted: new Set() }));
+        for (const found of read.found)
+            held.push({ found, transcript, origin: origins.get(found.crossing.name) ?? 'none-seen', prompted: prompted.has(found.crossing.name), next: nextOf(found, read) });
+    }
+    held.sort((one, two) => byTime(one.found, two.found));
+    const removedAt = lastRemovals(reads.flatMap(({ transcript, read }) => read.removals.map((removal) => ({ removal, transcript }))));
+    const file = crossingsFile(runtime.storeDir);
+    const cached = await cachedAnswers(file, options.now());
+    const answers = options.registry === undefined ? undefined : await askRegistry(held, options.registry, cached);
+    const novelty = noveltyWalker();
+    const records = held.map((one) => recordOf(one, novelty(one), removedAt.get(`${repositoryOf(one.transcript.project)}\0${keyOf(one.found.crossing)}`), answers));
+    const unread = {};
+    for (const { read } of reads) {
+        for (const shape of read.unread)
+            unread[shape] = (unread[shape] ?? 0) + 1;
+    }
+    const day = new Date(options.now()).toISOString().slice(0, 10);
+    const run = {
+        kind: 'run',
+        v: GATE_VERSION,
+        day,
+        transcripts,
+        unreadable,
+        badLines: reads.reduce((sum, { read }) => sum + read.badLines, 0),
+        calls: reads.reduce((sum, { read }) => sum + read.fresh, 0),
+        crossings: records.length,
+        unread,
+        registryRead: options.registry !== undefined,
+    };
+    const registry = registryRows(answers ?? new Map(), held, cached, day);
+    // The file is read again here, as late as it can be, so a row the hook appended while the transcripts were read is kept, not overwritten.
+    const live = liveCrossings(parseRows(await readFile(file, 'utf8').catch(() => '')));
+    await writeAtomic(file, `${[run, ...registry, ...mergeCrossings(records, live)].map((row) => JSON.stringify(row)).join('\n')}\n`);
+    // The hook reads novelty from a kept index, not from this file; every name a transcript showed is in it, in the scopes the hook names them in.
+    await seedIndex(runtime.storeDir, file, held.flatMap((one) => {
+        const scopes = scopesOf(keyOf(one.found.crossing), repositoryOf(one.transcript.project), one.transcript.session);
+        return [scopes.fleet, scopes.repository, scopes.session];
+    }));
+    return { run, file, text: summaryText(run, file) };
+};

package/dist/gate/report.d.ts

@@ -0,0 +1,50 @@
+import { type Row } from './record.js';
+export interface Tally {
+    value: string;
+    count: number;
+}
+export interface ClassCount {
+    class: string;
+    form: string;
+    count: number;
+    distinct: number;
+}
+export interface Report {
+    ok: true;
+    transcripts: number;
+    unreadable: number;
+    badLines: number;
+    calls: number;
+    crossings: number;
+    /** Whether a replay has run: when it has not, only the hook's rows are here and the transcript fields read `not-read`. */
+    replayed: boolean;
+    registryRead: boolean;
+    via: Tally[];
+    classes: ClassCount[];
+    origin: Tally[];
+    novelty: Tally[];
+    decidedBy: Tally[];
+    permission: Tally[];
+    status: Tally[];
+    next: Tally[];
+    miss: Tally[];
+    depth: Tally[];
+    againstLatest: Tally[];
+    registryState: Tally[];
+    registryAge: Tally[];
+    /** Whether a note that would show did (`shown`) or was held back (`held`); `none` is every row with no note to show, and every block. */
+    arm: Tally[];
+    /** The fixed id of the line a row showed. */
+    lineShown: Tally[];
+    /** The fixed id of the line a held note withheld. */
+    lineHeld: Tally[];
+    /** Which policy stood for the rows the hook wrote: no file, a file that fit, or one that did not (the defaults stood). Rows with no policy read (replay) are not counted. */
+    policy: Tally[];
+    removedLater: number;
+    unseen: Tally[];
+    limits: string[];
+}
+/** What a replay of logs on disk cannot see, said every time so a count is never read as the whole. */
+export declare const LIMITS: readonly string[];
+export declare const reportOf: (rows: readonly Row[]) => Report;
+export declare const formatReport: (report: Report) => string;