@henols/vice-mcp 0.2.1 → 0.2.3

package/stock-dispatch.ts

@@ -24,10 +24,13 @@
 //     one place a tools/call for the stock backend is routed from.
 //   - Never acquire a broker lease here (Task 2's own ensureStockSession()
 //     header comment explains this prohibition fully).
+//   - Never acquire channel-lock.ts's mutex anywhere but inside
+//     withChannelLockHeld() (plan 41-02, CHAN-04) -- that is the ONE acquire
+//     site on the binary side, and it wraps the delegated HANDLER call only,
+//     never the session-acquisition preamble above it.
 import { resolve, join } from "node:path";
 
-import type { ViceBackend } from "./backend-detect.mts";
-import type { ToolInfo } from "./vice.ts";
+import type { ToolInfo } from "./vice-errors.ts";
 import { type HeldLease } from "./vice-broker-client.ts";
 import { stockConnect, stockDisconnect, stockReconnect, type StockConnectSession, type StockConnectDeps } from "./stock-connect.ts";
 import {
@@ -42,6 +45,7 @@ import {
 } from "./stock-handler.ts";
 import { attachRunStateTracker } from "./stock-runstate.ts";
 import { STOCK_DERIVED_TOOLS, type DerivedPureHandler } from "./stock-derived.ts";
+import { acquireChannelLock, ChannelLockTimeoutError } from "./channel-lock.ts";
 
 // The six family modules (plans 03-06 through 03-11) -- each exports its
 // tools as StockSessionHandler-shaped values; this file (D-09) is the ONE
@@ -71,6 +75,7 @@ import { handleCyclesStopwatch, forgetTimingForOtherTargets } from "./stock-timi
 import { handleRunUntil } from "./stock-run-until.ts";
 import { handleDiagnoseStock } from "./stock-diagnose.ts";
 import { handleRecycleStock } from "./stock-recycle.ts";
+import { handleDeviceConsole, handleWarpSet, handleMemmapShow, handleMemmapZap, handleCpuHistory, handleProfileFlat, handleBacktrace, handleIoRegisters } from "./text-tools.ts";
 
 // Re-exported so Phase 2's existing import surface (and its 921-line test
 // file) keeps working unchanged -- these four names used to be DEFINED
@@ -85,21 +90,26 @@ export type { StockToolResult, StockOkResult, StockErrorResult };
 // ---------------------------------------------------------------------------
 
 /**
- * Resolves which manifest file backs a given backend's advertised tool
+ * Resolves the one manifest file backing the stock backend's advertised tool
  * surface, following the EXACT override precedence vice-proxy.ts's own
  * manifestPath() already establishes: an explicit VICE_TOOLS_MANIFEST value
  * (passed in as `envOverride`, never read from process.env directly here --
- * this function stays a pure, injectable seam) wins for either backend,
- * unchanged; otherwise the backend picks its own committed default file
- * beside `hereDir`. `envOverride` is deliberately a plain parameter, not a
- * process.env read, so this function has no hidden global dependency and a
- * test can drive every combination without mutating the real environment.
+ * this function stays a pure, injectable seam) wins, unchanged; otherwise the
+ * committed default file beside `hereDir` is used. `envOverride` is
+ * deliberately a plain parameter, not a process.env read, so this function
+ * has no hidden global dependency and a test can drive both cases without
+ * mutating the real environment.
+ *
+ * FORKRM-05 (plan 52-07): this used to take a `backend` parameter selecting
+ * between two committed manifest files -- there is one manifest now, so the
+ * parameter is gone rather than pinned to a literal no caller could ever
+ * vary.
  */
-export function manifestPathForBackend(backend: ViceBackend, hereDir: string, envOverride: string | undefined): string {
+export function manifestPathForBackend(hereDir: string, envOverride: string | undefined): string {
   if (envOverride) {
     return resolve(envOverride);
   }
-  return backend === "stock" ? join(hereDir, "tools-manifest.stock.json") : join(hereDir, "tools-manifest.json");
+  return join(hereDir, "tools-manifest.stock.json");
 }
 
 /**
@@ -107,44 +117,38 @@ export function manifestPathForBackend(backend: ViceBackend, hereDir: string, en
  * is a name-keyed record: whichever assignment to a given key runs LAST
  * wins, and vice-proxy.ts's own registration order used to assign
  * RECYCLE_TOOL/DIAGNOSE_TOOL's literal (fork-worded) definitions
- * UNCONDITIONALLY, on both backends, straight after the backend-aware
- * manifest loop had already populated the same keys correctly. So on the
- * stock backend, `tools/list` served the fork's five-verdict vocabulary --
- * including `stale_read_path`, which stock cannot produce (D-03) -- and
- * omitted `monitor_held_elsewhere`, which stock can, even though the
- * corrected stock manifest entry sat right there in
+ * UNCONDITIONALLY, straight after the manifest loop had already populated
+ * the same keys correctly. `tools/list` served the fork's five-verdict
+ * vocabulary -- including `stale_read_path`, which stock cannot produce
+ * (D-03) -- and omitted `monitor_held_elsewhere`, which stock can, even
+ * though the corrected stock manifest entry sat right there in
  * tools-manifest.stock.json, unread. This function is the ONE place that
  * decision is now made, so the manifest loop's own per-tool selection and
  * the two synthetic tools' registration agree.
  *
- * Behaviour:
- *   - `backend === "fork"`: always returns `syntheticDef` unchanged, no
- *     matter what `manifestTools` contains. The fork's advertised surface
- *     is frozen at v0.1.x and this function must never be able to alter it.
- *   - `backend === "stock"`: returns the `manifestTools` entry whose `name`
- *     equals `syntheticDef.name`, if one exists. Falls back to
- *     `syntheticDef` when no match exists -- `readManifestTools()`'s own
- *     malformed/unreadable-manifest fallbacks answer `[]`, and in that case
- *     the proxy must still advertise a WORKING tool rather than none at all
- *     (T-07-16-02).
- *   - NEVER merges fields from the two definitions. Picking one whole
- *     definition keeps `description`, `inputSchema` and `outputSchema`
- *     internally consistent; a field-by-field merge could pair a fork
- *     description with a stock `outputSchema`, or the reverse.
+ * Behaviour: returns the `manifestTools` entry whose `name` equals
+ * `syntheticDef.name`, if one exists. Falls back to `syntheticDef` when no
+ * match exists -- `readManifestTools()`'s own malformed/unreadable-manifest
+ * fallbacks answer `[]`, and in that case the proxy must still advertise a
+ * WORKING tool rather than none at all (T-07-16-02). NEVER merges fields
+ * from the two definitions -- picking one whole definition keeps
+ * `description`, `inputSchema` and `outputSchema` internally consistent; a
+ * field-by-field merge could pair one definition's description with the
+ * other's `outputSchema`.
  *
  * Declared as a `function`, not a `const` arrow, per this module tree's own
  * standing rule: stock-dispatch.ts <-> stock-diagnose.ts <-> stock-recycle.ts
  * form a runtime import cycle, and the phase already reproduced a live
  * `ReferenceError` from a `const` handler export sitting in that cycle.
+ *
+ * FORKRM-05 (plan 52-07): this used to take a `backend` parameter and
+ * return `syntheticDef` unchanged when it was `"fork"` -- vice-proxy.ts's
+ * two call sites always passed the literal `"stock"`, so that branch was
+ * dead from the moment plan 52-06 collapsed backend detection. Removed
+ * rather than left as an unreachable branch a reader could mistake for live
+ * code.
  */
-export function resolveAdvertisedToolDefinition(
-  syntheticDef: ToolInfo,
-  backend: ViceBackend,
-  manifestTools: ToolInfo[],
-): ToolInfo {
-  if (backend === "fork") {
-    return syntheticDef;
-  }
+export function resolveAdvertisedToolDefinition(syntheticDef: ToolInfo, manifestTools: ToolInfo[]): ToolInfo {
   const manifestEntry = manifestTools.find((t) => t.name === syntheticDef.name);
   return manifestEntry ?? syntheticDef;
 }
@@ -185,8 +189,8 @@ export type LeaseProvider = () => Promise<{ ok: true; lease: HeldLease | null }
  * never implies resolution it did not achieve. It is a plain string handed down from vice-proxy.ts's
  * OWN single, module-scope call to `resolvedBackend()` (see that file's own
  * "resolve the active backend once" discipline) -- this module must never
- * call `resolvedBackend()`/`probeBackend()` itself, per backend-detect.mts's
- * own "do not call this per tool or per call" prohibition. Omitted entirely
+ * call `resolvedBackend()` itself, per backend-detect.mts's own "do not
+ * call this per tool or per call" prohibition. Omitted entirely
  * (never expected in production) falls back to an empty string rather than
  * throwing.
  */
@@ -201,6 +205,12 @@ export interface StockDispatchDeps {
    * Omitted defaults to `false` -- the honest answer when nothing said
    * otherwise. */
   resolvedBinaryPathIsResolved?: boolean;
+  /** Test-only override of channel-lock.ts's acquire bound for THIS call's
+   * withChannelLockHeld() wrapping. Production call sites never set this --
+   * they always take channel-lock.ts's own CHANNEL_LOCK_ACQUIRE_TIMEOUT_MS
+   * default. Exists so a test can observe a ChannelLockTimeoutError (and its
+   * refusal text) without waiting out the real ~630-second default. */
+  channelLockTimeoutMs?: number;
 }
 
 export type EnsureStockSessionOutcome = { ok: true; session: StockConnectSession } | { ok: false; message: string };
@@ -421,7 +431,7 @@ export async function ensureStockSession(deps: StockDispatchDeps): Promise<Ensur
  * come from the lease vice-proxy.ts built (see HeldLease's own field comments
  * for why they are two DIFFERENT directories), and `binPath` is the same
  * already-settled `resolvedBinaryPath` vice_ping reports -- this module must
- * never call resolvedBackend()/probeBackend() itself.
+ * never call resolvedBackend() itself.
  *
  * An empty string is treated as ABSENT rather than passed through: the two
  * consumers both branch on truthiness, and passing "" would key a capability
@@ -461,6 +471,53 @@ export { stockDisconnect };
  * prohibits). */
 export type StockHandler = (args: Record<string, unknown>, deps: StockDispatchDeps) => Promise<StockToolResult>;
 
+/**
+ * withChannelLockHeld -- acquires channel-lock.ts's mutex for
+ * `channel: "binary"` around `fn`, releasing in a `finally` so a throwing
+ * `fn` still releases (D-05). This is the ONE acquire site on the binary
+ * side; withStockSession() and withDerivedTool()'s `needsSession: true`
+ * branch both call it, and neither may acquire the lock any other way.
+ *
+ * This is what makes the lock's critical section span a whole LOGICAL
+ * operation, not a single wire command: `vice_run_until`'s wait
+ * (stock-run-until.ts's `waitForCheckpointHit()`) and the reproducible-run
+ * path's wait (stock-reproducible-run.ts's `waitForReproducibleStop()`,
+ * reached through `runReproducible()`) both run INSIDE the wrapped `fn`, so
+ * the lock stays held across resume -> wait -> observe without either wait
+ * path being re-cut.
+ *
+ * FORBIDDEN ALTERNATIVE, named here because it is the obvious-looking wrong
+ * design: acquiring and releasing this lock around each individual wire
+ * command instead of around the whole handler call. A per-wire-command lock
+ * preserves the resume count while destroying what the count protects -- a
+ * foreign command (e.g. a text-channel command) can land in the gap between
+ * "resume sent" and "checkpoint observed", halting a machine that was
+ * supposed to be running toward the checkpoint, so the checkpoint never
+ * fires even though no protocol invariant was technically violated per
+ * command (41-RESEARCH.md Pitfall 6).
+ *
+ * A `ChannelLockTimeoutError` is converted into refusal text using the
+ * error's OWN message verbatim -- it is already `channelLockRefusalMessage()`'s
+ * output -- and NEVER routed through `convertWireError()`, which would
+ * re-frame a legitimate ownership statement as a wire fault.
+ */
+async function withChannelLockHeld(toolName: string, timeoutMs: number | undefined, fn: () => Promise<StockToolResult>): Promise<StockToolResult> {
+  let handle;
+  try {
+    handle = await acquireChannelLock({ channel: "binary", operation: toolName, timeoutMs });
+  } catch (err) {
+    if (err instanceof ChannelLockTimeoutError) {
+      return isErrorText(err.message);
+    }
+    throw err;
+  }
+  try {
+    return await fn();
+  } finally {
+    handle.release();
+  }
+}
+
 /**
  * withStockSession -- THE ONE adapter every STOCK_DISPATCH_TABLE entry goes
  * through (Task 1, plan 03-12). Before this existed, `viceHandlerPing` was
@@ -488,6 +545,17 @@ export type StockHandler = (args: Record<string, unknown>, deps: StockDispatchDe
  *      Code for the rest of the session (T-3-04) -- a single escaped
  *      exception here would silently end the session's entire tool surface,
  *      not just this one call.
+ *
+ * Step 3's own try/catch runs INSIDE withChannelLockHeld(toolName, ...)
+ * (plan 41-02, CHAN-04): the session-acquisition step above (step 1/2) is
+ * NOT covered by the lock -- only the delegated handler call is -- so a
+ * broker liveness classification or a handshake failure never queues behind
+ * the OTHER channel's halt authority. This is what makes D-05's critical
+ * section span a whole logical operation: `vice_run_until`'s and the
+ * reproducible-run path's waits run inside their handlers, so the lock is
+ * held across resume -> wait -> observe without either wait path being
+ * re-cut (see withChannelLockHeld()'s own header for the forbidden
+ * per-wire-command alternative).
  */
 export function withStockSession(toolName: string, handler: StockSessionHandler): StockHandler {
   return async (args, deps) => {
@@ -502,11 +570,13 @@ export function withStockSession(toolName: string, handler: StockSessionHandler)
       return isErrorText(outcome.message);
     }
 
-    try {
-      return await handler(args, outcome.session, deps);
-    } catch (err) {
-      return convertWireError(toolName, err);
-    }
+    return withChannelLockHeld(toolName, deps.channelLockTimeoutMs, async () => {
+      try {
+        return await handler(args, outcome.session, deps);
+      } catch (err) {
+        return convertWireError(toolName, err);
+      }
+    });
   };
 }
 
@@ -530,7 +600,14 @@ export function withStockSession(toolName: string, handler: StockSessionHandler)
  * calls ensureStockSession() at all -- not a lighter-weight variant of it
  * (04-RESEARCH.md Pitfall 3) -- and invokes `handler(args, deps)` inside a
  * single try/catch converting through convertWireError(), so the
- * never-throw boundary still holds.
+ * never-throw boundary still holds. This branch also NEVER acquires
+ * channel-lock.ts's mutex (plan 41-02, CHAN-04): taking halt authority for a
+ * pure client-side computation that never touches the wire would block a
+ * REAL halting operation for no reason. `vice_diagnose` is also registered
+ * `needsSession: false` and therefore also does not acquire here -- its own
+ * handler takes the lock with `tryAcquireChannelLock()` (channel-lock.ts)
+ * instead, deliberately, so that diagnosing contention never queues behind
+ * the holder it is diagnosing (plan 41-04).
  *
  * `needsSession: true` runs the EXACT same three-step preamble
  * withStockSession() runs, reusing the same imported converters -- never a
@@ -538,7 +615,11 @@ export function withStockSession(toolName: string, handler: StockSessionHandler)
  * inside its own try/catch -> convertHandshakeError(toolName, err); a
  * `{ ok: false }` outcome returns outcome.message verbatim through
  * isErrorText(), never re-worded; otherwise handler(args, outcome.session, deps)
- * inside a SECOND try/catch -> convertWireError(toolName, err).
+ * inside a SECOND try/catch -> convertWireError(toolName, err), with that
+ * second try/catch running inside withChannelLockHeld(toolName, ...) --
+ * exactly the same wrapping withStockSession() applies, and for the same
+ * reason (see that function's own comment on the forbidden per-wire-command
+ * alternative).
  */
 export function withDerivedTool(toolName: string, opts: { needsSession: true }, handler: StockSessionHandler): StockHandler;
 export function withDerivedTool(toolName: string, opts: { needsSession: false }, handler: DerivedPureHandler): StockHandler;
@@ -571,11 +652,13 @@ export function withDerivedTool(
       return isErrorText(outcome.message);
     }
 
-    try {
-      return await (handler as StockSessionHandler)(args, outcome.session, deps);
-    } catch (err) {
-      return convertWireError(toolName, err);
-    }
+    return withChannelLockHeld(toolName, deps.channelLockTimeoutMs, async () => {
+      try {
+        return await (handler as StockSessionHandler)(args, outcome.session, deps);
+      } catch (err) {
+        return convertWireError(toolName, err);
+      }
+    });
   };
 }
 
