@henols/vice-mcp 0.2.1 → 0.2.2

package/vice-proxy.ts

@@ -185,22 +185,22 @@ import * as stockDispatch from "./stock-dispatch.ts";
 // below, strictly after the DENY_LIST check -- see the comment at that call
 // site for why the ordering is load-bearing.
 import { capabilityRefusalMessage } from "./capability-registry.ts";
-// Plan 11-05: the curated r2000_* tool surface's DEFINITIONS, imported
+// Plan 29-01: the curated anno_* tool surface's DEFINITIONS, imported
 // STATICALLY -- registration below happens synchronously at module scope, so
-// a dynamic import cannot serve it. This costs no child process and no
-// socket: the heavy part (the MCP client, the spawned regenerator2000 child)
-// stays behind r2000-tools.ts's own `await import("./r2000-mcp-client.ts")`
-// inside runR2000Tool() itself, reached only when a tool is actually called.
-import { R2000_TOOL_DEFINITIONS, runR2000Tool } from "./r2000-tools.ts";
+// a dynamic import cannot serve it. This costs nothing at module load: no
+// store file is opened here. The owned SQLite annotation store stays behind
+// anno-tools.ts's own runAnnoTool(), which opens it, answers exactly one call
+// against it and closes it again (D-06), reached only when a tool is called.
+import { ANNO_TOOL_DEFINITIONS, runAnnoTool } from "./anno-tools.ts";
 
-// ------------------------------------------------------------ r2000 subcommand
+// ------------------------------------------------------------ anno subcommand
 //
-// D-06 / RESEARCH.md Open Question #1 (plan 10-04): `vice-mcp r2000 <verb>` is
+// D-06 / RESEARCH.md Open Question #1 (plan 10-04): `vice-mcp anno <verb>` is
 // the ONLY surface that resolves identically across the Claude Code plugin
 // route and both npm-installer routes -- `installer/bin/cli.mjs`'s
 // `viceServerEntry()` always launches this server via `npx` in BOTH
 // npm-installer modes (`--vendor` only pre-resolves the package; it never
-// places `.claude/mcp/vice/*.ts` as plain files inside a consuming project),
+// places `src/mcp/vice/*.ts` as plain files inside a consuming project),
 // so any design resolving a filesystem path to the seam would silently fail
 // to resolve for npm-installed users. This bin is the one surface proven to
 // work in all three routes.
@@ -212,7 +212,7 @@ import { R2000_TOOL_DEFINITIONS, runR2000Tool } from "./r2000-tools.ts";
 // must never open a socket, never probe a binary, and never write a byte of
 // JSON-RPC to stdout. WHAT NOT TO DO: never let this branch fall through
 // into the server path, and never print anything on stdout on the server
-// path that a CLI caller could confuse for `r2000` output.
+// path that a CLI caller could confuse for `anno` output.
 //
 // Ending the process here is deliberate and is NOT a violation of this
 // file's standing "never end the process from a teardown handler" rule (see
@@ -220,7 +220,7 @@ import { R2000_TOOL_DEFINITIONS, runR2000Tool } from "./r2000-tools.ts";
 // long-lived server's lease-release path, and this branch ends the process
 // before any lease, socket or handler exists. A dynamic import is used
 // (not a static one) so the CLI module is not part of the server's startup
-// cost on the normal, non-`r2000` path.
+// cost on the normal, non-`anno` path.
 //
 // IN-01 (10-REVIEW.md; 11.1-CONTEXT.md AUDIT-01, D-11.1-04): `console.log`/
 // `console.error` writes to `process.stdout`/`process.stderr` are
@@ -228,16 +228,18 @@ import { R2000_TOOL_DEFINITIONS, runR2000Tool } from "./r2000-tools.ts";
 // non-blocking, unlike a TTY or a regular file), so a bare `process.exit()`
 // immediately after can discard whatever write has not yet drained --
 // measured at a 128 KiB truncation point on this host's Node for a single
-// write exceeding the OS pipe's capacity. The reachable trigger is
-// `cmdExportAsm`'s `console.error(result.stderr)` in r2000-cli.ts, which can
-// carry a large diagnostic from the spawned regenerator2000 child: the one
+// write exceeding the OS pipe's capacity. The trigger this was FOUND
+// through -- a CLI verb that echoed a spawned child's whole stderr -- was
+// withdrawn with the analyser it spawned (plan 29-07, D-14), but the hazard
+// is a property of the exit path rather than of that verb: any verb that
+// prints a diagnostic larger than the pipe's capacity hits it, and the one
 // case where the user most needs the diagnostic is exactly the case a piped
 // invocation could silently lose it in. `drainStdio()` below explicitly
 // awaits both streams' own pending writes (a `write("", cb)`-style
 // zero-length write's callback fires only once every prior queued write has
 // actually flushed) before the terminating `process.exit(code)`.
 //
