@henols/vice-mcp 0.1.4

package/refresh-manifest.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// The ONLY writer of tools-manifest.json (see vice-proxy.mjs's tools/list
+// handler doc comment -- that handler is a pure, offline READ of the file
+// this CLI produces). An operator runs this by hand against a running host
+// to refresh the snapshot; vice-proxy.mjs never imports this file, so this
+// file's stdout is a normal CLI stream, not the MCP channel.
+//
+// Sibling import: the transport module lives in this skill's own scripts/
+// directory (plan 01.1-04 relocated it from the now-retired `vice-session`
+// skill).
+import { serverInfo, activeInstance, type ServerInfoPayload, type ToolInfo } from "./vice.ts";
+import { writeFileSync, chmodSync, renameSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_MANIFEST_PATH = join(HERE, "tools-manifest.json");
+
+function manifestPath(): string {
+  return process.env.VICE_TOOLS_MANIFEST
+    ? resolve(process.env.VICE_TOOLS_MANIFEST)
+    : DEFAULT_MANIFEST_PATH;
+}
+
+export interface ToolsManifest {
+  generated_at: string;
+  endpoint: string;
+  tools: ToolInfo[];
+}
+
+/** Write `manifest` to `path` via the tmp sibling -> restrict-mode -> content
+ * -> rename sequence (01.6.1-06 Decision 1), copied verbatim in shape from
+ * vice-broker.mts's writeBrokerRecord(). The tmp file is created EMPTY and
+ * mode-tightened to 0o600 BEFORE any content reaches it, then renamed into
+ * place -- so a crash or a full disk mid-write can only ever leave a stray
+ * tmp sibling behind, never a partial or empty file at the real path. This
+ * is what makes this module's own long-standing promise ("a partial or
+ * empty manifest is never written over a good one on failure") true against
+ * a crash, not only against a rejected handshake -- the rejected-handshake
+ * half of that guarantee already held (the early return below, unchanged
+ * from the original), but a crash between "open the file" and "write the
+ * content" could previously still truncate a good manifest to nothing. */
+function writeManifestAtomic(path: string, manifest: ToolsManifest): void {
+  const tmpPath = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmpPath, "");
+  chmodSync(tmpPath, 0o600);
+  writeFileSync(tmpPath, JSON.stringify(manifest, null, 2) + "\n");
+  renameSync(tmpPath, path);
+}
+
+/** Parses no arguments (there are none), performs the host handshake, and
+ * writes the manifest -- or leaves the existing one untouched and sets a
+ * non-zero exit code if the handshake fails. Exported (01.6.1-06 Decision 2)
+ * so this can be driven directly in a test without spawning a process; the
+ * bottom-of-module entry-point guard below is what makes that safe -- import
+ * alone must never perform a handshake or write anything. */
+export async function main(): Promise<void> {
+  const path = manifestPath();
+
+  // serverInfo() performs the host handshake (initialize + tools/list) and
+  // already strips DENY_LIST names before returning (vice.ts's own
+  // documented choke point) -- vice-proxy.mjs's tools/list handler applies
+  // the SAME filter again at read time, so a snapshot generated by any other
+  // means is still safe, but this refresh path inherits the omission for
+  // free.
+  let info: ServerInfoPayload;
+  try {
+    info = (await serverInfo()) as ServerInfoPayload;
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    console.error(
+      `refresh-manifest: could not reach the host VICE MCP server (${message}) -- ` +
+        `manifest at ${path} left UNCHANGED. A partial or empty manifest is never written over a good one on ` +
+        `failure -- whether the failure is a rejected handshake (this path) or a crash mid-write, the latter now ` +
+        `also covered by the tmp-sibling -> restrict-mode -> content -> rename sequence below.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const tools = Array.isArray(info?.tools) ? info.tools : [];
+  const manifest: ToolsManifest = {
+    generated_at: new Date().toISOString(),
+    endpoint: activeInstance().url,
+    tools,
+  };
+
+  writeManifestAtomic(path, manifest);
+  console.log(`refresh-manifest: wrote ${tools.length} tool${tools.length === 1 ? "" : "s"} to ${path}`);
+}
+
+// -------------------------------------------------------------------- CLI
+// Guarded exactly like vice-broker.mts's own entry point: importing this
+// module (e.g. from a test) must never itself perform a handshake or write
+// anything. process.exitCode, never process.exit(), so any pending I/O
+// flushes first.
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((e: unknown) => {
+    const detail = e instanceof Error && e.stack ? e.stack : String(e);
+    console.error(`refresh-manifest: unexpected error -- ${detail}`);
+    process.exitCode = 1;
+  });
+}

package/repo-root.ts

@@ -0,0 +1,198 @@
+// The ONE shared place every module in this directory resolves the repo
+// root through (D-2). Everything else in this module tree -- vice.mjs's
+// EPOCH_FILE, vice-broker-client.mjs's brokerRootDir() (and, before their
+// 2026-08-02 deletion, vice-pool.mjs's poolDir() and vice-session.mjs's
+// sessionFilePath()) -- derives its `.vice-supervisor` path through
+// supervisorDir() below, so there is exactly one definition of both "where
+// is the repo root" and "what is the shared state directory called".
+//
+// WHY THIS FILE EXISTS AT ALL: originally, each of the three modules
+// resolved the repo root with a fixed `resolve(dirname(SELF), "..", ...)` --
+// ONE level up from the module's own file. That was correct while the
+// modules lived in `tools/` (one level up from `tools/` IS the repo root),
+// but a move put them THREE levels deeper, at `.claude/skills/vice-session/`'s
+// `scripts/` directory (the original, now-retired home; plan 01.1-04
+// relocated it again, into the `vice-mcp-selector` skill, at the same
+// depth). A naive move that kept the old fixed `".."` would have silently
+// resolved to `.claude/skills/.vice-supervisor` or
+// `.claude/skills/vice-session/.vice-supervisor` instead of
+// `<repo>/.vice-supervisor` -- a directory the host-side shell launcher
+// (`tools/vice-launcher.sh`, plan 11's surviving script -- the paired
+// implementation this era's now-retired `tools/vice-supervisor.sh` and
+// `tools/vice-pool.sh` used to be) never writes to. NOTHING would have
+// errored: the container would just read a permanently-empty
+// epoch/registry/session directory, and restart detection (and the pool,
+// and sessions) would quietly stop working while every command kept
+// "succeeding". That failure mode -- a broken invariant with no error
+// anywhere -- is exactly the class of bug this codebase keeps rejecting
+// elsewhere (see vice.mjs's MachineRestartedError, vice-session.mjs's
+// epoch-continuity guard). Do not reintroduce a fixed `".."` (or any other
+// relative-to-this-file hop count) in place of this resolver; if the
+// directory depth of this module tree ever changes again, the ladder below
+// still gets the right answer without anyone having to count directories by
+// hand.
+//
+// THIRD MOVE (quick-260731-p8a): the implementation relocated again, out of
+// the `vice-mcp-selector` skill's `scripts/` into a new, flattened,
+// non-skill `.claude/mcp/vice/` directory -- ONE level SHALLOWER than the
+// old `.claude/skills/<skill>/scripts/` shape, since flattening removed the
+// `scripts/` segment. Branch 4's hop count below moved from four levels to
+// three to match. Branches 1-3 are depth-independent (an env var check, then
+// a `.git` ancestor walk) and needed no change.
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve, sep } from "node:path";
+
+import { ensureResourcesInstalled } from "./install-resources.ts";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+// Gates the two "last resort" stderr notes below so a long-running process
+// (or a test suite driving this module many times) emits each at most once,
+// rather than spamming stderr on every single call.
+let warnedEnvOutsideFrom = false;
+let warnedNoMarkerFound = false;
+
+/** Options accepted by repoRoot()/supervisorDir(): `from` overrides the
+ * caller location the ladder resolves relative to (defaults to this file's
+ * own location, HERE), and `env` overrides the environment it reads
+ * CONTAINER_WORKSPACE_PATH from (defaults to process.env) -- both exist so
+ * the ladder is deterministically testable without mutating real process
+ * state, per repo-root.test.ts's own injection idiom. */
+export interface RepoRootOptions {
+  from?: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * True iff `child` is `parent` itself or lies inside it, compared as plain
+ * resolved path strings (no filesystem access) -- deliberately not a symlink-
+ * aware realpath comparison, since CONTAINER_WORKSPACE_PATH and this file's
+ * own location are both already resolved, non-symlinked container paths in
+ * every case this project runs in.
+ */
+function isInside(child: string, parent: string): boolean {
+  const c = resolve(child);
+  const p = resolve(parent);
+  return c === p || c.startsWith(p.endsWith(sep) ? p : p + sep);
+}
+
+/**
+ * Resolve the repository root. Precedence, in order (D-2):
+ *
+ *   0. `env.CLAUDE_PROJECT_DIR`, when set -- the authoritative project root
+ *      Claude Code exports for the workspace it is driving. This is the ONLY
+ *      branch that is correct when this module is consumed as an installed
+ *      plugin: the MCP's own files then live under the plugin install dir
+ *      (e.g. `~/.claude/plugins/<marketplace>/<plugin>/.claude/mcp/vice/`),
+ *      NOT inside the project the user is working in, so neither the
+ *      `from`-relative `.git` walk (branch 2, which would find the plugin's
+ *      OWN checkout) nor a CONTAINER_WORKSPACE_PATH containment check
+ *      (branch 1, which fails the containment test) can reach the project
+ *      root. In the in-repo, non-plugin layout this variable is either unset
+ *      (the test injections below, a bare host) or already equal to the repo
+ *      root, so honouring it first is a safe no-op there and the branches
+ *      below are unchanged.
+ *   1. `env.CONTAINER_WORKSPACE_PATH`, when set AND `from` resolves inside
+ *      it -- this devcontainer sets it (`.devcontainer/devcontainer.json`'s
+ *      `containerEnv`, value `/workspaces/bruce_lee`), and it is the most
+ *      explicit signal available.
+ *   2. Otherwise, walk up from `from` toward the filesystem root, returning
+ *      the first directory containing a `.git` entry (`existsSync` on the
+ *      joined path -- matches both a real `.git` directory and a worktree's
+ *      `.git` file). This is what keeps the skill correct once exported into
+ *      a project that sets no such variable at all.
+ *   3. Otherwise, `env.CONTAINER_WORKSPACE_PATH` if it is set at all (just
+ *      not containing `from` -- an exported copy of this skill living
+ *      outside the mounted workspace the variable names). Silence here would
+ *      be exactly the quiet-wrong-answer failure class this file exists to
+ *      prevent, so this path emits a one-time stderr note naming both paths.
+ *   4. Otherwise, three levels up from `from`, with a one-time stderr note.
+ *      Last resort only -- three levels is what `<root>/.claude/mcp/<server>/`
+ *      implies. In this repo branch 4 never actually runs (there is always a
+ *      `.git` ancestor), which is exactly why the paired synthetic test in
+ *      repo-root.test.ts is the only thing that would catch a wrong hop
+ *      count here.
+ */
+export function repoRoot({ from = HERE, env = process.env }: RepoRootOptions = {}): string {
+  // Branch 0 (plugin-consumption signal): Claude Code sets CLAUDE_PROJECT_DIR
+  // to the root of the workspace it is driving. When this module runs as an
+  // installed plugin its own files sit outside that workspace, so this is the
+  // only signal that points at the user's project rather than the plugin's
+  // install dir. Unset / equal-to-root in the in-repo layout, so it is a
+  // no-op there.
+  const projectDir = env.CLAUDE_PROJECT_DIR;
+  if (projectDir) {
+    return resolve(projectDir);
+  }
+
+  const cwp = env.CONTAINER_WORKSPACE_PATH;
+
+  if (cwp && isInside(from, cwp)) {
+    return resolve(cwp);
+  }
+
+  let dir = resolve(from);
+  while (true) {
+    if (existsSync(join(dir, ".git"))) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break; // reached the filesystem root -- no .git found anywhere above `from`
+    dir = parent;
+  }
+
+  if (cwp) {
+    if (!warnedEnvOutsideFrom) {
+      warnedEnvOutsideFrom = true;
+      console.error(
+        `warn: CONTAINER_WORKSPACE_PATH is set (${cwp}) but does not contain ${from}, and no .git ` +
+          `ancestor was found either -- falling back to CONTAINER_WORKSPACE_PATH itself as the repo root. ` +
+          `This is expected for an exported copy of this skill living outside its mounted workspace; if ` +
+          `that is not the situation here, the repo root this resolved to may be wrong.`
+      );
+    }
+    return resolve(cwp);
+  }
+
+  if (!warnedNoMarkerFound) {
+    warnedNoMarkerFound = true;
+    const fallback = resolve(from, "..", "..", "..");
+    console.error(
+      `warn: could not find a .git ancestor above ${from} and CONTAINER_WORKSPACE_PATH is not set -- ` +
+        `falling back to three levels up (${fallback}), the shape <root>/.claude/mcp/<server>/ implies. ` +
+        `This is a last resort; if it's wrong, set CONTAINER_WORKSPACE_PATH or run from inside a git repo.`
+    );
+  }
+  return resolve(from, "..", "..", "..");
+}
+
+/** The one shared directory name every module in this skill reads/writes
+ * host-synchronised state through -- `join(repoRoot(...), ".vice-supervisor")`,
+ * so the literal directory name also has exactly one definition. */
+export function supervisorDir(opts: RepoRootOptions = {}): string {
+  return join(repoRoot(opts), ".vice-supervisor");
+}
+
+// Fires once per process, on whatever entry point happens to import THIS
+// module -- which is vice.mjs and vice-broker-client.mjs already (both
+// import repoRoot()/supervisorDir()), among other modules in this tree,
+// plus vice-probe.ts's own side-effect-only import (see that file). This
+// one call is what makes the
+// deploy-on-first-use check (quick-260730-q4b, D-3) fire for every skill
+// .mjs entry point without any of them referencing install-resources.ts
+// directly.
+//
+// POSITION IS LOAD-BEARING: this must run at the BOTTOM of this module body,
+// after HERE, repoRoot() and supervisorDir() are all initialised. Moving it
+// above HERE's initialisation reintroduces the exact module-cycle TDZ crash
+// install-resources.ts's own header describes ("Cannot access 'HERE' before
+// initialization") -- install-resources.ts takes the repo root as an
+// argument specifically so it never needs to import this file back.
+try {
+  ensureResourcesInstalled({ root: repoRoot() });
+} catch {
+  // ensureResourcesInstalled() already never throws (D-3) -- this catch is
+  // belt-and-suspenders against a future change to that contract, not a
+  // signal that one is expected.
+}

