vigiles 33.2.0 → 33.3.0

package/dist/eval.d.ts

@@ -168,8 +168,9 @@ export interface EvalSpec<M extends Metrics> {
      * **Ships default-OFF** because a too-narrow auth allowlist would silently break
      * the real `claude` CLI's authentication; leaving it off keeps every existing
      * eval (including one running right now) authenticating exactly as before. When
-     * absent / `false`, the per-trial env is byte-identical to today
-     * (`{ ...process.env, ...arm.env }`). See `docs/safety.md` (ephemerality) and
+     * absent / `false`, the per-trial env is the caller's (`{ ...process.env,
+     * ...arm.env }`) minus the harness's declared session identity, which no child
+     * run inherits in either mode. See `docs/safety.md` (ephemerality) and
      * `research/cross-platform-sandboxing.md`.
      */
     readonly ephemeralEnv?: boolean;
@@ -249,11 +250,13 @@ export interface EvalReport {
  * Resolve the environment a trial's subprocess actually runs with — the
  * SECURITY-CRITICAL decision behind `ephemeralEnv`. When `replaceEnv` is set, the
  * scrubbed `env` is the COMPLETE environment, so the real `$HOME` and inherited
- * secrets are DROPPED; otherwise `env` is an overlay on `base` (byte-identical to
- * the pre-ephemeral behaviour). Extracted from the `v8 ignore`d `spawnAgent` so
- * the one line that enforces the scrub is both unit- and behaviourally-tested — a
- * regression to an always-merge would otherwise silently defeat ephemerality and
- * leak the host environment into an untrusted, model-driven run.
+ * secrets are DROPPED; otherwise `env` is an overlay on `base`. In BOTH, the
+ * harness's declared session identity (`runEnv.sessionIdentity`) is removed: a
+ * run started from inside a live session must not run as that session, scrubbed
+ * or not. Extracted from the `v8 ignore`d `spawnAgent` so the one line that
+ * enforces the scrub is both unit- and behaviourally-tested — a regression to an
+ * always-merge would otherwise silently defeat ephemerality and leak the host
+ * environment into an untrusted, model-driven run.
  */
 export declare function resolveSpawnEnv(a: Pick<AgentRunArgs, "env" | "replaceEnv" | "effort">, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /**
@@ -268,10 +271,10 @@ export declare const EFFORT_ENV_VAR = "CLAUDE_CODE_EFFORT_LEVEL";
  *
  * WHY THIS EXISTS AND WHY IT IS NOT OPTIONAL. Effort has THREE inputs — the
  * `--effort` flag, the `effortLevel` settings key, and `CLAUDE_CODE_EFFORT_LEVEL`
- * — and the env var wins over the flag. `EPHEMERAL_ALLOW_PREFIXES` passes
- * `CLAUDE_*` through by design (the CLI reads several such knobs and dropping one
- * is the failure mode), so an ambient `CLAUDE_CODE_EFFORT_LEVEL=max` in the
- * author's shell survives even the SCRUBBED ephemeral env. Without this pin,
+ * — and the env var wins over the flag. The default (inherited) spawn env
+ * carries the caller's whole environment, so an ambient
+ * `CLAUDE_CODE_EFFORT_LEVEL=max` in the author's shell reaches the run unless
+ * something removes it. Without this pin,
  * hashing effort into the lock would make the lock CONFIDENTLY WRONG: it would
  * record `low` over a run that executed at `max` — the exact defect the feature
  * exists to prevent, reintroduced by the fix for it.
@@ -601,51 +604,48 @@ export declare function modelTier(id: string): number | null;
 export declare function belowModelFloor(model: string, floor: string): boolean;
 /**
  * Build an **ephemeral run environment** for a model-driven run: a NEW env object
- * with a *fresh* `HOME` (and `TMPDIR`) pointed at the throwaway `opts.home`, only
- * an allowlist of auth + runtime vars passed through from `base`, and everything
- * else DROPPED. Pure — no fs, no spawn.
+ * with a *fresh* `HOME` (and `TMPDIR`) pointed at the throwaway `opts.home`, the
+ * OS essentials (`PATH`, `LANG`, `LC_*`, `TERM`), the harness's OWN auth, and
+ * nothing else. Pure — no fs, no spawn.
  *
  * The rationale is "fresh HOME + only the harness credential injected, **not** a
  * blanket wipe": running a model-driven skill/agent is itself a side effect (the
  * *model*, not the author, chose the actions), so it should not be able to read
  * the real `~/.gitconfig` / `~/.ssh` / `~/.aws` or write to the real `~`. But the
- * real `claude` CLI must still AUTHENTICATE, so the harness's own credentials
- * ({@link EPHEMERAL_ALLOW} — `ANTHROPIC_*`, `CLAUDE_*`, locale/PATH) are
- * re-injected; a blanket `--clearenv`-style wipe would break every eval. Because
- * this needs no kernel features, it is the cross-platform STATE-protection floor
- * (lands on macOS immediately), orthogonal to the Linux bubblewrap HOST
- * confinement in `src/sandbox.ts`.
+ * real CLI must still AUTHENTICATE, so the auth names the harness declares
+ * (`runtime.runEnv.keep`) are re-injected, and the parent session's identity
+ * (`runtime.runEnv.sessionIdentity`) never is. Which names those are is the
+ * adapter's fact, not this file's: see `RunEnvPolicy` in `core/runtime.ts`.
+ * Because this needs no kernel features, it is the cross-platform
+ * STATE-protection floor (lands on macOS immediately), orthogonal to the Linux
+ * bubblewrap HOST confinement in `src/sandbox.ts`.
+ *
+ * Notably it does NOT pass through `GIT_*`, `GH_TOKEN`, `SSH_*`, `AWS_*` access
+ * keys, a config-dir override, or any other undeclared variable — those are
+ * exactly what an ephemeral run must not see. A too-narrow `keep` breaks auth
+ * loudly (the run fails to start); a too-broad one leaks silently, which is why
+ * it is an allowlist and not a prefix.
  *
  * @param base  the source environment to filter (usually `process.env`).
  * @param opts.home  the throwaway dir to set as `HOME`/`TMPDIR`.
  * @param opts.allow  extra var NAMES to pass through (e.g. the `VIGILES_*` keys
- *   the eval already injects). Layered ON TOP of the default allowlist.
+ *   the eval already injects). Layered ON TOP of the harness's `keep`; a
+ *   session-identity name is dropped even when listed here.
  */
 export declare function ephemeralRunEnv(base: NodeJS.ProcessEnv | Record<string, string | undefined>, opts: {
     home: string;
     allow?: readonly string[];
 }): Record<string, string>;
-/**
- * Home-relative AUTH files to carry from the real HOME into the throwaway one.
- *
- * A local subscription credential (OAuth token) often lives in a FILE under HOME,
- * not an env var — so scrubbing HOME would lose it and break a local-authed run.
- * This is the file half of the auth allowlist; {@link EPHEMERAL_ALLOW} covers the
- * env-var / host-brokered half. Kept a named constant so it's easy to extend, and
- * deliberately NARROW — only the explicit auth files, never `.gitconfig` / `.ssh`
- * / `.aws`, which are exactly what an ephemeral run must not see.
- */
-export declare const EPHEMERAL_HOME_KEEP: readonly string[];
 /**
  * Seed the throwaway HOME with the harness's own auth FILE(s) — best-effort;
- * covers local file-based OAuth; the env-var/host-brokered path is covered by the
- * allowlist in `ephemeralRunEnv`.
+ * covers local file-based OAuth; the env-var/host-brokered path is covered by
+ * `ephemeralRunEnv`. The files are the runtime's declared `keepHomeFiles`.
  *
- * COPIES (never symlinks) each {@link EPHEMERAL_HOME_KEEP} path from `realHome`
- * into `throwawayHome`, creating parent dirs as needed; a symlink would let the
- * model-driven run write back to the real credential file, defeating ephemerality.
- * A path that doesn't exist in the real HOME is skipped silently (that user auths
- * via env-var / host broker instead). Pure fs — no env, no spawn.
+ * COPIES (never symlinks) each path from `realHome` into `throwawayHome`,
+ * creating parent dirs as needed; a symlink would let the model-driven run write
+ * back to the real credential file, defeating ephemerality. A path that doesn't
+ * exist in the real HOME is skipped silently (that user auths via env-var / host
+ * broker instead). Pure fs — no env, no spawn.
  */
 export declare function seedEphemeralHome(throwawayHome: string, realHome: string, keep?: readonly string[]): void;
 /** Whether a run's captured output looks like a rate-limit / overload. Pure. */

package/dist/eval.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.claudeCodeLiveDriver = exports.claudeEvalDriver = exports.EPHEMERAL_HOME_KEEP = exports.spawnAgent = exports.EFFORT_ENV_VAR = void 0;
+exports.claudeCodeLiveDriver = exports.claudeEvalDriver = exports.spawnAgent = exports.EFFORT_ENV_VAR = void 0;
 exports.resolveSpawnEnv = resolveSpawnEnv;
 exports.pinEffortEnv = pinEffortEnv;
 exports.effortRejection = effortRejection;
@@ -76,6 +76,7 @@ const node_path_1 = require("node:path");
 const observe_js_1 = require("./observe.js");
 const plugin_loader_js_1 = require("./adapters/claude-code/plugin-loader.js");
 const runtime_js_1 = require("./adapters/claude-code/runtime.js");
+const run_env_js_1 = require("./core/run-env.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");
@@ -90,6 +91,14 @@ const tool_intercept_js_1 = require("./tool-intercept.js");
 const tool_stub_js_1 = require("./tool-stub.js");
 const tmp_root_js_1 = require("./core/tmp-root.js");
 const edit_distance_js_1 = require("./core/edit-distance.js");
+/**
+ * The harness the eval tier spawns. ONE binding on purpose: the paid tier is
+ * still wired to the Claude Code runner rather than chosen through the adapter's
+ * eval driver (#325), and every fact this file needs about that harness — its
+ * binary, its version key, which env a child may inherit — is read off this
+ * runtime's port fields, never spelled here.
+ */
+const EVAL_RUNTIME = runtime_js_1.claudeCodeRuntime;
 function writeFiles(cwd, files) {
     for (const [p, content] of Object.entries(files)) {
         const full = (0, node_path_1.resolve)(cwd, p);
@@ -101,15 +110,17 @@ function writeFiles(cwd, files) {
  * Resolve the environment a trial's subprocess actually runs with — the
  * SECURITY-CRITICAL decision behind `ephemeralEnv`. When `replaceEnv` is set, the
  * scrubbed `env` is the COMPLETE environment, so the real `$HOME` and inherited
- * secrets are DROPPED; otherwise `env` is an overlay on `base` (byte-identical to
- * the pre-ephemeral behaviour). Extracted from the `v8 ignore`d `spawnAgent` so
- * the one line that enforces the scrub is both unit- and behaviourally-tested — a
- * regression to an always-merge would otherwise silently defeat ephemerality and
- * leak the host environment into an untrusted, model-driven run.
+ * secrets are DROPPED; otherwise `env` is an overlay on `base`. In BOTH, the
+ * harness's declared session identity (`runEnv.sessionIdentity`) is removed: a
+ * run started from inside a live session must not run as that session, scrubbed
+ * or not. Extracted from the `v8 ignore`d `spawnAgent` so the one line that
+ * enforces the scrub is both unit- and behaviourally-tested — a regression to an
+ * always-merge would otherwise silently defeat ephemerality and leak the host
+ * environment into an untrusted, model-driven run.
  */
 function resolveSpawnEnv(a, base = process.env) {
     const resolved = a.replaceEnv ? (a.env ?? {}) : { ...base, ...a.env };
-    return pinEffortEnv(resolved, a.effort);
+    return pinEffortEnv((0, run_env_js_1.withoutSessionIdentity)(resolved, EVAL_RUNTIME.runEnv), a.effort);
 }
 /**
  * The env var name the harness reads for the reasoning budget. It sits ABOVE the
@@ -123,10 +134,10 @@ exports.EFFORT_ENV_VAR = "CLAUDE_CODE_EFFORT_LEVEL";
  *
  * WHY THIS EXISTS AND WHY IT IS NOT OPTIONAL. Effort has THREE inputs — the
  * `--effort` flag, the `effortLevel` settings key, and `CLAUDE_CODE_EFFORT_LEVEL`
- * — and the env var wins over the flag. `EPHEMERAL_ALLOW_PREFIXES` passes
- * `CLAUDE_*` through by design (the CLI reads several such knobs and dropping one
- * is the failure mode), so an ambient `CLAUDE_CODE_EFFORT_LEVEL=max` in the
- * author's shell survives even the SCRUBBED ephemeral env. Without this pin,
+ * — and the env var wins over the flag. The default (inherited) spawn env
+ * carries the caller's whole environment, so an ambient
+ * `CLAUDE_CODE_EFFORT_LEVEL=max` in the author's shell reaches the run unless
+ * something removes it. Without this pin,
  * hashing effort into the lock would make the lock CONFIDENTLY WRONG: it would
  * record `low` over a run that executed at `max` — the exact defect the feature
  * exists to prevent, reintroduced by the fix for it.
@@ -269,7 +280,7 @@ function spawnAgentRaw(a) {
     (0, foreign_runner_js_1.refuseUnderForeignRunner)("spawning `claude`");
     return new Promise((resolvePromise) => {
         const args = buildAgentArgs(a);
-        const child = (0, node_child_process_1.spawn)(runtime_js_1.claudeCodeRuntime.agentBinary, args, {
+        const child = (0, node_child_process_1.spawn)(EVAL_RUNTIME.agentBinary, args, {
             cwd: a.cwd,
             // The security-critical env resolution (overlay vs. scrubbed replacement)
             // lives in the tested `resolveSpawnEnv` seam above, not inline here.
@@ -866,7 +877,7 @@ let cachedHarnessVersion;
 function harnessVersion() {
     if (cachedHarnessVersion === undefined) {
         try {
-            cachedHarnessVersion = runtime_js_1.claudeCodeRuntime.versionKey((0, node_child_process_1.execSync)(`${runtime_js_1.claudeCodeRuntime.agentBinary} --version`, {
+            cachedHarnessVersion = EVAL_RUNTIME.versionKey((0, node_child_process_1.execSync)(`${EVAL_RUNTIME.agentBinary} --version`, {
                 encoding: "utf-8",
                 stdio: ["ignore", "pipe", "ignore"],
             }));
@@ -913,132 +924,68 @@ function withInterceptToolHook(settings, intercepts) {
         },
     };
 }
-/**
- * The default allowlist `ephemeralRunEnv` passes through from the real
- * environment. Two groups, both load-bearing for a real-model `claude` run:
- *
- * - **Auth** — the harness's OWN credentials. The eval drives the real `claude`
- *   CLI, which authenticates via the user's subscription (`~/.claude`, reached
- *   through the fresh HOME's allowed config — see below) OR via these env vars.
- *   We mirror the auth surface the runtime port already names
- *   (`ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`, see
- *   `adapters/claude-code/runtime.ts`) plus the OAuth/token + region variants the
- *   CLI accepts, so a token-authed user is not broken by a too-narrow list.
- * - **Runtime** — what any spawned process needs to *function*: `PATH` (resolve
- *   `node` / `claude`), the locale/terminal vars (`LANG` / `LC_*` / `TERM`), and
- *   `TMPDIR` (which we override to the fresh HOME). Mirrors what `bwrapArgs` /
- *   `setenvArgs` in `src/sandbox.ts` set back after `--clearenv`.
- *
- * Notably it does NOT pass through `GIT_*`, `GH_TOKEN`, `SSH_*`, `AWS_*`, or any
- * other non-allowlisted secret-shaped var — those are exactly what an ephemeral
- * run must not see. `CLAUDE_*` is allowlisted by prefix because the CLI reads
- * several `CLAUDE_*` knobs (config dir, etc.) and omitting one is the failure
- * mode this whole guard is conservative against.
- *
- * Conservative by design: a too-broad allowlist is safe (it just leaks a benign
- * var); a too-narrow one silently breaks auth — which is why the feature ships
- * default-OFF until validated against a real run.
- */
-const EPHEMERAL_ALLOW = [
-    // Runtime essentials (mirror sandbox.ts setenv-after-clearenv).
-    "PATH",
-    "LANG",
-    "TERM",
-    // Anthropic / Claude Code auth + endpoint (mirror runtime.ts + CLI auth vars).
-    runtime_js_1.claudeCodeRuntime.modelApiKeyEnv, // ANTHROPIC_API_KEY
-    runtime_js_1.claudeCodeRuntime.modelBaseUrlEnv, // ANTHROPIC_BASE_URL
-    "ANTHROPIC_AUTH_TOKEN",
-    "ANTHROPIC_API_URL",
-    "ANTHROPIC_MODEL",
-    "ANTHROPIC_DEFAULT_HEADERS",
-    "CLAUDE_CODE_USE_BEDROCK",
-    "CLAUDE_CODE_USE_VERTEX",
-    // Cloud-provider auth the CLI uses for Bedrock/Vertex backends (region/profile
-    // only — NOT the secret-shaped AWS_* access keys, which stay dropped).
-    "AWS_REGION",
-    "AWS_DEFAULT_REGION",
-    "AWS_PROFILE",
-    "CLOUD_ML_REGION",
-    "GOOGLE_CLOUD_PROJECT",
-    "GOOGLE_APPLICATION_CREDENTIALS",
-];
-/** Prefixes passed through wholesale — the CLI reads several `CLAUDE_*` knobs and
- *  a `LC_*` locale family; allowlist by prefix so omitting one isn't the silent
- *  auth/locale break this guard exists to avoid. */
-const EPHEMERAL_ALLOW_PREFIXES = ["CLAUDE_", "LC_"];
 /**
  * Build an **ephemeral run environment** for a model-driven run: a NEW env object
- * with a *fresh* `HOME` (and `TMPDIR`) pointed at the throwaway `opts.home`, only
- * an allowlist of auth + runtime vars passed through from `base`, and everything
- * else DROPPED. Pure — no fs, no spawn.
+ * with a *fresh* `HOME` (and `TMPDIR`) pointed at the throwaway `opts.home`, the
+ * OS essentials (`PATH`, `LANG`, `LC_*`, `TERM`), the harness's OWN auth, and
+ * nothing else. Pure — no fs, no spawn.
  *
  * The rationale is "fresh HOME + only the harness credential injected, **not** a
  * blanket wipe": running a model-driven skill/agent is itself a side effect (the
  * *model*, not the author, chose the actions), so it should not be able to read
  * the real `~/.gitconfig` / `~/.ssh` / `~/.aws` or write to the real `~`. But the
- * real `claude` CLI must still AUTHENTICATE, so the harness's own credentials
- * ({@link EPHEMERAL_ALLOW} — `ANTHROPIC_*`, `CLAUDE_*`, locale/PATH) are
- * re-injected; a blanket `--clearenv`-style wipe would break every eval. Because
- * this needs no kernel features, it is the cross-platform STATE-protection floor
- * (lands on macOS immediately), orthogonal to the Linux bubblewrap HOST
- * confinement in `src/sandbox.ts`.
+ * real CLI must still AUTHENTICATE, so the auth names the harness declares
+ * (`runtime.runEnv.keep`) are re-injected, and the parent session's identity
+ * (`runtime.runEnv.sessionIdentity`) never is. Which names those are is the
+ * adapter's fact, not this file's: see `RunEnvPolicy` in `core/runtime.ts`.
+ * Because this needs no kernel features, it is the cross-platform
+ * STATE-protection floor (lands on macOS immediately), orthogonal to the Linux
+ * bubblewrap HOST confinement in `src/sandbox.ts`.
+ *
+ * Notably it does NOT pass through `GIT_*`, `GH_TOKEN`, `SSH_*`, `AWS_*` access
+ * keys, a config-dir override, or any other undeclared variable — those are
+ * exactly what an ephemeral run must not see. A too-narrow `keep` breaks auth
+ * loudly (the run fails to start); a too-broad one leaks silently, which is why
+ * it is an allowlist and not a prefix.
  *
  * @param base  the source environment to filter (usually `process.env`).
  * @param opts.home  the throwaway dir to set as `HOME`/`TMPDIR`.
  * @param opts.allow  extra var NAMES to pass through (e.g. the `VIGILES_*` keys
- *   the eval already injects). Layered ON TOP of the default allowlist.
+ *   the eval already injects). Layered ON TOP of the harness's `keep`; a
+ *   session-identity name is dropped even when listed here.
  */
 function ephemeralRunEnv(base, opts) {
-    const out = {};
-    const allowExact = new Set([
-        ...EPHEMERAL_ALLOW,
-        ...(opts.allow ?? []),
-    ]);
-    for (const [k, v] of Object.entries(base)) {
-        if (v === undefined)
-            continue;
-        const allowed = allowExact.has(k) ||
-            EPHEMERAL_ALLOW_PREFIXES.some((p) => k.startsWith(p));
-        if (allowed)
-            out[k] = v;
-    }
-    // Fresh HOME + TMPDIR last so they always win over anything passed through.
-    out.HOME = opts.home;
-    out.TMPDIR = opts.home;
-    return out;
+    // A fresh object: the trial layers its overlay and stub PATH onto it.
+    return {
+        ...(0, run_env_js_1.scrubbedRunEnv)(base, {
+            home: opts.home,
+            policy: EVAL_RUNTIME.runEnv,
+            allow: opts.allow,
+        }),
+    };
 }
-/**
- * Home-relative AUTH files to carry from the real HOME into the throwaway one.
- *
- * A local subscription credential (OAuth token) often lives in a FILE under HOME,
- * not an env var — so scrubbing HOME would lose it and break a local-authed run.
- * This is the file half of the auth allowlist; {@link EPHEMERAL_ALLOW} covers the
- * env-var / host-brokered half. Kept a named constant so it's easy to extend, and
- * deliberately NARROW — only the explicit auth files, never `.gitconfig` / `.ssh`
- * / `.aws`, which are exactly what an ephemeral run must not see.
- */
-exports.EPHEMERAL_HOME_KEEP = [
-    ".claude/.credentials.json", // the Claude Code OAuth token
-];
 /**
  * Seed the throwaway HOME with the harness's own auth FILE(s) — best-effort;
- * covers local file-based OAuth; the env-var/host-brokered path is covered by the
- * allowlist in `ephemeralRunEnv`.
+ * covers local file-based OAuth; the env-var/host-brokered path is covered by
+ * `ephemeralRunEnv`. The files are the runtime's declared `keepHomeFiles`.
  *
- * COPIES (never symlinks) each {@link EPHEMERAL_HOME_KEEP} path from `realHome`
- * into `throwawayHome`, creating parent dirs as needed; a symlink would let the
- * model-driven run write back to the real credential file, defeating ephemerality.
- * A path that doesn't exist in the real HOME is skipped silently (that user auths
- * via env-var / host broker instead). Pure fs — no env, no spawn.
+ * COPIES (never symlinks) each path from `realHome` into `throwawayHome`,
+ * creating parent dirs as needed; a symlink would let the model-driven run write
+ * back to the real credential file, defeating ephemerality. A path that doesn't
+ * exist in the real HOME is skipped silently (that user auths via env-var / host
+ * broker instead). Pure fs — no env, no spawn.
  */
-function seedEphemeralHome(throwawayHome, realHome, keep = exports.EPHEMERAL_HOME_KEEP) {
+function seedEphemeralHome(throwawayHome, realHome, keep = EVAL_RUNTIME.runEnv?.keepHomeFiles ?? []) {
     for (const rel of keep) {
         const src = (0, node_path_1.join)(realHome, rel);
         if (!(0, node_fs_1.existsSync)(src))
             continue; // env-var / host-brokered auth covers this.
         const dest = (0, node_path_1.join)(throwawayHome, rel);
         (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(dest), { recursive: true });
-        (0, node_fs_1.cpSync)(src, dest); // copy, not symlink — keep the real credential read-only.
+        // The DATA, never a link: `cpSync` recreates a symlinked credential
+        // (dotfiles, a secret manager) as a link, and the run would write through
+        // it into the real file. `copyFileSync` always copies the contents.
+        (0, node_fs_1.copyFileSync)(src, dest);
     }
 }
 /** Execute one trial in a fresh sandbox; returns its metric row + usage. */

package/dist/harness-test.d.ts

@@ -5,6 +5,7 @@ export type { Trace, SubagentTrace } from "./core/eval-driver.js";
 import { parseReplies, reachedModel } from "./adapters/claude-code/replies.js";
 /** Re-exported for the eval tier's parser, which reads the same stream. */
 export { parseReplies, reachedModel };
+import type { HarnessRuntime } from "./core/runtime.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";
@@ -126,6 +127,31 @@ export declare function parseHooks(stdout: string): HookFire[];
 export declare function buildClaudeArgs(spec: HarnessTestSpec, hasSettings: boolean): string[];
 /** Parse the `claude` stdout/stream into the unified trace fields. */
 export declare function parseClaudeRun(stdout: string): ParsedRun;
+/**
+ * Where a harness-tier run's agent gets HOME and the rest of its environment.
+ *
+ * - `inherit` — the caller's env (real HOME), minus the harness's declared
+ *   session identity. The default of `runHarnessTest`: a test that reads the
+ *   machine's config keeps doing so, but no run executes AS the caller's live
+ *   session.
+ * - `throwaway` — a fresh HOME/TMPDIR at `dir`, the OS essentials, and nothing
+ *   else from the caller: no harness auth (the scripted mock needs none, and a
+ *   config-dir variable would point the run back at the real config), no
+ *   identity, no secrets. The same scrubbed shape as the eval tier's
+ *   `ephemeralEnv` (`scrubbedRunEnv`), without the auth.
+ */
+export type HarnessRunHome = {
+    readonly home: "inherit";
+} | {
+    readonly home: "throwaway";
+    readonly dir: string;
+};
+/**
+ * The spawn env of one harness-tier run: {@link HarnessRunHome} applied to
+ * `base`, with the runtime's mock wiring on top. Pure — the testable seam of
+ * the un-coverable spawn.
+ */
+export declare function harnessSpawnEnv(runtime: HarnessRuntime, wiredEnv: Readonly<Record<string, string>>, home: HarnessRunHome, base?: NodeJS.ProcessEnv): Readonly<Record<string, string>>;
 /** Whether the agent CLI is available — harness tests need it. */
 export declare function claudeAvailable(): boolean;
 /**
@@ -157,6 +183,15 @@ export interface RunHarnessTestOptions {
  * only — requesting confinement for another harness throws.
  */
 export declare function runHarnessTest(spec: HarnessTestSpec, opts?: RunHarnessTestOptions): Promise<HarnessTestResult>;
+/**
+ * {@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
+ * a throwaway HOME is vigiles's own preflight (`output-style-arms.ts`), whose
+ * run must not depend on, or act as, the machine it happens to run on. The
+ * confined (bubblewrap) path ignores `home`: it already runs with its own HOME
+ * and a cleared env.
+ */
+export declare function runHarnessTestIn(spec: HarnessTestSpec, opts: RunHarnessTestOptions, home: HarnessRunHome["home"]): Promise<HarnessTestResult>;
 /**
  * `runHarness` — the harness-scope entry of the revamped API (Phase 2 of
  * `research/testing-api-design.md`). The harness has two execution scopes, `hook`

package/dist/harness-test.js

@@ -8,8 +8,10 @@ exports.parseOutput = parseOutput;
 exports.parseHooks = parseHooks;
 exports.buildClaudeArgs = buildClaudeArgs;
 exports.parseClaudeRun = parseClaudeRun;
+exports.harnessSpawnEnv = harnessSpawnEnv;
 exports.claudeAvailable = claudeAvailable;
 exports.runHarnessTest = runHarnessTest;
+exports.runHarnessTestIn = runHarnessTestIn;
 exports.runHarness = runHarness;
 exports.outputStyleFixture = outputStyleFixture;
 /**
@@ -55,6 +57,7 @@ Object.defineProperty(exports, "parseReplies", { enumerable: true, get: function
 Object.defineProperty(exports, "reachedModel", { enumerable: true, get: function () { return replies_js_1.reachedModel; } });
 const adapter_registry_js_1 = require("./adapter-registry.js");
 const output_style_js_1 = require("./core/output-style.js");
+const run_env_js_1 = require("./core/run-env.js");
 const sandbox_js_1 = require("./sandbox.js");
 var mock_model_js_2 = require("./mock-model.js");
 Object.defineProperty(exports, "scriptModel", { enumerable: true, get: function () { return mock_model_js_2.scriptModel; } });
@@ -314,6 +317,19 @@ function parseClaudeRun(stdout) {
         replies: (0, replies_js_1.parseReplies)(stdout),
     };
 }
+/**
+ * The spawn env of one harness-tier run: {@link HarnessRunHome} applied to
+ * `base`, with the runtime's mock wiring on top. Pure — the testable seam of
+ * the un-coverable spawn.
+ */
+function harnessSpawnEnv(runtime, wiredEnv, home, base = process.env) {
+    switch (home.home) {
+        case "inherit":
+            return { ...(0, run_env_js_1.withoutSessionIdentity)(base, runtime.runEnv), ...wiredEnv };
+        case "throwaway":
+            return { ...(0, run_env_js_1.scrubbedRunEnv)(base, { home: home.dir }), ...wiredEnv };
+    }
+}
 /* v8 ignore start -- spawns the real claude CLI + filesystem; exercised by the
    claude-backed suite, excluded from the deterministic coverage gate (the parse
    helpers above carry the testable logic). */
@@ -345,13 +361,24 @@ function writeFixture(cwd, files, settings) {
         (0, node_fs_1.writeFileSync)((0, node_path_1.join)(cwd, "settings.json"), json);
     }
 }
+/**
+ * The {@link HarnessRunHome} for a run in `cwd`. A throwaway HOME lives under
+ * the run's own temp dir, as the eval tier's does, so `cleanup()` removes it
+ * with everything else.
+ */
+function runHomeIn(cwd, home) {
+    return home === "throwaway"
+        ? { home, dir: (0, node_fs_1.mkdtempSync)((0, node_path_1.join)(cwd, "home-")) }
+        : { home };
+}
 /**
  * Spawn the agent binary against the mock. The mock-wiring *args* are already in
  * `args` (the driver placed `wireMock(url).args` at the correct argv position
- * via `ctx.mockArgs`); here we only layer `wireMock(url).env` over the caller's
- * env. Driver-agnostic at the transport seam.
+ * via `ctx.mockArgs`); here the env is {@link harnessSpawnEnv} of the caller's,
+ * with `wireMock(url).env` on top. Driver-agnostic at the transport seam.
  */
-function spawnAgent(runtime, args, cwd, baseUrl, timeoutMs) {
+function spawnAgent(runtime, args, run) {
+    const { cwd, baseUrl, timeoutMs, home } = run;
     const wired = runtime.wireMock(baseUrl);
     return new Promise((resolvePromise) => {
         // vigiles:free-tier — the deterministic harness tier. `runtime.wireMock`
@@ -361,9 +388,8 @@ function spawnAgent(runtime, args, cwd, baseUrl, timeoutMs) {
         const child = (0, node_child_process_1.spawn)(runtime.agentBinary, [...args], {
             cwd,
             // Any key works — the mock ignores auth. wireMock supplies the overlay
-            // env (base-URL var + dummy key for CC; the dummy key for Codex); layer it
-            // over the caller's env.
-            env: { ...process.env, ...wired.env },
+            // env (base-URL var + dummy key for CC; the dummy key for Codex).
+            env: harnessSpawnEnv(runtime, wired.env, home),
             stdio: ["ignore", "pipe", "pipe"],
         });
         let stdout = "";
@@ -431,6 +457,17 @@ function makeResult(cwd, out, parsed, turns, modelRequests) {
  * only — requesting confinement for another harness throws.
  */
 async function runHarnessTest(spec, opts = {}) {
+    return runHarnessTestIn(spec, opts, "inherit");
+}
+/**
+ * {@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
+ * a throwaway HOME is vigiles's own preflight (`output-style-arms.ts`), whose
+ * run must not depend on, or act as, the machine it happens to run on. The
+ * confined (bubblewrap) path ignores `home`: it already runs with its own HOME
+ * and a cleared env.
+ */
+async function runHarnessTestIn(spec, opts, home) {
     // Tell the CLI runner this script exercised the harness, so a file that runs
     // NOTHING can be told apart from one that ran and passed. See check-count.ts.
     (0, check_count_js_1.recordCheck)();
@@ -492,7 +529,12 @@ async function runHarnessTest(spec, opts = {}) {
     const mock = await driver.startMock(spec.model);
     try {
         const args = buildArgs(driver.runtime.wireMock(mock.url).args);
-        const out = await spawnAgent(driver.runtime, args, cwd, mock.url, timeoutMs);
+        const out = await spawnAgent(driver.runtime, args, {
+            cwd,
+            baseUrl: mock.url,
+            timeoutMs,
+            home: runHomeIn(cwd, home),
+        });
         // A script that was never consumed is otherwise invisible — the run just
         // looks empty. `scriptUnconsumedWarning` names the one shape that produces
         // it (every request arriving without tool declarations, so nothing looked

package/dist/output-style-arms.js

@@ -14,7 +14,8 @@ exports.outputStyleArmsWith = outputStyleArmsWith;
  * all: it drives the real API, so no request is captured. The free run here
  * uses the scripted model, where requests ARE captured, with the same fixture
  * the paid arm gets — so a style that would not load stops the eval before the
- * first billed trial.
+ * first billed trial. That free run uses a throwaway HOME and none of the
+ * caller's environment beyond the OS essentials.
  */
 const adapter_registry_js_1 = require("./adapter-registry.js");
 const harness_test_js_1 = require("./harness-test.js");
@@ -37,7 +38,11 @@ async function experimental_outputStyleArms(path) {
  * run by a harness they were not checked on.
  */
 async function outputStyleArmsWith(path, adapter) {
-    const preflight = await (0, harness_test_js_1.runHarnessTest)({ outputStyle: path, prompt: "hi", model: [{ text: "ok" }] }, { adapter });
+    // A throwaway HOME: this run happens on every import of an eval file (even
+    // `vigiles eval --check`), so it must not read the machine's user config or
+    // run as the session that imported it. What it proves — the style reaches the
+    // model — is a fact about the fixture, not about this machine.
+    const preflight = await (0, harness_test_js_1.runHarnessTestIn)({ outputStyle: path, prompt: "hi", model: [{ text: "ok" }] }, { adapter }, "throwaway");
     preflight.cleanup();
     const { files, settings } = (0, harness_test_js_1.outputStyleFixture)(path, adapter);
     const none = adapter.layout.outputStyles?.selectNone ?? {};

package/dist/plugin-declaration.d.ts

@@ -17,12 +17,12 @@
  * boundary is deliberate: plugins "can execute arbitrary code on your machine
  * with your user privileges", so a repo is not allowed to install one for you.
  *
- * The declaration buys exactly one thing, and it is worth having: a collaborator
- * who clones the repo and never runs `vigiles init` currently gets **silence** —
- * the package is in `node_modules`, its six skills are unreachable, and nothing
- * says so. With the declaration, Claude Code tells them the project wants this
- * plugin and prints the command that installs it. **Silent absence becomes a
- * prompt.** It does not become a working install.
+ * The declaration buys exactly one thing: a collaborator who clones the repo is
+ * told the project wants this plugin, with the command that installs it.
+ * **Silent absence becomes a prompt.** It does not become a working install. What
+ * the plugin adds on their machine is the HOOKS; the SKILLS do not depend on it
+ * any more — `init` links them into `.claude/skills/` (`./skill-links.ts`), and
+ * the links travel with the clone.
  *
  * Nothing is vendored: what lands in the repo is a *reference* (a marketplace
  * source plus an enabled flag). The plugin content still lives in the global

package/dist/plugin-declaration.js

@@ -18,12 +18,12 @@
  * boundary is deliberate: plugins "can execute arbitrary code on your machine
  * with your user privileges", so a repo is not allowed to install one for you.
  *
- * The declaration buys exactly one thing, and it is worth having: a collaborator
- * who clones the repo and never runs `vigiles init` currently gets **silence** —
- * the package is in `node_modules`, its six skills are unreachable, and nothing
- * says so. With the declaration, Claude Code tells them the project wants this
- * plugin and prints the command that installs it. **Silent absence becomes a
- * prompt.** It does not become a working install.
+ * The declaration buys exactly one thing: a collaborator who clones the repo is
+ * told the project wants this plugin, with the command that installs it.
+ * **Silent absence becomes a prompt.** It does not become a working install. What
+ * the plugin adds on their machine is the HOOKS; the SKILLS do not depend on it
+ * any more — `init` links them into `.claude/skills/` (`./skill-links.ts`), and
+ * the links travel with the clone.
  *
  * Nothing is vendored: what lands in the repo is a *reference* (a marketplace
  * source plus an enabled flag). The plugin content still lives in the global