-// T-11.1-EXITHANG: the drain is BOUNDED to `R2000_CLI_DRAIN_TIMEOUT_MS`. An
+// T-11.1-EXITHANG: the drain is BOUNDED to `ANNO_CLI_DRAIN_TIMEOUT_MS`. An
 // exit that hangs forever waiting on a pipe nobody reads is worse than a
 // truncated diagnostic -- this project's standing rule is that a teardown
 // path never becomes a hang (see the "never end the process from a teardown
@@ -245,7 +247,7 @@ import { R2000_TOOL_DEFINITIONS, runR2000Tool } from "./r2000-tools.ts";
 // for the same reason the original unbounded `process.exit()` did not: this
 // still runs before any lease, socket or handler exists, and now also can
 // never block indefinitely).
-const R2000_CLI_DRAIN_TIMEOUT_MS = 300;
+const ANNO_CLI_DRAIN_TIMEOUT_MS = 300;
 
 /** Resolves once `stream`'s own pending writes have flushed, or after
  * `timeoutMs`, whichever comes first. A zero-length `write("", cb)`'s
@@ -260,7 +262,7 @@ function drainStdio(stream: NodeJS.WriteStream): Promise<void> {
       resolve();
       return;
     }
-    const timer = setTimeout(resolve, R2000_CLI_DRAIN_TIMEOUT_MS);
+    const timer = setTimeout(resolve, ANNO_CLI_DRAIN_TIMEOUT_MS);
     stream.write("", () => {
       clearTimeout(timer);
       resolve();
@@ -268,7 +270,7 @@ function drainStdio(stream: NodeJS.WriteStream): Promise<void> {
   });
 }
 
-if (process.argv[2] === "r2000") {
+if (process.argv[2] === "anno") {
   // A broken pipe (the reader closing early, e.g. `| head`) makes
   // `stream.write()` fail with EPIPE. Awaiting `drainStdio()` below gives
   // that failure the chance to actually surface as Node's stream 'error'
@@ -285,23 +287,25 @@ if (process.argv[2] === "r2000") {
   // Test-only escape hatch, never documented to end users and inert unless
   // this exact env var is set: writes a deterministic filler payload
   // through this SAME drained-exit path, so vice-proxy.test.ts can measure
-  // an exact byte count well above any OS pipe capacity without needing a
-  // real regenerator2000 project (empirically, neither `--help`'s ~5.6 KB
-  // USAGE text nor a synthesized/garbage `.regen2000proj` fed to
-  // export-asm's error path scales anywhere near 128 KiB on this host's
-  // regenerator2000 0.9.20 -- both were measured before this hatch was
-  // added; see 11.1-05-SUMMARY.md for the measurements). Never reachable
-  // from a real `r2000 <verb>` invocation: the check is against a specific,
+  // an exact byte count well above any OS pipe capacity without needing any
+  // real project file at all. That independence is the point: measured at
+  // the time, neither `--help`'s ~5.6 KB USAGE text nor a synthesized or
+  // garbage project file fed to a verb's error path scaled anywhere near
+  // 128 KiB on this host, so no real invocation could reach the truncation
+  // point on demand (see 11.1-05-SUMMARY.md for those measurements). The
+  // hatch outlives the routes it was measured against, because it depends on
+  // none of them. Never reachable
+  // from a real `anno <verb>` invocation: the check is against a specific,
   // unambiguous env var name no real caller would ever set.
-  const testFillBytes = process.env.VICE_TEST_R2000_CLI_STDOUT_FILL_BYTES;
+  const testFillBytes = process.env.VICE_TEST_ANNO_CLI_STDOUT_FILL_BYTES;
   if (testFillBytes) {
     process.stdout.write("x".repeat(Number(testFillBytes)));
     await Promise.all([drainStdio(process.stdout), drainStdio(process.stderr)]);
     process.exit(0);
   }
 
-  const { runR2000Cli } = await import("./r2000-cli.ts");
-  const code = await runR2000Cli(process.argv.slice(3));
+  const { runAnnoCli } = await import("./anno-cli.ts");
+  const code = await runAnnoCli(process.argv.slice(3));
   await Promise.all([drainStdio(process.stdout), drainStdio(process.stderr)]);
   process.exit(code);
 }
@@ -313,6 +317,23 @@ const HERE_DIR = dirname(fileURLToPath(import.meta.url));
 // selection, the tools construction loop's dispatch choice, and the final
 // ready log line) reads THIS constant, never the raw environment variable
 // and never a second detection call.
+//
+// `ACTIVE_BACKEND.binPath` is what `vice_ping`'s `resolvedBinaryPath` field
+// reports (see stock-dispatch.ts's `handlePing()`). It is resolved exactly
+// ONCE here, at MCP-server process startup, by a bare `x64sc` `$PATH` probe
+// run in THIS process's own environment -- it is NOT re-probed per request
+// and has no connection to the broker, a separate, already-running process
+// that leases whichever instance it chose to whatever request comes in. On a
+// host where bare `x64sc` resolves to one build, `resolvedBinaryPath` reports
+// that build's path on every ping, even when the broker actually launched
+// (or later recycled to) a different one. The authoritative per-instance
+// answer lives in the broker's own launch record (`epoch.json`'s `vice_bin`
+// field, written by `broker-epoch.mts`) -- Phase 8.2 plan 04's own
+// walkthrough had to route around this field entirely and prove backend
+// identity from that launch record plus a live `ps -o args=` read instead
+// (2026-08-19 finding, closed as a documentation fix by Phase 15 plan 15-09
+// rather than a per-request requery, which would be a behavioural change out
+// of a disposition phase's remit).
 const ACTIVE_BACKEND = backendDetect.resolvedBackend();
 
 // -------------------------------------------------------------- JSON-RPC
@@ -3136,6 +3157,7 @@ async function forwardToVice(name: string, args: Record<string, unknown>): Promi
 // and asserts that slice contains no promise-awaiting construct and calls
 // the control session's release function exactly once. Do not move either
 // marker away from the code each one bounds.
+//
 let teardownRan = false;
 
 function releaseLeaseNow(trigger: string): void {
@@ -3340,31 +3362,31 @@ tools[RESULT_CONTINUE_TOOL.name] = buildViceTool(RESULT_CONTINUE_TOOL, (args) =>
 // entry in `tools/list`.
 tools[RECYCLE_TOOL.name] = buildBackendAwareTool(stockDispatch.resolveAdvertisedToolDefinition(RECYCLE_TOOL, ACTIVE_BACKEND.backend, manifestTools), (args) => handleRecycle(args));
 tools[DIAGNOSE_TOOL.name] = buildBackendAwareTool(stockDispatch.resolveAdvertisedToolDefinition(DIAGNOSE_TOOL, ACTIVE_BACKEND.backend, manifestTools), (args) => handleDiagnose(args));
-// Backend-INDEPENDENT by construction (plan 11-05): the r2000_* family never
-// touches VICE at all -- regenerator2000 is a separate, static-analysis child
-// process, so there is no fork/stock distinction to make and
-// buildBackendAwareTool() would be flatly wrong here (there is nothing for it
-// to dispatch to on either backend). The family is in NEITHER
-// tools-manifest.json NOR tools-manifest.stock.json: both are regenerated by
-// refresh-manifest.ts from a live HOST VICE server's own tools/list, and an
-// r2000 child process is never that host -- a hand-added entry in either
-// manifest would be silently wiped on the next refresh. Registered here via
-// buildViceTool() directly (the SAME exception RESULT_CONTINUE_TOOL above
-// is), so no r2000_* runner can ever reach forwardToVice(), call(), or
-// ensureViceSession() -- CLAUDE.md's "derived tools must be intercepted
-// before forwardToVice()" constraint is satisfied by construction for this
-// family, not by an interception, because the runner is never wired to
-// forwardToVice() in the first place.
+// Backend-INDEPENDENT by construction (plan 29-01): the anno_* family never
+// touches VICE at all -- it reaches a PROXY-LOCAL SQLite annotation store
+// this repo owns, opened and closed inside the runner itself, so there is no
+// fork/stock distinction to make and buildBackendAwareTool() would be flatly
+// wrong here (there is nothing for it to dispatch to on either backend). The
+// family is in NEITHER tools-manifest.json NOR tools-manifest.stock.json:
+// both are regenerated by refresh-manifest.ts from a live HOST VICE server's
+// own tools/list, and a local store file is never that host -- a hand-added
+// entry in either manifest would be silently wiped on the next refresh.
+// Registered here via buildViceTool() directly (the SAME exception
+// RESULT_CONTINUE_TOOL above is), so no anno_* runner can ever reach
+// forwardToVice(), call(), or ensureViceSession() -- CLAUDE.md's "derived
+// tools must be intercepted before forwardToVice()" constraint is satisfied
+// by construction for this family, not by an interception, because the
+// runner is never wired to forwardToVice() in the first place.
 // Deliberately NOT named `def` (the manifest loop's own loop variable,
 // above): `stock-dispatch.test.ts`'s `proxyToolRegistrations()` regex-scans
 // this file's own `tools[...] = ...;` lines and keys each one by its raw
 // captured text, so an identically-named loop variable here would make this
 // registration textually indistinguishable from the manifest loop's -- a
-// distinct name (`r2000Def`) keeps the r2000 family's own exemption from
+// distinct name (`annoDef`) keeps the anno_* family's own exemption from
 // `buildBackendAwareTool()` from ever being confused with, or accidentally
 // widened to cover, the manifest loop's registration.
-for (const r2000Def of R2000_TOOL_DEFINITIONS) {
-  tools[r2000Def.name] = buildViceTool(r2000Def, (args) => runR2000Tool(r2000Def.name, args));
+for (const annoDef of ANNO_TOOL_DEFINITIONS) {
+  tools[annoDef.name] = buildViceTool(annoDef, (args) => runAnnoTool(annoDef.name, args));
 }
 
 const server = new MCPServer({ name: "vice", version: PROXY_VERSION, tools });