@manyoars/oars 0.1.1 → 0.3.0

package/dist/gate/command.js

@@ -0,0 +1,61 @@
+// The `oars gate` command group's bodies: each returns the `--json` document and the text a human sees.
+import { readFile } from 'node:fs/promises';
+import { CliError, ExitCode } from '../errors.js';
+import { crossingsPath } from './hook.js';
+import { COMMAND, EVENT, installGateHook, MATCHER, uninstallGateHook } from './install.js';
+import { loadIndex } from './novelty.js';
+import { formatPolicy, loadPolicy, policyPath } from './policy.js';
+import { parseRows } from './record.js';
+import { formatReport, reportOf } from './report.js';
+import { crossingsFile, replay } from './replay.js';
+const runtimeOf = (deps) => {
+    if (deps.sessions === undefined)
+        throw new CliError('The session store is not configured in this run.', ExitCode.UNEXPECTED, 'unexpected');
+    return deps.sessions;
+};
+/** Reads local logs only; a `registry` reader is passed solely by `--registry-state`. */
+export const gateReplay = async (deps, options) => {
+    const done = await replay(runtimeOf(deps), { allow: options.allow, now: deps.now, ...(options.registry === undefined ? {} : { registry: options.registry }) });
+    return { document: { ok: true, run: done.run, file: done.file }, text: done.text };
+};
+export const gateReport = async (deps) => {
+    const text = await readFile(crossingsFile(runtimeOf(deps).storeDir), 'utf8').catch(() => '');
+    const rows = parseRows(text);
+    if (!rows.some((row) => row.kind === 'run' || row.kind === 'crossing')) {
+        throw new CliError('No crossings have been recorded yet: run `oars gate install` to record them as they happen, or `oars gate replay --allow <folder>` to find the ones already in your logs.', ExitCode.USAGE, 'usage');
+    }
+    const report = reportOf(rows);
+    return { document: report, text: formatReport(report) };
+};
+const installOf = (deps) => {
+    if (deps.install === undefined)
+        throw new CliError('Hook install is not configured in this run.', ExitCode.UNEXPECTED, 'unexpected');
+    return deps.install;
+};
+/** User scope only: the one place the harness reads for every project, and the one place this command ever writes. */
+export const gateInstall = async (deps) => {
+    const file = installOf(deps).userSettings;
+    const result = await installGateHook(file);
+    const lines = [
+        result.changed
+            ? `Installed the gate hook in ${file}: ${EVENT} for ${MATCHER}, running \`${COMMAND}\`. It records each crossing in crossings.jsonl, adds a note about a young or missing name by default, and denies a call only if you write \`block\` in gate-policy.json; it never allows or changes a call.`
+            : `The gate hook is already installed in ${file}; nothing was changed.`,
+    ];
+    // A record with no kept index cannot tell what is new without a scan the hook must not do, so it reads `not-read` until a replay seeds the index.
+    const storeDir = deps.sessions?.storeDir;
+    if (storeDir !== undefined && (await loadIndex(storeDir, crossingsPath(storeDir))).state === 'unseeded') {
+        lines.push('Run `oars gate replay --allow <folder>` once to seed the novelty index; until then the hook records novelty as not-read and shows no note.');
+    }
+    return { document: { ok: true, file, changed: result.changed, event: EVENT, matcher: MATCHER, command: COMMAND }, text: lines.join('\n') };
+};
+/** The policy in force for this store: the file's settings, or the defaults and why. Reads one file, writes none. */
+export const gatePolicy = async (deps) => {
+    const storeDir = runtimeOf(deps).storeDir;
+    const read = await loadPolicy(storeDir);
+    return { document: { ok: true, file: policyPath(storeDir), source: read.source, policy: read.policy }, text: formatPolicy(read, policyPath(storeDir)) };
+};
+export const gateUninstall = async (deps) => {
+    const result = await uninstallGateHook(installOf(deps).userSettings);
+    const text = result.removed ? `Removed the gate hook from ${result.file}; other settings and hooks are untouched, and crossings.jsonl stays.` : `No gate hook in ${result.file}.`;
+    return { document: { ok: true, ...result }, text };
+};

package/dist/gate/hook-fill-main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/gate/hook-fill-main.js

