@manyoars/oars 0.2.0 → 0.4.0

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[];

package/dist/gate/record.js

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

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

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

package/dist/gate/registry-state.js

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

package/dist/gate/registry.d.ts

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

package/dist/gate/registry.js

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

package/dist/gate/replay.d.ts

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