package/resources/broker-control.mjs

@@ -0,0 +1,343 @@
+// GENERATED FILE -- DO NOT EDIT.
+// Compiled by `tsc` from broker-control.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.
+// broker-control.mts
+//
+// N / D-01 (plan 01, tracer): the framing, the token gate, and acquire/
+// release. THIS PLAN (05) completes the message set: recycle, status,
+// host_state, the arrival-ordered pending-acquire structure, and the
+// kernel-enforced singleton guard's low-level bind primitive. The
+// subsystem's FIRST network listener: a TCP control plane replacing the
+// bash broker's requests/grants/denials/leases directory tree entirely. One
+// JSON object per line; the connection open IS the claim, connection close
+// IS the release (T-01.6.2-01 through -09).
+//
+// Wire format confirmed at plan 01's blocking checkpoint:decision
+// (2026-08-03, `as-specified`, no amendments -- see .planning/RE-FINDINGS.md
+// for the full record, including the two accepted residual risks and the
+// unix-domain-socket dead end). Auth: per-boot capability token compared
+// constant-time, checked BEFORE any state read or write. Bind: 0.0.0.0
+// explicitly, never 127.0.0.1 -- host.docker.internal is the bridge
+// address, not loopback, so a loopback-only listener is structurally
+// unreachable from the container. Port: 19510 default via
+// VICE_BROKER_CONTROL_PORT.
+import { createServer } from "node:net";
+import { timingSafeEqual, randomBytes } from "node:crypto";
+/** 32 cryptographically random bytes rendered as hex -- the per-boot
+ * capability token. Held in memory only by the caller; written once into
+ * broker.json and never logged, never included in an error message
+ * (T-01.6.2-02). */
+export function newControlToken() {
+    return randomBytes(32).toString("hex");
+}
+const MAX_LINE_BYTES = 65536;
+export function resolveControlPort(override) {
+    if (typeof override === "number")
+        return override;
+    const raw = process.env.VICE_BROKER_CONTROL_PORT;
+    if (raw === undefined || raw === "")
+        return 19510;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : 19510;
+}
+/** Constant-time token comparison over EQUAL-LENGTH buffers -- an
+ * unequal-length comparison is refused without ever calling
+ * timingSafeEqual (which throws on a length mismatch), so the length check
+ * itself leaks nothing beyond what a fixed-length comparison already
+ * would not avoid. */
+function tokensMatch(candidate, expected) {
+    const a = Buffer.from(candidate, "utf8");
+    const b = Buffer.from(expected, "utf8");
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+function writeLine(socket, obj) {
+    if (socket.writable) {
+        socket.write(`${JSON.stringify(obj)}\n`);
+    }
+}
+function defaultRequestId(prefix) {
+    return `${prefix}-${process.pid}-${Date.now()}`;
+}
+/** Appends to the BACK of the queue -- the only mutation this structure
+ * ever performs on receipt. Nothing here sorts or re-orders; arrival order
+ * falls out of the array's own insertion order. */
+export function enqueueAcquire(queue, entry) {
+    queue.push(entry);
+}
+/** Drains the queue from the front, strictly in the order this CALL found
+ * them: takes a snapshot of everything currently pending (`splice`, never a
+ * sort), then attempts each in that order. An entry whose launch is still
+ * in flight is pushed back onto the queue for the NEXT drain pass rather
+ * than retried immediately in a tight loop -- a later-arriving acquire that
+ * queued behind it during THIS pass is not overtaken (it is appended after
+ * the requeued entry, never before), so the array never needs re-ordering
+ * to stay correct; a genuinely adversarial retry pattern could still starve
+ * an entry across MULTIPLE passes, which is exactly the direct fairness
+ * proof this module deliberately does not author -- injecting N acquires
+ * and asserting grants return in that order is Phase 01.6.2.1's D-08
+ * deliverable. The original defect this queue replaces (a lexical iteration
+ * over `req-<pid>-<ms>-<hex>` filenames) cannot exist here regardless: there
+ * is no file, and no re-ordering call of any kind anywhere in this region. */
+export async function drainPendingAcquires(queue) {
+    const snapshot = queue.splice(0, queue.length);
+    for (const entry of snapshot) {
+        const settled = await entry.attempt();
+        if (!settled) {
+            queue.push(entry);
+        }
+    }
+}
+/** Binds a bare TCP listener with NO protocol wired up -- no token check, no
+ * request handling, nothing. `startControlListener()` below calls this
+ * internally and then attaches the real protocol; a test wanting to occupy
+ * a control port with "something that is not a broker" (the loud singleton
+ * path's own fixture) can call this directly and never see anything that
+ * looks like this broker's wire format. */
+export function bindControlListener(host, port) {
+    return new Promise((resolvePromise, reject) => {
+        const server = createServer();
+        server.on("error", reject);
+        server.listen(port, host, () => {
+            const addr = server.address();
+            const boundPort = typeof addr === "object" && addr !== null ? addr.port : port;
+            resolvePromise({ server, port: boundPort, host });
+        });
+    });
+}
+/** Attaches the newline-delimited-JSON protocol (framing, token gate, all
+ * five request kinds) to an ALREADY-BOUND server. Split out of
+ * startControlListener() so the bind step and the protocol-wiring step are
+ * two separately callable primitives -- the real broker still calls
+ * startControlListener() as one step (this function is not part of its own
+ * public surface); this module's own tests exercise the two independently. */
+function attachControlProtocol(server, opts, pendingAcquires) {
+    server.on("connection", (socket) => {
+        let buffer = "";
+        let requestIdForThisConnection = null;
+        socket.on("data", (chunk) => {
+            buffer += chunk.toString("utf8");
+            if (Buffer.byteLength(buffer, "utf8") > MAX_LINE_BYTES) {
+                socket.destroy();
+                return;
+            }
+            let newlineIdx;
+            while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+                const line = buffer.slice(0, newlineIdx);
+                buffer = buffer.slice(newlineIdx + 1);
+                handleLine(line);
+            }
+        });
+        socket.on("close", () => {
+            // Connection close IS the release -- including on the client's own
+            // SIGKILL, since "close" always fires either way. Idempotent: an
+            // explicit `release` already having cleared
+            // requestIdForThisConnection makes this a no-op.
+            if (requestIdForThisConnection) {
+                const id = requestIdForThisConnection;
+                requestIdForThisConnection = null;
+                opts.onRelease(id);
+            }
+        });
+        socket.on("error", () => {
+            // Per-connection error handling isolates one peer's failure from
+            // every other connection and from the server itself (T-01.6.2-06).
+        });
+        /** Attempts one acquire over THIS connection/socket, writing the
+         * terminal response (grant or a non-queueing error) when settled, or
+         * enqueueing itself and returning unsettled when a launch is already in
+         * flight. Shared by the immediate first attempt and every later retry
+         * `drainPendingAcquires()` drives, so the two paths can never answer
+         * differently for the same requestId.
+         *
+         * Gap closure (plan 14, WR-03/T-01.6.2-87/-88): two destroyed-socket
+         * checks guard a grant against outliving the connection that owns it,
+         * and they bound TWO DIFFERENT failures -- do not conflate them into one
+         * claim.
+         *
+         * Half one -- the pre-check immediately below, BEFORE onAcquire() is
+         * ever called -- closes the ALWAYS-REACHABLE leak: a client that
+         * disconnects while queued leaves its entry pending (nothing removes it,
+         * since it never held a grant id to release), and the next drain pass
+         * would otherwise call the launch callback anyway -- which on the real
+         * broker allocates a port, spawns a real child, writes an epoch record
+         * and records a grant that no connection owns. This half turns that
+         * always-reachable leak into a bounded race (half two, below).
+         *
+         * Half two -- the release-on-late-grant branch on the success path --
+         * bounds the NARROW race the pre-check cannot close: a disconnect
+         * landing between the pre-check passing and onAcquire()'s own
+         * completion. This half does NOT eliminate that race -- it cannot, the
+         * pre-check and the callback are separated by a real await -- it turns
+         * the race from a leak into a reclaim, by invoking the existing release
+         * callback with the same request id instead of silently dropping the
+         * grant it produced.
+         */
+        function attemptAcquire(requestId) {
+            // Half one: a queued entry whose owning socket is already gone is
+            // settled immediately, WITHOUT ever calling onAcquire() -- this is
+            // what keeps a retried drain pass from performing a real, ownerless
+            // launch.
+            if (socket.destroyed)
+                return Promise.resolve(true);
+            return opts
+                .onAcquire(requestId)
+                .then((outcome) => {
+                if (outcome.ok) {
+                    // Half two: the pre-check above ran before this call; a
+                    // disconnect landing DURING the await is still possible and is
+                    // bounded, not eliminated, here -- a grant that settles for a
+                    // socket that is now gone is released through the existing
+                    // release path rather than dropped.
+                    if (socket.destroyed) {
+                        opts.onRelease(requestId);
+                        return true;
+                    }
+                    requestIdForThisConnection = requestId;
+                    writeLine(socket, {
+                        kind: "grant",
+                        id: requestId,
+                        port: outcome.grant.port,
+                        url: outcome.grant.url,
+                        epoch_file: outcome.grant.epochFile,
+                        supervisor_dir: outcome.grant.supervisorDir,
+                    });
+                    return true;
+                }
+                if (outcome.reason === "launch_in_flight") {
+                    return false; // still blocked -- caller re-queues
+                }
+                if (socket.destroyed)
+                    return true; // no grant was produced -- nothing to release, nothing left to answer
+                const code = outcome.reason === "internal" ? "internal" : outcome.reason;
+                writeLine(socket, { kind: "error", code, message: `acquire failed: ${outcome.reason}` });
+                return true;
+            })
+                .catch(() => {
+                if (!socket.destroyed) {
+                    writeLine(socket, { kind: "error", code: "internal", message: "acquire threw" });
+                }
+                return true;
+            });
+        }
+        function handleLine(line) {
+            if (line.trim() === "")
+                return;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                writeLine(socket, { kind: "error", code: "bad_request", message: "malformed JSON line" });
+                return;
+            }
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                writeLine(socket, { kind: "error", code: "bad_request", message: "request must be a JSON object" });
+                return;
+            }
+            const req = parsed;
+            // Token check BEFORE any state is read or written -- absence or
+            // mismatch is refused, the connection is destroyed, and nothing is
+            // allocated, spawned or signalled (T-01.6.2-01, T-01.6.2-03).
+            const token = typeof req.token === "string" ? req.token : "";
+            if (!tokensMatch(token, opts.token)) {
+                writeLine(socket, { kind: "error", code: "unauthorized", message: "missing or invalid control token" });
+                socket.destroy();
+                return;
+            }
+            if (req.op === "acquire") {
+                const requestId = typeof req.id === "string" && req.id !== "" ? req.id : defaultRequestId("req");
+                void attemptAcquire(requestId).then((settled) => {
+                    if (!settled) {
+                        enqueueAcquire(pendingAcquires, { requestId, attempt: () => attemptAcquire(requestId) });
+                    }
+                });
+            }
+            else if (req.op === "release") {
+                if (requestIdForThisConnection) {
+                    const id = requestIdForThisConnection;
+                    requestIdForThisConnection = null;
+                    opts.onRelease(id);
+                }
+                writeLine(socket, { kind: "released" });
+            }
+            else if (req.op === "recycle") {
+                const recycleId = typeof req.id === "string" && req.id !== "" ? req.id : defaultRequestId("recycle");
+                const targetId = typeof req.target_id === "string" ? req.target_id : "";
+                // T-01.6.2-31: a connection may only recycle the grant IT ITSELF
+                // holds. This check happens here, before onRecycle() is ever
+                // called, so a mismatched target never reaches the kill discipline
+                // and never signals anything -- an injected signal recorder stays
+                // empty for this case.
+                if (requestIdForThisConnection === null || targetId !== requestIdForThisConnection) {
+                    writeLine(socket, {
+                        kind: "error",
+                        code: "denied",
+                        message: "recycle may only target the grant this connection itself holds",
+                    });
+                    return;
+                }
+                opts
+                    .onRecycle(targetId)
+                    .then((result) => {
+                    writeLine(socket, {
+                        kind: "recycle_ack",
+                        id: recycleId,
+                        target_id: targetId,
+                        port: result.port,
+                        x64sc_pid: result.pid,
+                        vice_bin: result.viceBin,
+                        kill_stage: result.killStage,
+                        epoch_before: result.epochBefore,
+                        outcome: result.outcome,
+                        reason: result.reason,
+                    });
+                })
+                    .catch(() => {
+                    writeLine(socket, { kind: "error", code: "internal", message: "recycle threw" });
+                });
+            }
+            else if (req.op === "status") {
+                writeLine(socket, { kind: "status", instances: opts.onStatus() });
+            }
+            else if (req.op === "host_state") {
+                const hs = opts.onHostState();
+                writeLine(socket, {
+                    kind: "host_state",
+                    pid: hs.pid,
+                    started_at: hs.startedAt,
+                    node_version: hs.nodeVersion,
+                    vice_bin: hs.viceBin,
+                    warm_floor: hs.warmFloor,
+                    max_instances: hs.maxInstances,
+                    base_port: hs.basePort,
+                });
+            }
+            else {
+                writeLine(socket, { kind: "error", code: "bad_request", message: `unknown op: ${String(req.op)}` });
+            }
+        }
+    });
+}
+/** Starts the TCP control listener: binds (bindControlListener()), then
+ * attaches the full newline-delimited-JSON protocol (attachControlProtocol()
+ * above) -- all five request kinds, the token gate, and the arrival-ordered
+ * pending-acquire queue this listener instance owns. Frames inbound bytes as
+ * newline-delimited JSON: buffers, splits on "\n", parses each line with
+ * the never-throw posture this codebase already uses for untrusted input --
+ * a malformed line answers `bad_request` and the connection survives. A
+ * connection exceeding MAX_LINE_BYTES without a newline is destroyed rather
+ * than buffered further (T-01.6.2-04). */
+export function startControlListener(opts) {
+    const host = opts.host ?? process.env.VICE_BROKER_CONTROL_HOST ?? "0.0.0.0";
+    const port = resolveControlPort(opts.port);
+    return bindControlListener(host, port).then((bound) => {
+        const pendingAcquires = [];
+        attachControlProtocol(bound.server, opts, pendingAcquires);
+        return { server: bound.server, port: bound.port, host: bound.host, pendingAcquires };
+    });
+}