@@ -0,0 +1,16 @@
+// The entry the hook starts, detached, after a cut ask: `node hook-fill-main.js <storeDir> <class> <name> <cwd>`. It prints nothing, answers nothing, and exits 0 whatever
+// happens; nobody waits on it.
+import { CROSSING_CLASSES } from './checks.js';
+import { FILL_TIMEOUT_MS, runFill } from './hook-fill.js';
+import { managerReader } from './registry.js';
+const [storeDir, cls, name, cwd] = process.argv.slice(2);
+const known = CROSSING_CLASSES.find((one) => one === cls);
+try {
+    if (storeDir !== undefined && known !== undefined && name !== undefined && cwd !== undefined) {
+        await runFill(storeDir, { class: known, name, cwd }, { registry: managerReader(undefined, FILL_TIMEOUT_MS), now: Date.now });
+    }
+}
+catch {
+    // Fail-open: an answer that cannot be kept is asked about again.
+}
+process.exit(0);

package/dist/gate/hook-fill.d.ts

@@ -0,0 +1,38 @@
+import type { CrossingClass } from './checks.js';
+import { type RegistryReader } from './registry.js';
+export interface FillAsk {
+    class: CrossingClass;
+    name: string;
+    cwd: string;
+}
+/** The helper gives the manager this long. A lock younger than five minutes keeps a second helper from starting, whether the first is still asking or has failed. */
+export declare const FILL_TIMEOUT_MS = 15000;
+export declare const FILL_LOCK_MS = 300000;
+/** Whether a helper holds the name now: the lock is there and younger than `FILL_LOCK_MS`. The hook asks nothing of the manager itself while it is, so one name has one ask. */
+export declare const isLocked: (storeDir: string, ask: Pick<FillAsk, "class" | "name">, now: number) => Promise<boolean>;
+/**
+ * Takes the lock back: a helper that never started will never release it, and the name would go unasked until `FILL_LOCK_MS` passed. Synchronous, like `create`, so a deadline's
+ * `exit(0)` cannot end the process between the failed start and the removal.
+ */
+export declare const releaseLock: (storeDir: string, ask: Pick<FillAsk, "class" | "name">) => void;
+/** The part of `child_process.spawn` the helper start uses, so a test can hand in a child that fails to start. */
+export type HelperSpawn = (command: string, args: string[], options: {
+    detached: true;
+    stdio: 'ignore';
+    windowsHide: true;
+}) => {
+    on: (event: 'error', listener: () => void) => unknown;
+    unref: () => void;
+};
+/** The helper outlives the hook: detached, no stdio, never waited on, so the harness's call does not wait for it either. One that cannot start never releases its lock, so the lock goes on its `error`. */
+export declare const startHelper: (spawn: HelperSpawn, storeDir: string, ask: FillAsk) => void;
+/**
+ * Called by the hook after a cut ask: takes the lock and starts the helper. Nothing here throws into the hook: a store that cannot be written, or a helper that cannot
+ * start, is an answer that does not come. The lock goes when the start throws, so the next sight asks about the name again.
+ */
+export declare const startFill: (storeDir: string, ask: FillAsk, now: number, start: (storeDir: string, ask: FillAsk) => void) => Promise<void>;
+/** The helper's work: ask, and keep a `found` or `not-found` answer in the cache. The lock goes once an answer is kept; after a failure it stays, so a down registry is asked about at most every five minutes. */
+export declare const runFill: (storeDir: string, ask: FillAsk, deps: {
+    registry: RegistryReader;
+    now: () => number;
+}) => Promise<void>;

package/dist/gate/hook-fill.js

