vigiles 36.0.0 → 37.0.0

package/dist/cli-commands.d.ts

@@ -13,7 +13,7 @@
 /** Human-facing verbs (printed in help; typed by a human/agent/CI). */
 export declare const VERBS: readonly ["init", "compile", "eject", "lint", "test", "eval", "audit", "generate", "hook-runtime"];
 /** Runtime entrypoint kinds under `vigiles hook-runtime <kind>` (emitted, not typed). */
-export declare const HOOK_RUNTIME_KINDS: readonly ["run-program", "agent", "agent-start", "agent-done", "skill", "skill-tool", "skill-start", "skill-done", "run-skill", "intercept-tool", "guard", "action", "refs", "eval-lock-nudge", "effect-enter", "effect-exit"];
+export declare const HOOK_RUNTIME_KINDS: readonly ["run-program", "agent", "agent-start", "agent-done", "skill", "skill-tool", "skill-start", "skill-done", "run-skill", "intercept-tool", "stub", "guard", "action", "refs", "eval-lock-nudge", "effect-enter", "effect-exit"];
 export type Verb = (typeof VERBS)[number];
 export type HookRuntimeKind = (typeof HOOK_RUNTIME_KINDS)[number];
 //# sourceMappingURL=cli-commands.d.ts.map

package/dist/cli-commands.js

@@ -37,6 +37,7 @@ exports.HOOK_RUNTIME_KINDS = [
     "skill-done",
     "run-skill",
     "intercept-tool",
+    "stub",
     "guard",
     "action",
     "refs",

package/dist/cli-main.js

@@ -27,6 +27,7 @@ const generate_harness_js_1 = require("./core/generate-harness.js");
 const capability_diff_js_1 = require("./core/capability-diff.js");
 const validate_js_1 = require("./core/validate.js");
 const eval_lock_js_1 = require("./eval-lock.js");
+const eval_entry_js_1 = require("./eval-entry.js");
 const zod_1 = require("zod");
 const cli_flags_js_1 = require("./cli-flags.js");
 const cli_commands_js_1 = require("./cli-commands.js");
@@ -5572,6 +5573,18 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
         console.error(`\n✗ vigiles ${kind}: --min=${String(minRequired)} but only ${String(loadedCount)} of ` +
             `${String(files.length)} matched ${kind} file(s) loaded.`);
     }
+    // An eval whose stubs left a call unanswered measured an answer nobody wrote.
+    // That is not a failed assertion but a non-measurement, and it must fail the
+    // command even when the file's own `assert` never looks (eval-entry.ts). The
+    // file says so with its own exit code, so this names the cause from that code
+    // and not from the verb's usage-error 2.
+    const unanswered = results.filter((r) => r.code === eval_entry_js_1.UNANSWERED_STUB_EXIT_CODE);
+    if (kind === "eval" && unanswered.length > 0) {
+        console.error(`\n✗ vigiles eval: unanswered stub call(s) in ${unanswered.map((r) => r.file).join(", ")} — not a usage error. ` +
+            `The calls are listed above; add a rule for each, and no lock was written. ` +
+            `(Exit ${String(eval_entry_js_1.UNANSWERED_STUB_VERB_EXIT)}; the file itself exited ${String(eval_entry_js_1.UNANSWERED_STUB_EXIT_CODE)}.)`);
+        process.exit(eval_entry_js_1.UNANSWERED_STUB_VERB_EXIT);
+    }
     if ((0, run_scripts_js_1.anyFailed)(results))
         process.exit(1);
     // 🔴 A SKIP THE AUTHOR NEVER DECLARED IS NOT A SKIP — and the discriminator was

package/dist/cli.js

@@ -65,6 +65,53 @@ function die(e) {
     }
     process.exit(2);
 }
