@manyoars/oars 0.2.0 → 0.4.0

package/dist/gate/hook.js

@@ -0,0 +1,259 @@
+// `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);
+    }
+    if (blocks.length === 0 && notes.length === 0 && written.some((row) => row.arm === 'held'))
+        deps.ended?.('held');
+    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.
+        deps.ended?.('error');
+    }
+    return '';
+};

package/dist/gate/install.d.ts

@@ -0,0 +1,25 @@
+/** The tools whose calls can cross: shell commands (both shells), skills, and every MCP tool. */
+export declare const MATCHER = "Bash|PowerShell|Skill|mcp__.*";
+export declare const EVENT = "PreToolUse";
+/** Seconds the harness waits for the hook; the hook ends itself in under one, so this is only the ceiling for a cold node start. */
+export declare const TIMEOUT_SECONDS = 5;
+/**
+ * Run by the harness's shell (Git Bash on Windows). `command -v` is a shell builtin, so a missing `oars` costs a few milliseconds and no node start. The harness reads this command's stdout, so what
+ * `oars gate hook` prints (a note or a deny) is passed through, and only when it exits 0: an `oars` with no `gate hook` prints and exits 2, which would block the tool call, so that output is dropped.
+ * The trailing `exit 0` matters for the same reason.
+ */
+export declare const COMMAND = "command -v oars >/dev/null 2>&1 || exit 0; out=$(oars gate hook 2>/dev/null) && printf '%s' \"$out\"; exit 0";
+/** The command an earlier build wrote, which discarded the hook's output. Still ours, so a rerun replaces it and an uninstall removes it. */
+export declare const PREVIOUS_COMMAND = "command -v oars >/dev/null 2>&1 || exit 0; oars gate hook >/dev/null 2>&1; exit 0";
+export interface GateInstallResult {
+    file: string;
+    /** False when the file already held exactly this entry: nothing was written. */
+    changed: boolean;
+}
+/** Unparsable settings are refused by `readSettings` before anything is written. */
+export declare const installGateHook: (path: string) => Promise<GateInstallResult>;
+export interface GateUninstallResult {
+    file: string;
+    removed: boolean;
+}
+export declare const uninstallGateHook: (path: string) => Promise<GateUninstallResult>;

package/dist/gate/install.js

