@manyoars/oars 0.2.0 → 0.3.0

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);
+};

package/dist/gate/policy.d.ts

@@ -0,0 +1,25 @@
+/** The classes the policy sets. Each is something a row can already tell: a registry name first published recently, and a name the registry does not hold. */
+export declare const POLICY_CLASSES: readonly ["young-name", "not-found"];
+export type PolicyClass = (typeof POLICY_CLASSES)[number];
+export declare const POLICY_ACTIONS: readonly ["warn", "block", "off"];
+export type PolicyAction = (typeof POLICY_ACTIONS)[number];
+export interface Policy {
+    classes: Readonly<Record<PolicyClass, PolicyAction>>;
+    /** A name first published fewer days ago than this is a young name. */
+    youngDays: number;
+    /** The share, 0 to 100, of notes that would show and do not. Never applied to a block. */
+    holdbackPercent: number;
+}
+export declare const DEFAULT_POLICY: Policy;
+/** Where a row's policy came from: no file, a file that fit, or a file that was there and did not (so the defaults stood). */
+export declare const POLICY_SOURCES: readonly ["default", "file", "invalid"];
+export type PolicySource = (typeof POLICY_SOURCES)[number];
+export interface PolicyRead {
+    policy: Policy;
+    source: PolicySource;
+}
+export declare const policyPath: (storeDir: string) => string;
+/** Never throws. A file that is not there is the defaults; one that is there and cannot be read or does not fit is the defaults too, and says `invalid`. */
+export declare const loadPolicy: (storeDir: string) => Promise<PolicyRead>;
+/** What `oars gate policy` prints. */
+export declare const formatPolicy: (read: PolicyRead, file: string) => string;

package/dist/gate/policy.js

@@ -0,0 +1,73 @@
+// The gate policy file: what the hook may say, per class, in a closed vocabulary. The operator writes it; nothing here writes it. A missing file reads as the defaults, and so
+// does one that cannot be read or does not fit the shape: the hook never throws over it, and the row records which of the three it was, so `oars gate report` can count them.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** The classes the policy sets. Each is something a row can already tell: a registry name first published recently, and a name the registry does not hold. */
+export const POLICY_CLASSES = ['young-name', 'not-found'];
+export const POLICY_ACTIONS = ['warn', 'block', 'off'];
+/** What a young name can be set to: a note or nothing. A block is for a name the registry does not hold, since only that is a fact the registry answers by itself. */
+const ALLOWED = { 'young-name': ['warn', 'off'], 'not-found': POLICY_ACTIONS };
+export const DEFAULT_POLICY = { classes: { 'young-name': 'warn', 'not-found': 'warn' }, youngDays: 30, holdbackPercent: 10 };
+/** Where a row's policy came from: no file, a file that fit, or a file that was there and did not (so the defaults stood). */
+export const POLICY_SOURCES = ['default', 'file', 'invalid'];
+export const policyPath = (storeDir) => join(storeDir, 'gate-policy.json');
+const KEYS = new Set(['v', 'classes', 'youngDays', 'holdbackPercent']);
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const integerIn = (value, low, high) => (typeof value === 'number' && Number.isInteger(value) && value >= low && value <= high ? value : undefined);
+/** `undefined` for anything outside the closed vocabulary: an unknown key, class, or action, a number out of range, or another version. */
+const fit = (parsed) => {
+    if (!isObject(parsed) || Object.keys(parsed).some((key) => !KEYS.has(key)))
+        return undefined;
+    const version = Reflect.get(parsed, 'v');
+    if (version !== undefined && version !== 1)
+        return undefined;
+    const given = Reflect.get(parsed, 'classes');
+    if (given !== undefined && (!isObject(given) || Object.keys(given).some((key) => !POLICY_CLASSES.some((known) => known === key))))
+        return undefined;
+    const classes = { ...DEFAULT_POLICY.classes };
+    for (const cls of POLICY_CLASSES) {
+        const action = isObject(given) ? Reflect.get(given, cls) : undefined;
+        if (action === undefined)
+            continue;
+        const allowed = ALLOWED[cls].find((one) => one === action);
+        if (allowed === undefined)
+            return undefined;
+        classes[cls] = allowed;
+    }
+    const days = Reflect.get(parsed, 'youngDays');
+    const share = Reflect.get(parsed, 'holdbackPercent');
+    const youngDays = days === undefined ? DEFAULT_POLICY.youngDays : integerIn(days, 1, 365);
+    const holdbackPercent = share === undefined ? DEFAULT_POLICY.holdbackPercent : integerIn(share, 0, 100);
+    return youngDays === undefined || holdbackPercent === undefined ? undefined : { classes, youngDays, holdbackPercent };
+};
+/** Never throws. A file that is not there is the defaults; one that is there and cannot be read or does not fit is the defaults too, and says `invalid`. */
+export const loadPolicy = async (storeDir) => {
+    let body;
+    try {
+        body = await readFile(policyPath(storeDir), 'utf8');
+    }
+    catch (error) {
+        const code = isObject(error) ? Reflect.get(error, 'code') : undefined;
+        return { policy: DEFAULT_POLICY, source: code === 'ENOENT' ? 'default' : 'invalid' };
+    }
+    let parsed;
+    try {
+        // Windows PowerShell 5.1 writes UTF-8 with a byte order mark, and `JSON.parse` refuses it: an operator's `block` would silently not apply.
+        parsed = JSON.parse(body.charCodeAt(0) === 0xfeff ? body.slice(1) : body);
+    }
+    catch {
+        return { policy: DEFAULT_POLICY, source: 'invalid' };
+    }
+    const policy = fit(parsed);
+    return policy === undefined ? { policy: DEFAULT_POLICY, source: 'invalid' } : { policy, source: 'file' };
+};
+/** What `oars gate policy` prints. */
+export const formatPolicy = (read, file) => {
+    const origin = read.source === 'file' ? `Policy in force: ${file}` : read.source === 'default' ? `Policy in force: defaults (no file at ${file})` : `Policy in force: defaults (${file} is unreadable or invalid, so it is ignored)`;
+    return [
+        origin,
+        ...POLICY_CLASSES.map((cls) => `${cls}: ${read.policy.classes[cls]}`),
+        `Young name: first published within ${String(read.policy.youngDays)} days`,
+        `Holdback: ${String(read.policy.holdbackPercent)}% of notes are not shown`,
+    ].join('\n');
+};