+/**
+ * Any failure on the stub path — a log the agent's shell cannot append to, a
+ * rules file that does not parse — is a MISS to the caller: the same neutral
+ * line and code as a call no rule answers. A vigiles error line or stack would
+ * tell the model it is in a test, and a call that could not be logged must never
+ * read as answered. `VIGILES_DEBUG=1` shows the cause.
+ */
+async function stubAnswer(root, name, argv) {
+    const { runStub, unsupportedLine, UNANSWERED_EXIT_CODE } = await import("./core/stub-rules.js");
+    const { readFileSync, appendFileSync, existsSync } = await import("node:fs");
+    try {
+        return runStub(root, name, argv, {
+            readFile: (p) => (existsSync(p) ? readFileSync(p, "utf8") : null),
+            appendFile: (p, text) => {
+                appendFileSync(p, text);
+            },
+        });
+    }
+    catch (e) {
+        if (process.env.VIGILES_DEBUG)
+            console.error(e instanceof Error && e.stack ? e.stack : String(e));
+        return {
+            stdout: "",
+            stderr: unsupportedLine(name),
+            exitCode: UNANSWERED_EXIT_CODE,
+        };
+    }
+}
+/**
+ * A TOOL STUB's invocation — the eval tier writes a `gh`/`git` shim onto PATH
+ * that execs `hook-runtime stub <root> <name> <argv…>`, once per call the agent
+ * (or a script it runs) makes. Same cost argument as `run-program`, so the same
+ * kind of fast path: the pure decision (`core/stub-rules.js`) and `node:fs`,
+ * nothing else — no barrel, no zod. The argv is taken RAW: the stubbed tool's
+ * own `--flags` are its argv. It never reads stdin: a caller that leaves the
+ * pipe open (Node's `execFile` does) would hang until its own timeout.
+ */
+async function runStubCommand(raw) {
+    const [root, name, ...argv] = raw;
+    if (root === undefined || name === undefined) {
+        console.error("vigiles hook-runtime stub: emitted into a tool-stub shim by the eval tier, never typed by hand.");
+        process.exit(2);
+    }
+    const r = await stubAnswer(root, name, argv);
+    // Exit only once both streams have flushed: a pipe write is async on macOS.
+    process.stdout.write(r.stdout, () => process.stderr.write(r.stderr, () => process.exit(r.exitCode)));
+}
 async function dispatch() {
     // Parsed EXACTLY as `main()` parses it — `args.slice(1)` with `--flags`
     // dropped — so the fast path and the barrel agree on which argument is the
@@ -86,6 +133,10 @@ async function dispatch() {
         await runHookProgramCommand(rest[1]);
         return;
     }
+    if (command === "hook-runtime" && kind === "stub") {
+        await runStubCommand(args.slice(2));
+        return;
+    }
     const { main } = require("./cli-main.js");
     await main();
 }

package/dist/core/eval-driver.d.ts

@@ -18,6 +18,7 @@
  * runners re-export these names, so every existing import keeps resolving.
  */
 import type { ToolCall, HookFire, ModelRequest } from "./harness-driver.js";
