approval-md 0.4.0 → 0.4.1

package/dist/src/cli/hook.d.ts

@@ -75,7 +75,7 @@ import { type ClassifiedSegment, type CommandClassification, type ProtectedPathE
 import { type GateOptions } from "../core/gate.js";
 import { type HarnessKind } from "../core/harness-version.js";
 import { type HarnessLoopState } from "../core/loop.js";
-import type { EventRecord } from "../core/log.js";
+import { type EventRecord } from "../core/log.js";
 import { type ReadRecordsResult } from "../core/state.js";
 import type { Streams } from "./main.js";
 import { type Style } from "./style.js";
@@ -537,6 +537,51 @@ export declare function harnessBlockDirective(code: string, detail: string, harn
     stdout: string;
     exitCode: number;
 };
+/**
+ * Raised on `globalThis` while the runtime's own Hermes signal guards are
+ * registered (APRV-466). The `approval` bin reads the same registry symbol and
+ * steps aside while it is `true`, so the bin and the runtime never both print.
+ * An explicit flag rather than a listener count: an unrelated listener that
+ * does not exit must not switch the bin's guard off.
+ */
+export declare const HERMES_SIGNAL_OWNER: unique symbol;
+/**
+ * The block directive a Hermes hook prints when a signal arrives before it
+ * reached a verdict (APRV-445, APRV-466), as bytes.
+ *
+ * Two places print it: `hermesFailClosed`'s guard below, and the `approval` bin
+ * (`cli.js`), which has to answer a signal that lands while this module is
+ * still loading and so cannot import it. The bin spells the same bytes by hand,
+ * and `tests/hermes-bin-signal-guard.test.ts` pins the two equal, so the
+ * early-signal answer is one code with one spelling (SPEC.md §11.1 invariant
+ * 6). The wait's own handler words its message differently ("while waiting for
+ * a decision") under the same code.
+ *
+ * On the CLI the runtime's guard prints it for a signal held through the
+ * synchronous stretch before the first spend (the stdin read, the
+ * classification), at the pause `BEFORE_SPEND` (APRV-473); the bin prints it
+ * for a signal during the load (docs/hermes-hook.md, "Two layers against a
+ * signal").
+ */
+export declare function hermesInterruptedDirective(signal: NodeJS.Signals): string;
+/**
+ * The block directive a harness wait answers when a SIGTERM or SIGINT ends it
+ * (APRV-473 for Hermes, APRV-475 for every harness), as bytes and exit code.
+ *
+ * It is the harness's ORDINARY deny, built by {@link harnessBlockDirective}
+ * and so by {@link deny}, under the `hook-interrupted` code: the nested
+ * `hookSpecificOutput` deny at exit 0 for Claude Code, Codex and Muse,
+ * `{permission:"deny"}` at exit 0 for Cursor, `{decision:"deny"}` at exit 2
+ * for Grok, `{action:"block"}` at exit 2 for Hermes. One construction site per
+ * harness, so the answer to an interruption is spelled exactly as every other
+ * refusal that harness receives from this hook, and a harness that blocks on
+ * those blocks on this. `tests/harness-wait-interrupt.test.ts` pins the bytes
+ * per harness.
+ */
+export declare function interruptedWaitDirective(signal: NodeJS.Signals, harness: HarnessKind): {
+    stdout: string;
+    exitCode: number;
+};
 /** The machine-readable code a Hermes `execute_code` call is refused with. */
 export declare const HERMES_EXECUTE_CODE_REFUSAL = "hook-hermes-execute-code-unbound";
 /** The machine-readable code a Contributor-tier session is refused with. */
@@ -740,6 +785,41 @@ export declare function classifyForHook(command: string, protectedPaths: readonl
  * that the `json` veto on colour is the answer this process memoizes.
  */
 export declare function renderClassification(result: CommandClassification, json: boolean, st?: Style): string;
+/**
+ * The gate path from the event to a verdict, as steps (APRV-473).
+ *
+ * Each value the generator yields is a pause in milliseconds: the wait's poll
+ * interval, or `0` for one turn of the event loop and nothing longer. The
+ * return value is the verdict. ONE implementation of classify, register,
+ * request, wait and spend, run by one of two drivers:
+ *
+ * - {@link driveSync} sleeps each pause with `Atomics.wait`. Every caller that
+ *   needs a synchronous answer keeps one: `commandHook` for the in-process
+ *   callers and the serve worker, `decideHarnessCall` for the Codex bridge. A
+ *   zero pause is no pause, so their behaviour is what it was.
+ * - {@link driveYielding} sleeps each pause on a timer, so the event loop turns
+ *   while the hook waits and a JS signal listener runs then. Every
+ *   `approval hook <harness>` CLI route runs through it: Hermes first
+ *   (APRV-473), which sends SIGTERM on its hook timeout and on gateway
+ *   shutdown, then Claude Code, Cursor, Codex, Grok and Muse (APRV-475). A
+ *   signal held through a synchronous wait let a grant that landed afterwards
+ *   record `execution.started` for a call the harness had already abandoned.
+ *   The harness makes no difference to the steps: the pause before a spend
+ *   ({@link BEFORE_SPEND}) and the wait's withdrawing handler are the same code
+ *   for all six, and only the directive the handler prints is the harness's
+ *   own ({@link interruptedWaitDirective}).
+ *
+ * The pauses are the same durations under either driver, so the deadline
+ * arithmetic and the poll cadence do not depend on which one runs them.
+ *
+ * Each `next()` also tells the steps which driver is running them (APRV-478):
+ * `true` from {@link driveYielding}, a pause that turns the event loop, and
+ * `false` or nothing from {@link driveSync}. The one step that reads it is
+ * {@link spendUnderLock}, which waits for the log's lock on the event loop
+ * only when there is an event loop to wait on, and otherwise runs the writer's
+ * own synchronous wait exactly as before.
+ */
+type GateSteps<T> = Generator<number, T, boolean | undefined>;
 /**
  * Where a hook invocation stops appending and starts waiting, for a caller that
  * shares one store with other work in the same process (APRV-427).
@@ -963,7 +1043,9 @@ export type HarnessVerdict = {
     code: string;
     detail: string;
 };
-export declare function gateHarnessCall(streams: Streams, run: HookRun, classes: string[], 
+export declare function gateHarnessCall(...args: Parameters<typeof gateHarnessSteps>): HarnessVerdict;
+/** {@link gateHarnessCall} as steps, for a driver that yields (APRV-473). */
+declare function gateHarnessSteps(streams: Streams, run: HookRun, classes: string[], 
 /**
  * The bytes the grant binds to: `{command, cwd}` for a Bash call, the change
  * itself for a file tool (APRV-124). Whatever this is, it is what reaches the
@@ -997,7 +1079,7 @@ note?: string,
  * reads, and {@link floorApplies} below carves the read classes out of a mixed
  * one, so a floor never puts a question about looking on a human's phone.
  */
-floor?: HarnessLoopState | null): HarnessVerdict;
+floor?: HarnessLoopState | null): GateSteps<HarnessVerdict>;
 /**
  * Every line the counterpart can print, closed and machine-readable (§11.1
  * invariant 7).
@@ -1152,4 +1234,33 @@ export declare function commandHook(argv: string[], streams: Streams, cwd: strin
  * the call polls. Every CLI route omits it. See {@link HookWaitSeam}.
  */
 waitSeam?: HookWaitSeam | null): number;
