vigiles 29.1.0 → 30.0.1

package/dist/coverage-artifact.js

@@ -58,10 +58,10 @@ const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const coverage_evidence_js_1 = require("./coverage-evidence.js");
+const local_files_js_1 = require("./local-files.js");
+Object.defineProperty(exports, "COVERAGE_ARTIFACT_FILE", { enumerable: true, get: function () { return local_files_js_1.COVERAGE_ARTIFACT_FILE; } });
 /** Bumped when the record shape changes in a non-additive way. */
 exports.COVERAGE_ARTIFACT_VERSION = 1;
-/** The artifact filename under `.vigiles/`. */
-exports.COVERAGE_ARTIFACT_FILE = "coverage.json";
 /**
  * Every {@link RunAttribution}, as data — the artifact's validator reads it, so
  * the accepted set and the type cannot drift apart into a record shape the
@@ -576,7 +576,7 @@ function mergeRuns(previous, next, executed) {
 }
 /** Read the artifact, or `undefined` when there is none / it is not one. */
 function readCoverageArtifact(root) {
-    const file = (0, node_path_1.resolve)(root, ".vigiles", exports.COVERAGE_ARTIFACT_FILE);
+    const file = (0, node_path_1.resolve)(root, local_files_js_1.VIGILES_DIR, local_files_js_1.COVERAGE_ARTIFACT_FILE);
     if (!(0, node_fs_1.existsSync)(file))
         return undefined;
     let value;
@@ -618,9 +618,10 @@ function isCoverageRun(value) {
 /** Write the artifact. Best-effort: recording must never fail a green run. */
 function writeCoverageArtifact(root, artifact) {
     try {
-        const dir = (0, node_path_1.resolve)(root, ".vigiles");
+        const dir = (0, node_path_1.resolve)(root, local_files_js_1.VIGILES_DIR);
         (0, node_fs_1.mkdirSync)(dir, { recursive: true });
-        (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(dir, exports.COVERAGE_ARTIFACT_FILE), JSON.stringify(artifact, null, 2) + "\n");
+        (0, local_files_js_1.ensureLocalFilesIgnored)(dir);
+        (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(dir, local_files_js_1.COVERAGE_ARTIFACT_FILE), JSON.stringify(artifact, null, 2) + "\n");
     }
     catch {
         /* best-effort — a scratch-dir failure is not a test failure */

package/dist/eval-cache.d.ts

@@ -74,7 +74,12 @@ export declare function cacheKey(input: CacheKeyInput): SHA256Hash;
  * gate must surface, not mask. The message tells you how to recover.
  */
 export declare function readCache(dir: string, key: SHA256Hash): CacheRecord | null;
-/** Write a cached record by key (creating the cache dir as needed). */
+/**
+ * Write a cached record by key (creating the cache dir as needed). When `dir` is
+ * the default `.vigiles/eval-cache`, the recorded runs are per-checkout, so the
+ * `.vigiles/.gitignore` is kept current; a `cacheDir` the spec chose elsewhere is
+ * the author's to place and is left alone.
+ */
 export declare function writeCache(dir: string, key: SHA256Hash, record: CacheRecord): void;
 /** Snapshot the text files under `cwd` as `relativePath → contents` (bounded). */
 export declare function snapshotDir(cwd: string): Record<string, string>;

package/dist/eval-cache.js

@@ -28,6 +28,7 @@ exports.hashDir = hashDir;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const hash_js_1 = require("./core/hash.js");
+const local_files_js_1 = require("./local-files.js");
 const MAX_SNAPSHOT_FILE_BYTES = 1024 * 1024;
 const SKIP_DIRS = new Set(["node_modules", ".git"]);
 /**
@@ -113,9 +114,18 @@ function readCache(dir, key) {
         throw new Error(`eval cache: corrupt record ${path} (invalid JSON) — delete it or clear the cache dir`);
     }
 }
-/** Write a cached record by key (creating the cache dir as needed). */
+/**
+ * Write a cached record by key (creating the cache dir as needed). When `dir` is
+ * the default `.vigiles/eval-cache`, the recorded runs are per-checkout, so the
+ * `.vigiles/.gitignore` is kept current; a `cacheDir` the spec chose elsewhere is
+ * the author's to place and is left alone.
+ */
 function writeCache(dir, key, record) {
     (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    if ((0, node_path_1.basename)(dir) === local_files_js_1.EVAL_CACHE_DIR &&
+        (0, node_path_1.basename)((0, node_path_1.dirname)(dir)) === local_files_js_1.VIGILES_DIR) {
+        (0, local_files_js_1.ensureLocalFilesIgnored)((0, node_path_1.dirname)(dir));
+    }
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, `${key}.json`), JSON.stringify(record));
 }
 /** Snapshot the text files under `cwd` as `relativePath → contents` (bounded). */

package/dist/eval.d.ts

@@ -1,4 +1,7 @@
-import { parseToolCalls, parseHooks, parseSubagents, type ToolCall, type Trace } from "./harness-test.js";
+import type { HarnessLiveDriver } from "./core/live-driver.js";
+import type { AgentRunArgs, AgentRunner, EvalDriver, EvalUsage, ModelOutputParser, ParsedModelRun, RunOut } from "./core/eval-driver.js";
+export type { AgentRunArgs, AgentRunner, EvalDriver, EvalUsage, ModelOutputParser, ParsedModelRun, RunOut, } from "./core/eval-driver.js";
+import { type ToolCall, type Trace } from "./harness-test.js";
 import { type CacheMode } from "./eval-cache.js";
 import { type EvalLockOptions } from "./eval-lock.js";
 import type { Check, CheckJSON } from "./check.js";
@@ -54,20 +57,6 @@ export interface EvalArm {
      */
     readonly effort?: string | number;
 }
-/** Per-run resource use, parsed from the terminal `result` event (0 when absent). */
-export interface EvalUsage {
-    /** `total_cost_usd` reported by claude. */
-    readonly costUsd: number;
-    /** Wall-clock `duration_ms` of the run. */
-    readonly durationMs: number;
-    /** Fresh (uncached) input tokens, billed at full input price. */
-    readonly inputTokens: number;
-    readonly outputTokens: number;
-    /** Tokens written to the prompt cache this run (~1.25× input price). */
-    readonly cacheCreationTokens: number;
-    /** Tokens served from the prompt cache this run (~0.1× input price). */
-    readonly cacheReadTokens: number;
-}
 /**
  * Context handed to `measure` after a run, to compute that run's metrics. It is
  * a `Trace` (so the bare predicates `usedTool` / `skillResolved` / `toolCount` /
@@ -231,52 +220,6 @@ export interface EvalReport {
     /** True if a `maxCostUsd` budget cap stopped the run before all trials ran. */
     readonly aborted: boolean;
 }
-/** The raw output of one trial: the agent's exit code + captured streams. */
-export interface RunOut {
-    code: number;
-    stdout: string;
-    /** Captured stderr, when the runner provides it (used for rate-limit detection). */
-    stderr?: string;
-}
-/** The per-trial arguments handed to an {@link AgentRunner}. */
-export interface AgentRunArgs {
-    readonly task: string;
-    readonly cwd: string;
-    readonly model: string;
-    /**
-     * Reasoning-budget level for the run (`claude --effort`). Part of the
-     * MEASUREMENT, not a run knob: it changes the model's output distribution, not
-     * the sample size — so it lives on the spec next to `model` (never an env),
-     * and it is hashed into both the cache key and the eval lock. Deliberately
-     * `string | number` rather than a literal union: the binary accepts an alias
-     * map, is case-insensitive, and takes an integer budget, and its own valid set
-     * MOVED between builds (2.1.42 had no `xhigh`, 2.1.257 does) — a hard-coded
-     * union would reject a valid level after any upstream addition. A wrong value
-     * is caught at RUNTIME instead, by {@link effortRejection}, which is what the
-     * binary actually tells us. Omit for the harness default.
-     */
-    readonly effort?: string | number;
-    readonly tools: readonly string[];
-    readonly hasSettings: boolean;
-    readonly pluginDir: string | undefined;
-    readonly timeoutMs: number;
-    /** Extra env layered over `process.env` for this run (e.g. `VIGILES_INTERCEPT_TOOLS`). */
-    readonly env?: Record<string, string>;
-    /**
-     * 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`.
-     */
-    readonly replaceEnv?: boolean;
-}
-/**
- * Runs one trial and returns its raw output. The default (`spawnAgent`)
- * drives the real `claude` CLI; `runEvalWith` takes one explicitly, so the eval
- * orchestration is testable without a model (pass a fake returning canned
- * stream-json) and a custom runtime can be plugged in.
- */
-export type AgentRunner = (args: AgentRunArgs) => Promise<RunOut>;
 /**
  * Resolve the environment a trial's subprocess actually runs with — the
  * SECURITY-CRITICAL decision behind `ephemeralEnv`. When `replaceEnv` is set, the
@@ -528,22 +471,6 @@ export declare function checkReportToJUnit(report: CheckReport, opts?: {
 }): string;
 /** Parse per-run cost/latency/tokens from a stream — pure, model-free. */
 export declare function parseUsage(stdout: string): EvalUsage;
-/**
- * The harness-specific half of a run trace: how a real model's raw stdout maps
- * to the common fields. Claude Code's `parseClaudeRun` reads its stream-json; a
- * second harness (Codex) supplies its own parser of `codex exec --json` JSONL, so
- * the eval tier (`measureTriggerRate`/`runEval`) isn't bound to Claude's format.
- * The non-harness fields (cwd/exitCode/stdout/file/sh) stay in `makeContext`.
- */
-export interface ParsedModelRun {
-    readonly turns: number;
-    readonly output: string;
-    readonly toolCalls: ReturnType<typeof parseToolCalls>;
-    readonly hooks: ReturnType<typeof parseHooks>;
-    readonly subagents: ReturnType<typeof parseSubagents>;
-    readonly usage: EvalUsage;
-}
-export type ModelOutputParser = (out: RunOut) => ParsedModelRun;
 /** Parse Claude Code's stream-json stdout into the common trace fields. */
 export declare function parseClaudeRun(out: RunOut): ParsedModelRun;
 /**
@@ -864,37 +791,6 @@ export interface TriggerRateReport {
      */
     readonly experimental?: string;
 }
-/**
- * An eval-tier transport: how to RUN a real harness turn and PARSE its output.
- * The default is Claude Code (`claudeEvalDriver`); a second harness supplies its
- * own (e.g. `codexEvalDriver` from `vigiles/codex`) and passes it as
- * `measureTriggerRate(spec, { evalDriver })` — the eval-tier analog of
- * `runHarnessTest`'s `{ adapter }`. `runError` lets the loop drop an
- * errored/rate-limited turn instead of scoring it as a miss.
- */
-export interface EvalDriver {
-    readonly runner: AgentRunner;
-    readonly parse: ModelOutputParser;
-    readonly runError?: (out: RunOut) => string | null;
-    /**
-     * The harness this driver runs (e.g. `"claude-code"`, `"codex"`). Folded into a
-     * trigger-rate eval's LOCK hash so a report recorded on one harness is marked
-     * STALE if the eval is later switched to another (a different harness can fire a
-     * skill differently). Optional for back-compat — absent defaults to
-     * `"claude-code"`, so an existing single-harness lock is unaffected.
-     */
-    readonly harness?: string;
-    /**
-     * When set, this driver's trigger-rate number is EXPERIMENTAL and not
-     * validated — the string is the human caveat explaining why (e.g. Codex has no
-     * skill-selection event, so firing is inferred from a SKILL.md read, which can
-     * be wrong in both directions). Absent = supported/trustworthy (the default,
-     * Claude Code). `measureTriggerRate` copies it onto the report and warns; the
-     * formatter prints it. Precision-first: never let a possibly-wrong number read
-     * as a measurement.
-     */
-    readonly experimental?: string;
-}
 /**
  * The default (Claude Code) eval driver: real `claude` + stream-json parsing.
  *
@@ -909,6 +805,18 @@ export interface EvalDriver {
  * The asymmetry reflects default-vs-injected, not a hexagonal violation.
  */
 export declare const claudeEvalDriver: EvalDriver;
+/**
+ * The Claude Code {@link HarnessLiveDriver} — the EXECUTING tiers' side of the
+ * adapter, reached through `claudeCodeAdapter.liveDriver()`.
+ *
+ * It lives HERE, at the composition root, for exactly the reason
+ * `claudeEvalDriver` above does: it is assembled from the wired default runner
+ * and `whichSkillsFired`, and moving it into `src/adapters/claude-code/` would
+ * make `eval.ts → adapters/claude-code → eval.ts` a cycle. The adapter reaches
+ * it through a dynamic `import()`, so nothing pays for this graph until an
+ * executing tier actually runs.
+ */
+export declare const claudeCodeLiveDriver: HarnessLiveDriver;
 /**
  * Package loose `<skillsDir>/<name>/SKILL.md` skills into a throwaway plugin dir
  * that `claude --plugin-dir` accepts — so repo-local skills (e.g. `.claude/skills`)

package/dist/eval.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.claudeEvalDriver = exports.EPHEMERAL_HOME_KEEP = exports.spawnAgent = exports.EFFORT_ENV_VAR = void 0;
+exports.claudeCodeLiveDriver = exports.claudeEvalDriver = exports.EPHEMERAL_HOME_KEEP = exports.spawnAgent = exports.EFFORT_ENV_VAR = void 0;
 exports.resolveSpawnEnv = resolveSpawnEnv;
 exports.pinEffortEnv = pinEffortEnv;
 exports.effortRejection = effortRejection;
@@ -76,8 +76,10 @@ const plugin_loader_js_1 = require("./adapters/claude-code/plugin-loader.js");
 const runtime_js_1 = require("./adapters/claude-code/runtime.js");
 const eval_cost_js_1 = require("./eval-cost.js");
 const proofs_js_1 = require("./core/proofs.js");
+const model_access_js_1 = require("./adapters/claude-code/model-access.js");
 const harness_test_js_1 = require("./harness-test.js");
 const eval_cache_js_1 = require("./eval-cache.js");
+const local_files_js_1 = require("./local-files.js");
 const eval_lock_js_1 = require("./eval-lock.js");
 const stats_js_1 = require("./stats.js");
 const check_count_js_1 = require("./check-count.js");
@@ -1330,7 +1332,7 @@ async function runEvalWith(spec, runner) {
         tools: spec.allowedTools ?? ["Read", "Edit", "Write", "Bash"],
         timeoutMs: spec.timeoutMs ?? 240000,
         cache: spec.cache ?? "off",
-        cacheDir: spec.cacheDir ?? (0, node_path_1.resolve)(process.cwd(), ".vigiles", "eval-cache"),
+        cacheDir: spec.cacheDir ?? (0, node_path_1.resolve)(process.cwd(), local_files_js_1.VIGILES_DIR, local_files_js_1.EVAL_CACHE_DIR),
     };
     if (cfg.cache !== "off" && !isDatedModel(cfg.model)) {
         warnFloatingModel(cfg.model);
@@ -1413,6 +1415,38 @@ exports.claudeEvalDriver = {
     parse: parseClaudeRun,
     harness: "claude-code",
 };
+/**
+ * The Claude Code {@link HarnessLiveDriver} — the EXECUTING tiers' side of the
+ * adapter, reached through `claudeCodeAdapter.liveDriver()`.
+ *
+ * It lives HERE, at the composition root, for exactly the reason
+ * `claudeEvalDriver` above does: it is assembled from the wired default runner
+ * and `whichSkillsFired`, and moving it into `src/adapters/claude-code/` would
+ * make `eval.ts → adapters/claude-code → eval.ts` a cycle. The adapter reaches
+ * it through a dynamic `import()`, so nothing pays for this graph until an
+ * executing tier actually runs.
+ */
+exports.claudeCodeLiveDriver = {
+    evalDriver: exports.claudeEvalDriver,
+    // Env-only, and never a spent token: deciding whether to OFFER a measurement
+    // must not cost one. The three arms are what the consent prompt words
+    // differently — a key bills per token, a session is $0 metered, and neither
+    // present means the tier is skipped with `fix` printed.
+    access: (env) => (0, model_access_js_1.isMeteredAccess)(env)
+        ? { kind: "metered" }
+        : (0, model_access_js_1.hasModelAccess)(env)
+            ? { kind: "subscription" }
+            : { kind: "none", fix: model_access_js_1.CLAUDE_CODE_ACCESS_FIX },
+    // A discrete `Skill` tool_use in the trace says WHICH skill was selected, so
+    // the selection-collision matrix and the adversarial gate can run here.
+    firing: { kind: "event" },
+    // Claude Code namespaces a plugin's skill as `<plugin>:<skill>`; the manifest
+    // name is handed in by the domain, which read it off the layout.
+    firedFor: (skill, plugin) => (t) => whichSkillsFired(t).includes(plugin.name ? `${plugin.name}:${skill}` : skill),
+    // The probe may rebuild the plugin to skills-only stubs: this is the harness
+    // whose plugin shape vigiles packages, so a stubbed rebuild is validated.
+    installsStubs: true,
+};
 /**
  * Is this directory entry a skill DIRECTORY — following a symlink to one?
  *

package/dist/harness-test.d.ts

@@ -1,5 +1,7 @@
 import type { HarnessAdapter } from "./core/adapter.js";
-import type { HarnessTestDriver, ToolCall, HookFire, ParsedRun, ModelTurn, ModelRequest } from "./core/harness-driver.js";
+import type { HarnessTestDriver, ToolCall, HookFire, ParsedRun, ModelTurn } from "./core/harness-driver.js";
+import type { Trace, SubagentTrace } from "./core/eval-driver.js";
+export type { Trace, SubagentTrace } from "./core/eval-driver.js";
 import { type SandboxMode } from "./sandbox.js";
 export { scriptModel } from "./mock-model.js";
 export type { ModelTurn, ModelRequest, ToolCall, HookFire, HarnessTestDriver, } from "./core/harness-driver.js";
@@ -56,68 +58,6 @@ export interface HarnessTestSpec {
      */
     readonly sandbox?: SandboxMode;
 }
