@henols/vice-mcp 0.2.2 → 0.2.4

package/stock-dispatch.ts

@@ -24,11 +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 { capabilityRefusalMessage } from "./capability-registry.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 {
@@ -43,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
@@ -72,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
@@ -86,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");
 }
 
 /**
@@ -108,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;
 }
@@ -186,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.
  */
@@ -202,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 };
@@ -422,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
@@ -462,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
@@ -489,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) => {
@@ -503,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);
+      }
+    });
   };
 }
 
@@ -531,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
@@ -539,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;
@@ -572,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);
+      }
+    });
   };
 }
 
@@ -713,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
@@ -726,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
@@ -740,31 +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) {
-    // WR-13: route through capability-registry.ts's ONE authoritative
-    // refusal renderer rather than a second, locally-composed wording --
-    // that renderer knows which backend ACTUALLY provides each name
-    // (avoiding the false "the fork backend provides this tool" claim for a
-    // stock-only-gain name) and never uses "wait for a later phase" framing
-    // for a hardware loss. Fall back to an internal-inconsistency message
-    // ONLY when the registry has no entry at all for `name` -- meaning the
-    // tool is advertised on the stock manifest (so it reached this branch)
-    // but stockHandlerFor() has no dispatch entry AND capability-registry.ts
-    // has no divergence entry either: a bug to report, not a capability gap.
     return isErrorText(
-      capabilityRefusalMessage(name, "stock") ??
-        `${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.`,
+      `${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-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-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. */

package/stock-protocol.ts

@@ -41,7 +41,7 @@
 import { EventEmitter } from "node:events";
 import net from "node:net";
 
-import { ViceError } from "./vice.ts";
+import { ViceError } from "./vice-errors.ts";
 
 // ---------------------------------------------------------------------------
 // Wire constants (hand-copied, not imported -- see header comment above)

package/stock-recycle.ts

@@ -64,7 +64,7 @@ import { handleRegistersGet } from "./stock-registers.ts";
 import { stockAnswer, isErrorText, type StockSessionHandler, type StockToolResult } from "./stock-handler.ts";
 import { stockDisconnect, type StockConnectSession } from "./stock-connect.ts";
 import type { StockDispatchDeps } from "./stock-dispatch.ts";
-import { readEpoch } from "./vice.ts";
+import { readEpoch } from "./vice-errors.ts";
 
 function describeError(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
@@ -307,6 +307,81 @@ export async function gatherStockWedgeEvidence(session: StockConnectSession, dep
  * per-outcome vocabulary is the same one. Redeclared locally rather than
  * imported: importing it would mean importing vice-proxy.ts, which this
  * module must never do. */
+const DEFAULT_RECYCLE_EPOCH_POLL_TIMEOUT_MS = 3000;
+const RECYCLE_EPOCH_POLL_INTERVAL_MS = 50;
+
+/** Read fresh on EVERY call -- same load-time-vs-call-time reasoning as
+ * stockCaptureStepTimeoutMs() above: a static `import` is hoisted ahead of
+ * any top-level statement in the importing file, so a module-level constant
+ * computed once at load time could never be retuned by a test that sets
+ * `process.env` afterwards. Deliberately its OWN environment variable,
+ * distinct from `VICE_RECYCLE_CAPTURE_TIMEOUT_MS` -- that knob bounds one
+ * evidence-gathering step before the kill; this one bounds the epoch poll
+ * after it, and a single shared knob would let retuning one silently retune
+ * the other. Exported so the test file can assert the default directly. */
+export function stockRecycleEpochPollTimeoutMs(): number {
+  const raw = process.env.VICE_RECYCLE_EPOCH_POLL_TIMEOUT_MS;
+  if (raw === undefined || raw === "") return DEFAULT_RECYCLE_EPOCH_POLL_TIMEOUT_MS;
+  const parsed = Number(raw);
+  // A non-positive deadline would make the poll finish before it ever reads,
+  // so every confirmed kill would record a null epoch_after -- and the field
+  // would look present (the producer ran) while carrying no information at
+  // all, which is worse than the missing producer this poll exists to fix.
+  if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  console.error(
+    `VICE_RECYCLE_EPOCH_POLL_TIMEOUT_MS=${JSON.stringify(raw)} is not a positive number of milliseconds -- ignoring it and using the ` +
+      `default ${DEFAULT_RECYCLE_EPOCH_POLL_TIMEOUT_MS}ms. A value of 0 would end the post-kill epoch poll before its first read, so a ` +
+      "confirmed kill would always record a null epoch_after, indistinguishable from a genuine stall.",
+  );
+  return DEFAULT_RECYCLE_EPOCH_POLL_TIMEOUT_MS;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** The ONE predicate that may promote a post-kill read into the record. A
+ * present-but-unchanged value must stay out: a pair of equal before/after
+ * numbers reads to a future investigator as a confirmed no-turnover, which is
+ * a false claim for a kill the guard above this call already established
+ * succeeded. Absence of a pre-kill epoch (a lease that never had one) makes
+ * the first present read count as an advance -- there is nothing higher than
+ * "nothing" to compare against. */
+function epochAdvanced(before: number | null, after: ReturnType<typeof readEpoch>): boolean {
+  if (!after.present || after.epoch === null) return false;
+  return before === null || after.epoch > before;
+}
+
+/**
+ * Bounded post-kill epoch poll. Reuses the SAME dependency-injected reader
+ * and file path the pre-kill read above already used, so the before and
+ * after values come from one source. Loops until either the epoch has
+ * advanced (epochAdvanced() above) or its own wall-clock deadline passes,
+ * clamping the final sleep so the loop cannot overshoot that deadline. A
+ * lease with no epoch file polls nothing and resolves null immediately --
+ * there is nothing to read. A throw from the reader is treated as a read
+ * that did not advance, never as a fatal error on a path that runs after a
+ * destructive action has already happened.
+ */
+async function pollEpochAfter(readEpochFn: typeof readEpoch, epochFile: string, epochBefore: number | null): Promise<number | null> {
+  if (!epochFile) return null;
+  const deadline = Date.now() + stockRecycleEpochPollTimeoutMs();
+  for (;;) {
+    let result: ReturnType<typeof readEpoch> | null;
+    try {
+      result = readEpochFn(epochFile);
+    } catch {
+      result = null;
+    }
+    if (result && epochAdvanced(epochBefore, result)) {
+      return result.epoch;
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return null;
+    await sleep(Math.min(RECYCLE_EPOCH_POLL_INTERVAL_MS, remaining));
+  }
+}
+
 function recycleAckOutcomeMessage(ack: { outcome: string; kill_stage: string; reason: string }): string {
   const stage = ack.kill_stage || "unknown";
   const reasonSuffix = ack.reason ? ` (${ack.reason})` : "";
@@ -472,7 +547,13 @@ export async function handleRecycleStock(args: Record<string, unknown>, session:
       return isErrorText(`vice_recycle: ${recycleAckOutcomeMessage(ack)} Incident record: ${recordPath}.`);
     }
 
-    finaliseIncidentRecord(recordPath, { outcome: "ok", kill_stage: killStage });
+    // Post-kill epoch poll -- the record's own `epoch_after` producer. Only
+    // reached on a confirmed kill: a refusal, a timeout or a broker-gone
+    // outcome each leave the machine's state unknown, and polling for an
+    // epoch advance on any of those would invent a fact this handler has no
+    // basis for.
+    const epochAfter = await pollEpochAfter(readEpochFn, lease.epochFile, epochBefore);
+    finaliseIncidentRecord(recordPath, { outcome: "ok", kill_stage: killStage, epoch_after: epochAfter });
 
     // stockAnswer() stamps runState from session.client -- read BEFORE the
     // teardown below disconnects it, so the answer reports the machine's