+/**
+ * {@link commandHook}, with its pauses on the event loop (APRV-473).
+ *
+ * Every `approval hook` CLI route, from `main`: Hermes since APRV-473, the
+ * other five harnesses (and `classify`, which never pauses) since APRV-475.
+ * The same steps as the synchronous form; the difference is that a SIGTERM or
+ * SIGINT reaches the listener in force within one pause of arriving, instead
+ * of after the run returns. In the wait that listener withdraws the question
+ * this invocation opened, prints the harness's own `hook-interrupted` block
+ * directive ({@link interruptedWaitDirective}) and exits with that directive's
+ * exit code, so a grant that lands after the harness abandoned the call is
+ * never spent on it. See {@link GateSteps} and {@link BEFORE_SPEND}.
+ */
+export declare function commandHookYielding(argv: string[], streams: Streams, cwd: string, readStdin?: () => string): Promise<number>;
+/**
+ * The steps {@link commandHook} and {@link commandHookYielding} drive, for a
+ * test that drives them itself (APRV-475 refuter).
+ *
+ * A test seam and nothing more: it exists so a test can stop at each pause and
+ * look at the log, which is the only deterministic way to pin that the pause
+ * before a spend ({@link BEFORE_SPEND}) sits between the read that found a
+ * grant and the append that spends it, on every harness. No CLI route and no
+ * embedding caller uses it; the one entry for those is the two drivers above.
+ *
+ * Pass `true` to each `next()` to step as {@link commandHookYielding} does
+ * (the spend then waits for a held log lock in yields, APRV-478); `false` or
+ * nothing steps as {@link commandHook} does.
+ */
+export declare function commandHookSteps(argv: string[], streams: Streams, cwd: string, readStdin: () => string): Generator<number, number, boolean | undefined>;
 export {};