@henols/vice-mcp 0.1.4

package/resources/broker-state.mjs

@@ -0,0 +1,173 @@
+// GENERATED FILE -- DO NOT EDIT.
+// Compiled by `tsc` from broker-state.mts. Edit the TypeScript source and rebuild;
+// changes made directly to this file are silently overwritten by the next build, and are never
+// deployed to the host on their own -- install-resources.mjs copies THIS file's on-disk contents
+// verbatim to tools/, so an edit made only here reaches the host but is lost on the very next
+// rebuild.
+import { createServer } from "node:net";
+export function createBrokerState() {
+    return { instances: new Map(), grants: new Map(), blockedPorts: new Set() };
+}
+/** Deep, plain-object copy of `state` for tests -- a real, typed, named
+ * export imported directly by test files, modelled on build.ts's own
+ * exported build(). Never a global, never a subprocess-and-inspect round
+ * trip. */
+export function _snapshotState(state) {
+    return {
+        instances: Array.from(state.instances.values()).map((r) => ({ ...r, viceArgs: [...r.viceArgs] })),
+        grants: Array.from(state.grants.values()).map((g) => ({ ...g })),
+        blockedPorts: Array.from(state.blockedPorts).sort((a, b) => a - b),
+    };
+}
+/** VICE_BROKER_BASE_PORT's default (D-18): the broker's port band moves
+ * from 6510 to 6600 in this phase -- 6510-6599 stays reserved by convention
+ * for an x64sc a human launches for their own work. */
+export const DEFAULT_BASE_PORT = 6600;
+/** Scan ceiling matching vice-broker.sh's own next_free_port(): exactly one
+ * hundred candidates starting at (and including) the base port. Bounded so
+ * an exhausted host produces one explicit `no_free_port` result rather than
+ * an unbounded scan. */
+const PORT_SCAN_CEILING = 100;
+/** Exported (plan 05): vice-broker.mts's host_state control-plane response
+ * and broker.json's own `base_port` field both need the SAME resolved base
+ * port this allocator itself uses -- reading it here rather than
+ * re-duplicating the env-var lookup a third time keeps the two values
+ * structurally unable to disagree. */
+export function resolveBasePort() {
+    const raw = process.env.VICE_BROKER_BASE_PORT;
+    if (raw === undefined || raw === "")
+        return DEFAULT_BASE_PORT;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : DEFAULT_BASE_PORT;
+}
+/** Real default: attempts to bind the candidate port on 127.0.0.1 and
+ * immediately releases it. Answers ONLY "is a TCP listener already bound
+ * here" -- the exact question vice-broker.sh's own /dev/tcp-based
+ * port_in_use() asked, and deliberately never reused as a readiness check
+ * (see broker-launch.mts's probeReady() header comment for why those two
+ * questions are never conflated: a C64 can accept a connection before it
+ * has finished booting). EADDRINUSE means genuinely in use; any other
+ * listen error is treated as "not in use" -- cheaper and clearer than
+ * letting a launch fail later for an unrelated reason. */
+export function defaultPortInUse(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", (err) => {
+            resolve(err.code === "EADDRINUSE");
+        });
+        server.once("listening", () => {
+            server.close(() => resolve(false));
+        });
+        server.listen(port, "127.0.0.1");
+    });
+}
+export function isPortBlocked(state, port) {
+    return state.blockedPorts.has(port);
+}
+/** Remembers a refused port for the lifetime of THIS broker process only --
+ * never persisted. A port refused now may be free after the next reboot;
+ * persisting the refusal would silently shrink the allocation band
+ * forever. Idempotent: blocking an already-blocked port is a no-op. */
+export function blockPort(state, port) {
+    state.blockedPorts.add(port);
+}
+/** Allocates the lowest free port at or above the base port (default 6600
+ * per D-18, overridable via VICE_BROKER_BASE_PORT -- the same env var name
+ * the bash daemon used), scanning up to PORT_SCAN_CEILING candidates.
+ * "Free" means: not already recorded in the instance map (granted,
+ * launching or ready all occupy their port), not already in the
+ * process-scoped blocked set, and not reported in use by the injectable
+ * port-in-use probe (defaulting to defaultPortInUse's real bind-and-release
+ * check). A candidate the probe reports as in use is added to the blocked
+ * set before scanning continues, so it is never re-offered or re-probed by
+ * this process again. Never throws -- returns a typed failure naming
+ * exhaustion when every candidate in the window is taken. */
+// Gap closure (plan 14, discovered live during Task 2's own end-to-end
+// proof -- see RE-FINDINGS.md's dated entry for the full account):
+// EADDRINUSE is delivered to defaultPortInUse()'s `error` listener without
+// ever yielding to libuv's poll phase, so a scan running against MANY
+// already-bound candidates in a row does not merely take longer -- for its
+// ENTIRE duration, the control listener cannot accept a new connection or
+// read data already sitting on an existing one (verified live: a second,
+// already-established connection's own request was not read by this
+// process until the ENTIRE scan, spawn and record sequence had already
+// resolved, confirmed with the real production functions in isolation
+// before this fix). That is a real liveness gap independent of this
+// plan's own test -- a release, a recycle or a status request over an
+// UNRELATED connection would be held up for as long as a contended scan
+// takes, not merely a competing acquire. Yielding via setImmediate every
+// few candidates restores that liveness at negligible cost (the scan
+// itself already costs one real bind-and-release round trip per
+// candidate; this adds one cheap timer-phase turn every YIELD_EVERY of
+// them) without changing what this function returns for any input.
+const YIELD_EVERY_N_CANDIDATES = 5;
+export async function nextFreePort(state, opts = {}) {
+    const basePort = opts.basePort ?? resolveBasePort();
+    const portInUse = opts.portInUse ?? defaultPortInUse;
+    const limit = basePort + PORT_SCAN_CEILING;
+    let checked = 0;
+    for (let port = basePort; port < limit; port++) {
+        if (state.instances.has(port))
+            continue;
+        if (isPortBlocked(state, port))
+            continue;
+        if (await portInUse(port)) {
+            blockPort(state, port);
+            checked++;
+            if (checked % YIELD_EVERY_N_CANDIDATES === 0) {
+                await new Promise((resolvePromise) => setImmediate(resolvePromise));
+            }
+            continue;
+        }
+        return { ok: true, port };
+    }
+    return { ok: false, reason: "no_free_port" };
+}
+/** Counts ready, unclaimed instances -- filters the SAME in-memory map every
+ * other count reads, no filesystem access anywhere in this expression. */
+export function countReady(state) {
+    let n = 0;
+    for (const record of state.instances.values()) {
+        if (record.state === "ready")
+            n++;
+    }
+    return n;
+}
+/** Counts every launched instance regardless of state (launching, ready or
+ * granted) -- the denominator of the total <= VICE_BROKER_MAX ceiling. */
+export function countTotal(state) {
+    return state.instances.size;
+}
+/** Counts instances currently "launching" -- THE single counter both launch
+ * paths (a cold acquire, via handleAcquire in vice-broker.mts, and warm
+ * floor maintenance, via maintainWarmFloor in broker-launch.mts) consult
+ * before starting a new launch. Two counters that could ever disagree about
+ * whether a boot is already under way is exactly how the two bash launch
+ * paths raced each other into the 2026-08-01 outage (three simultaneous
+ * x64sc launches: one SEGV, one exit 1, one exit 0 at the identical spawn
+ * second) -- there is now exactly one, read here and nowhere else. */
+export function countLaunching(state) {
+    let n = 0;
+    for (const record of state.instances.values()) {
+        if (record.state === "launching")
+            n++;
+    }
+    return n;
+}
+function resolveCeiling(override) {
+    if (typeof override === "number")
+        return override;
+    const raw = process.env.VICE_BROKER_MAX;
+    if (raw === undefined || raw === "")
+        return 16;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : 16;
+}
+/** True once countTotal() has reached the configured instance ceiling
+ * (VICE_BROKER_MAX, default 16, untouched by this phase). A cold acquire
+ * consults this BEFORE attempting to allocate a port or spawn (plan 05's
+ * control-plane `at_capacity` error code), so an at-capacity host answers
+ * without ever touching the port allocator. */
+export function atCapacity(state, ceiling) {
+    return countTotal(state) >= resolveCeiling(ceiling);
+}