package/dist/gate/record.d.ts

@@ -0,0 +1,120 @@
+import type { PolicySource } from './policy.js';
+import { CROSSING_CLASSES, CROSSING_FORMS, type CrossingClass, type CrossingForm, type UnreadShape, type VersionForm } from './checks.js';
+export declare 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 declare const VIAS: readonly ["hook", "replay", "both"];
+export type Via = (typeof VIAS)[number];
+/** `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 declare 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 declare const PROGRAMS: readonly ["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 type Program = (typeof PROGRAMS)[number];
+export declare const ORIGINS: readonly ["prompt", "repo-file", "web", "tool-output", "skill", "harness", "none-seen", "not-read"];
+export type Origin = (typeof ORIGINS)[number];
+export declare const NOVELTIES: readonly ["fleet", "repository", "session", "none", "not-read"];
+export type Novelty = (typeof NOVELTIES)[number];
+export declare const DECIDERS: readonly ["operator", "agent", "not-read"];
+export type Decider = (typeof DECIDERS)[number];
+export declare const PERMISSIONS: readonly ["default", "acceptEdits", "plan", "bypassPermissions", "dontAsk", "auto", "other", "unknown"];
+export type Permission = (typeof PERMISSIONS)[number];
+export declare const STATUSES: readonly ["ok", "error", "refused", "none", "not-read"];
+export type Status = (typeof STATUSES)[number];
+export declare const NEXTS: readonly ["proceeded", "retried", "routed-around", "changed-name", "stopped", "no-result", "not-read"];
+export type Next = (typeof NEXTS)[number];
+export declare const MISSES: readonly ["none", "not-found", "not-read"];
+export type Miss = (typeof MISSES)[number];
+export declare const AGAINST_LATEST: readonly ["not-read", "latest", "not-latest", "range", "unstated", "unknown"];
+export type AgainstLatest = (typeof AGAINST_LATEST)[number];
+export declare const REGISTRY_STATES: readonly ["not-read", "found", "not-found", "unreachable"];
+export type RegistryState = (typeof REGISTRY_STATES)[number];
+export declare const REGISTRY_AGES: readonly ["not-read", "after-crossing", "under-7-days", "under-30-days", "under-1-year", "older", "unknown"];
+export type RegistryAge = (typeof REGISTRY_AGES)[number];
+export declare const DEPTHS: readonly ["main", "subagent"];
+export type Depth = (typeof DEPTHS)[number];
+/** 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 declare const ARMS: readonly ["none", "shown", "held"];
+export type Arm = (typeof ARMS)[number];
+/** 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 declare const LINE_IDS: readonly ["none", "young-name-note", "not-found-note", "not-found-block"];
+export type LineId = (typeof LINE_IDS)[number];
+export interface CrossingRecord {
+    kind: 'crossing';
+    v: number;
+    /** Absent in a row an earlier build wrote: those were all replays. */
+    via?: Via;
+    day: string | null;
+    class: CrossingClass;
+    form: CrossingForm;
+    program: Program;
+    versionForm: VersionForm;
+    statusReports: boolean;
+    origin: Origin;
+    novelty: Novelty;
+    decidedBy: Decider;
+    permission: Permission;
+    status: Status;
+    next: Next;
+    removedLater: boolean | typeof NOT_READ;
+    depth: Depth;
+    miss: Miss;
+    againstLatest: AgainstLatest;
+    registryState: RegistryState;
+    registryAge: RegistryAge;
+    arm: Arm;
+    lineShown: LineId;
+    /** The line a held note would have shown. Recorded apart from `lineShown` (which stays `none` when held) so the arms can be compared line by line; a row cannot be backfilled. */
+    lineHeld: LineId;
+    /** Which policy stood when the hook wrote the row. Absent in a replay row and in a row an earlier build wrote: no policy was read. */
+    policy?: PolicySource;
+    session: string;
+    agent: string | null;
+    toolUseId: string | null;
+    ts: string | null;
+    name: string;
+    version: string | null;
+}
+/** The run's own books, so `report` can say what this replay read and could not. Counts and a day: class P. */
+export interface RunRow {
+    kind: 'run';
+    v: number;
+    day: string;
+    transcripts: number;
+    unreadable: number;
+    badLines: number;
+    calls: number;
+    crossings: number;
+    unread: Partial<Record<UnreadShape, number>>;
+    registryRead: boolean;
+}
+/** One kept registry answer, the cache of the `--registry-state` option. Held here so a replay writes one file. `name`, `latest`, and `created` are class A; `created` is a full timestamp, which class P cannot hold. */
+export interface RegistryRow {
+    kind: 'registry';
+    v: number;
+    day: string;
+    /** When the answer was read, to the millisecond; a row an earlier build wrote has none. A not-found answer is trusted for minutes, not days. */
+    ts?: string;
+    /** Which folder the answer came from (`folderKey`): a folder's own config can name another registry, so a kept answer answers only that folder. A row with none is not fresh. Class A. */
+    folder?: string;
+    class: CrossingClass;
+    state: 'found' | 'not-found';
+    created: string | null;
+    name: string;
+    latest: string | null;
+}
+export type Row = CrossingRecord | RunRow | RegistryRow;
+/** A truncated SHA-256 of the folder an ask ran in, so a kept answer names its folder without storing the path. */
+export declare const folderKey: (cwd: string) => string;
+/** The harness's permission mode, in the closed vocabulary: a mode this version does not know reads `other`. */
+export declare const permissionOf: (value: string) => Permission;
+/** A line this version cannot read is skipped: a torn tail or a newer row kind says nothing about the rest. */
+export declare const parseRows: (text: string) => Row[];
+export { CROSSING_CLASSES, CROSSING_FORMS };
+/**
+ * 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 declare const mergeCrossings: (replayed: readonly CrossingRecord[], live: readonly CrossingRecord[]) => CrossingRecord[];
+/** The crossings of a file's rows with each counted once: replay rows and hook rows of the same call become one. */
+export declare const crossingsOf: (rows: readonly Row[]) => CrossingRecord[];
+/** The hook-written rows (and merged ones) of a file, which a replay keeps when it rewrites the rest. */
+export declare const liveCrossings: (rows: readonly Row[]) => CrossingRecord[];