vigiles 33.3.0 → 35.0.0

package/dist/harness-test.js

@@ -6,10 +6,14 @@ exports.parseSubagents = parseSubagents;
 exports.parseResultEvent = parseResultEvent;
 exports.parseOutput = parseOutput;
 exports.parseHooks = parseHooks;
+exports.toolAvailabilityList = toolAvailabilityList;
+exports.unofferedScriptedTool = unofferedScriptedTool;
+exports.unsupportedToolsFlag = unsupportedToolsFlag;
 exports.buildClaudeArgs = buildClaudeArgs;
 exports.parseClaudeRun = parseClaudeRun;
 exports.harnessSpawnEnv = harnessSpawnEnv;
 exports.claudeAvailable = claudeAvailable;
+exports.warnUnconsumed = warnUnconsumed;
 exports.runHarnessTest = runHarnessTest;
 exports.runHarnessTestIn = runHarnessTestIn;
 exports.runHarness = runHarness;
@@ -49,6 +53,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const adapter_conformance_js_1 = require("./adapter-conformance.js");
 const check_count_js_1 = require("./check-count.js");
+const script_overrun_js_1 = require("./core/script-overrun.js");
 const coverage_probe_js_1 = require("./coverage-probe.js");
 const runtime_js_1 = require("./adapters/claude-code/runtime.js");
 const mock_model_js_1 = require("./mock-model.js");
@@ -274,6 +279,51 @@ function parseHooks(stdout) {
     }
     return hooks;
 }