@@ -0,0 +1,94 @@
+// The fill: a registry ask the hook had to cut is finished by a helper process that outlives the hook and writes the answer to the hook's cache, so the next sight of the
+// name reads it inside the budget. The helper calls the installed manager as the hook does (`managerReader`), contacts nothing the manager would not, and a failed or
+// unreachable ask writes nothing. One ask per name at a time: a lock file in the store, dated by its mtime, is taken before the helper starts.
+import { createHash } from 'node:crypto';
+import { rmSync, writeFileSync } from 'node:fs';
+import { appendFile, mkdir, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { GATE_VERSION, folderKey } from './record.js';
+import { askable } from './registry.js';
+/** The helper gives the manager this long. A lock younger than five minutes keeps a second helper from starting, whether the first is still asking or has failed. */
+export const FILL_TIMEOUT_MS = 15_000;
+export const FILL_LOCK_MS = 300_000;
+const lockPath = (storeDir, ask) => join(storeDir, `gate-ask-${createHash('sha256').update(`${ask.class}\0${ask.name}`).digest('hex').slice(0, 16)}.lock`);
+/**
+ * Creates the lock, failing if it exists: of two hooks racing for the name, one wins. It is synchronous so the lock never exists across a turn of the event loop before the
+ * helper starts: a deadline timer firing in such a turn would end the hook with a lock held and nothing behind it.
+ */
+const create = (path) => {
+    try {
+        writeFileSync(path, '', { mode: 0o600, flag: 'wx' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Takes the name's lock. False when a younger one is held; an older one is a helper that died, and is taken over. */
+const takeLock = async (path, now) => {
+    if (create(path))
+        return true;
+    const held = await stat(path).then((found) => found.mtimeMs, () => now);
+    if (now - held < FILL_LOCK_MS)
+        return false;
+    await rm(path, { force: true });
+    return create(path);
+};
+/** Whether a helper holds the name now: the lock is there and younger than `FILL_LOCK_MS`. The hook asks nothing of the manager itself while it is, so one name has one ask. */
+export const isLocked = async (storeDir, ask, now) => {
+    const held = await stat(lockPath(storeDir, ask)).then((found) => found.mtimeMs, () => undefined);
+    return held !== undefined && now - held < FILL_LOCK_MS;
+};
+/**
+ * Takes the lock back: a helper that never started will never release it, and the name would go unasked until `FILL_LOCK_MS` passed. Synchronous, like `create`, so a deadline's
+ * `exit(0)` cannot end the process between the failed start and the removal.
+ */
+export const releaseLock = (storeDir, ask) => {
+    try {
+        rmSync(lockPath(storeDir, ask), { force: true });
+    }
+    catch {
+        // Fail-open: a lock that stays is only a name left unasked until it ages out.
+    }
+};
+/** The helper outlives the hook: detached, no stdio, never waited on, so the harness's call does not wait for it either. One that cannot start never releases its lock, so the lock goes on its `error`. */
+export const startHelper = (spawn, storeDir, ask) => {
+    const child = spawn(process.execPath, [fileURLToPath(new URL('./hook-fill-main.js', import.meta.url)), storeDir, ask.class, ask.name, ask.cwd], { detached: true, stdio: 'ignore', windowsHide: true });
+    child.on('error', () => {
+        releaseLock(storeDir, ask);
+    });
+    child.unref();
+};
+/**
+ * Called by the hook after a cut ask: takes the lock and starts the helper. Nothing here throws into the hook: a store that cannot be written, or a helper that cannot
+ * start, is an answer that does not come. The lock goes when the start throws, so the next sight asks about the name again.
+ */
+export const startFill = async (storeDir, ask, now, start) => {
+    try {
+        await mkdir(storeDir, { recursive: true });
+        if (!(await takeLock(lockPath(storeDir, ask), now)))
+            return;
+        try {
+            start(storeDir, ask);
+        }
+        catch {
+            releaseLock(storeDir, ask);
+        }
+    }
+    catch {
+        // Fail-open.
+    }
+};
+/** The helper's work: ask, and keep a `found` or `not-found` answer in the cache. The lock goes once an answer is kept; after a failure it stays, so a down registry is asked about at most every five minutes. */
+export const runFill = async (storeDir, ask, deps) => {
+    if (!askable(ask.class, ask.name))
+        return;
+    const answer = await deps.registry(ask);
+    if (answer.state === 'unreachable')
+        return;
+    const at = new Date(deps.now()).toISOString();
+    const row = { kind: 'registry', v: GATE_VERSION, day: at.slice(0, 10), ts: at, folder: folderKey(ask.cwd), class: ask.class, state: answer.state, created: answer.created, name: ask.name, latest: answer.latest };
+    await appendFile(join(storeDir, 'gate-registry.jsonl'), `${JSON.stringify(row)}\n`, { mode: 0o600 });
+    await rm(lockPath(storeDir, ask), { force: true });
+};

package/dist/gate/hook-main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/gate/hook-main.js

@@ -0,0 +1,35 @@
+// The entry for `oars gate hook`: it imports the hook and the little it needs, never the CLI. Everything it does is in `hook-process.ts`, which a test can drive; this file
+// only wires the real process into it, and every line of the wiring sits inside the guard that exits 0.
+import { spawn } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { defaultConfigDir } from '../credentials.js';
+import { DEADLINE_MS } from './hook.js';
+import { isLocked, startFill, startHelper } from './hook-fill.js';
+import { runHookProcess } from './hook-process.js';
+import { managerReader } from './registry.js';
+/** The process itself ends this long after `DEADLINE_MS`. */
+const GRACE_MS = 100;
+const readStdin = async () => {
+    process.stdin.setEncoding('utf8');
+    let text = '';
+    for await (const chunk of process.stdin)
+        text += String(chunk);
+    return text;
+};
+const depsFor = (stage) => {
+    const storeDir = join(defaultConfigDir(process.env, process.platform, homedir()), 'oars', 'sessions');
+    return {
+        storeDir,
+        now: Date.now,
+        // `performance.now()` counts from the start of the process, so node's own start is inside the budget.
+        clock: () => performance.now(),
+        deadlineMs: DEADLINE_MS,
+        registry: managerReader(undefined, DEADLINE_MS),
+        fill: (ask) => startFill(storeDir, ask, Date.now(), (dir, one) => { startHelper(spawn, dir, one); }),
+        locked: (ask) => isLocked(storeDir, ask, Date.now()),
+        stage,
+    };
+};
+await runHookProcess({ stdin: readStdin, deps: depsFor, exit: (code) => process.exit(code), write: (text) => new Promise((done) => process.stdout.write(text, () => { done(); })), deadlineMs: DEADLINE_MS + GRACE_MS - performance.now() });

package/dist/gate/hook-process.d.ts

@@ -0,0 +1,14 @@
+import { type GateHookDeps } from './hook.js';
+export interface HookProcess {
+    /** Reads the whole of stdin. Called inside the guard, so a stream that cannot be set up is a failed read, not a crash. */
+    stdin: () => Promise<string>;
+    /** Builds the hook's dependencies, handed the function that records what is about to be written. Called inside the guard. */
+    deps: (stage: NonNullable<GateHookDeps['stage']>) => GateHookDeps;
+    exit: (code: number) => void;
+    /** Writes the hook's answer to stdout and resolves once it is flushed. Absent: nothing is written. */
+    write?: (text: string) => Promise<void>;
+    /** Milliseconds from now until the process ends itself. */
+    deadlineMs: number;
+}
+/** Resolves once `exit(0)` has been called, or never when the deadline timer is what ended the process. */
+export declare const runHookProcess: ({ stdin, deps, exit, write, deadlineMs }: HookProcess) => Promise<void>;

package/dist/gate/hook-process.js

@@ -0,0 +1,64 @@
+// The process behind `oars gate hook`, with every side effect handed in so a test can drive it: stdin in, at most one JSON document out, `exit(0)` whatever happens. A hard deadline ends
+// the process before the harness's own, writing the record it has staged if the write had not finished. Nothing here may throw past `runHookProcess`: exit 1 from a
+// PreToolUse hook is a visible error and exit 2 blocks the tool call, and the hook must never cost a session either.
+import { appendFileSync, readFileSync, statSync } from 'node:fs';
+import { gateHook } from './hook.js';
+import { parseRows } from './record.js';
+/** The staged record is written before anything prints, so when the deadline ends the process with it still staged no note or deny was shown: its crossing rows read as no exposure, since a row cannot be backfilled. A block row has `arm: none` already but names its line, so every crossing row is reset, not only those with an arm. */
+const unprinted = (text) => parseRows(text)
+    .map((row) => `${JSON.stringify(row.kind === 'crossing' ? { ...row, arm: 'none', lineShown: 'none', lineHeld: 'none' } : row)}\n`)
+    .join('');
+const sizeOf = (file) => {
+    try {
+        return statSync(file).size;
+    }
+    catch {
+        return 0;
+    }
+};
+/** Whether the record's own bytes are in the file past the length it had when the record was staged. Another hook's row may have grown the file too, so growth alone proves nothing. */
+const landed = (file, text, size) => {
+    try {
+        return readFileSync(file).subarray(size).includes(text);
+    }
+    catch {
+        return false;
+    }
+};
+/** Resolves once `exit(0)` has been called, or never when the deadline timer is what ended the process. */
+export const runHookProcess = async ({ stdin, deps, exit, write, deadlineMs }) => {
+    // `size` is the file's length when the record was staged: an append that wrote and then stalled has put the record's own bytes past it, and the deadline must not write it again.
+    let staged = null;
+    // The last resort when the process is stuck past its grace: keep the staged record, then go. A write that fails here has nowhere to report, so it is dropped.
+    setTimeout(() => {
+        // The row first: it is the record this timer exists to keep, and the stop can be slow (on Windows it is a `taskkill` spawn at a moment already past the deadline).
+        try {
+            if (staged !== null && !landed(staged.file, staged.text, staged.size))
+                appendFileSync(staged.file, unprinted(staged.text), { mode: 0o600 });
+        }
+        catch {
+            // Fail-open.
+        }
+        // A registry ask still running is then stopped, so the manager the hook started does not outlive it; a stop that throws must not cost the exit.
+        try {
+            staged?.stop?.();
+        }
+        catch {
+            // Fail-open.
+        }
+        exit(0);
+    }, Math.max(deadlineMs, 0)).unref();
+    try {
+        const built = deps((pending) => {
+            staged = pending === null ? null : { ...pending, size: sizeOf(pending.file) };
+        });
+        const output = await gateHook(await stdin(), built);
+        if (output !== '')
+            await write?.(output);
+    }
+    catch {
+        // Fail-open: a throw anywhere above is a record not written, never an exit code.
+    }
+    // A manager the registry ask started can outlive the ask; leaving by `exit` rather than waiting for it is what keeps the call under a second.
+    exit(0);
+};

package/dist/gate/hook.d.ts

@@ -0,0 +1,46 @@
+import type { FillAsk } from './hook-fill.js';
+import { type RegistryReader } from './registry.js';
+/** Where the crossings go. Named here, not imported from `replay.ts`, which reads transcripts and would be loaded for nothing. */
+export declare const crossingsPath: (storeDir: string) => string;
+/** The hook's kept registry answers, small and its own: reading the record for them would scan it. */
+export declare const registryCachePath: (storeDir: string) => string;
+/** The registry ask is cut at this many ms on the process clock, less a write reserve; `hook-main.ts` ends the process a short grace after it, so the whole call is under a second. */
+export declare const DEADLINE_MS = 800;
+/** A registry answer the hook kept is used for this many days. A `latest` is read "as of the crossing", so an older one is asked again. */
+export declare const HOOK_REGISTRY_DAYS = 1;
+/** A not-found answer is trusted this long: a name can be published any minute, and a block rests on the answer. */
+export declare const NOT_FOUND_MS = 600000;
+export interface GateHookDeps {
+    storeDir: string;
+    now: () => number;
+    /** The process clock: ms since the process started in the entry, so the deadline counts node's own start. */
+    clock: () => number;
+    /** The whole hook ends by this many ms on `clock`. */
+    deadlineMs: number;
+    /** The draw for the holdback, in [0, 1). Absent: `Math.random`. */
+    random?: () => number;
+    /** Asks the package manager. Absent: no question is ever asked. */
+    registry?: RegistryReader;
+    /** Appends text to a file. Replaceable so a full disk can be tried. */
+    append?: (file: string, text: string) => Promise<void>;
+    /** Called with the name whose ask was cut or had no time to start, so a helper can finish it and fill the cache for the next sight. Absent: nothing is finished. */
+    fill?: (ask: FillAsk) => Promise<void>;
+    /** Whether a helper already holds the name, which keeps the hook from asking the manager a second time. Absent: never locked. */
+    locked?: (ask: FillAsk) => Promise<boolean>;
+    /**
+     * Told what is about to be written (and `null` once it is), so a process that must stop at a hard deadline can write the record it has. While a registry ask is live the record
+     * is the rows so far plus a not-read row for the crossing asked about, with `stop` ending that ask: a process cut off mid-ask stops it and leaves one row, not a manager running unseen.
+     */
+    stage?: (pending: {
+        file: string;
+        text: string;
+        stop?: () => void;
+    } | null) => void;
+}
+/**
+ * Records the crossings of one tool call. Resolves with the JSON to print: a note as context, or a deny labeled with the fact; never an allow or a changed call.
+ * Nothing is written, and no network is touched, for a call that crosses nothing.
+ */
+export declare const runGateHook: (stdin: string, deps: GateHookDeps) => Promise<string>;
+/** What the hook writes to stdout: the JSON of a note or a deny, or '' when silent and on any failure, so the call runs as asked. */
+export declare const gateHook: (stdin: string, deps: GateHookDeps) => Promise<string>;

package/dist/gate/hook.js

@@ -0,0 +1,256 @@
+// `oars gate hook`: the PreToolUse hook that records a crossing as it happens. It records, and says something only when the policy (`policy.ts`) says to: a note, or a deny labeled with a fact. It reads the call the harness hands it, runs the same
+// `checkCall` replay runs, and appends one row per crossing to `crossings.jsonl`; it never allows a call and never changes its input, so the call
+// runs as asked whatever happens here. Every failure is swallowed: malformed input, a missing store, a full disk, a throw. It imports only what it needs, because the
+// harness waits on it before every matching tool call, and it ends before `deadlineMs` however slow the registry is.
+import { appendFile, mkdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { makeRedactor } from '../sessions/redact.js';
+import { checkCall } from './checks.js';
+import { withLocalBin } from './local-bin.js';
+import { decide } from './notes.js';
+import { loadPolicy } from './policy.js';
+import { loadIndex, keepIndex, noveltyOf, scopesOf } from './novelty.js';
+import { GATE_VERSION, folderKey, parseRows, permissionOf } from './record.js';
+import { askable } from './registry.js';
+import { ageOf, againstLatestOf, askedOf, DAY_MS } from './registry-state.js';
+import { repositoryOfCwd } from './scope.js';
+/** Where the crossings go. Named here, not imported from `replay.ts`, which reads transcripts and would be loaded for nothing. */
+export const crossingsPath = (storeDir) => join(storeDir, 'crossings.jsonl');
+/** The hook's kept registry answers, small and its own: reading the record for them would scan it. */
+export const registryCachePath = (storeDir) => join(storeDir, 'gate-registry.jsonl');
+/** The registry ask is cut at this many ms on the process clock, less a write reserve; `hook-main.ts` ends the process a short grace after it, so the whole call is under a second. */
+export const DEADLINE_MS = 800;
+/** A registry answer the hook kept is used for this many days. A `latest` is read "as of the crossing", so an older one is asked again. */
+export const HOOK_REGISTRY_DAYS = 1;
+/** A not-found answer is trusted this long: a name can be published any minute, and a block rests on the answer. */
+export const NOT_FOUND_MS = 600_000;
+/** The room a row's write is given after the registry ask has been cut off. */
+const WRITE_RESERVE_MS = 150;
+/** One call hands at most this many names to helpers; the rest wait for a later sight, so a call naming dozens cannot start dozens of processes. */
+const MAX_HELPERS = 3;
+/** An ask with less than this left is not started: it could not finish. */
+const MIN_ASK_MS = 100;
+const isInput = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const text = (value) => (typeof value === 'string' && value !== '' ? value : null);
+const parse = (stdin) => {
+    try {
+        const parsed = JSON.parse(stdin);
+        return isInput(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+};
+const isFolder = (path) => stat(path).then((found) => found.isDirectory(), () => false);
+/** The organization domains a deposit saved to mask, read only when a call crossed something. */
+const redactDomains = async (storeDir) => {
+    try {
+        const parsed = JSON.parse(await readFile(join(storeDir, 'state.json'), 'utf8'));
+        const domains = isInput(parsed) ? parsed.redactDomains : undefined;
+        return Array.isArray(domains) ? domains.filter((domain) => typeof domain === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+};
+const keyOf = (crossing) => `${crossing.class}\0${crossing.name}`;
+const keptAnswers = async (storeDir) => {
+    const body = await readFile(registryCachePath(storeDir), 'utf8').catch(() => '');
+    const kept = new Map();
+    for (const row of parseRows(body)) {
+        if (row.kind === 'registry')
+            kept.set(keyOf(row), row);
+    }
+    return kept;
+};
+/** A kept answer is dated by its UTC day, so "a day" is that day and the next: at most 48 hours old. Every kept answer is trusted only for the folder that asked, since its config can name another registry and a note says "the registry your package manager uses". A not-found answer is also cut short, since a name can be published any minute. */
+const fresh = (row, now, folder) => row.folder === folder && (row.state === 'not-found' ? row.ts !== undefined && now - Date.parse(row.ts) < NOT_FOUND_MS : now - Date.parse(row.day) < (HOOK_REGISTRY_DAYS + 1) * DAY_MS);
+const within = (promise, ms) => new Promise((resolve) => {
+    const timer = setTimeout(() => {
+        resolve(undefined);
+    }, Math.max(ms, 0));
+    promise.then((value) => {
+        clearTimeout(timer);
+        resolve(value);
+    }, () => {
+        clearTimeout(timer);
+        resolve(undefined);
+    });
+});
+/** What is left for a registry ask on the process clock, less the room a row's write is given. */
+const budgetOf = (deps) => deps.deadlineMs - WRITE_RESERVE_MS - deps.clock();
+const asAnswer = (row) => ({ state: row.state, latest: row.latest, created: row.created });
+/** The registry state at the moment: a kept answer first, else one bounded ask. `undefined` is "not read": not asked, not askable, or not answered in time. */
+const registryAnswer = async (deps, crossing, cwd, kept, helpers, hold) => {
+    if (!askedOf(crossing) || crossing.versionForm === 'url' || !askable(crossing.class, crossing.name))
+        return undefined;
+    const held = kept.get(keyOf(crossing));
+    if (held !== undefined && cwd !== null && fresh(held, deps.now(), folderKey(cwd)))
+        return { answer: asAnswer(held), asked: false };
+    if (deps.registry === undefined || cwd === null || !(await isFolder(cwd)))
+        return undefined;
+    const ask = { class: crossing.class, name: crossing.name, cwd };
+    // A helper already asks for this name (or failed within the last five minutes): one ask per name, so this sight reads nothing.
+    if ((await deps.locked?.(ask).catch(() => false)) === true)
+        return undefined;
+    const stop = new AbortController();
+    let answer;
+    if (budgetOf(deps) >= MIN_ASK_MS) {
+        // The first sight on a fresh store has no folder yet, and the deadline's synchronous write needs one: made here, before the ask, so a cut-off hook can still leave its row.
+        await mkdir(deps.storeDir, { recursive: true }).catch(() => undefined);
+        hold(() => { stop.abort(); });
+        const pending = deps.registry({ ...ask, signal: stop.signal });
+        // Starting the manager is a blocking spawn that can take a good part of the budget, so the cut counts what is left now, not what was left before the call: read before it, the cut
+        // could land behind the process's own deadline, which ends the process with the ask still running.
+        answer = await within(pending, budgetOf(deps));
+    }
+    if (answer === undefined) {
+        // Not answered in time: the row reads not-read, and a helper finishes the ask so the next sight reads it from the cache. This ask is stopped first, so the manager is never asked twice at once.
+        stop.abort();
+        if (helpers.started < MAX_HELPERS) {
+            helpers.started += 1;
+            await deps.fill?.(ask).catch(() => undefined);
+        }
+        return undefined;
+    }
+    return { answer, asked: true };
+};
+const recordOf = (input, crossing, novelty, read, policy, decision) => ({
+    kind: 'crossing',
+    v: GATE_VERSION,
+    via: 'hook',
+    day: input.ts.slice(0, 10),
+    class: crossing.class,
+    form: crossing.form,
+    program: crossing.program,
+    versionForm: crossing.versionForm,
+    statusReports: crossing.statusReports,
+    // What a transcript gives is not read here and not guessed: replay fills these in.
+    origin: 'not-read',
+    novelty,
+    decidedBy: 'not-read',
+    permission: input.permission,
+    status: 'not-read',
+    next: 'not-read',
+    removedLater: 'not-read',
+    depth: input.agent === null ? 'main' : 'subagent',
+    miss: 'not-read',
+    againstLatest: read === undefined ? 'not-read' : againstLatestOf(crossing, read.answer),
+    registryState: read?.answer.state ?? 'not-read',
+    registryAge: read === undefined ? 'not-read' : ageOf(read.answer, input.ts),
+    arm: decision.arm,
+    lineShown: decision.arm === 'held' ? 'none' : decision.lineId,
+    lineHeld: decision.arm === 'held' ? decision.lineId : 'none',
+    policy,
+    session: input.session,
+    agent: input.agent,
+    toolUseId: input.toolUseId,
+    ts: input.ts,
+    name: crossing.name,
+    version: crossing.version,
+});
+const appendText = async (file, body) => {
+    await mkdir(join(file, '..'), { recursive: true });
+    await appendFile(file, body, { mode: 0o600 });
+};
+/** A row for a note that never reached the agent: no exposure, no arm. Used when a deny prints instead of the note. */
+const withoutExposure = (row) => row.arm === 'none' ? row : { ...row, arm: 'none', lineShown: 'none', lineHeld: 'none' };
+/** A block is a deny whose reason is the label; else the notes are context for the agent. Never an allow, an ask, or a changed input: with neither, nothing is printed. */
+const outputOf = (blocks, notes) => {
+    if (blocks.length > 0)
+        return JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: blocks.join('\n') } });
+    return notes.length > 0 ? JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: notes.join('\n') } }) : '';
+};
+/**
+ * Records the crossings of one tool call. Resolves with the JSON to print: a note as context, or a deny labeled with the fact; never an allow or a changed call.
+ * Nothing is written, and no network is touched, for a call that crosses nothing.
+ */
+export const runGateHook = async (stdin, deps) => {
+    const input = parse(stdin);
+    const tool = text(input.tool_name);
+    const session = text(input.session_id);
+    if (tool === null || session === null)
+        return '';
+    const call = { tool, input: input.tool_input };
+    let check = checkCall(call, makeRedactor());
+    if (check.crossings.length === 0)
+        return '';
+    const domains = await redactDomains(deps.storeDir);
+    if (domains.length > 0)
+        check = checkCall(call, makeRedactor(domains));
+    const append = deps.append ?? appendText;
+    const cwd = text(input.cwd);
+    const ts = new Date(deps.now()).toISOString();
+    const common = { session, toolUseId: text(input.tool_use_id), agent: text(input.agent_id), permission: permissionOf(text(input.permission_mode) ?? 'unknown'), ts };
+    const index = await loadIndex(deps.storeDir, crossingsPath(deps.storeDir));
+    const repository = cwd === null ? '' : await repositoryOfCwd(cwd);
+    const kept = await keptAnswers(deps.storeDir);
+    const { policy, source } = await loadPolicy(deps.storeDir);
+    const random = deps.random ?? Math.random;
+    const blocks = [];
+    const notes = [];
+    const rows = [];
+    const lines = new Set();
+    const answered = [];
+    const binMemo = new Map();
+    const inCall = new Set();
+    const helpers = { started: 0 };
+    for (const seen of check.crossings) {
+        // A project's own bin is a stat walk, local and fast; it runs before the registry ask so a bin that is there is never asked about.
+        const crossing = await withLocalBin(seen, cwd, binMemo);
+        const scopes = scopesOf(keyOf(crossing), repository, session);
+        const { novelty, add, noted: indexed } = noveltyOf(index, scopes);
+        // One name twice in a call is one sight: the repeat reads as noted, so its note does not print again and its row is not a second draw.
+        const key = keyOf(crossing);
+        const noted = indexed || inCall.has(key);
+        inCall.add(key);
+        for (const line of add)
+            lines.add(line);
+        // What a process cut off during this ask writes: the rows so far and a not-read row for this crossing (the cut-off hook prints nothing, so none shows a note).
+        const hold = (stop) => {
+            const unread = recordOf(common, crossing, novelty, undefined, source, { arm: 'none', lineId: 'none', kind: 'none', text: null });
+            deps.stage?.({ file: crossingsPath(deps.storeDir), text: [...rows, unread].map((row) => `${JSON.stringify(row)}\n`).join(''), stop });
+        };
+        const read = await registryAnswer(deps, crossing, cwd, kept, helpers, hold);
+        deps.stage?.(null);
+        const state = read?.answer.state;
+        const answeredState = state === 'found' || state === 'not-found' ? state : undefined;
+        // A sight with no answer (a cut ask, no time, a name not asked, an unreachable registry) spends nothing: the session's note waits for the first sight that has one.
+        if (answeredState !== undefined && !noted)
+            lines.add(scopes.read);
+        if (read?.asked === true && read.answer.state !== 'unreachable') {
+            answered.push({ kind: 'registry', v: GATE_VERSION, day: ts.slice(0, 10), ts, folder: folderKey(cwd ?? ''), class: crossing.class, state: read.answer.state, created: read.answer.created, name: crossing.name, latest: read.answer.latest });
+        }
+        const decision = decide(policy, answeredState === undefined ? undefined : { state: answeredState, created: read?.answer.created ?? null, noted }, deps.now(), random, crossing.name);
+        if (decision.kind === 'block' && decision.text !== null && !blocks.includes(decision.text))
+            blocks.push(decision.text);
+        if (decision.kind === 'note' && decision.text !== null)
+            notes.push(decision.text);
+        rows.push(recordOf(common, crossing, novelty, read, source, decision));
+    }
+    // A call that holds a block prints only the deny, so a note row (shown or held) was never in front of the agent: it reads as no exposure, since a row cannot be backfilled.
+    const written = blocks.length > 0 ? rows.map(withoutExposure) : rows;
+    // The record first: an index line for a row that was never written would call the next crossing of the name old.
+    const record = { file: crossingsPath(deps.storeDir), text: written.map((row) => `${JSON.stringify(row)}\n`).join('') };
+    deps.stage?.(record);
+    try {
+        await append(record.file, record.text);
+    }
+    finally {
+        deps.stage?.(null);
+    }
+    await keepIndex(deps.storeDir, index, [...lines]).catch(() => undefined);
+    if (answered.length > 0)
+        await append(registryCachePath(deps.storeDir), answered.map((row) => `${JSON.stringify(row)}\n`).join('')).catch(() => undefined);
+    return outputOf(blocks, notes);
+};
+/** What the hook writes to stdout: the JSON of a note or a deny, or '' when silent and on any failure, so the call runs as asked. */
+export const gateHook = async (stdin, deps) => {
+    try {
+        return await runGateHook(stdin, deps);
+    }
+    catch {
+        // Fail-open: a recorder that cannot record must not cost a session its tool call.
+    }
+    return '';
+};