vigiles 2.6.0 → 4.0.0

package/dist/adapter-conformance.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkAdapterConformance = checkAdapterConformance;
+exports.assertAdapterConformance = assertAdapterConformance;
+exports.assertHarnessTestable = assertHarnessTestable;
+exports.assertAdapterLoadsHooks = assertAdapterLoadsHooks;
+/**
+ * Adapter conformance kit — the reusable check every `HarnessAdapter` runs, so
+ * authoring one is guided and safe rather than "hope it's wired right". It
+ * verifies each port is populated AND a behavioural invariant: the adapter's
+ * dialect actually drives tool-contract verification (its own built-in tool is
+ * accepted). A third-party adapter author runs `assertAdapterConformance(myAdapter)`
+ * in their test suite. See `docs/authoring-an-adapter.md`.
+ */
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const compile_js_1 = require("./core/compile.js");
+const spec_js_1 = require("./core/spec.js");
+const plugin_loader_js_1 = require("./plugin-loader.js");
+/** Check an adapter against the port contracts; returns the (possibly empty) failure list. */
+function checkAdapterConformance(adapter) {
+    const failures = [];
+    const need = (cond, msg) => {
+        if (!cond)
+            failures.push(msg);
+    };
+    const caps = adapter.capabilities;
+    // Widen to boolean so a malformed (non-TS) adapter that set this false is still
+    // caught at runtime — the literal `true` type would make a direct check redundant.
+    const refVerification = caps.referenceVerification;
+    need(adapter.name.length > 0, "name is empty");
+    need(refVerification, "capabilities.referenceVerification must be true (every adapter does pillar 1)");
+    // --- Pillar 1 (always required): dialect + layout ---
+    need(adapter.dialect.builtinAgentTools.length > 0, "dialect has no builtinAgentTools");
+    need(adapter.dialect.instructionTargets.length > 0, "dialect has no instructionTargets");
+    need(adapter.layout.instructionFile.length > 0, "layout.instructionFile is empty");
+    need(adapter.layout.manifestPath.length > 0, "layout.manifestPath is empty");
+    need(adapter.layout.surfaceDirs.length > 0, "layout has no surfaceDirs");
+    need(typeof adapter.detect === "function", "detect is not a function");
+    // --- Pillar 2 transport ports: required ONLY for the capabilities the
+    // adapter declares. A pillar-1-only adapter (harnessTesting:false) may omit
+    // runtime/modelMock; a code-module-hook adapter (shellHooks:false) may omit
+    // hookProtocol — and conformance must NOT demand a fake one. The flip side:
+    // if it CLAIMS the capability, the port must be there and populated.
+    const portNames = [
+        ["dialect", adapter.dialect.name],
+        ["layout", adapter.layout.name],
+    ];
+    if (caps.harnessTesting) {
+        need(adapter.runtime !== undefined, "capabilities.harnessTesting is true but runtime is missing");
+        need(adapter.modelMock !== undefined, "capabilities.harnessTesting is true but modelMock is missing");
+        if (adapter.runtime) {
+            need(adapter.runtime.agentBinary.length > 0, "runtime.agentBinary is empty");
+            need(adapter.runtime.modelBaseUrlEnv.length > 0, "runtime.modelBaseUrlEnv is empty");
+            portNames.push(["runtime", adapter.runtime.name]);
+        }
+        if (adapter.modelMock) {
+            need(adapter.modelMock.modelEndpoint.length > 0, "modelMock.modelEndpoint is empty");
+            portNames.push(["modelMock", adapter.modelMock.name]);
+        }
+    }
+    else {
+        need(adapter.runtime === undefined && adapter.modelMock === undefined, "capabilities.harnessTesting is false — omit runtime/modelMock (a pillar-1-only adapter must not ship a half-wired transport)");
+    }
+    if (caps.shellHooks) {
+        need(adapter.hookProtocol !== undefined, "capabilities.shellHooks is true but hookProtocol is missing");
+        if (adapter.hookProtocol) {
+            need(Number.isInteger(adapter.hookProtocol.blockExitCode), "hookProtocol.blockExitCode is not an integer");
+            portNames.push(["hookProtocol", adapter.hookProtocol.name]);
+        }
+    }
+    else {
+        need(adapter.hookProtocol === undefined, "capabilities.shellHooks is false — omit hookProtocol (hooks are code modules, not shell processes)");
+    }
+    // Cross-port invariants — the kind of mismatch a copy-paste authoring slip
+    // produces, that no single-port check would catch. Only the present ports.
+    for (const [port, name] of portNames) {
+        need(name === adapter.name, `${port}.name "${name}" != adapter.name "${adapter.name}"`);
+    }
+    need(adapter.layout.pluginRootToken === adapter.dialect.pluginRootToken, "layout.pluginRootToken and dialect.pluginRootToken disagree");
+    need(adapter.dialect.instructionTargets.includes(adapter.layout.instructionFile), `layout.instructionFile "${adapter.layout.instructionFile}" is not one of dialect.instructionTargets`);
+    need(adapter.layout.settingsFormat === "json" ||
+        adapter.layout.settingsFormat === "toml", `layout.settingsFormat "${adapter.layout.settingsFormat}" is not "json" | "toml"`);
+    // Behavioural: the dialect drives the compiler — its own built-in tool must
+    // pass the subagent tool-contract check under this dialect.
+    const tool = adapter.dialect.builtinAgentTools[0];
+    if (tool) {
+        const spec = (0, spec_js_1.agent)({
+            name: "conformance",
+            description: "conformance probe",
+            tools: [tool],
+            body: "probe",
+        });
+        const r = (0, compile_js_1.compileAgent)(spec, {
+            specFile: "conformance.md.spec.ts",
+            dialect: adapter.dialect,
+        });
+        need(!r.errors.some((e) => e.type === "unknown-tool"), `dialect rejects its own built-in tool "${tool}"`);
+    }
+    return { ok: failures.length === 0, failures };
+}
+/** Throw if the adapter fails conformance — drop this in an adapter's test suite. */
+function assertAdapterConformance(adapter) {
+    const r = checkAdapterConformance(adapter);
+    if (!r.ok) {
+        throw new Error(`Adapter "${adapter.name}" failed conformance:\n  - ${r.failures.join("\n  - ")}`);
+    }
+}
+/**
+ * Guard for the pillar-2 entry points (runHarnessTest/runEval): a pillar-1-only
+ * adapter (Cursor, Devin, Amp, Amazon Q) has no mockable transport, so driving
+ * the deterministic/eval tiers against it would hang or spawn nothing. Calling
+ * this up front turns that into a clear, immediate error. Returns the narrowed
+ * runtime+modelMock so the caller can use them without re-checking for undefined.
+ */
+function assertHarnessTestable(adapter) {
+    if (!adapter.capabilities.harnessTesting ||
+        !adapter.runtime ||
+        !adapter.modelMock) {
+        throw new Error(`Adapter "${adapter.name}" does not support harness testing (pillar 2): it is reference-verification-only (no mockable runtime). Use it for compile/scan/audit, not runHarnessTest/runEval.`);
+    }
+    return { runtime: adapter.runtime, modelMock: adapter.modelMock };
+}
+/**
+ * Behavioural conformance the pure checks can't reach: write a minimal settings
+ * file in the adapter's declared `settingsFormat` (with a hook), load it through
+ * the adapter's `layout`, and assert the hooks actually came back. This is what
+ * catches a layout that points at the right file but in the wrong format (the
+ * JSON-vs-TOML trap) — the pure checker would pass it, the agent would silently
+ * run with zero hooks. Does filesystem IO, so it's a separate opt-in assert.
+ */
+function assertAdapterLoadsHooks(adapter) {
+    const dir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-conformance-"));
+    try {
+        const settingsAbs = (0, node_path_1.join)(dir, adapter.layout.settingsPath);
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(settingsAbs), { recursive: true });
+        const content = adapter.layout.settingsFormat === "toml"
+            ? '[[hooks.PreToolUse]]\ncommand = "echo conformance"\n'
+            : JSON.stringify({
+                hooks: { PreToolUse: [{ command: "echo conformance" }] },
+            });
+        (0, node_fs_1.writeFileSync)(settingsAbs, content);
+        const loaded = (0, plugin_loader_js_1.loadPlugin)(dir, adapter.layout);
+        if (!loaded.settings.hooks) {
+            throw new Error(`Adapter "${adapter.name}": loadPlugin read no hooks from a ${adapter.layout.settingsFormat} settings file at ${adapter.layout.settingsPath} — the settings-format wiring is broken.`);
+        }
+    }
+    finally {
+        (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=adapter-conformance.js.map

package/dist/adapter-registry.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Adapter registry — the composition-root list the CLI uses to auto-detect which
+ * harness a repo targets. The library API selects an adapter by import
+ * (`vigiles/claude-code`); the CLI can't, so it walks this registry. Claude Code
+ * is the default, so detection is backwards-compatible: an undetected repo (or a
+ * repo with no adapter markers) resolves to Claude Code exactly as before.
+ *
+ * Adding a harness = add its `HarnessAdapter` to `ADAPTERS` (and a
+ * `vigiles/<harness>` export). Order matters only if two adapters could both
+ * match a repo; `detect()` returns a specificity score so the strongest signal
+ * wins regardless of order.
+ */
+import type { HarnessAdapter } from "./core/adapter.js";
+/** The default adapter when detection finds no harness markers. */
+export declare const defaultAdapter: HarnessAdapter;
+/** All registered adapters. detect() specificity (not order) breaks ties. */
+export declare const ADAPTERS: readonly HarnessAdapter[];
+/** The result of auto-detecting a harness from a repo's layout. */
+export interface DetectResult {
+    readonly adapter: HarnessAdapter;
+    /** True when detection found no harness markers and fell back to the default. */
+    readonly fallback: boolean;
+    /**
+     * Other adapters that matched at the same top specificity — a non-empty list
+     * means the repo looks like more than one harness (e.g. a CLAUDE.md + an
+     * AGENTS.md), so the pick is ambiguous; resolve with `--harness`.
+     */
+    readonly ambiguousWith: readonly string[];
+}
+/** Auto-detect the harness for a repo at `root` by highest detect() specificity. */
+export declare function detectAdapterResult(root: string): DetectResult;
+/** The detected adapter (highest specificity), else the default (Claude Code). */
+export declare function detectAdapter(root: string): HarnessAdapter;
+/** Look up a registered adapter by `name` (e.g. for a `--harness` override). */
+export declare function getAdapter(name: string): HarnessAdapter | undefined;
+/**
+ * Resolve the adapter for a command: an explicit `--harness <name>` wins (throws
+ * if unknown); otherwise auto-detect from `root`. The single entry point the CLI
+ * uses so detection + override live in one place.
+ */
+export declare function resolveAdapter(root: string, harness?: string): HarnessAdapter;
+//# sourceMappingURL=adapter-registry.d.ts.map

package/dist/adapter-registry.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADAPTERS = exports.defaultAdapter = void 0;
+exports.detectAdapterResult = detectAdapterResult;
+exports.detectAdapter = detectAdapter;
+exports.getAdapter = getAdapter;
+exports.resolveAdapter = resolveAdapter;
+const adapter_js_1 = require("./adapters/claude-code/adapter.js");
+const adapter_js_2 = require("./adapters/codex/adapter.js");
+/** The default adapter when detection finds no harness markers. */
+exports.defaultAdapter = adapter_js_1.claudeCodeAdapter;
+/** All registered adapters. detect() specificity (not order) breaks ties. */
+exports.ADAPTERS = [
+    adapter_js_1.claudeCodeAdapter,
+    adapter_js_2.codexAdapter,
+];
+/** Auto-detect the harness for a repo at `root` by highest detect() specificity. */
+function detectAdapterResult(root) {
+    const scored = exports.ADAPTERS.map((a) => ({ a, score: a.detect(root) })).filter((s) => s.score > 0);
+    if (scored.length === 0) {
+        return { adapter: exports.defaultAdapter, fallback: true, ambiguousWith: [] };
+    }
+    const top = Math.max(...scored.map((s) => s.score));
+    const winners = scored.filter((s) => s.score === top).map((s) => s.a);
+    return {
+        adapter: winners[0],
+        fallback: false,
+        ambiguousWith: winners.slice(1).map((a) => a.name),
+    };
+}
+/** The detected adapter (highest specificity), else the default (Claude Code). */
+function detectAdapter(root) {
+    return detectAdapterResult(root).adapter;
+}
+/** Look up a registered adapter by `name` (e.g. for a `--harness` override). */
+function getAdapter(name) {
+    return exports.ADAPTERS.find((a) => a.name === name);
+}
+/**
+ * Resolve the adapter for a command: an explicit `--harness <name>` wins (throws
+ * if unknown); otherwise auto-detect from `root`. The single entry point the CLI
+ * uses so detection + override live in one place.
+ */
+function resolveAdapter(root, harness) {
+    if (harness !== undefined) {
+        const a = getAdapter(harness);
+        if (!a) {
+            const known = exports.ADAPTERS.map((x) => x.name).join(", ");
+            throw new Error(`Unknown harness "${harness}". Known: ${known}.`);
+        }
+        return a;
+    }
+    return detectAdapter(root);
+}
+//# sourceMappingURL=adapter-registry.js.map

package/dist/adapter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `vigiles/adapter` — the harness-adapter authoring kit.
+ *
+ * Everything you need to teach vigiles a new harness, in one import: the five
+ * port interfaces to implement, the `HarnessAdapter` bundle that groups them,
+ * the conformance kit to validate yours, and the registry the CLI detects
+ * through. vigiles ships a Claude Code adapter; building your own is welcome and
+ * supported — see `docs/authoring-an-adapter.md`.
+ *
+ *   import {
+ *     type HarnessAdapter, type HarnessDialect, type PluginLayout,
+ *     type HarnessRuntime, type HookProtocol, type ModelMock,
+ *     assertAdapterConformance,
+ *   } from "vigiles/adapter";
+ *
+ *   export const myHarnessAdapter: HarnessAdapter = { name: "my-harness", … };
+ */
+export type { HarnessAdapter, AdapterCapabilities } from "./core/adapter.js";
+export type { HarnessDialect } from "./core/dialect.js";
+export type { PluginLayout } from "./core/layout.js";
+export type { HarnessRuntime } from "./core/runtime.js";
+export type { HookProtocol } from "./core/hook-protocol.js";
+export type { ModelMock } from "./core/model-mock.js";
+export { checkAdapterConformance, assertAdapterConformance, assertAdapterLoadsHooks, assertHarnessTestable, type ConformanceResult, } from "./adapter-conformance.js";
+export { ADAPTERS, defaultAdapter, detectAdapter, detectAdapterResult, resolveAdapter, getAdapter, type DetectResult, } from "./adapter-registry.js";
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAdapter = exports.resolveAdapter = exports.detectAdapterResult = exports.detectAdapter = exports.defaultAdapter = exports.ADAPTERS = exports.assertHarnessTestable = exports.assertAdapterLoadsHooks = exports.assertAdapterConformance = exports.checkAdapterConformance = void 0;
+var adapter_conformance_js_1 = require("./adapter-conformance.js");
+Object.defineProperty(exports, "checkAdapterConformance", { enumerable: true, get: function () { return adapter_conformance_js_1.checkAdapterConformance; } });
+Object.defineProperty(exports, "assertAdapterConformance", { enumerable: true, get: function () { return adapter_conformance_js_1.assertAdapterConformance; } });
+Object.defineProperty(exports, "assertAdapterLoadsHooks", { enumerable: true, get: function () { return adapter_conformance_js_1.assertAdapterLoadsHooks; } });
+Object.defineProperty(exports, "assertHarnessTestable", { enumerable: true, get: function () { return adapter_conformance_js_1.assertHarnessTestable; } });
+var adapter_registry_js_1 = require("./adapter-registry.js");
+Object.defineProperty(exports, "ADAPTERS", { enumerable: true, get: function () { return adapter_registry_js_1.ADAPTERS; } });
+Object.defineProperty(exports, "defaultAdapter", { enumerable: true, get: function () { return adapter_registry_js_1.defaultAdapter; } });
+Object.defineProperty(exports, "detectAdapter", { enumerable: true, get: function () { return adapter_registry_js_1.detectAdapter; } });
+Object.defineProperty(exports, "detectAdapterResult", { enumerable: true, get: function () { return adapter_registry_js_1.detectAdapterResult; } });
+Object.defineProperty(exports, "resolveAdapter", { enumerable: true, get: function () { return adapter_registry_js_1.resolveAdapter; } });
+Object.defineProperty(exports, "getAdapter", { enumerable: true, get: function () { return adapter_registry_js_1.getAdapter; } });
+//# sourceMappingURL=adapter.js.map

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

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

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

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeAdapter = void 0;
+/**
+ * claudeCodeAdapter — the Claude Code `HarnessAdapter`: the five port
+ * implementations bundled, plus a `detect` that recognizes a Claude Code repo
+ * (a `.claude-plugin/` manifest, a `.claude/settings.json`, or a `CLAUDE.md`).
+ * This is the reference adapter a second harness (Codex, Gemini, …) mirrors.
+ */
+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 harness_test_js_1 = require("./harness-test.js");
+exports.claudeCodeAdapter = {
+    name: "claude-code",
+    // The reference harness: every tier. Mockable transport (Anthropic SSE) and
+    // shell hooks (exit 2 / decision JSON) — both pillars, all tiers.
+    capabilities: {
+        referenceVerification: true,
+        harnessTesting: true,
+        shellHooks: true,
+    },
+    dialect: dialect_js_1.claudeCodeDialect,
+    layout: layout_js_1.claudeCodeLayout,
+    runtime: runtime_js_1.claudeCodeRuntime,
+    hookProtocol: hook_protocol_js_1.claudeCodeHookProtocol,
+    modelMock: model_mock_js_1.claudeCodeModelMock,
+    harnessTestDriver: harness_test_js_1.claudeCodeDriver,
+    detect(root) {
+        // Most specific signal wins: a plugin manifest (3) > repo settings (2) >
+        // a bare CLAUDE.md (1, weak — many tools also read it / AGENTS.md).
+        const has = (rel) => (0, node_fs_1.existsSync)((0, node_path_1.join)(root, rel));
+        if (has(layout_js_1.claudeCodeLayout.manifestPath))
+            return 3;
+        if (has(layout_js_1.claudeCodeLayout.settingsPath))
+            return 2;
+        if (has(layout_js_1.claudeCodeLayout.instructionFile))
+            return 1;
+        return 0;
+    },
+};
+//# sourceMappingURL=adapter.js.map

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

@@ -17,7 +17,7 @@
  * third `malformed` track for a worker that didn't honor its contract (no block,
  * bad JSON, or a shape that doesn't match the declared schema).
  */
-import type { OutputContract } from "./spec.js";
+import type { OutputContract } from "../../core/spec.js";
 /** The outcome of parsing a worker's result block. */
 export type ParsedAgentResult<S = Record<string, unknown>, E = Record<string, unknown>> = {
     readonly kind: "ok";

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

@@ -0,0 +1,13 @@
+/**
+ * claudeCodeDialect — the Claude Code adapter's `HarnessDialect` (format axis).
+ * The concrete dialect is DEFINED here, in the adapter, symmetric with the other
+ * four ports (`claudeCodeLayout`/`Runtime`/`HookProtocol`/`ModelMock`): the core
+ * holds only the `HarnessDialect` interface and never a harness's vocabulary. The
+ * compiler/validator receive this by injection (`compileAgent(spec, { dialect })`,
+ * the CLI/composition root supplies it). A second harness defines its own dialect
+ * in its adapter (e.g. `src/adapters/codex/dialect.ts` exporting `codexDialect`).
+ */
+import type { HarnessDialect } from "../../core/dialect.js";
+export declare const claudeCodeDialect: HarnessDialect;
+export type { HarnessDialect } from "../../core/dialect.js";
+//# sourceMappingURL=dialect.d.ts.map

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

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeDialect = void 0;
+exports.claudeCodeDialect = {
+    name: "claude-code",
+    // The tool contract a subagent may declare — the rails it runs on. Anything
+    // else must be an MCP tool, else it's a typo / nonexistent tool.
+    builtinAgentTools: [
+        "Read",
+        "Write",
+        "Edit",
+        "Bash",
+        "Grep",
+        "Glob",
+        "WebSearch",
+        "WebFetch",
+        "NotebookEdit",
+        "TodoWrite",
+        "Task",
+        "Skill",
+    ],
+    // Tools the platform never exposes to a subagent, whatever the list says — so
+    // a subagent listing one is a guaranteed-dead reference only a compiler catches.
+    neverAvailableTools: [
+        "Agent",
+        "AskUserQuestion",
+        "EnterPlanMode",
+        "ExitPlanMode",
+        "ScheduleWakeup",
+        "WaitForMcpServers",
+    ],
+    mcpToolPattern: /^mcp__[a-z0-9_-]+__[a-z0-9_-]+$/i,
+    hookEvents: [
+        "PreToolUse",
+        "PostToolUse",
+        "PreSession",
+        "PostSession",
+        "Notification",
+    ],
+    // Claude Code natively reads CLAUDE.md only — it does NOT auto-load AGENTS.md
+    // (anthropics/claude-code#34235 is open; AGENTS.md works solely via an
+    // `@AGENTS.md` import inside CLAUDE.md or a symlink). AGENTS.md is the
+    // cross-tool standard (Codex's native target), not a CC dialect fact; vigiles's
+    // tool-agnostic recognition of it lives in validate.ts's INSTRUCTION_FILES.
+    instructionTargets: ["CLAUDE.md"],
+    pluginRootToken: "${CLAUDE_PLUGIN_ROOT}",
+    // Claude Code reads the full SKILL.md frontmatter set (description,
+    // disable-model-invocation, argument-hint, …).
+    skillFrontmatter: "claude-code",
+};
+//# sourceMappingURL=dialect.js.map

package/dist/adapters/claude-code/egress-entry.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=egress-entry.d.ts.map

package/dist/adapters/claude-code/egress-entry.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * vigiles — the allowlisted-egress orchestrator (in-process subprocess entry).
+ *
+ * `runHook` is synchronous (`spawnSync`), but allowlisted egress needs TWO
+ * processes alive at once: `bwrap` (which creates the netns and runs the hook)
+ * and `slirp4netns` (which, from the PARENT netns, attaches a tap to bwrap's netns
+ * to give it controlled egress). So the parent `spawnSync`s THIS entry, which runs
+ * the concurrent dance and writes a result file the parent reads back — keeping
+ * `runHook` synchronous while the handoff happens here.
+ *
+ * The dance (proven in `research/spikes/sandbox-network-allowlist.sh`):
+ *   1. spawn bwrap with `--info-fd` → learn the sandboxed child's PID;
+ *   2. `slirp4netns --configure --ready-fd N <pid> tap0` → tap up inside the netns;
+ *   3. touch the netready file → the in-sandbox wrapper (blocked on it) proceeds:
+ *      it loads the nft allowlist, runs the hook, then dumps the nft counters to a
+ *      bound file BEFORE exiting (the netns dies with the child, so the read-back
+ *      must happen inside);
+ *   4. capture bwrap's stdout/stderr/exit + the counters → write the result file.
+ *
+ * Run as: `node dist/egress-entry.js <config.json>`. v8-ignored: it spawns real
+ * bwrap + slirp4netns and is exercised only by the bwrap/slirp-gated integration
+ * test; the testable logic (ruleset, counter parse) lives in `src/egress.ts`.
+ */
+/* v8 ignore start */
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Is a binary on PATH? (probe via `--version`; ENOENT sets `.error`.) */
+function hasBinary(name) {
+    return !(0, node_child_process_1.spawnSync)(name, ["--version"], { stdio: "ignore" }).error;
+}
+/** Poll a file until it has content (the info / ready fd targets), or time out. */
+async function waitForFile(path, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            if ((0, node_fs_1.readFileSync)(path, "utf-8").trim().length > 0)
+                return true;
+        }
+        catch {
+            /* not written yet */
+        }
+        await sleep(50);
+    }
+    return false;
+}
+async function main() {
+    const cfg = JSON.parse((0, node_fs_1.readFileSync)(process.argv[2], "utf-8"));
+    // bwrap writes the sandboxed child's PID (init-namespace view) to fd 3.
+    const infoFd = (0, node_fs_1.openSync)(cfg.infoFile, "w");
+    const bwrap = (0, node_child_process_1.spawn)("bwrap", cfg.bwrapArgv, {
+        stdio: ["ignore", "pipe", "pipe", infoFd],
+    });
+    (0, node_fs_1.closeSync)(infoFd);
+    let stdout = "";
+    let stderr = "";
+    bwrap.stdout?.on("data", (d) => (stdout += d.toString()));
+    bwrap.stderr?.on("data", (d) => (stderr += d.toString()));
+    let connector;
+    const timer = setTimeout(() => bwrap.kill("SIGKILL"), cfg.timeoutMs);
+    const exit = new Promise((resolve) => {
+        bwrap.on("close", (status, signal) => {
+            resolve({ status, signal });
+        });
+    });
+    // Learn the child PID, attach a rootless egress connector to its netns, release
+    // the wrapper. Prefer pasta (passt): it routes on hosted runners where
+    // slirp4netns's tap-attach silently fails (the netns ends up with only `lo`).
+    // Fall back to slirp4netns where pasta isn't installed. nft (the allowlist wall)
+    // matches on destination, not interface name, so it's connector-agnostic. See
+    // research/egress-sandbox-tooling.md.
+    if (await waitForFile(cfg.infoFile, 5_000)) {
+        const info = (0, node_fs_1.readFileSync)(cfg.infoFile, "utf-8");
+        const m = /"child-pid":\s*(\d+)/.exec(info);
+        if (m) {
+            if (cfg.connector === "pasta" && hasBinary("pasta")) {
+                // pasta configures the netns then forks to background; no ready-fd, so
+                // give it a moment to bring the interface + routes up. (Experimental:
+                // pasta's attach-to-existing-netns path is fragile in nested-namespace
+                // sandboxes — see research/egress-sandbox-tooling.md. The connector
+                // defaults to slirp4netns; both need /dev/net/tun + privilege, which is
+                // why the e2e CI job runs privileged.)
+                connector = (0, node_child_process_1.spawn)("pasta", [...cfg.pastaArgs, m[1]], {
+                    stdio: "ignore",
+                });
+                await sleep(800);
+            }
+            else {
+                const readyFd = (0, node_fs_1.openSync)(cfg.readyFile, "w");
+                connector = (0, node_child_process_1.spawn)("slirp4netns", [...cfg.slirpArgs, "--ready-fd", "4", m[1], "tap0"], { stdio: ["ignore", "ignore", "ignore", "ignore", readyFd] });
+                (0, node_fs_1.closeSync)(readyFd);
+                // slirp writes "1" to the ready fd once tap0 is configured; fall back to a
+                // short sleep if it never signals (older builds).
+                if (!(await waitForFile(cfg.readyFile, 4_000)))
+                    await sleep(800);
+            }
+        }
+    }
+    (0, node_fs_1.writeFileSync)(cfg.netreadyFile, "1");
+    const { status, signal } = await exit;
+    clearTimeout(timer);
+    connector?.kill("SIGKILL");
+    const counters = (0, node_fs_1.existsSync)(cfg.countersFile)
+        ? (0, node_fs_1.readFileSync)(cfg.countersFile, "utf-8")
+        : "";
+    (0, node_fs_1.writeFileSync)(cfg.resultFile, JSON.stringify({ status, signal, stdout, stderr, counters }));
+}
+main().catch((e) => {
+    (0, node_fs_1.writeFileSync)(process.argv[2] + ".error", e instanceof Error ? (e.stack ?? e.message) : String(e));
+    process.exit(1);
+});
+/* v8 ignore stop */
+//# sourceMappingURL=egress-entry.js.map

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

@@ -0,0 +1,114 @@
+import { type EgressAttempt } from "./sandbox.js";
+/** A host plus the IPs it resolved to, split by family (nft needs them apart). */
+export interface ResolvedHost {
+    readonly host: string;
+    readonly v4: readonly string[];
+    readonly v6: readonly string[];
+}
+/** Per-host and aggregate nftables counters read back after a confined run. */
+export interface EgressCounters {
+    /** Allowlisted hosts that saw traffic, with the nft counter for each. */
+    readonly allowed: readonly {
+        readonly host: string;
+        readonly packets: number;
+        readonly bytes: number;
+    }[];
+    /** The catch-all drop rule: traffic to anything OFF the allowlist. */
+    readonly dropped: {
+        readonly packets: number;
+        readonly bytes: number;
+    };
+}
+/**
+ * Whether this host can run the allowlisted-egress sandbox: it needs the same
+ * bubblewrap confinement the other tiers use PLUS `slirp4netns` (the rootless
+ * gateway) and `nft` (the packet-layer allowlist). Cached — the answer can't
+ * change within a run. `available` is injected so the bwrap probe isn't repeated.
+ */
+export declare function probeEgressAvailable(available: boolean): boolean;
+/** Cached {@link probeEgressAvailable}. `available` = the bwrap-sandbox probe. */
+export declare function egressAvailable(available: boolean): boolean;
+/**
+ * Parse `getent ahosts <host>` output into the unique IPs, split by family. The
+ * first whitespace token of each line is an address; `:` marks IPv6. Pure, so the
+ * resolution-parsing is unit-tested without touching DNS.
+ */
+export declare function parseGetent(stdout: string): {
+    v4: string[];
+    v6: string[];
+};
+/**
+ * Resolve every allowlisted host to IPs. The lookup is injectable so the
+ * empty-result / family-split behaviour is unit-tested with a fake resolver.
+ */
+export declare function resolveAllow(hosts: readonly string[], lookup?: (host: string) => {
+    v4: string[];
+    v6: string[];
+}): ResolvedHost[];
+/**
+ * Nameservers usable from INSIDE the egress netns. Parses a resolv.conf body but
+ * drops loopback stubs (see {@link isLoopbackResolver}) — they can't be reached
+ * across the namespace — and falls back to a public resolver (8.8.8.8, which
+ * slirp4netns NATs out) when nothing routable remains.
+ */
+export declare function parseResolvers(resolvConf: string): string[];
+/**
+ * Build the nftables ruleset that enforces the allowlist INSIDE the netns: a
+ * `policy drop` output chain that accepts loopback, established replies, DNS to
+ * the resolvers, and each allowlisted host's resolved IPs (a per-host `counter` +
+ * `comment "allow:<host>"` so the read-back maps traffic to a name), then a
+ * catch-all `log`+`counter`+`drop`. v4 and v6 are separate rules (an `inet` set
+ * can't mix families) sharing the host's comment. Pure → the ruleset is asserted
+ * in a unit test.
+ */
+export declare function buildEgressNft(opts: {
+    allow: readonly ResolvedHost[];
+    resolvers: readonly string[];
+}): string;
+/** The bound paths the in-netns wrapper and the orchestrator hand back through. */
+export interface EgressFiles {
+    readonly ioDir: string;
+    readonly netready: string;
+    readonly nft: string;
+    readonly event: string;
+    readonly counters: string;
+}
+/**
+ * Assemble the full bwrap argv for an allowlisted-egress run: the shared
+ * confinement args, the hook's added-back env, `CAP_NET_ADMIN` (so the in-netns
+ * wrapper can load nft), `--info-fd 3` (so the orchestrator learns the child PID
+ * to hand slirp4netns), the `VIG_*` paths the wrapper reads, and the trailing
+ * `sh -c <wrapper>`. Pure (the bwrap/setenv args are computed by the caller), so
+ * the assembled shape — caps, info-fd, the VIG_* env, the wrapper payload — is
+ * asserted in a unit test.
+ */
+export declare function buildEgressBwrapArgv(opts: {
+    base: readonly string[];
+    setenv: readonly string[];
+    files: EgressFiles;
+    command: string;
+    wrapper: string;
+    /** Host path to the generated resolv.conf bound over /etc/resolv.conf in-netns,
+     * so the hook resolves via the routable resolvers, not the host's loopback stub. */
+    resolvConf: string;
+}): string[];
+/**
+ * Parse `nft list chain inet vig output` back into per-host allowed counters and
+ * the aggregate drop counter. Sums multiple rules that share a host comment (the
+ * v4 + v6 split). Pure, so the read-back is unit-tested without a sandbox.
+ */
+export declare function parseNftCounters(nftText: string): EgressCounters;
+/**
+ * Map parsed counters to the run result: one {@link EgressAttempt} per
+ * allowlisted host that saw traffic (`allowed: true`, with its packet/byte
+ * counts), plus the aggregate dropped counter. `ts` is stamped once per run (the
+ * counters are end-of-run totals, not per-connection events). Pure.
+ */
+export declare function countersToResult(counters: EgressCounters, now: number): {
+    egress: EgressAttempt[];
+    egressDropped: {
+        packets: number;
+        bytes: number;
+    };
+};
+//# sourceMappingURL=egress.d.ts.map