-/**
- * The observable record of ONE run — the unified shape produced by BOTH testing
- * tiers: `runHarnessTest`'s result and `runEval`'s `measure` ctx (`eval.ts`)
- * both satisfy it. That's what lets the bare predicates in `harness-assert.ts`
- * (`usedTool` / `skillResolved` / `toolCount` / `toolUsedWith` / `hookFired` /
- * `outputContains`) run over either, with the testing helpers asserting and eval
- * measuring over the same vocabulary.
- */
-export interface Trace {
-    /**
-     * The tools the agent invoked, each paired with its result — parsed from the
-     * transcript. Empty unless the run captured the stream (`transcript: true` on
-     * the harness tier; always on the eval tier). Lets a test assert on the
-     * agent's *actions* (skills, MCP tools, subagents) instead of grepping stdout.
-     */
-    readonly toolCalls: readonly ToolCall[];
-    /**
-     * The hooks that fired during the run, each with its decision — parsed from
-     * the CLI's `hook_response` stream events. Same capture requirement as
-     * `toolCalls` (empty without the stream). Lets a test assert hook firing
-     * honestly instead of via a marker file.
-     */
-    readonly hooks: readonly HookFire[];
-    /** The agent's final answer text (the terminal `result` event), or "". */
-    readonly output: string;
-    /**
-     * The requests the model received, captured by the scripted mock — each with
-     * its `system` prompt and `messages`, flattened to text. Lets a test assert
-     * what actually reached the model (a SessionStart hook's injected context, a
-     * slash command's expansion), not just that a hook fired. **Harness tier
-     * only**: the mock sees the requests, so this is populated by `runHarnessTest`
-     * (with or without `transcript`); the eval tier drives the real API, so its
-     * `modelRequests` is always empty.
-     */
-    readonly modelRequests: readonly ModelRequest[];
-    /** Number of model turns. */
-    readonly turns: number;
-    /**
-     * Sub-agent (`Task`) runs as nested traces, keyed by `subagent_type`. A
-     * subagent runs its own session; CC tags its events with `parent_tool_use_id`
-     * (= the `Task` tool call) so its tool calls are recovered into a sub-trace
-     * here, lettng a test assert what the subagent DID (not just that `Task` fired).
-     * Empty unless the stream was captured / the harness emits subagent events.
-     */
-    readonly subagents?: readonly SubagentTrace[];
-    /** Final contents of a file under the working dir, or null if absent. */
-    file(path: string): string | null;
-}
-/** A sub-agent (`Task`) run as a nested trace: its name + the tools it used. */
-export interface SubagentTrace {
-    /** The `subagent_type` from the `Task` tool input. */
-    readonly name: string;
-    /** The tools the subagent invoked (events tagged with the Task's id). */
-    readonly toolCalls: readonly ToolCall[];
-    /**
-     * The subagent's RETURNED text — the dispatch tool_result the orchestrator
-     * receives back. This is where a `result()` contract's `vigiles:ok`/`vigiles:err`
-     * block lands, so `subagent(name, [output(/vigiles:ok/)])` can assert the typed
-     * outcome. "" if not captured.
-     */
-    readonly output: string;
-}
 export interface HarnessTestResult extends Trace {
     readonly exitCode: number;
     readonly stdout: string;

package/dist/hook-install.d.ts

@@ -128,7 +128,18 @@ interface ConfigToml {
 }
 /** The TOML sibling of {@link mergeHooksJson} (Codex `[[hooks.<event>]]`). */
 export declare function mergeHooksToml(existing: ConfigToml, compiled: CompiledHooks, hookPath: string): ConfigToml;
-/** Serialize a merged config back to its on-disk text (with trailing newline). */
+/**
+ * Serialize a merged config back to its on-disk text.
+ *
+ * ⚠️ DEPRECATED IN PLACE, not deleted, and the distinction matters: the
+ * harness-driven path (`installHookFile` in `cli-main.ts`) goes through
+ * `PluginLayout.settings.render` now, so no adapter's encoding is decided here
+ * any more. The one remaining caller is `cli-main.ts`'s Codex-plugin wiring,
+ * which writes `.codex/config.toml` for a harness it names ITSELF, at the
+ * composition root — a caller that already knows the encoding, rather than one
+ * branching on a layout field. Its `format` argument is therefore a literal at
+ * the call site, not a value read off a port.
+ */
 export declare function serializeConfig(merged: Record<string, unknown>, format: "json" | "toml"): string;
 export {};
 //# sourceMappingURL=hook-install.d.ts.map

package/dist/hook-install.js

@@ -298,7 +298,18 @@ function mergeHooksToml(existing, compiled, hookPath) {
     ]));
     return { ...existing, hooks: { ...before, ...rewritten } };
 }
