@manyoars/oars 0.2.0 → 0.4.0

package/dist/gate/command.js

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

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

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

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

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

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

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

package/dist/gate/hook-fill.js

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

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

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

package/dist/gate/hook-main.js

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

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

@@ -0,0 +1,24 @@
+import { type GateHookDeps } from './hook.js';
+/** What telemetry is told of one fire of `oars gate hook`: how long the handler took, how it ended, and the bytes it printed. */
+export interface HookFire {
+    latencyMs: number;
+    outcome: 'hit' | 'miss' | 'held' | 'error';
+    bytes: number;
+}
+export interface HookProcess {
+    /** Reads the whole of stdin. Called inside the guard, so a stream that cannot be set up is a failed read, not a crash. */
+    stdin: () => Promise<string>;
+    /** Builds the hook's dependencies, handed the function that records what is about to be written. Called inside the guard. */
+    deps: (stage: NonNullable<GateHookDeps['stage']>) => GateHookDeps;
+    exit: (code: number) => void;
+    /** Writes the hook's answer to stdout and resolves once it is flushed. Absent: nothing is written. */
+    write?: (text: string) => Promise<void>;
+    /** Milliseconds from now until the process ends itself. */
+    deadlineMs: number;
+    /** Told once how the fire went, with the transcript path the harness named (to read the frame from, never to record), after its output is written so recording is never in front of the answer. A throw here is swallowed: the exit code and stdout do not depend on it. */
+    record?: (fire: HookFire, transcript: string | undefined) => void | Promise<void>;
+    /** Milliseconds, only compared with itself: the latency in a fire is the difference across the handler. Absent: `Date.now`. */
+    clock?: () => number;
+}
+/** Resolves once `exit(0)` has been called, or never when the deadline timer is what ended the process. */
+export declare const runHookProcess: ({ stdin, deps, exit, write, deadlineMs, record, clock }: HookProcess) => Promise<void>;

package/dist/gate/hook-process.js