@@ -591,7 +674,22 @@ export function withDerivedTool(
  * comment on why). Built through stockAnswer() so the answer now also
  * carries `runState` (D-06: every stock answer, and `vice_ping` is a stock
  * answer) alongside every field that was already there.
+ *
+ * 2026-08-19 finding (closed Phase 15 plan 15-09): `resolvedBinaryPath` is a
+ * ONE-TIME, MCP-server-process-startup `$PATH` probe (see vice-proxy.ts's
+ * `ACTIVE_BACKEND` comment) -- it is independent of which binary the broker
+ * actually leased for THIS request. `resolvedBinaryPathScope` below is an
+ * additive, backward-compatible sibling field (the existing field name and
+ * shape are unchanged) that carries that qualification into the answer
+ * itself, so a caller reading the response -- not just this source comment --
+ * learns not to treat the path as this request's authoritative binary
+ * identity.
  */
+const RESOLVED_BINARY_PATH_SCOPE =
+  "one-time MCP-server-process-startup PATH probe; NOT the binary the broker leased for this " +
+  "request -- for the authoritative per-instance binary, read the broker's own launch record " +
+  "(epoch.json's vice_bin field)";
+
 const handlePing: StockSessionHandler = async (_args, session, deps) => {
   return stockAnswer(session.client, {
     status: "ok",
@@ -602,6 +700,9 @@ const handlePing: StockSessionHandler = async (_args, session, deps) => {
     // it, an agent reading `"x64sc"` cannot tell "this is where the binary is"
     // from "this is what we were told to look for, and we could not find it".
     resolvedBinaryPathIsResolved: deps.resolvedBinaryPathIsResolved ?? false,
+    // 2026-08-19 finding: names what resolvedBinaryPath actually is (a
+    // startup-time probe) and where to look instead for a per-request answer.
+    resolvedBinaryPathScope: RESOLVED_BINARY_PATH_SCOPE,
     capabilities: session.capabilities,
   });
 };
@@ -611,11 +712,11 @@ const handlePing: StockSessionHandler = async (_args, session, deps) => {
  * not an oversight (Task 2, plan 03-12):
  *   - `vice_checkpoint_set_ignore_count` (D-15)
  *   - `vice_snapshot_list` (D-16 -- deleted from both manifests)
- *   - `vice_disk_detach` (D-13 -- Phase 7, via the text monitor)
- *   - `vice_joystick_tap` (needs a resume plus Phase 7's timing route)
+ *   - `vice_disk_detach` (CUT from scope 2026-08-17 -- docs/stock-vice-parity.md's dated cut record)
+ *   - `vice_joystick_tap` (permanently excluded -- stock-input.ts's own header)
  *   - `vice_disk_read_sector` (CUT from scope 2026-08-17 -- no skill calls it; see ROADMAP.md "Cut from scope (v0.2.0, 2026-08-17)" and docs/stock-vice-parity.md item 6)
  *   - `vice_sid_get_state` and the low-level keyboard family (hard losses)
- *   - `vice_machine_config_get` / `vice_machine_config_set` (Phase 6)
+ *   - `vice_machine_config_get` / `vice_machine_config_set` (CUT from scope 2026-08-17 along with the whole of Stock-Only Gains -- docs/stock-vice-parity.md's dated cut record)
  * `dispatchStock()`'s miss branch already refuses any of these by name,
  * without reading `deps` -- there is nothing else to add for them here.
  */
@@ -694,9 +795,9 @@ const STOCK_DISPATCH_TABLE: Record<string, StockHandler> = {
   vice_run_until: withDerivedTool("vice_run_until", { needsSession: true }, handleRunUntil),
 
   // derived (TIME-04) -- the two proxy-local synthetic tools (RECYCLE_TOOL/
-  // DIAGNOSE_TOOL in vice-proxy.ts), backend-routed to dispatchStock() by
-  // buildBackendAwareTool() rather than served from the fork's HTTP
-  // transport. Deliberate asymmetry, documented at this call site (see also
+  // DIAGNOSE_TOOL in vice-proxy.ts), registered via buildViceTool() and
+  // routed to this table's own dispatchStock() entry point, never to the
+  // deleted fork transport. Deliberate asymmetry, documented at this call site (see also
   // DerivedPureHandler's amended doc comment in stock-derived.ts):
   // vice_diagnose uses needsSession:false because its own handler acquires
   // the session itself (inside its own try/catch) so it can convert a
@@ -707,6 +808,30 @@ const STOCK_DISPATCH_TABLE: Record<string, StockHandler> = {
   // evidence and has no verdict vocabulary of its own to preserve.
   vice_diagnose: withDerivedTool("vice_diagnose", { needsSession: false }, handleDiagnoseStock),
   vice_recycle: withDerivedTool("vice_recycle", { needsSession: true }, handleRecycleStock),
+
+  // text-channel remedy tools (plan 41-06, CHAN-03). needsSession:false,
+  // deliberately -- NOT withStockSession()/withDerivedTool(needsSession:
+  // true): both of those wrap the whole handler call in
+  // withChannelLockHeld("binary", ...), and each handler below takes its OWN
+  // channel-lock.ts acquire for `channel: "text"` internally
+  // (withTextChannelLock(), text-protocol.ts). Registering through either
+  // binary-locking adapter would nest a second acquireChannelLock() call
+  // inside the first (channel-lock.ts is one single, non-reentrant mutex
+  // across both channels) -- a self-deadlock that only resolves by expiring
+  // CHANNEL_LOCK_ACQUIRE_TIMEOUT_MS. See text-tools.ts's own header comment
+  // (ADAPTER CHOICE) for the full measurement. Neither handler needs a
+  // binary session at all -- both resolve the lease via deps.ensureLease()
+  // themselves and dial only through textConnect() -- so needsSession:false
+  // is not merely the deadlock-avoiding choice, it is also the structurally
+  // correct one, matching vice_diagnose's own precedent above.
+  vice_device_console: withDerivedTool("vice_device_console", { needsSession: false }, handleDeviceConsole),
+  vice_warp_set: withDerivedTool("vice_warp_set", { needsSession: false }, handleWarpSet),
+  vice_memmap_show: withDerivedTool("vice_memmap_show", { needsSession: false }, handleMemmapShow),
+  vice_memmap_zap: withDerivedTool("vice_memmap_zap", { needsSession: false }, handleMemmapZap),
+  vice_cpu_history: withDerivedTool("vice_cpu_history", { needsSession: false }, handleCpuHistory),
+  vice_profile_flat: withDerivedTool("vice_profile_flat", { needsSession: false }, handleProfileFlat),
+  vice_backtrace: withDerivedTool("vice_backtrace", { needsSession: false }, handleBacktrace),
+  vice_io_registers: withDerivedTool("vice_io_registers", { needsSession: false }, handleIoRegisters),
 };
 
 /** Looks up the table entry for `name` -- `undefined` on a miss, never a
@@ -721,20 +846,27 @@ export function stockHandlerFor(name: string): StockHandler | undefined {
 /**
  * The ONE dispatch entry point for the stock backend (D-09). On a hit,
  * delegates to the table entry, unchanged. On a miss, refuses EXPLICITLY --
- * naming the tool, stating the stock backend does not implement it, and
- * naming the fork as the backend that does -- WITHOUT reading `deps` at all
- * (no lease is ever requested for a tool that does not exist on this
- * backend). There is no third branch, and in particular NO fall-through to
- * the fork's HTTP-forwarding path anywhere in this file or anything it calls
- * -- that is D-09's whole point, grep-gated to zero occurrences of that
- * function's name in this file's own code lines.
+ * naming the tool and stating there is no dispatch entry for it -- WITHOUT
+ * reading `deps` at all (no lease is ever requested for a tool that does not
+ * exist on this backend). There is no third branch, and in particular NO
+ * fall-through to the fork's HTTP-forwarding path anywhere in this file or
+ * anything it calls -- that is D-09's whole point, grep-gated to zero
+ * occurrences of that function's name in this file's own code lines.
+ *
+ * FORKRM-05 (plan 52-07): this used to fall back to the deleted per-backend
+ * capability registry's refusal renderer first, naming the fork as the
+ * backend that provides the tool -- that renderer, and the fork it named,
+ * are both gone. A name reaching this branch is advertised on the stock
+ * manifest (so it passed vice-proxy.ts's own lookup) but has no dispatch
+ * entry: that is always an internal inconsistency now, never a capability
+ * gap with a second backend to point a caller at.
  */
 export async function dispatchStock(name: string, args: Record<string, unknown>, deps: StockDispatchDeps): Promise<StockToolResult> {
   const handler = stockHandlerFor(name);
   if (!handler) {
     return isErrorText(
-      `${name} is not implemented by the stock backend -- the fork backend provides this tool. ` +
-        `Set VICE_BACKEND=fork to use it there, or wait for a later phase to extend the stock dispatch table.`,
+      `${name} is advertised on the stock backend's manifest but has no handler in the stock ` +
+        `dispatch table -- this is an internal inconsistency, not a capability gap; please file an issue.`,
     );
   }
   return handler(args, deps);

package/stock-execution.ts

@@ -224,9 +224,11 @@ export const handleExecutionRun: StockSessionHandler = async (args, session) =>
  * the derived run state is "unknown" (D-07, via refuseIfUnknown()).
  *
  * `stepOver: true`'s runtime semantic (skip a JSR's subroutine as one step)
- * is [ASSUMED] -- RESEARCH.md Assumptions Log row A2 -- never probed against
- * a real JSR. See `.planning/todos/pending/2026-08-14-probe-phase3-assumed-wire-details.md`
- * for the outstanding probe debt. This is NOT claimed as verified here.
+ * was live-probed against a real JSR on fork VICE 3.10 and CONFIRMED
+ * (RESEARCH.md Assumptions Log row A2, closed by 13-PROBE-RESULTS.md §A2):
+ * the post-step PC landed at JSR+3, matching a full subroutine skip, and
+ * the result was reproduced identically across two independent live
+ * sessions.
  */
 export const handleExecutionStep: StockSessionHandler = async (args, session) => {
   const unexpected = refuseUnexpectedArgs(args, ["count", "stepOver"], "vice_execution_step");

package/stock-handler.ts

@@ -36,7 +36,7 @@
 //     time, so it creates no runtime cycle even though stock-dispatch.ts
 //     imports this file at runtime.
 import { MonitorOwnershipError } from "./vice-broker-client.ts";
-import { MachineRestartedError } from "./vice.ts";
+import { MachineRestartedError } from "./vice-errors.ts";
 import { ErrorCode, StockFramingError, StockProtocolError, StockResponseMismatchError, type ViceMonitorClient } from "./stock-protocol.ts";
 import { runStateFor } from "./stock-runstate.ts";
 import type { StockConnectSession } from "./stock-connect.ts";

package/stock-input.ts

@@ -25,10 +25,10 @@
 //     resumes explicitly, on its own schedule.
 //   - Never add vice_joystick_tap. A tap needs the machine to RUN for a
 //     measured interval -- an unrequested EXIT (forbidden by D-05) plus a
-//     frame/cycle measurement that does not exist on stock until Phase 7's
-//     timing route lands (docs/stock-vice-parity.md section A item 7).
-//     vice_joystick_set (hold/release/centre) satisfies DIRECT-07's
-//     joystick half in the meantime.
+//     frame/cycle measurement stock's wire protocol has no route for at
+//     all (docs/stock-vice-parity.md section A item 7). This exclusion is
+//     permanent, not pending: vice_joystick_set (hold/release/centre)
+//     satisfies DIRECT-07's joystick half instead.
 //   - Never construct an ok-answer outside stockAnswer(). Every successful
 //     result below is built through it, never a bare
 //     `{ content: [...], isError: false }` literal.
@@ -187,11 +187,11 @@ function isValidDirection(value: string): value is JoystickDirection {
  * the fork's exact names and documented string-or-array shape.
  *
  * vice_joystick_tap is deliberately absent from this module (and the whole
- * stock manifest) -- a tap needs the machine to run for a measured
- * interval, which is an unrequested EXIT (forbidden by D-05) plus a
- * frame/cycle measurement stock does not have until Phase 7's timing route
- * lands (docs/stock-vice-parity.md section A item 7). Do not approximate it
- * with a sleep; do not implement it here.
+ * stock manifest), permanently -- a tap needs the machine to run for a
+ * measured interval, which is an unrequested EXIT (forbidden by D-05) plus
+ * a frame/cycle measurement stock's wire protocol has no route for at all
+ * (docs/stock-vice-parity.md section A item 7). Do not approximate it with
+ * a sleep; do not implement it here.
  */
 export const handleJoystickSet: StockSessionHandler = async (args, session) => {
   if (!isPlainObject(args)) {

package/stock-machine.ts

@@ -12,17 +12,17 @@
 // WHAT NOT TO DO:
 //   - Never gate or deny vice_machine_reset's hard mode. CLAUDE.md's
 //     power-cycle warning is about RESOURCE_SET (0x52) writes to
-//     MachineVideoStandard/VICIIModel/MachinePowerFrequency -- Phase 6
-//     territory, a DIFFERENT opcode entirely. RESET (0xcc) is a distinct
+//     MachineVideoStandard/VICIIModel/MachinePowerFrequency -- the CUT
+//     vice_machine_config_get/set pair's resources (docs/stock-vice-parity.md), a DIFFERENT opcode entirely. RESET (0xcc) is a distinct
 //     command, and an agent-requested hard reset via RESET is exactly what
 //     DIRECT-06 asks for. It needs no deny-list (RESEARCH.md Pitfall 1).
 //   - Never look for a per-unit disk-attach route mid-implementation.
 //     AUTOSTART (0xdd) has NO drive-unit field on the wire at all -- this is
 //     a protocol gap, not a code bug you can fix by looking harder
 //     (RESEARCH.md Pitfall 2).
-//   - Never add a disk-detach handler here. D-13 ships that tool in Phase 7
-//     through the text monitor -- grep-gated to zero occurrences of its name
-//     in this file's own acceptance criteria.
+//   - Never add a disk-detach handler here. D-13's vice_disk_detach was
+//     CUT from scope 2026-08-17 (docs/stock-vice-parity.md) -- grep-gated
+//     to zero occurrences of its name in this file's own acceptance criteria.
 //   - Never build a host path outside stock-paths.ts. Every filename this
 //     file sends through the wire goes through that same one wrapper --
 //     grep-gated to zero direct hostPath()/hostPathCandidates() calls here.
@@ -150,7 +150,18 @@ export const handleAutostart: StockSessionHandler = async (args, session) => {
  * at all, so an agent told "attached to unit 9" when the image landed on
  * unit 8 would debug the wrong drive. See docs/stock-vice-parity.md's D-14
  * entry.
+ *
+ * The returned `approximation` string names BOTH real side effects Phase 13
+ * plan 13-03's live A5 probe observed against real fork VICE 3.10: a full
+ * machine reset AND a program load, not "attach without disturbing machine
+ * state." Exported so the pinning test derives its expectation from this
+ * constant rather than re-typing the sentence, so the two cannot drift. See
+ * `.planning/phases/13-external-verification/13-PROBE-RESULTS.md` § A5.
  */
+export const DISK_ATTACH_APPROXIMATION =
+  "AUTOSTART (D-14): performs a full machine reset and loads a program from the image; " +
+  "unlike vice_autostart it does not issue a final run step, as far as observed.";
+
 export const handleDiskAttach: StockSessionHandler = async (args, session) => {
   const a = isPlainObject(args) ? args : {};
 
@@ -182,7 +193,7 @@ export const handleDiskAttach: StockSessionHandler = async (args, session) => {
       unit: 8,
       path: containerPath,
       sentPath,
-      approximation: "AUTOSTART with the run flag clear (D-14)",
+      approximation: DISK_ATTACH_APPROXIMATION,
     });
   } catch (err) {
     return convertWireError("vice_disk_attach", err);

package/stock-paths.ts

@@ -17,11 +17,14 @@
 // side finds this comment.
 //
 // WHAT NOT TO DO:
-//   - Never call rewriteArguments() from a stock handler. It lives INSIDE
-//     forwardToVice() (vice-proxy.ts, around line 2773) -- the one function
-//     Phase 2's D-09 says the stock path must never touch -- and its own
-//     comment inverts on stock: what is correct for the fork's derived tools
-//     is exactly wrong here.
+//   - Never merge this file's emulator-side translation with, or replace it
+//     by, a general argument-rewriting pass applied before dispatch. Stock
+//     tool calls no longer go through any such pass -- vice-proxy.ts's own
+//     fork-only per-call path-rewriter (and the generic forwarding function
+//     that ran it) is deleted outright -- and reintroducing one would
+//     re-create exactly the inversion this file's header names: what a
+//     general rewriter does for a client-side-derived path is precisely
+//     wrong for the four emulator-side filenames this file translates.
 //   - Never build a host path with a local heuristic (a hand-rolled prefix
 //     swap, a hardcoded mount guess, anything not routed through
 //     hostpath.ts's own hostPathCandidates()/tryHostPaths()). hostpath.ts is
@@ -35,8 +38,8 @@
 //     through withEmulatorSidePath() should stop and re-read this paragraph.
 import { dirname, join } from "node:path";
 
-import { ViceError, type ViceErrorOptions } from "./vice.ts";
-import { repoRoot } from "./repo-root.ts";
+import { ViceError, type ViceErrorOptions } from "./vice-errors.ts";
+import { repoRoot, toolsDir } from "./repo-root.ts";
 import { isInsideContainer } from "./container-guard.mts";
 import { tryHostPaths } from "./hostpath.ts";
 import { ErrorCode, StockProtocolError } from "./stock-protocol.ts";
@@ -167,21 +170,22 @@ export function sanitizeSnapshotName(name: unknown): string {
 
 /**
  * The container path a snapshot named `name` lives at:
- * `<repoRoot>/.vice-snapshots/<name>.vsf`. The directory is inside the
- * workspace rather than under `~/.config/vice/` (the fork's own location)
- * because only a workspace path is inside hostpath.ts's bind-mount mapping
- * -- anything outside it cannot be translated for the host at all -- and
- * keeping it inside the workspace makes workspace escape structurally
+ * `<toolsDir>/snapshots/<name>.vsf` -- a subdirectory of the single
+ * tool-written root `repo-root.ts`'s `toolsDir()` owns (D-33). The directory
+ * is inside the workspace rather than under `~/.config/vice/` (the fork's own
+ * location) because only a workspace path is inside hostpath.ts's bind-mount
+ * mapping -- anything outside it cannot be translated for the host at all --
+ * and keeping it inside the workspace makes workspace escape structurally
  * impossible rather than merely checked (T-3-05).
  */
 export function snapshotPathFor(name: string): string {
-  return join(repoRoot(), ".vice-snapshots", `${sanitizeSnapshotName(name)}.vsf`);
+  return join(toolsDir(), "snapshots", `${sanitizeSnapshotName(name)}.vsf`);
 }
 
 /** The sidecar metadata path for the same snapshot: same directory, `.json`
  * extension, same sanitisation. */
 export function snapshotMetaPathFor(name: string): string {
-  return join(repoRoot(), ".vice-snapshots", `${sanitizeSnapshotName(name)}.json`);
+  return join(toolsDir(), "snapshots", `${sanitizeSnapshotName(name)}.json`);
 }
 
 // Re-exported so a caller building a directory before translating (Task 3's

package/stock-petscii.ts

@@ -32,7 +32,7 @@
 //     bytes (0x40/0x41, 0x5a/0x5b, 0x60/0x61, 0x7a/0x7b) and the control-code
 //     regions do not follow that rule uniformly; each range below is
 //     checked explicitly, not derived from a single arithmetic shortcut.
-import { ViceError } from "./vice.ts";
+import { ViceError } from "./vice-errors.ts";
 
 /** PETSCII's Return code. Both ASCII LF (`\n`) and CR (`\r`) map here -- this
  * is what the fork's own "Use \n for Return" tool description promises. */