@@ -0,0 +1,126 @@
+// `oars gate install` and `oars gate uninstall`: one PreToolUse entry in Claude Code's user settings that runs `oars gate hook`. The entry is ours when its command is
+// exactly `COMMAND` or `PREVIOUS_COMMAND`, so uninstall removes that entry and nothing else, and every other key and hook in the file is carried through as parsed JSON. The command calls the
+// installed `oars`, never `npx` (which would fetch a package on the hook's clock), and does nothing when `oars` is not on the PATH, so a settings file that outlives the
+// install cannot cost a session its tool calls.
+import { chmod, lstat, mkdir, readlink, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { CliError, ExitCode } from '../errors.js';
+import { readSettings } from '../sessions/install.js';
+/** The tools whose calls can cross: shell commands (both shells), skills, and every MCP tool. */
+export const MATCHER = 'Bash|PowerShell|Skill|mcp__.*';
+export const EVENT = 'PreToolUse';
+/** Seconds the harness waits for the hook; the hook ends itself in under one, so this is only the ceiling for a cold node start. */
+export const TIMEOUT_SECONDS = 5;
+/**
+ * Run by the harness's shell (Git Bash on Windows). `command -v` is a shell builtin, so a missing `oars` costs a few milliseconds and no node start. The harness reads this command's stdout, so what
+ * `oars gate hook` prints (a note or a deny) is passed through, and only when it exits 0: an `oars` with no `gate hook` prints and exits 2, which would block the tool call, so that output is dropped.
+ * The trailing `exit 0` matters for the same reason.
+ */
+export const COMMAND = `command -v oars >/dev/null 2>&1 || exit 0; out=$(oars gate hook 2>/dev/null) && printf '%s' "$out"; exit 0`;
+/** The command an earlier build wrote, which discarded the hook's output. Still ours, so a rerun replaces it and an uninstall removes it. */
+export const PREVIOUS_COMMAND = 'command -v oars >/dev/null 2>&1 || exit 0; oars gate hook >/dev/null 2>&1; exit 0';
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isOwnHook = (hook) => isObject(hook) && (hook.command === COMMAND || hook.command === PREVIOUS_COMMAND);
+const holdsOwn = (group) => isObject(group) && Array.isArray(group.hooks) && group.hooks.some(isOwnHook);
+/** The group we write: our matcher, our one entry. */
+const ownGroup = () => ({ matcher: MATCHER, hooks: [{ type: 'command', command: COMMAND, timeout: TIMEOUT_SECONDS }] });
+/** A group of the operator's, with our entry taken out of it; `[]` when ours was all it held. */
+const remainder = (group) => {
+    const rest = group.hooks.filter((hook) => !isOwnHook(hook));
+    return rest.length === 0 ? [] : [{ ...group, hooks: rest }];
+};
+/** Our group put in the place our entry already holds, or at the end. Placing it where it is keeps a rerun from moving it past a group someone added after it. */
+const withOwn = (groups) => {
+    const first = groups.findIndex(holdsOwn);
+    if (first === -1)
+        return [...groups, ownGroup()];
+    return groups.flatMap((group, at) => {
+        if (!holdsOwn(group))
+            return [group];
+        const kept = remainder(group);
+        return at === first ? [...kept, ownGroup()] : kept;
+    });
+};
+const withoutOwn = (groups) => groups.flatMap((group) => (holdsOwn(group) ? remainder(group) : [group]));
+/** Where a symlink that points at nothing yet would land, so the rename writes the file it names and leaves the link a link. `undefined` when `path` is not a symlink. */
+const danglingTarget = async (path) => {
+    try {
+        return (await lstat(path)).isSymbolicLink() ? resolve(dirname(path), await readlink(path)) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The file as it stands, followed through a symlink (a dotfile manager's), with its permission bits. `mode` is `undefined` when there is no file yet; `target` is then where it will land. */
+const existing = async (path) => {
+    try {
+        const target = await realpath(path);
+        return { target, mode: (await stat(target)).mode & 0o777 };
+    }
+    catch {
+        const target = await danglingTarget(path);
+        return target === undefined ? undefined : { target, mode: undefined };
+    }
+};
+/** Whole and atomic: a half-written settings file would take every other hook in it down too. The temp file sits beside the real target with the file's own mode (0600 when new: `env` can hold secrets), and the rename lands on the resolved path, so a symlinked settings file stays a symlink. The mode is set after the write because the umask masks the one `writeFile` is given; a failed rename leaves no temp file behind. */
+const writeSettings = async (path, settings) => {
+    const found = await existing(path);
+    const target = found?.target ?? path;
+    await mkdir(dirname(target), { recursive: true });
+    const temp = `${target}.${String(process.pid)}.oars-gate.tmp`;
+    const mode = found?.mode ?? 0o600;
+    try {
+        await writeFile(temp, `${JSON.stringify(settings, null, 2)}
+`, { mode });
+        await chmod(temp, mode);
+        await rename(temp, target);
+    }
+    catch (error) {
+        await rm(temp, { force: true });
+        throw error;
+    }
+};
+// A `hooks` key, or a PreToolUse key under it, of another shape is the operator's and this version cannot merge into it: refuse it, and write nothing.
+const hooksOf = (settings, path) => {
+    if (settings.hooks === undefined)
+        return {};
+    if (!isObject(settings.hooks))
+        throw new CliError(`"hooks" in ${path} is not an object; nothing was changed.`, ExitCode.USAGE, 'usage');
+    return settings.hooks;
+};
+const groupsOf = (hooks, path) => {
+    const groups = hooks[EVENT];
+    if (groups === undefined)
+        return [];
+    if (!Array.isArray(groups))
+        throw new CliError(`"hooks.${EVENT}" in ${path} is not a list; nothing was changed.`, ExitCode.USAGE, 'usage');
+    return groups;
+};
+/** Unparsable settings are refused by `readSettings` before anything is written. */
+export const installGateHook = async (path) => {
+    const settings = await readSettings(path);
+    const before = JSON.stringify(settings);
+    const hooks = hooksOf(settings, path);
+    hooks[EVENT] = withOwn(groupsOf(hooks, path));
+    settings.hooks = hooks;
+    if (JSON.stringify(settings) === before)
+        return { file: path, changed: false };
+    await writeSettings(path, settings);
+    return { file: path, changed: true };
+};
+export const uninstallGateHook = async (path) => {
+    const settings = await readSettings(path);
+    const hooks = hooksOf(settings, path);
+    const groups = groupsOf(hooks, path);
+    if (!groups.some(holdsOwn))
+        return { file: path, removed: false };
+    const kept = withoutOwn(groups);
+    // An event this call emptied goes, and so does a `hooks` key it emptied; anything else the operator wrote stays where it was.
+    if (kept.length === 0)
+        Reflect.deleteProperty(hooks, EVENT);
+    else
+        hooks[EVENT] = kept;
+    settings.hooks = Object.keys(hooks).length === 0 ? undefined : hooks;
+    await writeSettings(path, settings);
+    return { file: path, removed: true };
+};

package/dist/gate/local-bin.d.ts

@@ -0,0 +1,8 @@
+import type { Crossing } from './checks.js';
+/** Answers already found, so one folder and bin cost one walk however many calls ask. */
+export type LocalBinMemo = Map<string, Promise<boolean>>;
+/**
+ * The crossing as it should be recorded: `local-bin-run` for an unstated `npx` whose folder, or a parent's, holds the bin, else the crossing itself. A version, a call that chose
+ * its own folder or registry (`registryAsked` false), or an unknown folder leaves the question open, so the crossing stays a fetch-and-run.
+ */
+export declare const withLocalBin: (crossing: Crossing, cwd: string | null, memo: LocalBinMemo) => Promise<Crossing>;

package/dist/gate/local-bin.js

@@ -0,0 +1,36 @@
+// `npx <name>` where the folder already has `node_modules/.bin/<name>` runs the project's own copy and fetches nothing. It is the common case (most main-session `npx` crossings
+// whose folder exists), so it gets its own closed form, `local-bin-run`, and is not counted as a fetch-and-run pick. Live and replay both apply this one rule.
+import { stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+const LEVELS = 12;
+/** A Windows install leaves `.cmd` and `.ps1` shims beside the bare name. */
+const SHIMS = ['', '.cmd', '.ps1'];
+const exists = (path) => stat(path).then(() => true, () => false);
+/** The bin an `npx` name runs: the last segment of a scoped name. */
+const binOf = (name) => name.slice(name.lastIndexOf('/') + 1);
+const walk = async (cwd, bin) => {
+    let folder = cwd;
+    for (let level = 0; level < LEVELS; level += 1) {
+        for (const shim of SHIMS) {
+            if (await exists(join(folder, 'node_modules', '.bin', `${bin}${shim}`)))
+                return true;
+        }
+        const parent = dirname(folder);
+        if (parent === folder)
+            break;
+        folder = parent;
+    }
+    return false;
+};
+/**
+ * The crossing as it should be recorded: `local-bin-run` for an unstated `npx` whose folder, or a parent's, holds the bin, else the crossing itself. A version, a call that chose
+ * its own folder or registry (`registryAsked` false), or an unknown folder leaves the question open, so the crossing stays a fetch-and-run.
+ */
+export const withLocalBin = async (crossing, cwd, memo) => {
+    if (crossing.program !== 'npx' || crossing.form !== 'fetch-and-run' || crossing.versionForm !== 'unstated' || !crossing.registryAsked || cwd === null)
+        return crossing;
+    const key = `${cwd}\0${binOf(crossing.name)}`;
+    const known = memo.get(key) ?? walk(cwd, binOf(crossing.name));
+    memo.set(key, known);
+    return (await known) ? { ...crossing, form: 'local-bin-run' } : crossing;
+};

package/dist/gate/notes.d.ts

@@ -0,0 +1,19 @@
+import type { Policy } from './policy.js';
+import type { Arm, LineId } from './record.js';
+/** The facts a decision reads: what the registry answered, when the name was first published, and whether this session has already had a sight of the name with a reading (`noted`). */
+export interface LineFacts {
+    state: 'found' | 'not-found';
+    created: string | null;
+    noted: boolean;
+}
+export interface Decision {
+    arm: Arm;
+    lineId: LineId;
+    kind: 'block' | 'note' | 'none';
+    text: string | null;
+}
+/** The only words the hook ever shows. Each states what the registry said and nothing about what to do. */
+export declare const LINE_TABLE: Readonly<Record<Exclude<LineId, 'none'>, string>>;
+export declare const lineText: (id: LineId, name: string, days: number) => string;
+/** Silent unless a class fires. A block is for a name the registry answered as not found, only when the policy says `block`, and is never held back. */
+export declare const decide: (policy: Policy, facts: LineFacts | undefined, now: number, random: () => number, name: string) => Decision;

package/dist/gate/notes.js

@@ -0,0 +1,27 @@
+import { DAY_MS } from './registry-state.js';
+/** The only words the hook ever shows. Each states what the registry said and nothing about what to do. */
+export const LINE_TABLE = {
+    'young-name-note': 'Registry note: {name} was first published {age} ago in the registry your package manager uses.',
+    'not-found-note': 'Registry note: {name} was not found in the registry your package manager uses.',
+    'not-found-block': 'Blocked by your gate policy: {name} was not found in the registry your package manager uses.',
+};
+const ageText = (days) => (days < 1 ? 'less than a day' : days === 1 ? '1 day' : `${String(days)} days`);
+export const lineText = (id, name, days) => (id === 'none' ? '' : LINE_TABLE[id].replace('{name}', name).replace('{age}', ageText(days)));
+const NONE = { arm: 'none', lineId: 'none', kind: 'none', text: null };
+/** A note that would show, held back when the draw falls inside the share. The draw is spent on a note only. */
+const note = (policy, lineId, name, days, random) => random() < policy.holdbackPercent / 100 ? { arm: 'held', lineId, kind: 'none', text: null } : { arm: 'shown', lineId, kind: 'note', text: lineText(lineId, name, days) };
+/** Silent unless a class fires. A block is for a name the registry answered as not found, only when the policy says `block`, and is never held back. */
+export const decide = (policy, facts, now, random, name) => {
+    if (facts === undefined)
+        return NONE;
+    if (facts.state === 'not-found') {
+        const action = policy.classes['not-found'];
+        if (action === 'block')
+            return { arm: 'none', lineId: 'not-found-block', kind: 'block', text: lineText('not-found-block', name, 0) };
+        return action === 'warn' && !facts.noted ? note(policy, 'not-found-note', name, 0, random) : NONE;
+    }
+    if (policy.classes['young-name'] !== 'warn' || facts.created === null || facts.noted)
+        return NONE;
+    const days = (now - Date.parse(facts.created)) / DAY_MS;
+    return days >= 0 && days < policy.youngDays ? note(policy, 'young-name-note', name, Math.floor(days), random) : NONE;
+};

package/dist/gate/novelty.d.ts

@@ -0,0 +1,35 @@
+import type { Novelty } from './record.js';
+export declare const INDEX_HEADER = "oars-gate-index 1";
+export declare const indexFile: (storeDir: string) => string;
+/** The entries of one crossing, as the lines the index keeps. `read` is the session's sight of the name that had a registry reading, which is what spends the session's one note. */
+export interface Scopes {
+    fleet: string;
+    repository: string;
+    session: string;
+    read: string;
+}
+/** `key` is the class and name; the repository and session ids are as the caller knows them. */
+export declare const scopesOf: (key: string, repository: string, session: string) => Scopes;
+/**
+ * `ready`: read cleanly. `fresh`: no index and no record, so an empty one is right. `unseeded`: no index but a record exists, so what is new cannot be told without a
+ * scan; `oars gate replay` seeds it. `damaged`: it did not read cleanly, and nothing is written to it.
+ */
+export type KeptIndex = {
+    state: 'ready';
+    lines: ReadonlySet<string>;
+} | {
+    state: 'fresh' | 'unseeded' | 'damaged';
+};
+export declare const loadIndex: (storeDir: string, record: string) => Promise<KeptIndex>;
+export declare const noveltyOf: (index: KeptIndex, scopes: Scopes) => {
+    novelty: Novelty;
+    add: string[];
+    noted: boolean;
+};
+/**
+ * Appends the lines a crossing added. A `fresh` index starts with its header (a second header from a hook racing this one is skipped on read). A torn tail (a line cut off
+ * before its line break) gets one first, so the append is its own lines and the torn one costs only itself.
+ */
+export declare const keepIndex: (storeDir: string, index: KeptIndex, add: readonly string[]) => Promise<void>;
+/** Writes the index from every line given plus the ones already kept, whole and atomic. Used by `replay`, which is not in a hurry. */
+export declare const seedIndex: (storeDir: string, record: string, lines: Iterable<string>) => Promise<void>;

package/dist/gate/novelty.js

@@ -0,0 +1,99 @@
+// The kept index behind the hook's `novelty`: which names have been seen in the whole record, in a repository, and in a session. The hook reads it instead of scanning
+// `crossings.jsonl`, which a long-lived record would make slow. It holds hashes only (a name, a repository, or a session id is never written here), one per line, and a
+// line is only ever appended, so two hooks running at once cannot lose each other's update. A file that does not read cleanly is `damaged`: the row says `not-read`.
+import { createHash } from 'node:crypto';
+import { appendFile, mkdir, open, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const INDEX_HEADER = 'oars-gate-index 1';
+export const indexFile = (storeDir) => join(storeDir, 'gate-index.txt');
+const LINE = /^[frs][0-9a-f]{12}$/;
+const TORN = /^(?:[frs][0-9a-f]{0,11})?$/;
+const digest = (...parts) => createHash('sha256').update(parts.join('\0')).digest('hex').slice(0, 12);
+/** `key` is the class and name; the repository and session ids are as the caller knows them. */
+export const scopesOf = (key, repository, session) => ({
+    fleet: `f${digest(key)}`,
+    repository: `r${digest(repository, key)}`,
+    session: `s${digest(session, key)}`,
+    read: `s${digest(session, key, 'read')}`,
+});
+const notFound = (error) => error instanceof Error && Reflect.get(error, 'code') === 'ENOENT';
+const hasRecord = (file) => stat(file).then((found) => found.size > 0, () => false);
+const parseIndex = (text) => {
+    const parts = text.split('\n');
+    // The last part is empty after a complete line; anything else there is a line that was being appended, and says nothing yet.
+    parts.pop();
+    if (parts[0] !== INDEX_HEADER)
+        return { state: 'damaged' };
+    const lines = new Set();
+    for (const [at, line] of parts.entries()) {
+        if (line === INDEX_HEADER)
+            continue;
+        // A torn line that the next append closed with a line break: a cut-off hash, or an empty line when two appends raced on the same torn tail. Skipped, and only ever before a later line.
+        if (at < parts.length - 1 && TORN.test(line))
+            continue;
+        if (!LINE.test(line))
+            return { state: 'damaged' };
+        lines.add(line);
+    }
+    return { state: 'ready', lines };
+};
+export const loadIndex = async (storeDir, record) => {
+    try {
+        return parseIndex(await readFile(indexFile(storeDir), 'utf8'));
+    }
+    catch (error) {
+        if (!notFound(error))
+            return { state: 'damaged' };
+        return (await hasRecord(record)) ? { state: 'unseeded' } : { state: 'fresh' };
+    }
+};
+export const noveltyOf = (index, scopes) => {
+    // With no readable index there is no telling whether the name was noted, and no line can be kept to say so: it counts as noted, so no note shows until a replay seeds the index. A block does not read `noted`.
+    if (index.state === 'damaged' || index.state === 'unseeded')
+        return { novelty: 'not-read', add: [], noted: true };
+    const held = index.state === 'ready' ? index.lines : new Set();
+    const add = [scopes.fleet, scopes.repository, scopes.session].filter((line) => !held.has(line));
+    const noted = held.has(scopes.read);
+    if (!held.has(scopes.fleet))
+        return { novelty: 'fleet', add, noted };
+    if (!held.has(scopes.repository))
+        return { novelty: 'repository', add, noted };
+    return { novelty: held.has(scopes.session) ? 'none' : 'session', add, noted };
+};
+/** True when the file's last byte is a line break, so an append starts a line of its own. The caller has read the header, so the file is not empty. */
+const endsClean = async (file) => {
+    const handle = await open(file, 'r');
+    try {
+        const { size } = await handle.stat();
+        const last = Buffer.alloc(1);
+        await handle.read(last, 0, 1, size - 1);
+        return last[0] === 0x0a;
+    }
+    finally {
+        await handle.close();
+    }
+};
+/**
+ * Appends the lines a crossing added. A `fresh` index starts with its header (a second header from a hook racing this one is skipped on read). A torn tail (a line cut off
+ * before its line break) gets one first, so the append is its own lines and the torn one costs only itself.
+ */
+export const keepIndex = async (storeDir, index, add) => {
+    if (add.length === 0 || (index.state !== 'ready' && index.state !== 'fresh'))
+        return;
+    await mkdir(storeDir, { recursive: true });
+    const file = indexFile(storeDir);
+    const lead = index.state === 'fresh' ? `${INDEX_HEADER}\n` : (await endsClean(file)) ? '' : '\n';
+    await appendFile(file, `${lead}${add.join('\n')}\n`, { mode: 0o600 });
+};
+/** Writes the index from every line given plus the ones already kept, whole and atomic. Used by `replay`, which is not in a hurry. */
+export const seedIndex = async (storeDir, record, lines) => {
+    const kept = await loadIndex(storeDir, record);
+    const all = new Set(kept.state === 'ready' ? kept.lines : []);
+    for (const line of lines)
+        all.add(line);
+    await mkdir(storeDir, { recursive: true });
+    const file = indexFile(storeDir);
+    const temp = `${file}.${String(process.pid)}.tmp`;
+    await writeFile(temp, `${[INDEX_HEADER, ...all].join('\n')}\n`, { mode: 0o600 });
+    await rename(temp, file);
+};