package/resources/container-guard.mjs

@@ -0,0 +1,211 @@
+// GENERATED FILE -- DO NOT EDIT.
+// Compiled by `tsc` from container-guard.mts. Edit the TypeScript source and rebuild;
+// changes made directly to this file are silently overwritten by the next build, and are never
+// deployed to the host on their own -- install-resources.mjs copies THIS file's on-disk contents
+// verbatim to tools/, so an edit made only here reaches the host but is lost on the very next
+// rebuild.
+// container-guard.mts
+//
+// PD-03: TypeScript port of resources/lib/container-guard.sh's five
+// container-detection signals, checked at broker PROCESS STARTUP -- not
+// only at vice-launcher.sh's shell wrapper. This closes the
+// invocation-scoped hole recorded in RE-FINDINGS.md (2026-08-03): running
+// the compiled broker directly (bypassing the launcher) was previously
+// unguarded, since the bash guard only ever ran inside the scripts that
+// sourced it.
+//
+// Every dependency this needs (filesystem existence/reads, the environment,
+// a subprocess runner for systemd-detect-virt) is injected with real
+// defaults, so every signal is exercised in a test without a real
+// /proc/1/cgroup or a real systemd-detect-virt binary on the machine
+// running the test.
+import { existsSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+const defaultDeps = {
+    fileExists: (path) => existsSync(path),
+    readFile: (path) => readFileSync(path, "utf8"),
+    env: process.env,
+    runSystemdDetectVirt: () => {
+        try {
+            return execFileSync("systemd-detect-virt", ["--container"], { encoding: "utf8" }).trim();
+        }
+        catch {
+            return null;
+        }
+    },
+};
+/** Matches container-guard.sh's own awk cgroup matcher: the field after the
+ * LAST colon on any /proc/1/cgroup line, tested against a container-naming
+ * path component. Deliberately does NOT match a systemd host's
+ * `0::/init.scope`, a bare root cgroup, or the Docker daemon's own
+ * `/system.slice/docker.service` cgroup -- only `/docker/<id>`,
+ * `/system.slice/docker-<id>.scope`, `/kubepods/...`, `/libpod-...` and
+ * `/lxc/...` match. */
+function cgroupNamesContainer(cgroupText) {
+    const CONTAINER_PATH = /(^|\/)(docker|lxc|kubepods|libpod)(\/|-|$)/;
+    for (const line of cgroupText.split("\n")) {
+        const idx = line.lastIndexOf(":");
+        if (idx === -1)
+            continue;
+        const path = line.slice(idx + 1);
+        if (CONTAINER_PATH.test(path))
+            return line;
+    }
+    return null;
+}
+/** Evaluates all five signals and returns one ContainerSignal per signal
+ * (fired or not, with its evidence) -- the same two-array shape
+ * container_guard_evaluate() builds (CONTAINER_SIGNALS/CONTAINER_REPORT),
+ * as one typed return value.
+ *
+ * REMOVED, DO NOT RE-ADD: a `grep docker /proc/self/mountinfo` signal used
+ * to exist here (ported from the bash guard's own header). It answers "is
+ * Docker installed on this machine", not "is THIS process inside a
+ * container" -- it fires on the real host (which runs the devcontainer
+ * daemon) and refuses to launch on exactly the machine this guard exists to
+ * allow. Not fixable by tightening the pattern; the signal itself is
+ * invalid. It is gone in the bash version and must not come back here
+ * either. */
+export function evaluateContainerSignals(deps = defaultDeps) {
+    const signals = [];
+    signals.push({
+        description: "/.dockerenv exists",
+        fired: deps.fileExists("/.dockerenv"),
+        evidence: "",
+    });
+    signals.push({
+        description: "/run/.containerenv exists (podman)",
+        fired: deps.fileExists("/run/.containerenv"),
+        evidence: "",
+    });
+    const workspacePath = deps.env.CONTAINER_WORKSPACE_PATH;
+    signals.push({
+        description: "CONTAINER_WORKSPACE_PATH is set (this devcontainer sets it)",
+        fired: Boolean(workspacePath),
+        evidence: workspacePath ?? "",
+    });
+    const detectedVirt = deps.runSystemdDetectVirt();
+    const virtFired = detectedVirt !== null && detectedVirt !== "" && detectedVirt !== "none";
+    signals.push({
+        description: "systemd-detect-virt --container",
+        fired: virtFired,
+        evidence: detectedVirt === null ? "binary not present, signal skipped" : `reports: ${detectedVirt || "none"}`,
+    });
+    let cgroupMatch = null;
+    if (deps.fileExists("/proc/1/cgroup")) {
+        try {
+            cgroupMatch = cgroupNamesContainer(deps.readFile("/proc/1/cgroup"));
+        }
+        catch {
+            cgroupMatch = null;
+        }
+    }
+    signals.push({
+        description: "/proc/1/cgroup path names a container",
+        fired: cgroupMatch !== null,
+        evidence: cgroupMatch ?? "no container path component in PID 1's cgroup",
+    });
+    return signals;
+}
+/** Prints one report line per signal to stderr and returns 3 in a container
+ * (>=1 signal fired), 0 on a host (none fired) -- mirrors
+ * container_guard_report()'s exit-code contract exactly. Never calls
+ * process.exit() itself (D-4 discipline this module tree observes
+ * throughout): the caller (vice-broker.mts's CLI wrapper) turns the
+ * returned code into process.exitCode. */
+export function containerGuardReport(deps = defaultDeps) {
+    const signals = evaluateContainerSignals(deps);
+    process.stderr.write("vice-broker: container guard evaluation\n");
+    for (const s of signals) {
+        if (s.fired) {
+            process.stderr.write(`  [FIRED] ${s.description}${s.evidence ? ` -- evidence: ${s.evidence}` : ""}\n`);
+        }
+        else {
+            process.stderr.write(`  [clear] ${s.description}${s.evidence ? ` (${s.evidence})` : ""}\n`);
+        }
+    }
+    const fired = signals.filter((s) => s.fired);
+    if (fired.length > 0) {
+        process.stderr.write(`verdict: CONTAINER (${fired.length} signal(s) fired) -- the guard would refuse here.\n`);
+        return 3;
+    }
+    process.stderr.write("verdict: HOST (no signals fired) -- the guard would allow x64sc to launch here.\n");
+    return 0;
+}
+/** Evaluates the guard and, if any signal fired, writes a FATAL block naming
+ * every fired signal and returns 2 -- UNLESS VICE_SUPERVISOR_ALLOW_CONTAINER
+ * is EXACTLY "1" (testing only; never set it to actually run VICE). On a
+ * clear host verdict, returns 0 and writes nothing. Mirrors
+ * container_guard_enforce()'s escape hatch, wording and exit-code contract
+ * verbatim -- never calls process.exit() itself, matching
+ * containerGuardReport()'s own posture above. */
+export function containerGuardEnforce(deps = defaultDeps) {
+    const signals = evaluateContainerSignals(deps);
+    const fired = signals.filter((s) => s.fired);
+    if (fired.length > 0 && deps.env.VICE_SUPERVISOR_ALLOW_CONTAINER !== "1") {
+        process.stderr.write("FATAL: vice-broker refuses to run inside a container.\n");
+        process.stderr.write("This process is HOST-ONLY. Signals that fired:\n");
+        for (const s of fired) {
+            process.stderr.write(`  - ${s.description}${s.evidence ? ` -- ${s.evidence}` : ""}\n`);
+        }
+        process.stderr.write("\n");
+        process.stderr.write("If you believe this IS the host, run --check-container for the full\n");
+        process.stderr.write("per-signal breakdown and report which signal is wrong.\n");
+        process.stderr.write("\n");
+        process.stderr.write("This cannot work in here: there is no x64sc binary, no display, and\n");
+        process.stderr.write("the entire point of this process is to launch or supervise a process\n");
+        process.stderr.write("the container has no access to in the first place.\n");
+        process.stderr.write("\n");
+        process.stderr.write("Escape hatch (TESTING ONLY -- never to actually run VICE):\n");
+        process.stderr.write("  VICE_SUPERVISOR_ALLOW_CONTAINER=1\n");
+        process.stderr.write("\n");
+        process.stderr.write("Run this broker on the HOST instead, from the host workspace.\n");
+        return 2;
+    }
+    return 0;
+}
+// -------------------------------------------------- environment predicate
+//
+// containerGuardReport()/containerGuardEnforce() above answer "should this
+// process REFUSE to run here". This answers the different question "which
+// environment am I in", for callers that must CHOOSE behaviour rather than
+// refuse -- specifically vice.ts's mcpHost(), which has to return the
+// container-visible bridge alias inside a container and a loopback address
+// on a host, because `host.docker.internal` is a Docker-provided alias that
+// does not resolve on the host at all.
+//
+// It shares this module's detection deliberately rather than growing a
+// second, weaker copy. That is the exact mistake this file's own header
+// records for the REMOVED /proc/self/mountinfo signal: an independent
+// "looks dockery" heuristic fired on the real host -- the machine running
+// the devcontainer daemon -- and so answered the wrong question. Any new
+// detector would risk re-earning that bug; this one is already calibrated
+// against precisely the host-versus-container distinction being asked here.
+//
+// The verdict rule is not invented here: it is the one containerGuardReport()
+// and containerGuardEnforce() both state -- >=1 signal fired means CONTAINER,
+// none fired means HOST.
+/** Memoised verdict for the default-deps path only. */
+let cachedDefaultVerdict = null;
+/** True inside a container, false on a host.
+ *
+ * MEMOISED on the default-deps path, deliberately: one of the five signals
+ * shells out to `systemd-detect-virt`, and mcpHost() is read fresh on EVERY
+ * forwarded tool call -- spawning a subprocess per call would be a real cost
+ * for an answer that cannot change. Container membership is fixed for a
+ * process lifetime, so caching the verdict is safe. Note what is NOT cached:
+ * the caller's own env-var read (`VICE_MCP_HOST`) stays fresh, preserving the
+ * override-sensitivity mcpHost()'s comment says a module-level constant would
+ * have silently destroyed.
+ *
+ * Passing explicit deps ALWAYS re-evaluates and never touches the cache, so
+ * tests can drive both branches in-process, in any order, without one test's
+ * verdict leaking into another's. */
+export function isInsideContainer(deps) {
+    if (deps)
+        return evaluateContainerSignals(deps).some((s) => s.fired);
+    if (cachedDefaultVerdict === null) {
+        cachedDefaultVerdict = evaluateContainerSignals(defaultDeps).some((s) => s.fired);
+    }
+    return cachedDefaultVerdict;
+}