vigiles 2.6.0 → 4.0.0

package/dist/{run-hook.js → adapters/claude-code/run-hook.js}

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseHookOutput = parseHookOutput;
 exports.decideHook = decideHook;
 exports.runHookWith = runHookWith;
+exports.egressRoutes = egressRoutes;
 exports.runHook = runHook;
 /**
  * vigiles — the *unit* tier for Claude Code hooks.
@@ -37,6 +38,8 @@ const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
+const hook_protocol_js_1 = require("./hook-protocol.js");
+const egress_js_1 = require("./egress.js");
 const sandbox_js_1 = require("./sandbox.js");
 /** Parse stdout as a hook JSON decision (pure, testable without a process). */
 function parseHookOutput(stdout) {
@@ -54,10 +57,11 @@ function parseHookOutput(stdout) {
  * Decide whether a hook result blocked, and the normalized decision. Pure, so
  * the policy is unit-testable independent of spawning anything.
  */
-function decideHook(exitCode, json) {
+function decideHook(exitCode, json, protocol = hook_protocol_js_1.claudeCodeHookProtocol) {
     const permission = json?.hookSpecificOutput?.permissionDecision;
     const decision = permission ?? json?.decision;
-    const blocked = exitCode === 2 || decision === "block" || decision === "deny";
+    const blocked = exitCode === protocol.blockExitCode ||
+        (decision !== undefined && protocol.denyDecisionValues.includes(decision));
     return { blocked, decision };
 }
 /**
@@ -68,6 +72,41 @@ function decideHook(exitCode, json) {
  * bwrap. `runHook` is this with the real seams.
  */
 function runHookWith(command, input, opts, deps) {
+    // Allowlisted egress is its own confined path (bwrap netns + slirp4netns + nft);
+    // it can't run unconfined, so it refuses outright when the tooling is absent
+    // rather than falling back to a direct run that would ignore the allowlist.
+    const res = opts.egress
+        ? runEgress(command, input, opts, deps)
+        : runConfinedOrDirect(command, input, opts, deps);
+    const exitCode = res.status ?? (res.signal ? 1 : 0);
+    const stdout = res.stdout ?? "";
+    const stderr = res.stderr ?? "";
+    const json = parseHookOutput(stdout);
+    const { blocked, decision: dec } = decideHook(exitCode, json);
+    return {
+        exitCode,
+        stdout,
+        stderr,
+        json,
+        blocked,
+        egress: res.egress ?? [],
+        egressDropped: res.egressDropped,
+        filesWritten: res.filesWritten ?? [],
+        decision: dec,
+    };
+}
+/** The allowlisted-egress branch: confine-with-netns, or refuse if unavailable. */
+function runEgress(command, input, opts, deps) {
+    if (!deps.egressAvailable) {
+        throw new Error("refusing to run egress: { allow } without the allowlist sandbox: it " +
+            "needs Linux + bubblewrap (bwrap) + slirp4netns + nft — install them to " +
+            "run with a packet-layer egress allowlist, or use recordEgress to record " +
+            "and block instead");
+    }
+    return deps.egress(command, input, opts);
+}
+/** The default branch: pick direct vs. confined via the safe-by-default policy. */
+function runConfinedOrDirect(command, input, opts, deps) {
     // Confinement follows provenance: a trusted hook (the default) runs directly;
     // marking a hook untrusted defaults it to "auto" (confine-or-refuse), so
     // foreign code is never run unconfined by accident. An explicit `sandbox`
@@ -84,24 +123,9 @@ function runHookWith(command, input, opts, deps) {
     });
     if (decision.action === "throw")
         throw new Error(decision.reason);
-    const res = decision.action === "sandbox"
+    return decision.action === "sandbox"
         ? deps.sandboxed(command, input, opts)
         : deps.direct(command, input, opts);
-    const exitCode = res.status ?? (res.signal ? 1 : 0);
-    const stdout = res.stdout ?? "";
-    const stderr = res.stderr ?? "";
-    const json = parseHookOutput(stdout);
-    const { blocked, decision: dec } = decideHook(exitCode, json);
-    return {
-        exitCode,
-        stdout,
-        stderr,
-        json,
-        blocked,
-        egress: res.egress ?? [],
-        filesWritten: res.filesWritten ?? [],
-        decision: dec,
-    };
 }
 /** Run the hook command directly through a shell (the default, unconfined). */
 function directSpawn(command, input, opts) {
@@ -238,11 +262,147 @@ function sandboxedSpawn(command, input, opts) {
         (0, node_fs_1.rmSync)(ioDir, { recursive: true, force: true });
     }
 }
+function egressEntry() {
+    return ([
+        (0, node_path_1.join)(__dirname, "egress-entry.js"),
+        (0, node_path_1.join)(__dirname, "..", "dist", "egress-entry.js"),
+    ].find((p) => (0, node_fs_1.existsSync)(p)) ?? (0, node_path_1.join)(__dirname, "egress-entry.js"));
+}
+// Runs INSIDE the bwrap netns: block until the parent has attached slirp4netns
+// (the netready file), load the nft allowlist, run the hook with the event on its
+// stdin, then dump the nft counters to a bound file BEFORE exiting — the netns
+// (and its counters) die with this process, so the read-back must happen here.
+const EGRESS_ALLOW_WRAPPER = [
+    "i=0",
+    'while [ ! -s "$VIG_NETREADY" ] && [ "$i" -lt 400 ]; do sleep 0.05; i=$((i+1)); done',
+    'nft -f "$VIG_NFT" > "$VIG_IODIR/nfterr" 2>&1',
+    'sh -c "$VIG_HOOK" < "$VIG_EVENT"',
+    "code=$?",
+    'nft list chain inet vig output > "$VIG_COUNTERS" 2>/dev/null',
+    'exit "$code"',
+].join("\n");
+/** Read the orchestrator's result file, or a failed-run default if it's absent. */
+function readEgressResult(resultFile) {
+    return (0, node_fs_1.existsSync)(resultFile)
+        ? JSON.parse((0, node_fs_1.readFileSync)(resultFile, "utf-8"))
+        : { status: 1, signal: null, stdout: "", stderr: "", counters: "" };
+}
+function egressSpawn(command, input, opts) {
+    const ioDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-hook-egr-"));
+    const home = (0, node_path_1.join)(ioDir, "home");
+    (0, node_fs_1.mkdirSync)(home);
+    const work = opts.cwd ?? (0, node_path_1.join)(ioDir, "work");
+    (0, node_fs_1.mkdirSync)(work, { recursive: true });
+    try {
+        // Resolve the allowlist to IPs and the system resolvers, then generate the
+        // nft ruleset (pure helpers in src/egress.ts) — the packet-layer wall.
+        const files = {
+            ioDir,
+            netready: (0, node_path_1.join)(ioDir, "netready"),
+            nft: (0, node_path_1.join)(ioDir, "rules.nft"),
+            event: (0, node_path_1.join)(ioDir, "event.json"),
+            counters: (0, node_path_1.join)(ioDir, "counters.txt"),
+        };
+        const allow = (0, egress_js_1.resolveAllow)(opts.egress?.allow ?? []);
+        const resolvers = (0, egress_js_1.parseResolvers)((0, node_fs_1.existsSync)("/etc/resolv.conf")
+            ? (0, node_fs_1.readFileSync)("/etc/resolv.conf", "utf-8")
+            : "");
+        (0, node_fs_1.writeFileSync)(files.nft, (0, egress_js_1.buildEgressNft)({ allow, resolvers }));
+        (0, node_fs_1.writeFileSync)(files.event, JSON.stringify(input));
+        // The in-netns resolv.conf: only the routable resolvers (the host's may be a
+        // 127.0.0.53 stub the netns can't reach). Bound over /etc/resolv.conf below.
+        const resolvConf = (0, node_path_1.join)(ioDir, "resolv.conf");
+        (0, node_fs_1.writeFileSync)(resolvConf, resolvers.map((r) => `nameserver ${r}`).join("\n") + "\n");
+        const bwrapArgv = (0, egress_js_1.buildEgressBwrapArgv)({
+            base: (0, sandbox_js_1.bwrapArgs)({
+                cwd: work,
+                ioDir,
+                home,
+                path: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
+            }),
+            setenv: (0, sandbox_js_1.setenvArgs)(opts.env ?? {}),
+            files,
+            command,
+            wrapper: EGRESS_ALLOW_WRAPPER,
+            resolvConf,
+        });
+        const configFile = (0, node_path_1.join)(ioDir, "config.json");
+        const resultFile = (0, node_path_1.join)(ioDir, "result.json");
+        (0, node_fs_1.writeFileSync)(configFile, JSON.stringify({
+            bwrapArgv,
+            slirpArgs: ["--configure", "--disable-host-loopback"],
+            // --config-net brings up the interface + host-derived routes in the
+            // target netns. The connector is slirp4netns by default (proven local);
+            // set VIGILES_EGRESS_CONNECTOR=pasta to use pasta (passt), which routes
+            // on hosted runners where slirp4netns's tap-attach fails.
+            pastaArgs: ["--config-net"],
+            connector: process.env.VIGILES_EGRESS_CONNECTOR === "pasta"
+                ? "pasta"
+                : "slirp4netns",
+            infoFile: (0, node_path_1.join)(ioDir, "info.json"),
+            readyFile: (0, node_path_1.join)(ioDir, "ready"),
+            netreadyFile: files.netready,
+            countersFile: files.counters,
+            resultFile,
+            timeoutMs: opts.timeoutMs ?? 30000,
+        }));
+        (0, node_child_process_1.spawnSync)("node", [egressEntry(), configFile], {
+            encoding: "utf-8",
+            timeout: (opts.timeoutMs ?? 30000) + 20000,
+        });
+        const result = readEgressResult(resultFile);
+        const { egress, egressDropped } = (0, egress_js_1.countersToResult)((0, egress_js_1.parseNftCounters)(result.counters), Date.now());
+        return {
+            status: result.status,
+            signal: result.signal,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            egress,
+            egressDropped,
+        };
+    }
+    finally {
+        (0, node_fs_1.rmSync)(ioDir, { recursive: true, force: true });
+    }
+}
 const REAL_DEPS = {
     available: (0, sandbox_js_1.sandboxAvailable)(),
+    egressAvailable: (0, egress_js_1.egressAvailable)((0, sandbox_js_1.sandboxAvailable)()),
     direct: directSpawn,
     sandboxed: sandboxedSpawn,
+    egress: egressSpawn,
 };
+/**
+ * Whether allowlisted egress can ACTUALLY route here — not just whether the tools
+ * exist. On GitHub-hosted runners bwrap+slirp4netns+nft are all present, yet
+ * slirp4netns fails to attach `tap0`: the netns has only `lo`, so nothing leaves
+ * and the egress assertions can't be exercised. Run a trivial hook in the egress
+ * sandbox and check a non-loopback interface came up; memoized (the capability is
+ * fixed per run). Gates the egress e2e tests so they run for real where egress
+ * works and SKIP — honestly — where it provably can't, instead of failing red.
+ * (slirp4netns → pasta is the fix that makes it route in CI too; see
+ * research/egress-sandbox-tooling.md.)
+ */
+let egressRoutesMemo;
+function egressRoutes() {
+    if (egressRoutesMemo !== undefined)
+        return egressRoutesMemo;
+    if (!(0, egress_js_1.egressAvailable)((0, sandbox_js_1.sandboxAvailable)()))
+        return (egressRoutesMemo = false);
+    try {
+        // The only reliable signal is the egress path itself: try to reach an
+        // allowlisted host and check a packet actually got out. Filesystem probes
+        // (/proc/net/dev) and `ip` are unreliable here — bwrap may bind the host
+        // /proc (so /proc/net shows host interfaces, a false positive) and `ip` isn't
+        // on the sandbox PATH. A real reach is namespace-accurate by construction.
+        const r = egressSpawn("curl -s -m 8 -o /dev/null https://example.com/ || true", { hook_event_name: "PreToolUse" }, { egress: { allow: ["example.com"] }, timeoutMs: 20000 });
+        egressRoutesMemo = (r.egress ?? []).some((e) => e.host === "example.com" && (e.packets ?? 0) > 0);
+    }
+    catch {
+        egressRoutesMemo = false;
+    }
+    return egressRoutesMemo;
+}
 /* v8 ignore stop */
 /**
  * Run a hook command, piping `input` as JSON to its stdin, and report the exit

package/dist/adapters/claude-code/run-scripts.d.ts

@@ -0,0 +1,52 @@
+export type ScriptStatus = "pass" | "skip" | "fail";
+export interface ScriptRunResult {
+    readonly file: string;
+    readonly code: number;
+    readonly status: ScriptStatus;
+}
+/**
+ * Exit code a harness/eval script uses to report itself SKIPPED (e.g. the
+ * deterministic tier when `claude` isn't installed) — the autotools convention.
+ * The runner surfaces it as a loud `⊘ SKIPPED` instead of a silent `✓`, and a
+ * skip never fails the run. Scripts call `skip()` (vigiles/testing) to emit it.
+ */
+export declare const SKIP_EXIT_CODE = 77;
+/** Filename extensions accepted for harness/eval scripts (JS and TS). */
+export declare const SCRIPT_EXTS: readonly ["mjs", "cjs", "js", "mts", "cts", "ts"];
+/** Glob suffix matching every accepted script extension, e.g. `harness`. */
+export declare function scriptGlob(kind: "harness" | "eval"): string;
+/** Node runtime capabilities that decide how a TypeScript script is run. */
+export interface NodeCaps {
+    /** `tsx` is installed locally (the preferred, version-agnostic TS loader). */
+    readonly tsx: boolean;
+    /** Node supports `--experimental-strip-types` (>= 22.6). */
+    readonly stripTypes: boolean;
+}
+/**
+ * The `node` argv (after the binary) to run a single script. Plain JS runs
+ * directly; a TypeScript script picks `tsx` when available, else Node's native
+ * type stripping. Throws a clear, actionable error when neither is available.
+ * Pure — exported for testing.
+ */
+export declare function interpreterArgs(file: string, caps: NodeCaps): string[];
+/** Detect TS-running capabilities for a project root. */
+export declare function detectNodeCaps(cwd: string): NodeCaps;
+/**
+ * Expand the given path/glob patterns into concrete script files. A pattern
+ * that is an existing file passes through unchanged; anything else is treated
+ * as a glob. Falls back to `defaultGlob` when no patterns are given. Results
+ * are deduped and sorted; `node_modules` and `dist` are always ignored.
+ */
+export declare function discoverScripts(patterns: readonly string[], defaultGlob: string, cwd: string): string[];
+/**
+ * Run each script as `node <file>`, inheriting stdio so the script's own report
+ * streams to the console. `env` is merged over `process.env` for every child
+ * (e.g. `VIGILES_TRIALS`). Returns the per-file exit codes.
+ */
+export declare function runScripts(files: readonly string[], cwd: string, env?: NodeJS.ProcessEnv): ScriptRunResult[];
+/** Whether any script FAILED (a skip is not a failure). */
+export declare function anyFailed(results: readonly ScriptRunResult[]): boolean;
+/** One line per file + an explicit pass/skip/fail tally. Skips are SHOWN, never
+ * folded into "passed" — a `⊘ SKIPPED` is loud, not a silent green. */
+export declare function formatScriptSummary(results: readonly ScriptRunResult[]): string;
+//# sourceMappingURL=run-scripts.d.ts.map

package/dist/adapters/claude-code/run-scripts.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCRIPT_EXTS = exports.SKIP_EXIT_CODE = void 0;
+exports.scriptGlob = scriptGlob;
+exports.interpreterArgs = interpreterArgs;
+exports.detectNodeCaps = detectNodeCaps;
+exports.discoverScripts = discoverScripts;
+exports.runScripts = runScripts;
+exports.anyFailed = anyFailed;
+exports.formatScriptSummary = formatScriptSummary;
+/**
+ * vigiles — run harness-test / eval script files via the CLI.
+ *
+ * `vigiles test` and `vigiles eval` discover `*.harness.*` / `*.eval.*`
+ * scripts and run each as a child `node` process, so the two-tier
+ * harness-testing API (`src/harness-test.ts`, `src/eval.ts`) works as a CI
+ * command, not just `node x.mjs`. Scripts may be authored in **JavaScript**
+ * (`.mjs` / `.cjs` / `.js`) **or TypeScript** (`.ts` / `.mts` / `.cts`) — a TS
+ * script is run through `tsx` when installed, else Node's built-in type
+ * stripping (Node >= 22.6). The scripts import from the built `dist/`, so they
+ * also run standalone — the CLI just discovers, runs, and aggregates exit codes.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const glob_1 = require("glob");
+/**
+ * Exit code a harness/eval script uses to report itself SKIPPED (e.g. the
+ * deterministic tier when `claude` isn't installed) — the autotools convention.
+ * The runner surfaces it as a loud `⊘ SKIPPED` instead of a silent `✓`, and a
+ * skip never fails the run. Scripts call `skip()` (vigiles/testing) to emit it.
+ */
+exports.SKIP_EXIT_CODE = 77;
+function statusForCode(code) {
+    if (code === 0)
+        return "pass";
+    if (code === exports.SKIP_EXIT_CODE)
+        return "skip";
+    return "fail";
+}
+/** Filename extensions accepted for harness/eval scripts (JS and TS). */
+exports.SCRIPT_EXTS = ["mjs", "cjs", "js", "mts", "cts", "ts"];
+/** Glob suffix matching every accepted script extension, e.g. `harness`. */
+function scriptGlob(kind) {
+    return `**/*.${kind}.{${exports.SCRIPT_EXTS.join(",")}}`;
+}
+const TS_EXT = /\.(?:m|c)?ts$/;
+/**
+ * The `node` argv (after the binary) to run a single script. Plain JS runs
+ * directly; a TypeScript script picks `tsx` when available, else Node's native
+ * type stripping. Throws a clear, actionable error when neither is available.
+ * Pure — exported for testing.
+ */
+function interpreterArgs(file, caps) {
+    if (!TS_EXT.test(file))
+        return [file];
+    if (caps.tsx)
+        return ["--import", "tsx", file];
+    if (caps.stripTypes)
+        return ["--experimental-strip-types", file];
+    throw new Error(`Cannot run TypeScript test script "${file}": install tsx ` +
+        `(npm i -D tsx) or use Node >= 22.6, or author it as a .mjs file.`);
+}
+/** Detect TS-running capabilities for a project root. */
+function detectNodeCaps(cwd) {
+    const tsx = (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, "node_modules/tsx/package.json")) ||
+        (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, "node_modules/.bin/tsx"));
+    const stripTypes = process.allowedNodeEnvironmentFlags.has("--experimental-strip-types");
+    return { tsx, stripTypes };
+}
+/**
+ * Expand the given path/glob patterns into concrete script files. A pattern
+ * that is an existing file passes through unchanged; anything else is treated
+ * as a glob. Falls back to `defaultGlob` when no patterns are given. Results
+ * are deduped and sorted; `node_modules` and `dist` are always ignored.
+ */
+function discoverScripts(patterns, defaultGlob, cwd) {
+    const globs = patterns.length > 0 ? patterns : [defaultGlob];
+    const found = new Set();
+    for (const p of globs) {
+        if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, p))) {
+            found.add(p);
+            continue;
+        }
+        for (const m of (0, glob_1.globSync)(p, {
+            cwd,
+            ignore: ["node_modules/**", "dist/**"],
+        })) {
+            found.add(m);
+        }
+    }
+    return [...found].sort();
+}
+/**
+ * Run each script as `node <file>`, inheriting stdio so the script's own report
+ * streams to the console. `env` is merged over `process.env` for every child
+ * (e.g. `VIGILES_TRIALS`). Returns the per-file exit codes.
+ */
+function runScripts(files, cwd, env = {}) {
+    const caps = detectNodeCaps(cwd);
+    const results = [];
+    for (const file of files) {
+        let argv;
+        try {
+            argv = interpreterArgs(file, caps);
+        }
+        catch (e) {
+            console.error(`✗ ${file}: ${e.message}`);
+            results.push({ file, code: 1, status: "fail" });
+            continue;
+        }
+        const res = (0, node_child_process_1.spawnSync)("node", argv, {
+            cwd,
+            stdio: "inherit",
+            env: { ...process.env, ...env },
+        });
+        const code = res.status ?? 1;
+        results.push({ file, code, status: statusForCode(code) });
+    }
+    return results;
+}
+/** Whether any script FAILED (a skip is not a failure). */
+function anyFailed(results) {
+    return results.some((r) => r.status === "fail");
+}
+const MARK = {
+    pass: "✓",
+    skip: "⊘",
+    fail: "✗",
+};
+/** One line per file + an explicit pass/skip/fail tally. Skips are SHOWN, never
+ * folded into "passed" — a `⊘ SKIPPED` is loud, not a silent green. */
+function formatScriptSummary(results) {
+    const lines = results.map((r) => {
+        if (r.status === "skip")
+            return `  ⊘ ${r.file} — SKIPPED`;
+        if (r.status === "fail")
+            return `  ✗ ${r.file} (exit ${String(r.code)})`;
+        return `  ${MARK.pass} ${r.file}`;
+    });
+    const n = (s) => results.filter((r) => r.status === s).length;
+    const parts = [`${String(n("pass"))} passed`];
+    if (n("skip") > 0)
+        parts.push(`${String(n("skip"))} skipped`);
+    if (n("fail") > 0)
+        parts.push(`${String(n("fail"))} failed`);
+    lines.push(`\n${parts.join(", ")}.`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=run-scripts.js.map

package/dist/adapters/claude-code/runtime.d.ts

@@ -0,0 +1,16 @@
+/**
+ * claudeCodeRuntime — the Claude Code `HarnessRuntime` (spawn `claude`, reach the
+ * mock via `ANTHROPIC_BASE_URL` with a dummy `ANTHROPIC_API_KEY`). The runners
+ * (`harness-test.ts`, `eval.ts`) read the binary + env from here instead of
+ * hard-coding them; a Codex adapter defines `codexRuntime` and its runner uses it.
+ */
+import type { HarnessRuntime } from "../../core/runtime.js";
+export declare const claudeCodeRuntime: HarnessRuntime;
+/**
+ * Build the spawn env that points the agent CLI at the mock model: the caller's
+ * environment plus the runtime's base-URL var (→ the mock's URL) and a dummy
+ * API key. Pure (no spawn), so it's unit-tested directly — the testable seam of
+ * the otherwise un-coverable real-subprocess path.
+ */
+export declare function mockModelEnv(runtime: HarnessRuntime, baseUrl: string, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/adapters/claude-code/runtime.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeRuntime = void 0;
+exports.mockModelEnv = mockModelEnv;
+exports.claudeCodeRuntime = {
+    name: "claude-code",
+    agentBinary: "claude",
+    modelBaseUrlEnv: "ANTHROPIC_BASE_URL",
+    modelApiKeyEnv: "ANTHROPIC_API_KEY",
+    mockApiKey: "sk-vigiles-mock",
+    /**
+     * Claude Code reaches the mock purely through env (no argv flags): the
+     * base-URL var + a dummy key. The returned `env` is the overlay the runner
+     * layers over `process.env`, so the spawn env is identical to `mockModelEnv`.
+     */
+    wireMock(baseUrl) {
+        return {
+            args: [],
+            env: {
+                [exports.claudeCodeRuntime.modelBaseUrlEnv]: baseUrl,
+                [exports.claudeCodeRuntime.modelApiKeyEnv]: exports.claudeCodeRuntime.mockApiKey,
+            },
+        };
+    },
+};
+/**
+ * Build the spawn env that points the agent CLI at the mock model: the caller's
+ * environment plus the runtime's base-URL var (→ the mock's URL) and a dummy
+ * API key. Pure (no spawn), so it's unit-tested directly — the testable seam of
+ * the otherwise un-coverable real-subprocess path.
+ */
+function mockModelEnv(runtime, baseUrl, base = process.env) {
+    return {
+        ...base,
+        [runtime.modelBaseUrlEnv]: baseUrl,
+        [runtime.modelApiKeyEnv]: runtime.mockApiKey,
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/{sandbox.d.ts → adapters/claude-code/sandbox.d.ts}

@@ -79,6 +79,16 @@ export interface EgressAttempt {
     readonly port: number;
     /** ms epoch when the attempt was recorded. */
     readonly ts: number;
+    /**
+     * Allowlist mode (`egress: { allow }`) only: whether this host was on the
+     * allowlist (and so reachable). Undefined for the `recordEgress` proxy, where
+     * every attempt is blocked.
+     */
+    readonly allowed?: boolean;
+    /** Allowlist mode: packets the nftables counter recorded for this host. */
+    readonly packets?: number;
+    /** Allowlist mode: bytes the nftables counter recorded for this host. */
+    readonly bytes?: number;
 }
 /**
  * Parse the egress recorder's ndjson log into {@link EgressAttempt}s. Pure, so

package/dist/{sandbox.js → adapters/claude-code/sandbox.js}

@@ -35,6 +35,7 @@ const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
+const runtime_js_1 = require("./runtime.js");
 let cachedAvailable;
 /**
  * Whether this environment can ACTUALLY confine untrusted code under bubblewrap.
@@ -232,9 +233,10 @@ const WRAPPER = [
     "MOCKPID=$!",
     "i=0",
     'while [ ! -s "$VIG_PORT" ] && [ "$i" -lt 200 ]; do sleep 0.05; i=$((i+1)); done',
-    'export ANTHROPIC_BASE_URL="http://127.0.0.1:$(cat "$VIG_PORT")"',
-    "export ANTHROPIC_API_KEY=sk-vigiles-mock",
-    'claude "$@"',
+    // base-URL / API-key vars + the agent binary come from the runtime port.
+    `export ${runtime_js_1.claudeCodeRuntime.modelBaseUrlEnv}="http://127.0.0.1:$(cat "$VIG_PORT")"`,
+    `export ${runtime_js_1.claudeCodeRuntime.modelApiKeyEnv}=${runtime_js_1.claudeCodeRuntime.mockApiKey}`,
+    `${runtime_js_1.claudeCodeRuntime.agentBinary} "$@"`,
     "code=$?",
     'kill "$MOCKPID" 2>/dev/null',
     'exit "$code"',

package/dist/{skill-driver.d.ts → adapters/claude-code/skill-driver.d.ts}

@@ -13,7 +13,7 @@
  * is fed back into the generator). Gates are deterministic and reuse the gate
  * runtime. This module is the mechanics — fully testable without a live model.
  */
-import type { Gate } from "./spec.js";
+import type { Gate } from "../../core/spec.js";
 import { type GateOutcome } from "./skill-runtime.js";
 export type SkillEffect = {
     readonly kind: "act";

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

@@ -0,0 +1,3 @@
+import type { HarnessAdapter } from "../../core/adapter.js";
+export declare const codexAdapter: HarnessAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapters/codex/adapter.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codexAdapter = void 0;
+/**
+ * codexAdapter — the OpenAI Codex `HarnessAdapter`. Bundles the five Codex ports
+ * + a `detect`. SHIPPED: registered in `src/adapter-registry.ts` (the CLI
+ * auto-detects a `.codex/config.toml` or `AGENTS.md` repo) and exported as
+ * `vigiles/codex`. It passes `assertAdapterConformance`/`assertAdapterLoadsHooks`,
+ * drives the compiler + loader against real Codex fixtures (codex.test.ts), and
+ * its transport (`mock-model.ts`) is proven against the real `codex` binary.
+ *
+ * Caveat — pillar 1 (compile) is partial: the instruction/skill *renderers* still
+ * emit the Claude-Code shape until the format-axis renderers land
+ * (`research/code-adapter-architecture.md`). Pillar 2 (harness testing) is full.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const dialect_js_1 = require("./dialect.js");
+const layout_js_1 = require("./layout.js");
+const runtime_js_1 = require("./runtime.js");
+const hook_protocol_js_1 = require("./hook-protocol.js");
+const model_mock_js_1 = require("./model-mock.js");
+const driver_js_1 = require("./driver.js");
+exports.codexAdapter = {
+    name: "codex",
+    // Full convergence with Claude Code: mockable (Responses SSE) + shell hooks
+    // with veto (permissionDecision/exit 2). Both pillars, all tiers.
+    capabilities: {
+        referenceVerification: true,
+        harnessTesting: true,
+        shellHooks: true,
+    },
+    dialect: dialect_js_1.codexDialect,
+    layout: layout_js_1.codexLayout,
+    runtime: runtime_js_1.codexRuntime,
+    hookProtocol: hook_protocol_js_1.codexHookProtocol,
+    modelMock: model_mock_js_1.codexModelMock,
+    harnessTestDriver: driver_js_1.codexDriver,
+    detect(root) {
+        // A `.codex/config.toml` is a strong signal; a bare AGENTS.md is weak (many
+        // harnesses read it). (Unused while unregistered — kept for symmetry.)
+        if ((0, node_fs_1.existsSync)((0, node_path_1.join)(root, ".codex", "config.toml")))
+            return 3;
+        if ((0, node_fs_1.existsSync)((0, node_path_1.join)(root, layout_js_1.codexLayout.instructionFile)))
+            return 1;
+        return 0;
+    },
+};
+//# sourceMappingURL=adapter.js.map

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

@@ -0,0 +1,10 @@
+/**
+ * codexDialect — EXPERIMENTAL, internal-only. A prototype `HarnessDialect` for
+ * OpenAI Codex, built from the mid-2026 research (research/harness-landscape.md)
+ * to validate that the format axis actually generalizes beyond Claude Code. NOT
+ * exported from `vigiles/*` and NOT registered in the adapter registry — it
+ * exists to be run through the conformance kit + real Codex-shaped fixtures.
+ */
+import type { HarnessDialect } from "../../core/dialect.js";
+export declare const codexDialect: HarnessDialect;
+//# sourceMappingURL=dialect.d.ts.map

package/dist/adapters/codex/dialect.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codexDialect = void 0;
+exports.codexDialect = {
+    name: "codex",
+    // Codex model-facing tools (shell/exec, file edits, plan, web), + MCP tools.
+    builtinAgentTools: ["shell", "apply_patch", "update_plan", "web_search"],
+    // No documented "never available to a subagent" set yet — left empty.
+    neverAvailableTools: [],
+    mcpToolPattern: /^mcp__[a-z0-9_-]+__[a-z0-9_-]+$/i,
+    // Codex hooks (near-1:1 with Claude Code) + its extras.
+    hookEvents: [
+        "SessionStart",
+        "SubagentStart",
+        "SubagentStop",
+        "PreToolUse",
+        "PostToolUse",
+        "PermissionRequest",
+        "PreCompact",
+        "PostCompact",
+        "UserPromptSubmit",
+        "Stop",
+    ],
+    instructionTargets: ["AGENTS.md"],
+    pluginRootToken: "${PLUGIN_ROOT}",
+    // Codex SKILL.md frontmatter is name + description ONLY — the CC-only keys
+    // (disable-model-invocation, argument-hint, …) are not part of its format.
+    skillFrontmatter: "minimal",
+};
+//# sourceMappingURL=dialect.js.map