vigiles 35.0.0 → 37.0.0

package/dist/adapters/codex/driver.d.ts

@@ -7,6 +7,9 @@ import type { HarnessTestDriver, HarnessDriverContext, ParsedRun } from "../../c
  * `--dangerously-bypass-approvals-and-sandbox` make it run unattended;
  * `--skip-git-repo-check` lets it run in a bare temp dir; `--ignore-user-config`
  * keeps the host's `~/.codex` out. The prompt is the trailing positional.
+ * `ctx.allowedTools` is ignored: `codex exec` runs with approvals bypassed, so
+ * everything is already approved. `ctx.tools` is refused (throws): Codex has no
+ * per-run tool availability.
  * Pure, so the arg shape is unit-tested.
  */
 export declare function buildCodexArgs(ctx: HarnessDriverContext): string[];

package/dist/adapters/codex/driver.js

@@ -26,9 +26,15 @@ const mock_model_js_1 = require("./mock-model.js");
  * `--dangerously-bypass-approvals-and-sandbox` make it run unattended;
  * `--skip-git-repo-check` lets it run in a bare temp dir; `--ignore-user-config`
  * keeps the host's `~/.codex` out. The prompt is the trailing positional.
+ * `ctx.allowedTools` is ignored: `codex exec` runs with approvals bypassed, so
+ * everything is already approved. `ctx.tools` is refused (throws): Codex has no
+ * per-run tool availability.
  * Pure, so the arg shape is unit-tested.
  */
 function buildCodexArgs(ctx) {
+    if (ctx.tools !== undefined) {
+        throw new Error("tools is not supported for codex: it has no per-run tool availability, and a list that withheld nothing would let a test pass over a run where nothing was withheld. Drop tools, or assert on what the agent did.");
+    }
     return [
         "exec",
         "--ignore-user-config",

package/dist/cli-commands.d.ts

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

package/dist/cli-commands.js

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

package/dist/cli-main.js

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

package/dist/cli.js

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

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

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

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

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

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

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

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

@@ -108,10 +108,17 @@ export interface HarnessDriverContext {
     /** Whether a settings file was written (CC: pass `--settings`). */
     readonly hasSettings: boolean;
     /**
-     * The ONLY tools the agent has, when the spec lists them; undefined = no
-     * restriction (every tool is offered, the default four are pre-approved).
+     * Which tools EXIST in the session, when the spec lists them (CC: `--tools`);
+     * undefined = every tool exists. A driver whose harness has no such concept
+     * (Codex) throws on one rather than ignore it.
      */
     readonly tools?: readonly string[];
+    /**
+     * Which tools are PRE-APPROVED (CC: `--allowedTools`); undefined = the
+     * default four. It never removes a tool. A driver with no such concept
+     * ignores it.
+     */
+    readonly allowedTools?: readonly string[];
     /** Capture the full event transcript instead of just the final result. */
     readonly transcript: boolean;
     /** Path to a plugin dir to install natively, if any. */

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

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

package/dist/core/run-env.js

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