-/** Serialize a merged config back to its on-disk text (with trailing newline). */
+/**
+ * Serialize a merged config back to its on-disk text.
+ *
+ * ⚠️ DEPRECATED IN PLACE, not deleted, and the distinction matters: the
+ * harness-driven path (`installHookFile` in `cli-main.ts`) goes through
+ * `PluginLayout.settings.render` now, so no adapter's encoding is decided here
+ * any more. The one remaining caller is `cli-main.ts`'s Codex-plugin wiring,
+ * which writes `.codex/config.toml` for a harness it names ITSELF, at the
+ * composition root — a caller that already knows the encoding, rather than one
+ * branching on a layout field. Its `format` argument is therefore a literal at
+ * the call site, not a value read off a port.
+ */
 function serializeConfig(merged, format) {
     return format === "toml"
         ? stringifyToml(merged).trimEnd() + "\n"

package/dist/hook-runtime.js

@@ -50,6 +50,7 @@ const hook_install_js_1 = require("./hook-install.js");
 const hook_providers_js_1 = require("./core/hook-providers.js");
 const hook_state_store_js_1 = require("./hook-state-store.js");
 const observe_js_1 = require("./observe.js");
+const local_files_js_1 = require("./local-files.js");
 const load_hook_js_1 = require("./load-hook.js");
 const event_capability_js_1 = require("./core/event-capability.js");
 /**
@@ -168,8 +169,9 @@ async function loadProviderRegistry(root) {
 /** Append an observe-mode record to `.vigiles/hook-observations.jsonl` (best-effort). */
 function recordObservation(file, on, would, reason, root) {
     try {
-        const dir = (0, node_path_1.resolve)(root, ".vigiles");
+        const dir = (0, node_path_1.resolve)(root, local_files_js_1.VIGILES_DIR);
         (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+        (0, local_files_js_1.ensureLocalFilesIgnored)(dir);
         const line = JSON.stringify({
             ts: new Date().toISOString(),
             hook: file,
@@ -177,7 +179,7 @@ function recordObservation(file, on, would, reason, root) {
             would,
             reason,
         }) + "\n";
-        (0, node_fs_1.appendFileSync)((0, node_path_1.resolve)(dir, "hook-observations.jsonl"), line);
+        (0, node_fs_1.appendFileSync)((0, node_path_1.resolve)(dir, local_files_js_1.HOOK_OBSERVATIONS_FILE), line);
     }
     catch {
         /* recording is best-effort — never let it break a live session */

package/dist/hook-state-store.js

@@ -57,6 +57,7 @@ const node_path_1 = require("node:path");
 const hash_js_1 = require("./core/hash.js");
 const hook_state_js_1 = require("./core/hook-state.js");
 const hook_install_js_1 = require("./hook-install.js");
+const local_files_js_1 = require("./local-files.js");
 /**
  * The directory a hook's recorded facts live in — the SCOPE of `state()`/`record()`.
  *
@@ -78,7 +79,7 @@ function hookStateDir(file, cwd = process.cwd()) {
     const dir = (0, node_path_1.dirname)((0, node_path_1.resolve)(cwd, file));
     const rel = (0, node_path_1.relative)(cwd, dir);
     const inside = rel !== "" && !rel.startsWith("..") && !(0, node_path_1.isAbsolute)(rel);
-    return (0, node_path_1.resolve)(cwd, ".vigiles/state", inside ? rel : `external-${(0, hash_js_1.sha256short)(dir)}`);
+    return (0, node_path_1.resolve)(cwd, local_files_js_1.VIGILES_DIR, local_files_js_1.HOOK_STATE_DIR, inside ? rel : `external-${(0, hash_js_1.sha256short)(dir)}`);
 }
 /** Read one recorded fact for a hook, or `null` if it was never recorded. */
 function readHookState(file, key, cwd = process.cwd()) {
@@ -112,6 +113,7 @@ function writeHookState(file, w, opts = {}) {
         by: (0, hook_install_js_1.normalizeHookRef)(file, cwd),
     };
     (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    (0, local_files_js_1.ensureLocalFilesIgnored)((0, node_path_1.resolve)(cwd, local_files_js_1.VIGILES_DIR));
     const tmp = `${target}.${String(process.pid)}.tmp`;
     (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(entry, null, 2) + "\n");
     (0, node_fs_1.renameSync)(tmp, target);

package/dist/local-files-tracked.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The per-checkout files under `<root>/.vigiles/` that git tracks, as
+ * repo-relative paths from `root`. Empty when nothing is tracked, when `root` is
+ * not in a git work tree, or when `git` is missing — silence is the answer to
+ * every "cannot tell".
+ */
+export declare function trackedLocalFiles(root: string): string[];
+/**
+ * The one-line warning for {@link trackedLocalFiles}, or `null` when there is
+ * nothing to say. Files inside a tracked local DIRECTORY (`state/`,
+ * `eval-cache/`) are named by that directory, so one line stays one line and the
+ * command it prints untracks all of them.
+ */
+export declare function formatTrackedLocalFiles(tracked: readonly string[]): string | null;
+/** Print the warning for `root` to stderr when there is one. CLI-only. */
+export declare function warnTrackedLocalFiles(root: string): void;
+//# sourceMappingURL=local-files-tracked.d.ts.map

package/dist/local-files-tracked.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackedLocalFiles = trackedLocalFiles;
+exports.formatTrackedLocalFiles = formatTrackedLocalFiles;
+exports.warnTrackedLocalFiles = warnTrackedLocalFiles;
+/**
+ * The half `.gitignore` cannot do: tell the owner when a per-checkout file under
+ * `.vigiles/` is ALREADY tracked.
+ *
+ * `ensureLocalFilesIgnored` (`local-files.ts`) keeps new copies out of git, but
+ * an ignore rule does not untrack a file git already follows — a repo that
+ * committed `.vigiles/coverage.json` before this existed keeps committing every
+ * rewrite of it. Only the owner can fix that (`git rm --cached`), and changing
+ * the index is theirs to decide, so this reports and never acts.
+ *
+ * CLI-only, by construction: it spawns `git`, and a hook decision must never pay
+ * for a child process. That is why it is a separate module from the ignore half,
+ * which hook runtimes import.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+const local_files_js_1 = require("./local-files.js");
+/**
+ * The per-checkout files under `<root>/.vigiles/` that git tracks, as
+ * repo-relative paths from `root`. Empty when nothing is tracked, when `root` is
+ * not in a git work tree, or when `git` is missing — silence is the answer to
+ * every "cannot tell".
+ */
+function trackedLocalFiles(root) {
+    const specs = local_files_js_1.LOCAL_FILES.map((f) => node_path_1.posix.join(local_files_js_1.VIGILES_DIR, f.name));
+    try {
+        const r = (0, node_child_process_1.spawnSync)("git", ["ls-files", "-z", "--", ...specs], {
+            cwd: root,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (r.status !== 0 || typeof r.stdout !== "string")
+            return [];
+        return r.stdout.split("\0").filter((p) => p !== "");
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The one-line warning for {@link trackedLocalFiles}, or `null` when there is
+ * nothing to say. Files inside a tracked local DIRECTORY (`state/`,
+ * `eval-cache/`) are named by that directory, so one line stays one line and the
+ * command it prints untracks all of them.
+ */
+function formatTrackedLocalFiles(tracked) {
+    if (tracked.length === 0)
+        return null;
+    // `.vigiles/state/.claude/hooks/x.json` → `.vigiles/state`: the list entry.
+    const entries = [
+        ...new Set(tracked.map((p) => p.split("/").slice(0, 2).join("/"))),
+    ];
+    const one = entries.length === 1;
+    return (`⚠ ${entries.join(", ")} ${one ? "is" : "are"} tracked by git, but ` +
+        `${local_files_js_1.VIGILES_DIR}/ local files describe one checkout and would credit a ` +
+        `machine where nothing ran. .gitignore does not untrack a tracked file; ` +
+        `untrack ${one ? "it" : "them"} once: git rm -r --cached ${entries.join(" ")}`);
+}
+/** Print the warning for `root` to stderr when there is one. CLI-only. */
+function warnTrackedLocalFiles(root) {
+    const line = formatTrackedLocalFiles(trackedLocalFiles(root));
+    if (line)
+        process.stderr.write(line + "\n");
+}
+//# sourceMappingURL=local-files-tracked.js.map

package/dist/local-files.d.ts

@@ -0,0 +1,62 @@
+/** vigiles's own directory in a project. */
+export declare const VIGILES_DIR = ".vigiles";
+/** The execution tier of coverage (`coverage-artifact.ts`). */
+export declare const COVERAGE_ARTIFACT_FILE = "coverage.json";
+/** The flight-recorder ledger (`observe.ts`). */
+export declare const LEDGER_FILE = "runs.jsonl";
+/** Compiled hooks' named state, `record()`/`state()` (`hook-state-store.ts`). */
+export declare const HOOK_STATE_DIR = "state";
+/** The skill in progress (`adapters/claude-code/skill-runtime.ts`). */
+export declare const ACTIVE_SKILL_FILE = "active-skill.json";
+/** The subagent stack in progress (`adapters/claude-code/agent-runtime.ts`). */
+export declare const ACTIVE_AGENT_FILE = "active-agent.json";
+/** Inside-an-effect-boundary marker (`adapters/claude-code/effect-region.ts`). */
+export declare const EFFECT_ACTIVE_FILE = "effect-active.json";
+/** The calls a guard allowed this session (`core/guards.ts`). */
+export declare const GUARD_LEDGER_FILE = "guard-ledger.json";
+/** What an `observe`-mode hook would have blocked (`hook-runtime.ts`). */
+export declare const HOOK_OBSERVATIONS_FILE = "hook-observations.jsonl";
+/** Recorded model runs for eval replay, the default `cacheDir` (`eval.ts`). */
+export declare const EVAL_CACHE_DIR = "eval-cache";
+/** One per-checkout path under `.vigiles/`. */
+export interface LocalFile {
+    /** The name directly under `.vigiles/`. */
+    readonly name: string;
+    /** A directory (its whole subtree is local) rather than a single file. */
+    readonly dir: boolean;
+}
+/** Every per-checkout path vigiles writes under `.vigiles/`. The one list. */
+export declare const LOCAL_FILES: readonly LocalFile[];
+/**
+ * The names under `.vigiles/` that ARE the project's and must stay committable.
+ * Not used at runtime — it is the other half of the classification the guard in
+ * `local-files.test.ts` holds the source to, and the list that test checks is
+ * NOT ignored.
+ */
+export declare const COMMITTED_PATHS: readonly string[];
+/** The header comment on a `.vigiles/.gitignore` vigiles creates. */
+export declare const LOCAL_GITIGNORE_HEADER: readonly string[];
+/** The ignore lines, in order: every local path, then the file itself. */
+export declare function localIgnoreEntries(): string[];
+/**
+ * Keep `<vigilesDir>/.gitignore` listing every local path. Call it where a
+ * local file is written — not from `vigiles init`, which a project may never
+ * run, while the write always happens.
+ *
+ * - Absent → created with {@link LOCAL_GITIGNORE_HEADER} and every entry.
+ * - Every entry IN EFFECT → not touched (no rewrite, no mtime change).
+ * - Otherwise the entries not in effect are appended and nothing is removed
+ *   or reordered. Appending is enough because git's last matching rule wins.
+ *
+ * "In effect" is judged the way git reads the file, not by text membership:
+ * lines in order, a later `!/entry` cancels an earlier `/entry`, and leading
+ * whitespace is part of the pattern (only trailing whitespace is dropped).
+ * Both cases were measured with `git check-ignore`: `/coverage.json` followed
+ * by `!/coverage.json`, and ` /coverage.json`, each leave the file NOT
+ * ignored while a trimmed set would call the entry present.
+ *
+ * Costs one read on the hot path. Best-effort: any fs error is swallowed —
+ * keeping git tidy must never break a hook, a test run or an audit.
+ */
+export declare function ensureLocalFilesIgnored(vigilesDir: string): void;
+//# sourceMappingURL=local-files.d.ts.map