+import type { StubCall } from "./stub-rules.js";
 /** Per-run resource use, parsed from the terminal `result` event (0 when absent). */
 export interface EvalUsage {
     /** `total_cost_usd` reported by the harness binary. */
@@ -99,6 +100,13 @@ export interface Trace {
      * Empty unless the stream was captured / the harness emits subagent events.
      */
     readonly subagents?: readonly SubagentTrace[];
+    /**
+     * Every invocation of a tool stub during the run, in order — including calls a
+     * script the agent ran made itself (`execFile(gh, …)`), which never appear as
+     * a tool call. Each says which rule answered it, or that none did. Absent when
+     * the run had no stubs (eval tier: `stubs` on the spec).
+     */
+    readonly stubCalls?: readonly StubCall[];
     /** Final contents of a file under the working dir, or null if absent. */
     file(path: string): string | null;
 }
@@ -137,7 +145,7 @@ export interface AgentRunArgs {
      * When true, `env` is the COMPLETE spawn environment (an ephemeral run env from
      * `ephemeralRunEnv`) — the runner does NOT prepend `process.env`, so the
      * real `$HOME` / secrets are scrubbed. Default false: `env` is an overlay over
-     * `process.env` (the byte-identical-to-today path). Set only by `ephemeralEnv`.
+     * `process.env` (the byte-identical-to-today path). Set only by an ephemeral `env`.
      */
     readonly replaceEnv?: boolean;
 }

package/dist/core/eval-spec-parse.d.ts

@@ -0,0 +1,14 @@
+import { type ToolStub } from "./stub-rules.js";
+import { type RunEnv } from "./run-env.js";
+/**
+ * Parse an eval spec's `stubs`. Absent → `[]`. Throws, naming the field, on the
+ * old shape, a malformed rule, a stateful RegExp, or two stubs of one name.
+ */
+export declare function parseToolStubs(raw: unknown, caller: string): readonly ToolStub[];
+/**
+ * Parse an eval spec's `env`, including its seeded HOME: every seed path is
+ * HOME-relative, stays inside HOME, and does not overwrite one of the harness's
+ * own auth files (`keepHomeFiles`). Throws before any trial on a bad value.
+ */
+export declare function parseRunEnv(raw: unknown, caller: string, keepHomeFiles: readonly string[]): RunEnv;
+//# sourceMappingURL=eval-spec-parse.d.ts.map

package/dist/core/eval-spec-parse.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseToolStubs = parseToolStubs;
+exports.parseRunEnv = parseRunEnv;
+/**
+ * The eval spec boundary for `stubs` and `env` — parsed ONCE, before anything is
+ * packaged or spent, into the plain data the runner then trusts.
+ *
+ * An eval file is often plain JavaScript, so no type checks its literal. A shape
+ * the runner would silently mis-read must fail here, naming the field and the
+ * rewrite. Two such shapes are the reason this module exists:
+ *
+ * - the old argv-blind stub `{ name, stdout }`, which printed one answer for
+ *   every invocation (a fabricated observation for every command nobody
+ *   anticipated);
+ * - a spec with no `env`, which used to inherit your HOME and environment by
+ *   default — so a comparison measured the author's machine.
+ *
+ * zod lives HERE and not in `stub-rules.ts`: the stub process reads its rules
+ * once per `gh` call and must not pay for a schema library; the rules file it
+ * reads is this parse's output, written by vigiles.
+ */
+const zod_1 = require("zod");
+const stub_rules_js_1 = require("./stub-rules.js");
+const run_env_js_1 = require("./run-env.js");
+/** `stubs[0].rules[1].argv` from a zod issue path. */
+function pathText(root, path) {
+    return path.reduce((acc, k) => typeof k === "number" ? `${acc}[${String(k)}]` : `${acc}.${String(k)}`, root);
+}
+function refuse(caller, root, error) {
+    const lines = error.issues.map((i) => `${caller}: ${pathText(root, i.path)}: ${i.message}`);
+    throw new Error(lines.join("\n"));
+}
+// --- stubs ---------------------------------------------------------------------
+const regexToken = zod_1.z.instanceof(RegExp).refine((r) => !r.global && !r.sticky, {
+    message: "a RegExp token may not carry the flags g and y — test() would carry lastIndex from one call to the next",
+});
+const token = zod_1.z.union([zod_1.z.string(), regexToken]);
+const restToken = zod_1.z
+    .strictObject({ kind: zod_1.z.literal("rest") })
+    .transform(() => stub_rules_js_1.ARGV_REST);
+/** A plain object (not an array, not a RegExp), readable by key. */
+const isObj = (v) => typeof v === "object" &&
+    v !== null &&
+    !Array.isArray(v) &&
+    !(v instanceof RegExp);
+const isRestToken = (t) => isObj(t) && t.kind === "rest";
+const argvPattern = zod_1.z
+    .array(zod_1.z.union([token, restToken]))
+    .refine((p) => p.slice(0, -1).every((t) => !isRestToken(t)), {
+    message: "experimental_stub.rest may appear only as the last token",
+});
+const answerFields = {
+    stdout: zod_1.z.string().optional(),
+    stderr: zod_1.z.string().optional(),
+    exitCode: zod_1.z.number().int().min(0).max(255).optional(),
+};
+const reply = zod_1.z.discriminatedUnion("kind", [
+    zod_1.z.strictObject({ kind: zod_1.z.literal("always"), ...answerFields }),
+    zod_1.z.strictObject({
+        kind: zod_1.z.literal("inOrder"),
+        answers: zod_1.z
+            .array(zod_1.z.strictObject(answerFields))
+            .min(1, { message: "an inOrder reply needs at least one answer" }),
+    }),
+]);
+const rule = zod_1.z
+    .strictObject({
+    argv: argvPattern,
+    contains: zod_1.z.array(token).optional(),
+    reply,
+})
+    .refine((r) => r.contains === undefined || isRestToken(r.argv.at(-1)), {
+    message: "`contains` matches tokens after the positional prefix, so it needs a trailing experimental_stub.rest in `argv`",
+    path: ["contains"],
+});
+const stub = zod_1.z.strictObject({
+    name: zod_1.z
+        .string()
+        .min(1)
+        .refine((n) => !/[/\\]/.test(n) && n !== "." && n !== "..", {
+        message: "a bare binary name, as it is looked up on PATH (no path separator)",
+    }),
+    rules: zod_1.z.array(rule).min(1, {
+        message: "a stub needs at least one rule — one per command the agent runs",
+    }),
+});
+/** Is this the removed `{ name, stdout?, stderr?, exitCode? }` shape? */
+const isOldShape = (s) => isObj(s) &&
+    !("rules" in s) &&
+    ["stdout", "stderr", "exitCode"].some((k) => k in s);
+function oldShapeMessage(caller, i, s) {
+    const name = typeof s.name === "string" ? s.name : "<tool>";
+    const stdout = typeof s.stdout === "string" ? JSON.stringify(s.stdout) : '"…"';
+    return (`${caller}: stubs[${String(i)}] (${JSON.stringify(name)}) is the old shape \`{ name, stdout }\`, which printed one answer for EVERY invocation — ` +
+        `a command nobody scripted got that answer as if the tool had said it. A stub is now a list of rules, one per command the agent runs:\n` +
+        `    experimental_stub(${JSON.stringify(name)}, [\n` +
+        `      { argv: ["<command>", experimental_stub.rest], reply: { kind: "always", stdout: ${stdout} } },\n` +
+        `      // one rule per further command; an invocation no rule answers fails the run\n` +
+        `    ])\n` +
+        `  The argv a run used is printed when it goes unanswered, so the first run tells you which rules to add.`);
+}
+/**
+ * Parse an eval spec's `stubs`. Absent → `[]`. Throws, naming the field, on the
+ * old shape, a malformed rule, a stateful RegExp, or two stubs of one name.
+ */
+function parseToolStubs(raw, caller) {
+    if (raw === undefined)
+        return [];
+    const items = Array.isArray(raw) ? raw : [];
+    const old = items.findIndex(isOldShape);
+    const oldItem = items[old];
+    if (isOldShape(oldItem))
+        throw new Error(oldShapeMessage(caller, old, oldItem));
+    const parsed = zod_1.z.array(stub).safeParse(raw);
+    if (!parsed.success)
+        refuse(caller, "stubs", parsed.error);
+    const names = parsed.data.map((s) => s.name);
+    const dup = names.find((n, i) => names.indexOf(n) !== i);
+    if (dup !== undefined)
+        throw new Error(`${caller}: two stubs named ${JSON.stringify(dup)} — one binary has one stub; put both rule lists in it.`);
+    // The zod output has the shape; `toToolStub` gives it the type, without a cast.
+    return parsed.data.map(stub_rules_js_1.toToolStub);
+}
+// --- env -----------------------------------------------------------------------
+const homeSeed = zod_1.z.strictObject({
+    kind: zod_1.z.literal("files"),
+    files: zod_1.z.record(zod_1.z.string(), zod_1.z.string()),
+});
+const runEnv = zod_1.z.discriminatedUnion("kind", [
+    zod_1.z.strictObject({ kind: zod_1.z.literal("ephemeral"), home: homeSeed.optional() }),
+    zod_1.z.strictObject({
+        kind: zod_1.z.literal("inherit"),
+        reason: zod_1.z.string().refine((r) => r.trim() !== "", {
+            message: "say why this run must see your real HOME and environment",
+        }),
+    }),
+]);
+function envRequiredMessage(caller) {
+    return (`${caller}: \`env\` is required — say where each trial runs:\n` +
+        `    env: { kind: "ephemeral" }               a throwaway HOME and a scrubbed environment; only the harness's own auth passes\n` +
+        `    env: { kind: "inherit", reason: "…" }    your real HOME and environment; the reason is printed with the report\n` +
+        `  There is no default. Inheriting measures your machine (your config, your tokens), and an ephemeral run\n` +
+        `  fails on its first trial if your auth is not where the harness expects it — so the choice is yours to make.`);
+}
+/**
+ * Parse an eval spec's `env`, including its seeded HOME: every seed path is
+ * HOME-relative, stays inside HOME, and does not overwrite one of the harness's
+ * own auth files (`keepHomeFiles`). Throws before any trial on a bad value.
+ */
+function parseRunEnv(raw, caller, keepHomeFiles) {
+    if (raw === undefined)
+        throw new Error(envRequiredMessage(caller));
+    if (isObj(raw) && raw.kind === "inherit" && "home" in raw)
+        throw new Error(`${caller}: env.home: \`home\` exists only on an ephemeral env: seeding would write into your real HOME. ` +
+            `Use env: { kind: "ephemeral", home: … }.`);
+    const parsed = runEnv.safeParse(raw);
+    if (!parsed.success)
+        refuse(caller, "env", parsed.error);
+    const env = parsed.data;
+    if (env.kind === "ephemeral" && env.home !== undefined) {
+        const plan = (0, run_env_js_1.planHome)(env.home, keepHomeFiles);
+        if (plan.kind === "refused")
+            throw new Error(`${caller}: env.home.files: ${plan.reason}`);
+    }
+    return env;
+}
+//# sourceMappingURL=eval-spec-parse.js.map

package/dist/core/run-env.d.ts

@@ -6,7 +6,7 @@
  *
  * - SCRUBBED (`scrubbedRunEnv`): a throwaway HOME/TMPDIR, the OS essentials, the
  *   harness's declared auth, and the caller's own named extras. Everything else
- *   is dropped. The eval tier's `ephemeralEnv` and the harness-tier preflight of
+ *   is dropped. The eval tier's `env: { kind: "ephemeral" }` and the harness-tier preflight of
  *   `experimental_outputStyleArms` use it.
  * - INHERITED (`withoutSessionIdentity`): the caller's env as-is, minus the
  *   harness's declared session identity. The default spawn of both tiers.
@@ -46,5 +46,50 @@ export declare function scrubbedRunEnv(base: EnvLike, opts: {
  * a plain spawn env. Without a policy nothing is removed.
  */
 export declare function withoutSessionIdentity(base: EnvLike, policy?: RunEnvPolicy): Readonly<Record<string, string>>;
+/** Files to write under a throwaway HOME: HOME-relative POSIX path → contents. */
+export type HomeFiles = Readonly<Record<string, string>>;
+/**
+ * Where a throwaway HOME's starting contents come from. A FILE map, so an empty
+ * directory cannot be expressed — Claude Code's startup housekeeping removes
+ * empty task directories, and a seed that could hold one would lose it.
+ */
+export interface HomeSeed {
+    readonly kind: "files";
+    readonly files: HomeFiles;
+}
+/**
+ * Where a run executes. Two cases, and `home` exists only on `ephemeral`: there
+ * is no way to write "seed my real HOME".
+ *
+ * - `ephemeral` — a throwaway HOME (seeded from `home`, then given the
+ *   harness's own auth files) and a scrubbed environment.
+ * - `inherit` — your real HOME and environment, minus the parent session's
+ *   identity. `reason` says why, and is printed with the report.
+ */
+export type RunEnv = {
+    readonly kind: "ephemeral";
+    readonly home?: HomeSeed;
+} | {
+    readonly kind: "inherit";
+    readonly reason: string;
+};
+/** One file a seed writes, HOME-relative. */
+export interface HomeFile {
+    readonly path: string;
+    readonly contents: string;
+}
+/** The files a seed writes, sorted by path — or why the seed is refused. */
+export type HomePlan = {
+    readonly kind: "ok";
+    readonly files: readonly HomeFile[];
+} | {
+    readonly kind: "refused";
+    readonly reason: string;
+};
+/**
+ * Validate a seed and list the files it writes. Pure. `keepHomeFiles` are the
+ * harness's auth files (`RunEnvPolicy.keepHomeFiles`), copied in after the seed.
+ */
+export declare function planHome(seed: HomeSeed | undefined, keepHomeFiles: readonly string[]): HomePlan;
 export {};
 //# sourceMappingURL=run-env.d.ts.map

package/dist/core/run-env.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OS_ESSENTIAL_ENV = void 0;
 exports.scrubbedRunEnv = scrubbedRunEnv;
 exports.withoutSessionIdentity = withoutSessionIdentity;
+exports.planHome = planHome;
 /**
  * What ANY spawned process needs to function, whatever the harness: resolve
  * binaries (`PATH`) and keep the locale and terminal (`LANG`, `LC_*`, `TERM`).
@@ -48,4 +49,62 @@ function withoutSessionIdentity(base, policy) {
 function defined(base, keep) {
     return Object.fromEntries(Object.entries(base).filter((e) => e[1] !== undefined && keep(e[0])));
 }
+/** Why `path` cannot be a HOME-relative seed path, or undefined when it can. */
+function seedPathProblem(path, keepHomeFiles) {
+    if (path === "")
+        return "an empty path";
+    if (path.startsWith("/") || path.includes("\\"))
+        return `${JSON.stringify(path)} is not a HOME-relative POSIX path`;
+    const parts = path.split("/");
+    if (parts.some((p) => p === "" || p === "." || p === ".."))
+        return `${JSON.stringify(path)} must stay inside HOME and be spelled plainly (no "", ".", or ".." segments)`;
+    if (keepHomeFiles.includes(path))
+        return `${JSON.stringify(path)} is the harness's own auth file, which the run copies in itself; a seed may not replace it`;
+    return undefined;
+}
+/**
+ * The pairs that cannot both exist: one path written as a FILE while another
+ * needs it to be a DIRECTORY (`a` and `a/b`). Over the seed's paths and the
+ * harness's auth files, as a seed file standing on an auth file's parent
+ * (`.claude`) would fail the same way. Auth files among themselves are the
+ * harness's own business. Without this the run fails mid-trial with a raw
+ * `EEXIST`/`ENOTDIR`, after the trial's directories were built.
+ */
+function seedConflicts(paths, keepHomeFiles) {
+    const isSeed = (p) => paths.includes(p);
+    const label = (p) => isSeed(p)
+        ? JSON.stringify(p)
+        : `${JSON.stringify(p)} (the harness's own auth file)`;
+    const all = [...paths, ...keepHomeFiles];
+    return all.flatMap((file) => all
+        .filter((under) => under.startsWith(`${file}/`))
+        .filter((under) => isSeed(file) || isSeed(under))
+        .map((under) => `${label(file)} is written as a file but ${label(under)} needs it to be a directory`));
+}
+/**
+ * Validate a seed and list the files it writes. Pure. `keepHomeFiles` are the
+ * harness's auth files (`RunEnvPolicy.keepHomeFiles`), copied in after the seed.
+ */
+function planHome(seed, keepHomeFiles) {
+    if (seed === undefined)
+        return { kind: "ok", files: [] };
+    const paths = Object.keys(seed.files).sort();
+    if (paths.length === 0)
+        return {
+            kind: "refused",
+            reason: "a files seed with no files — omit `home` for an empty HOME",
+        };
+    const problems = paths.flatMap((p) => {
+        const why = seedPathProblem(p, keepHomeFiles);
+        return why === undefined ? [] : [why];
+    });
+    // Conflicts are read over well-formed paths only: a "" or "/x" would pair with everything.
+    const refusals = problems.length > 0 ? problems : seedConflicts(paths, keepHomeFiles);
+    if (refusals.length > 0)
+        return { kind: "refused", reason: refusals.join("; ") };
+    return {
+        kind: "ok",
+        files: paths.map((path) => ({ path, contents: seed.files[path] ?? "" })),
+    };
+}
 //# sourceMappingURL=run-env.js.map

package/dist/core/stub-rules.d.ts

@@ -0,0 +1,199 @@
+/**
+ * A tool stub that answers PER INVOCATION — the pure core.
+ *
+ * A stub shadows a binary on PATH (`gh`, `git`, `psql`) so a run that calls it
+ * gets a recorded answer instead of the real service. The earlier stub printed
+ * ONE answer for every argv. That is a test double answering by default, and a
+ * default answer is a fabricated observation: a stub set up to answer
+ * `gh issue create` with an issue URL also answered a script's
+ * `gh api repos/o/r/issues?…` with that URL, the script failed to parse it as
+ * JSON, and a model that read the stub's source stopped trusting it.
+ *
+ * So a stub is a non-empty list of RULES over the argv TOKEN ARRAY. Each rule has
+ * a positional pattern (an exact string or a RegExp per token, and an explicit
+ * trailing `rest` for "any further tokens"), an optional order-free `contains`
+ * for flags, and a reply. The first matching rule answers. An argv no rule
+ * matches is UNANSWERED: the stub exits non-zero, the call is logged, and the
+ * run fails — the same choice `script-overrun.ts` made for a scripted model that
+ * runs past its script.
+ *
+ * Argv is a list, not a line: joining it loses token boundaries (`--title "a b"`
+ * is one token), and a RegExp over the joined line matches across them.
+ *
+ * Everything here is pure and JSON-serialisable, because the same rules are
+ * read by the stub process (one per invocation), folded into the eval cache key
+ * and the lock, and printed in failure messages. No zod here on purpose: this
+ * module is on the stub process's path, which runs once per `gh` call.
+ */
+/** "Any number of further tokens, including none." Only valid as the LAST token. */
+export interface ArgvRest {
+    readonly kind: "rest";
+}
+/** The `rest` marker. One frozen value, so a pattern carries no free-form object. */
+export declare const ARGV_REST: ArgvRest;
+/** One positional token: exact string, or a RegExp tested against that one token. */
+export type ArgvToken = string | Readonly<RegExp>;
+/**
+ * A positional pattern: token i matches argv token i. Without a trailing
+ * {@link ARGV_REST} the argv must have EXACTLY this many tokens, so a read rule
+ * `["api", /^repos\//]` does not also answer `api repos/… -f title=x`.
+ */
+export type ArgvPattern = readonly ArgvToken[] | readonly [...ArgvToken[], ArgvRest];
+/** What the fake binary does when a rule answers. */
+export interface StubAnswer {
+    /** Printed to stdout. Default "". */
+    readonly stdout?: string;
+    /** Printed to stderr. Default none. */
+    readonly stderr?: string;
+    /** Exit code, 0–255. Default 0. */
+    readonly exitCode?: number;
+}
+/**
+ * `always`: every matching call gets the answer. `inOrder`: the k-th matching
+ * call gets `answers[k-1]`, and a call past the end is UNANSWERED — repetition
+ * is something a rule says, never a default.
+ */
+export type StubReply = ({
+    readonly kind: "always";
+} & StubAnswer) | {
+    readonly kind: "inOrder";
+    readonly answers: readonly [StubAnswer, ...StubAnswer[]];
+};
+/** One rule: an argv pattern, optional order-free tokens, and a reply. */
+export interface StubRule {
+    readonly argv: ArgvPattern;
+    /**
+     * Tokens that must each match some argv token AFTER the positional prefix, in
+     * any order — for flags a model writes in any order (`--repo o/r` or `-R o/r`).
+     * Needs a trailing `rest` in `argv` (without it nothing follows the prefix).
+     */
+    readonly contains?: readonly ArgvToken[];
+    readonly reply: StubReply;
+}
+/** A stub for one binary: its name on PATH and its rules, first match wins. */
+export interface ToolStub {
+    readonly name: string;
+    readonly rules: readonly [StubRule, ...StubRule[]];
+}
+/**
+ * What happened to one invocation. Three cases, because the two ways a call goes
+ * unanswered need different fixes: no rule matched (add a rule), or a rule
+ * matched but its `inOrder` answers ran out (add an answer).
+ */
+export type StubOutcome = {
+    readonly kind: "answered";
+    /** 0-based rule index. */
+    readonly rule: number;
+    /** 0-based answer index (always 0 for an `always` reply). */
+    readonly answer: number;
+} | {
+    readonly kind: "no-rule";
+} | {
+    readonly kind: "exhausted";
+    readonly rule: number;
+}
+/**
+ * The stub printed its neutral miss line but left no log line (its directory
+ * was not writable from the agent's shell). Never read from a log: the eval
+ * derives it from the agent's tool results.
+ */
+ | {
+    readonly kind: "unlogged";
+};
+/** One recorded invocation of a stub. */
+export interface StubCall {
+    readonly tool: string;
+    readonly argv: readonly string[];
+    readonly outcome: StubOutcome;
+}
+/** Does `rule` match `argv`? Positional prefix, then `contains` over the tail. Pure, total. */
+export declare function matchArgv(rule: Pick<StubRule, "argv" | "contains">, argv: readonly string[]): boolean;
+/** How many times each rule of `tool` has already answered, from the log so far. */
+export declare function priorAnswers(calls: readonly StubCall[], tool: string): ReadonlyMap<number, number>;
+/** The decision for one invocation: (rules, answers so far, argv) → outcome. Pure, total. */
+export declare function decideInvocation(stub: ToolStub, prior: ReadonlyMap<number, number>, argv: readonly string[]): StubOutcome;
+/** Whether an outcome left the call without an answer. */
+export declare function isUnanswered(o: StubOutcome): boolean;
+/** The answer an `answered` outcome refers to; `undefined` for an unanswered one. */
+export declare function answerFor(stub: ToolStub, o: StubOutcome): StubAnswer | undefined;
+/**
+ * Serialise a stub to JSON. A RegExp becomes `{kind:"re",source,flags}` —
+ * `JSON.stringify(/x/)` is `{}`, which would make two different rules hash the
+ * same in the cache key and the lock.
+ */
+export declare function encodeStub(stub: ToolStub): string;
+/** A typed {@link ToolStub} from a value already known to have its shape. */
+export declare function toToolStub(v: unknown): ToolStub;
+/**
+ * Read back what {@link encodeStub} wrote. The input is vigiles' own output,
+ * written after the spec was parsed, so a bad shape is an internal error.
+ */
+export declare function decodeStub(json: string): ToolStub;
+/** One log line for one call (no trailing newline). */
+export declare function stubLogLine(call: StubCall): string;
+/** Read the JSONL log the stub processes appended. Blank lines are skipped. */
+export declare function parseStubLog(jsonl: string): readonly StubCall[];
+/** A pattern the way a rule is written: `["issue", "create", experimental_stub.rest]`. */
+export declare function describePattern(p: readonly (ArgvToken | ArgvRest)[]): string;
+/**
+ * The failure message for a run with unanswered calls, addressed to the AUTHOR
+ * (the model only ever sees a neutral one-liner). Each distinct argv once, with
+ * a count; the rules it was tried against; and a rule for that exact command to
+ * add. It never suggests a catch-all: answering everything is the defect this
+ * exists to stop. `undefined` when every call was answered.
+ */
+export declare function unansweredMessage(calls: readonly StubCall[], stubs: readonly ToolStub[]): string | undefined;
+/**
+ * The exit code of an unanswered call. Not 127: that tells the caller "not
+ * installed", and a model changes plans for the wrong reason.
+ */
+export declare const UNANSWERED_EXIT_CODE = 97;
+/**
+ * What an unanswered call prints to stderr — the only thing the MODEL sees. One
+ * fixed line: no argv, no rules, no "add a rule". Instructions here would tell
+ * the model it is in a test and what the author will do, and the rest of the
+ * trial would measure a reaction to that. The diagnostic goes to the author,
+ * from the log, through {@link unansweredMessage}.
+ */
+export declare function unsupportedLine(name: string): string;
+/**
+ * The misses a stub could not log, found from the agent's side: every
+ * occurrence of a stubbed tool's neutral miss line ({@link unsupportedLine}) in
+ * `texts` (the agent's tool results) beyond the unanswered calls the log already
+ * holds for that tool. The line is vigiles' own marker, not a guess about what
+ * the agent ran, so this is a count of a thing we printed. A miss the log has
+ * is counted once — by the log. Pure.
+ */
+export declare function unloggedMisses(texts: readonly string[], logged: readonly StubCall[], names: readonly string[]): readonly StubCall[];
+/** Where a stub root keeps its files (`name` picks the per-stub ones). Pure path arithmetic. */
+export declare function stubPaths(root: string, name?: string): {
+    readonly binDir: string;
+    readonly rulesDir: string;
+    readonly rules: string;
+    readonly log: string;
+    readonly bin: string;
+};
+/** The two file operations one invocation needs — injected, so the decision stays testable. */
+export interface StubIo {
+    /** File contents, or null when the file does not exist. */
+    readonly readFile: (path: string) => string | null;
+    /** Append text; one call per log line (`O_APPEND`, one write). */
+    readonly appendFile: (path: string, text: string) => void;
+}
+/** What the stub process prints and how it exits. */
+export interface StubProcessResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+}
+/**
+ * One invocation: read the rules and the log so far, decide, append one log
+ * line, return what to print. It never reads stdin: a caller that leaves the
+ * pipe open (Node's `execFile` does) would block until its own timeout.
+ *
+ * Concurrency, said plainly: two simultaneous calls of the same `inOrder` rule
+ * can both read "answered k times" and both get answer k. One line per write
+ * keeps the log itself intact.
+ */
+export declare function runStub(root: string, name: string, argv: readonly string[], io: StubIo): StubProcessResult;
+//# sourceMappingURL=stub-rules.d.ts.map