+/**
+ * The first `claude` that has `--tools` (print mode). Found by diffing the
+ * published `@anthropic-ai/claude-code` tarballs: 2.0.30 has no such option,
+ * 2.0.31 does (the changelog does not list it; its 2.1.0 entry only extends the
+ * flag to interactive mode).
+ */
+const TOOLS_FLAG_MIN_CLAUDE = "2.0.31";
+/**
+ * The names `--tools` should offer for an `allowedTools` list. `--allowedTools`
+ * takes permission rules (`Bash(git *)`); `--tools` takes tool NAMES, and a rule
+ * with a specifier there makes the CLI offer no tools at all. So the specifier is
+ * dropped (`Bash(git *)` → `Bash`) and repeats collapse. Pure.
+ */
+function toolAvailabilityList(allowed) {
+    const names = allowed.map((rule) => rule.replace(/\(.*$/, "").trim());
+    return [...new Set(names.filter((n) => n !== ""))];
+}
+/**
+ * A scripted call to a tool an EXPLICIT `allowedTools` does not offer. The CLI
+ * answers it with "No such tool available" and the run goes on, so a test that
+ * scripts the call and then asserts on something else passes over a step that
+ * never happened. Returns the message to throw, or undefined. MCP tools are not
+ * built-ins, so `--tools` does not withhold them and they are skipped. Pure.
+ */
+function unofferedScriptedTool(model, allowed) {
+    if (allowed === undefined)
+        return undefined;
+    const offered = toolAvailabilityList(allowed);
+    const at = model.findIndex((t) => t.tool !== undefined &&
+        !t.tool.startsWith("mcp__") &&
+        !offered.includes(t.tool));
+    return at < 0
+        ? undefined
+        : `scripted call to "${model[at]?.tool ?? ""}" on turn ${String(at + 1)}, but this run offers only: ${offered.join(", ")} — add it to allowedTools`;
+}
+/**
+ * A run on a `claude` that predates `--tools` exits at argument parsing, and
+ * commander's "unknown option" says nothing about WHY vigiles passed it. Returns
+ * the message to throw, or undefined when the run did not die that way. Pure.
+ */
+function unsupportedToolsFlag(stderr) {
+    return /unknown option '--tools'/.test(stderr)
+        ? `this \`claude\` does not know \`--tools\`, which runHarnessTest uses to withhold every tool not in \`allowedTools\` (#252). Update Claude Code to ${TOOLS_FLAG_MIN_CLAUDE} or newer. Running without it would hand the agent every tool while the test reads as if it were fenced.`
+        : undefined;
+}
 /**
  * The `claude` CLI argv for a harness run (shared by the direct and sandboxed
  * paths). `ANTHROPIC_BASE_URL` is set by the caller's environment / wrapper, not
@@ -293,8 +343,17 @@ function buildClaudeArgs(spec, hasSettings) {
             ? ["--plugin-dir", (0, node_path_1.resolve)(spec.pluginDir)]
             : []),
         ...(hasSettings ? ["--settings", "settings.json"] : []),
-        // A permission allowlist: an empty one approves nothing, so the flag is
-        // left out (a bare `--allowedTools` exits before any model turn).
+        // An EXPLICIT list restricts: `--tools` is the AVAILABILITY list, a tool left
+        // out is not offered at all. `--allowedTools` only PRE-APPROVES (it never
+        // restricts), so on its own it left every unnamed tool runnable (#252). An
+        // empty list is `--tools ""` = no tools. With no list, nothing is withheld:
+        // the default four are pre-approved and every other tool stays available.
+        ...(spec.allowedTools === undefined
+            ? []
+            : ["--tools", toolAvailabilityList(spec.allowedTools).join(",")]),
+        // Pre-approval for the offered tools, so none stops on a permission prompt
+        // (headless). An empty one approves nothing, so the flag is left out (a bare
+        // `--allowedTools` exits before any model turn).
         ...(tools.length === 0 ? [] : ["--allowedTools", ...tools]),
     ];
 }
@@ -415,6 +474,26 @@ exports.claudeCodeDriver = {
     parseRun: parseClaudeRun,
     available: claudeAvailable,
 };
+/** Say so on stderr when side-channel calls arrived and no script turn was served. */
+function warnUnconsumed(count, sideChannelCount) {
+    const unconsumed = (0, mock_model_js_1.scriptUnconsumedWarning)(count, sideChannelCount);
+    if (unconsumed !== undefined)
+        console.error(unconsumed);
+}
+/**
+ * A run that proves nothing about the script fails the test instead of coming
+ * back as a result: the `claude` on PATH predates `--tools` (#252), or the agent
+ * asked for a model turn the script did not have and the mock answered with an
+ * error rather than an invented turn (#340). Removes the run's directory, since
+ * no result is handed back to clean it up.
+ */
+function assertRunSound(cwd, stderr, scripted, modelRequests) {
+    const problem = unsupportedToolsFlag(stderr) ?? (0, script_overrun_js_1.overrunMessageFor)(scripted, modelRequests);
+    if (problem === undefined)
+        return;
+    (0, node_fs_1.rmSync)(cwd, { recursive: true, force: true });
+    throw new Error(problem);
+}
 /* v8 ignore start -- spawns the real agent CLI + filesystem; exercised by the
    claude-backed + gated codex suites, excluded from the deterministic coverage
    gate (the parse helpers above carry the testable logic). */
@@ -457,8 +536,22 @@ function makeResult(cwd, out, parsed, turns, modelRequests) {
  * only — requesting confinement for another harness throws.
  */
 async function runHarnessTest(spec, opts = {}) {
+    refuseUnrunnableSpec(spec);
     return runHarnessTestIn(spec, opts, "inherit");
 }
+/**
+ * The scripted model tells an agent turn from the CLI's own bookkeeping calls by
+ * the tools the request declares (`isMainLoopRequest`). An agent with none is
+ * never served a script turn, and the run would decide on nothing.
+ */
+function refuseUnrunnableSpec(spec) {
+    if (spec.allowedTools?.length === 0) {
+        throw new Error("allowedTools: [] leaves the agent with no tools, and the scripted model only serves a turn to a request that declares tools — no script turn would be consumed. Name the tools the agent has.");
+    }
+    const unoffered = unofferedScriptedTool(spec.model, spec.allowedTools);
+    if (unoffered !== undefined)
+        throw new Error(unoffered);
+}
 /**
  * {@link runHarnessTest} with the run's HOME chosen by the caller — see
  * {@link HarnessRunHome}. Not on a public entry point: the one caller that needs
@@ -491,13 +584,12 @@ async function runHarnessTestIn(spec, opts, home) {
     const { files, settings, check } = fixtureFor(spec, opts.adapter);
     const cwd = (0, tmp_root_js_1.makeTmpDir)("harness");
     writeFixture(cwd, files, settings);
-    const tools = spec.allowedTools ?? ["Read", "Edit", "Write", "Bash"];
     const timeoutMs = spec.timeoutMs ?? 60000;
     const buildArgs = (mockArgs) => driver.buildArgs({
         prompt: spec.prompt ?? "go",
         cwd,
         hasSettings: settings !== undefined,
-        tools,
+        tools: spec.allowedTools,
         transcript: spec.transcript ?? false,
         pluginDir: spec.pluginDir,
         mockArgs,
@@ -519,9 +611,8 @@ async function runHarnessTestIn(spec, opts, home) {
         // the direct one stays right. Same recovery feeds the unconsumed-script
         // warning, which the sandbox path could not emit at all before.
         const { count, sideChannelCount } = (0, mock_model_js_1.splitRequestCounts)(out.requests);
-        const unconsumed = (0, mock_model_js_1.scriptUnconsumedWarning)(count, sideChannelCount);
-        if (unconsumed !== undefined)
-            console.error(unconsumed);
+        warnUnconsumed(count, sideChannelCount);
+        assertRunSound(cwd, "", spec.model.length, out.requests);
         return check(makeResult(cwd, out, parseClaudeRun(out.stdout), count, out.requests));
     }
     // Direct path: mock runs in this process; the agent reaches it over localhost.
@@ -539,9 +630,8 @@ async function runHarnessTestIn(spec, opts, home) {
         // looks empty. `scriptUnconsumedWarning` names the one shape that produces
         // it (every request arriving without tool declarations, so nothing looked
         // like an agent turn) instead of leaving it to be rediscovered.
-        const unconsumed = (0, mock_model_js_1.scriptUnconsumedWarning)(mock.count, mock.sideChannelCount ?? 0);
-        if (unconsumed !== undefined)
-            console.error(unconsumed);
+        warnUnconsumed(mock.count, mock.sideChannelCount ?? 0);
+        assertRunSound(cwd, out.stderr, spec.model.length, mock.requests);
         return check(makeResult(cwd, out, driver.parseRun(out.stdout), mock.count, [
             ...mock.requests,
         ]));

package/dist/mock-model.d.ts

@@ -78,7 +78,10 @@ export declare function extractRequest(body: {
 }): ModelRequest;
 /**
  * Start the scripted mock on a free port. Each MAIN-LOOP `/v1/messages` POST
- * consumes the next turn (the last turn repeats if the client asks for more);
+ * consumes the next turn; one past the end of the script is answered with a
+ * non-retryable API error, never a copy of the last turn (#340 — a looping
+ * agent would pass on turns nobody scripted), and `runHarnessTest` then fails
+ * the test from the recorded requests ({@link findScriptOverrun});
  * a SIDE-CHANNEL POST — the CLI's own bookkeeping calls, see
  * {@link isMainLoopRequest} — is answered from outside the script and consumes
  * nothing. Resolves to a handle with the base `url` and a `close()`.

package/dist/mock-model.js

@@ -28,6 +28,7 @@ exports.startMock = startMock;
  * and echoing the requested model.
  */
 const node_http_1 = __importDefault(require("node:http"));
+const script_overrun_js_1 = require("./core/script-overrun.js");
 /** Build a scripted model from an ordered list of turns. */
 function scriptModel(turns) {
     return [...turns];
@@ -388,9 +389,41 @@ function extractRequest(body) {
         : [];
     return { system: flattenContent(body.system), messages };
 }
+/**
+ * The 400 body for an agent request past the end of the script: an API error,
+ * because the CLI retries 429/5xx and an invented turn would let the agent act on
+ * a step nobody scripted (#340). Pure.
+ */
+function pastScriptBody(scripted, request) {
+    const message = (0, script_overrun_js_1.scriptOverrunMessage)({
+        scripted,
+        request: scripted + 1,
+        lastMessage: request.messages.at(-1)?.text ?? "",
+    });
+    return JSON.stringify({
+        type: "error",
+        error: { type: "invalid_request_error", message },
+    });
+}
+/** Does a message's content carry a tool result (the agent reacting to a tool)? */
+function endsWithToolResult(content) {
+    return JSON.stringify(content ?? "").includes('"tool_result"');
+}
+/** The JSON body of a request, `{}` for the HEAD / health checks that have none. */
+function parseReqBody(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * Start the scripted mock on a free port. Each MAIN-LOOP `/v1/messages` POST
- * consumes the next turn (the last turn repeats if the client asks for more);
+ * consumes the next turn; one past the end of the script is answered with a
+ * non-retryable API error, never a copy of the last turn (#340 — a looping
+ * agent would pass on turns nobody scripted), and `runHarnessTest` then fails
+ * the test from the recorded requests ({@link findScriptOverrun});
  * a SIDE-CHANNEL POST — the CLI's own bookkeeping calls, see
  * {@link isMainLoopRequest} — is answered from outside the script and consumes
  * nothing. Resolves to a handle with the base `url` and a `close()`.
@@ -406,13 +439,7 @@ function startMock(script, opts = {}) {
             const url = req.url ?? "";
             const isCount = url.includes("count_tokens");
             const isMessages = url.includes("/v1/messages") && !isCount;
-            let reqBody = {};
-            try {
-                reqBody = JSON.parse(body);
-            }
-            catch {
-                /* HEAD / health checks have no JSON body */
-            }
+            const reqBody = parseReqBody(body);
             if (req.method === "HEAD" || (!isMessages && !isCount)) {
                 res.writeHead(200, { "content-type": "application/json" });
                 res.end("{}");
@@ -445,13 +472,17 @@ function startMock(script, opts = {}) {
                     jsonTurn(res, reply, model);
                 return;
             }
-            const last = JSON.stringify(reqBody.messages?.at(-1)?.content ?? "");
+            const turn = script[i];
+            if (turn === undefined) {
+                res.writeHead(400, { "content-type": "application/json" });
+                res.end(pastScriptBody(script.length, request));
+                return;
+            }
             opts.onTurn?.({
                 n: i,
                 stream: reqBody.stream === true,
-                hasToolResult: last.includes('"tool_result"'),
+                hasToolResult: endsWithToolResult(reqBody.messages?.at(-1)?.content),
             });
-            const turn = script[Math.min(i, script.length - 1)] ?? { text: "" };
             i++;
             if (reqBody.stream === true)
                 streamTurn(res, turn, model);

package/dist/setup-plan.d.ts

@@ -77,6 +77,11 @@ export interface ParsedSetupArgs {
      * DISCOVERY row of `cohesive-feature-delivery`.
      */
     ciOnly: boolean;
+    /**
+     * `--full` — run the whole setup even on a repo that already uses vigiles.
+     * Without it, a re-run there is the minimal one (see {@link rerunScope}).
+     */
+    full: boolean;
 }
 /** Parse `init` args into the choices the user pinned. The two pillars are
  * selected with `--lint` / `--test`. */
@@ -87,29 +92,6 @@ export declare function parseSetupArgs(args: readonly string[]): ParsedSetupArgs
  * raw files WITHOUT scaffolding a spec (gate-first-adoption). Non-interactive
  * behaviour is unchanged: bare `init` (lint on) scaffolds as before. */
 export declare function defaultPlan(strict?: boolean): SetupPlan;
-/**
- * Pure config-merge for what `vigiles init` writes to `.vigilesrc.json`: record
- * the `harness` if absent, add strict rule severities if `--strict`, NEVER
- * clobber an existing key. Returns the merged config, or `null` when nothing
- * changed (so the IO layer skips the write). The IO (read/parse/write + the
- * malformed-file guard) stays in cli.ts.
- */
-/**
- * The structural rules `init` gates BY DEFAULT (severity `error`, so a broken
- * surface fails `vigiles lint`). Every one is HIGH-PRECISION / FP-safe — it fires
- * only on a genuine defect (a never-available/typo'd tool, a subagent missing
- * `name`/`description`, a typo'd hook event, a dead hook script, a broken MCP
- * ref, two skills that collide in the selector) — so a well-formed plugin stays
- * green and catching real breakage out of the box never cries wolf.
- *
- * Deliberately EXCLUDES `require-instructions-spec` and the workflow-forcing rules:
- * those make a CLEAN repo fail (you simply haven't written the spec/test yet), so
- * they stay opt-in under `--strict` (progressive adoption — see
- * `STRICT_EXTRA_RULES`).
- *
- * This is the **`structural`** rule group (see research/install-enforcement-dx.md).
- */
-export declare const STRUCTURAL_RULES: readonly ["subagent-tool-contract", "subagent-frontmatter", "hook-events", "hook-script-exists", "mcp-config", "mcp-tool-resolves", "mcp-hook-target-resolves", "disallowed-tools-contract", "description-overlap"];
 /**
  * The **`workflow`** group — the WORKFLOW-FORCING / opinionated tier `--strict`
  * gates, which a clean repo can still fail because you haven't done the work yet:
@@ -135,7 +117,24 @@ export declare const WORKFLOW_RULES: readonly ["require-instructions-spec", "unt
  * (research/install-enforcement-dx.md).
  */
 export declare const NUDGE_RULES: readonly ["skill-description-budget", "frontmatter-valid", "skill-frontmatter", "prefer-compiled-hooks", "unmarked-refs", "lethal-trifecta", "skill-resource-resolves", "skill-missing-fence", "plugin-dir-layout", "delegation-trifecta", "hook-block-ineffective", "hook-matcher", "doc-refs"];
-export declare function mergeProjectConfig(existing: Record<string, unknown>, opts: {
+/**
+ * Pure config-merge for what `vigiles init` writes to `.vigilesrc.json`: record
+ * the harnesses if absent, gate the structural rules by EXTENDING the
+ * `vigiles:recommended` preset (never by writing each rule), add the workflow
+ * rules on `--strict`, and NEVER clobber an existing key or severity. Returns
+ * the merged config, or `null` when nothing changed (so the IO layer skips the
+ * write). The IO (read/parse/write + the malformed-file guard) stays in cli.ts.
+ *
+ * 🔴 THE PRESET, NOT NINE LINES (#338). Written lines are a snapshot of the
+ * structural group on the day `init` ran, so a repo adopted earlier never got a
+ * rule added to the group later; the preset is resolved by the loader on every
+ * run (`src/core/presets.ts`).
+ *
+ * `--report-only` is the exception and stays EXPLICIT: it promises that nothing
+ * fails CI, and extending a preset that later gains a rule at `error` would
+ * break that promise on an upgrade. So it writes the same rules at `warn`.
+ */
+export declare function mergeProjectConfig(existing: Readonly<Record<string, unknown>>, opts: Readonly<{
     /** Canonical harness names this repo targets, in the order to declare them. */
     harnesses: readonly string[];
     strict: boolean;
@@ -144,7 +143,7 @@ export declare function mergeProjectConfig(existing: Record<string, unknown>, op
      * concern, so a test-only setup (`init --test` / `--no-lint`) records the
      * harness but writes NO lint rules. */
     lint?: boolean;
-}): Record<string, unknown> | null;
+}>): Record<string, unknown> | null;
 /**
  * Whether to drop into interactive prompts: a human at a TTY who passed neither
  * `--yes` nor an explicit `--target`, and who hasn't already pinned every choice
@@ -292,6 +291,75 @@ export declare function codexPluginHooks(): CodexPluginHook[];
  * (and every other config key) untouched. Returns a new object.
  */
 export declare function applyCodexPluginHooks(existing: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Whether this repo already uses vigiles, decided from what is ON DISK.
+ *
+ * 🔴 THE SIGNAL IS `.vigilesrc.json` OR A SPEC NEXT TO AN INSTRUCTION FILE, and
+ * deliberately NOT a `vigiles` devDependency: the documented first step on a new
+ * repo can be `npm i -D vigiles` followed by `npx vigiles init`, and that run
+ * must still be the full setup. Every `init` writes `.vigilesrc.json` (it records
+ * the harnesses even on a test-only run), and a hand-written one means the owner
+ * has already configured vigiles. A spec beside `CLAUDE.md`/`AGENTS.md` covers a
+ * repo adopted before the config file existed.
+ */
+export type AdoptionState = {
+    readonly kind: "fresh";
+} | {
+    readonly kind: "adopted";
+    readonly evidence: string;
+};
+/** {@link AdoptionState} from the two disk facts that decide it. */
+export declare function adoptionState(facts: Readonly<{
+    hasConfig: boolean;
+    specs: readonly string[];
+}>): AdoptionState;
+/**
+ * Which setup a run performs: the full one, or the minimal re-run (#338).
+ *
+ * MINIMAL only when the repo is adopted AND the run named nothing that asks for
+ * more. A flag that selects or widens the setup (`--full`, `--strict`,
+ * `--ci-only`, `--report-only`, `--force`, `--target=`, a positive `--lint` /
+ * `--test`) is an explicit request and keeps today's behaviour; the narrowing
+ * flags (`--no-*`, `--harness=`, `--yes`) do not, because they can only make a
+ * run do less.
+ */
+export declare function rerunScope(parsed: Readonly<ParsedSetupArgs>, state: AdoptionState): "full" | "minimal";
+/**
+ * The `devDependencies` a minimal re-run writes, or null to leave package.json
+ * alone. It ADDS vigiles when no dependency field declares it and never edits an
+ * existing declaration: rewriting `^33.3.0` to `^33` loosens a pin the owner
+ * chose, and moving it between fields is a decision, not a missing piece.
+ */
+export declare function missingVigilesDevDep(pkg: Readonly<{
+    dependencies?: Readonly<Record<string, string>>;
+    devDependencies?: Readonly<Record<string, string>>;
+}>, spec: string): Readonly<Record<string, string>> | null;
+/** What a full setup would add on an adopted repo — the facts that decide it. */
+export interface FullSetupGap {
+    /** `.github/workflows/vigiles.yml` is absent (and CI wiring is not opted out). */
+    readonly workflow: boolean;
+    /** `.vigilesrc.json`: absent, present without the preset, or already extending it. */
+    readonly config: "missing" | "no-preset" | "has-preset";
+    /** `vigiles.harness.mjs` is absent (and the test layer is not opted out). */
+    readonly harnessTest: boolean;
+    /** Instruction files and surfaces a full setup would adopt into a spec. */
+    readonly unspecced: readonly string[];
+    /** `.vigiles/generated.d.ts` / `.vigiles/schema.json` would be created. */
+    readonly generated: boolean;
+    /** The global plugin install / hook wiring a full setup would run, one line each. */
+    readonly installs: readonly string[];
+    /** The devDependency rewrite a full setup would make, if any. */
+    readonly devDep: Readonly<{
+        from: string;
+        to: string;
+    }> | null;
+}
+/**
+ * The lines a minimal re-run prints about what it did NOT do: each thing a full
+ * setup would add here, then the flag that does it. Empty when nothing is
+ * missing, so a fully set-up repo is not told to run anything.
+ */
+export declare function fullSetupFollowUps(gap: FullSetupGap): readonly string[];
 /**
  * Resolve the final plan: defaults, then flags, then interactive answers (each
  * layer overrides the previous only where it has an opinion). `--target` pins a