@@ -0,0 +1,112 @@
+// The process behind `oars gate hook`, with every side effect handed in so a test can drive it: stdin in, at most one JSON document out, `exit(0)` whatever happens. A hard deadline ends
+// the process before the harness's own, writing the record it has staged if the write had not finished. Nothing here may throw past `runHookProcess`: exit 1 from a
+// PreToolUse hook is a visible error and exit 2 blocks the tool call, and the hook must never cost a session either.
+import { appendFileSync, readFileSync, statSync } from 'node:fs';
+import { gateHook } from './hook.js';
+import { parseRows } from './record.js';
+/** The staged record is written before anything prints, so when the deadline ends the process with it still staged no note or deny was shown: its crossing rows read as no exposure, since a row cannot be backfilled. A block row has `arm: none` already but names its line, so every crossing row is reset, not only those with an arm. */
+const unprinted = (text) => parseRows(text)
+    .map((row) => `${JSON.stringify(row.kind === 'crossing' ? { ...row, arm: 'none', lineShown: 'none', lineHeld: 'none' } : row)}\n`)
+    .join('');
+/** The transcript path the harness put in the hook input, when there is one; anything else, including input that is not JSON, names none. */
+const transcriptOf = (input) => {
+    try {
+        const parsed = JSON.parse(input);
+        const path = typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'transcript_path') : undefined;
+        return typeof path === 'string' && path !== '' ? path : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const sizeOf = (file) => {
+    try {
+        return statSync(file).size;
+    }
+    catch {
+        return 0;
+    }
+};
+/** Whether the record's own bytes are in the file past the length it had when the record was staged. Another hook's row may have grown the file too, so growth alone proves nothing. */
+const landed = (file, text, size) => {
+    try {
+        return readFileSync(file).subarray(size).includes(text);
+    }
+    catch {
+        return false;
+    }
+};
+/** Resolves once `exit(0)` has been called, or never when the deadline timer is what ended the process. */
+export const runHookProcess = async ({ stdin, deps, exit, write, deadlineMs, record, clock = Date.now }) => {
+    const started = clock();
+    // `held` and `error` are what the output cannot say; the callback reaches the hook through `deps`.
+    const how = { ended: null };
+    let fired;
+    let transcript;
+    // Telemetry hears of a fire once: the deadline timer records the fire it cuts short (the slowest ones), and the main path skips a fire the timer has already told.
+    let recorded = false;
+    // Set once the main path's `record` has resolved. While it is false after `recorded`, the main path is still reading the transcript, and a stalled read would otherwise lose the fire at the deadline.
+    let settled = false;
+    let told;
+    const send = async (result, transcript) => {
+        try {
+            await record?.({ latencyMs: Math.max(0, Math.round(clock() - started)), ...result }, transcript);
+        }
+        catch {
+            // Telemetry never changes what the hook did.
+        }
+    };
+    const tell = async (result, transcript) => {
+        if (recorded)
+            return;
+        recorded = true;
+        told = result;
+        await send(result, transcript);
+        settled = true;
+    };
+    // `size` is the file's length when the record was staged: an append that wrote and then stalled has put the record's own bytes past it, and the deadline must not write it again.
+    let staged = null;
+    // The last resort when the process is stuck past its grace: keep the staged record, then go. A write that fails here has nowhere to report, so it is dropped.
+    setTimeout(() => {
+        // The row first: it is the record this timer exists to keep, and the stop can be slow (on Windows it is a `taskkill` spawn at a moment already past the deadline).
+        try {
+            if (staged !== null && !landed(staged.file, staged.text, staged.size))
+                appendFileSync(staged.file, unprinted(staged.text), { mode: 0o600 });
+        }
+        catch {
+            // Fail-open.
+        }
+        // The fire the deadline cut short is still a fire: recorded as an error with nothing printed, after the row and before the stop so a slow stop cannot lose it.
+        // When the main path had told it first and its transcript read is still going, the fire it settled on goes now, with no transcript, so the read cannot cost the event.
+        if (!recorded)
+            void tell({ outcome: 'error', bytes: 0 });
+        else if (!settled && told !== undefined)
+            void send(told);
+        // A registry ask still running is then stopped, so the manager the hook started does not outlive it; a stop that throws must not cost the exit.
+        try {
+            staged?.stop?.();
+        }
+        catch {
+            // Fail-open.
+        }
+        exit(0);
+    }, Math.max(deadlineMs, 0)).unref();
+    try {
+        const built = deps((pending) => {
+            staged = pending === null ? null : { ...pending, size: sizeOf(pending.file) };
+        });
+        const input = await stdin();
+        transcript = transcriptOf(input);
+        const output = await gateHook(input, { ...built, ended: (result) => { how.ended = result; built.ended?.(result); } });
+        if (output !== '')
+            await write?.(output);
+        fired = { outcome: how.ended ?? (output === '' ? 'miss' : 'hit'), bytes: Buffer.byteLength(output) };
+    }
+    catch {
+        // Fail-open: a throw anywhere above is a record not written, never an exit code.
+        fired = { outcome: 'error', bytes: 0 };
+    }
+    await tell(fired, transcript);
+    // A manager the registry ask started can outlive the ask; leaving by `exit` rather than waiting for it is what keeps the call under a second.
+    exit(0);
+};

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

@@ -0,0 +1,3 @@
+import type { Emit } from '../telemetry/emit.js';
+import type { HookProcess } from './hook-process.js';
+export declare const fireRecorder: (emit: Emit) => NonNullable<HookProcess["record"]>;

package/dist/gate/hook-record.js

@@ -0,0 +1,8 @@
+// What `oars gate hook` tells telemetry about one fire: the fire itself, plus the harness version and model its transcript states. Apart from `hook-main.ts` so a test drives the same line the process runs.
+import { statedAt } from '../sessions/transcript-tail.js';
+import { frameWords, HOOK_HARNESS } from '../telemetry/fields.js';
+export const fireRecorder = (emit) => async (fire, transcript) => {
+    // No await before this on the deadline path (no transcript), so that fire is written before the timer's `exit`.
+    const stated = transcript === undefined ? undefined : await statedAt(transcript);
+    emit('hook', { name: 'gate', ...fire, ...frameWords(HOOK_HARNESS, stated?.harnessVersion, stated?.model) });
+};

package/dist/gate/hook.d.ts

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