@henols/vice-mcp 0.2.1 → 0.2.3

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)
@@ -720,12 +720,15 @@ export function registersSetBody({ memspace, items }: RegistersSetBodyOptions):
 
 // ---------------------------------------------------------------------------
 // Execution and machine-control body encoders (Phase 3, Task 2). Every
-// body layout below is [CITED] against the official VICE manual (§13) but
-// has NOT been exercised against a real binary in this environment -- each
-// JSDoc says so explicitly, and where RESEARCH.md's Assumptions Log flags a
-// behavioural (not wire-shape) assumption, the JSDoc names the row (A2, A3,
-// A5) and points at .planning/todos/pending/ for the probe debt. None of
-// these are claimed as verified.
+// body layout below is [CITED] against the official VICE manual (§13);
+// each encoder's own JSDoc states whether its behavioural (not wire-shape)
+// claim has since been live-probed. RESEARCH.md Assumptions Log row A2 was
+// closed CONFIRMED by 13-PROBE-RESULTS.md. Two rows below are still
+// unconfirmed -- A3 stayed INCONCLUSIVE (no observable signal either way)
+// and A5 was CONTRADICTED (still pending its correction) -- and each of
+// those two encoders' own JSDoc, below, still carries its own [ASSUMED]
+// naming that row and pointing at .planning/todos/pending/ for the
+// remaining probe debt.
 // ---------------------------------------------------------------------------
 
 export interface AdvanceInstructionsBodyOptions {
@@ -739,9 +742,11 @@ export interface AdvanceInstructionsBodyOptions {
  * exercised, with stepOver=0 only, in probe-binmon.mjs's async-events check]
  *
  * `stepOver = true`'s runtime meaning (skip a `JSR`'s subroutine as one
- * step, matching the fork's own `stepOver` field name) is [ASSUMED] --
- * RESEARCH.md Assumptions Log row A2 -- never probed against a real `JSR`.
- * See `.planning/todos/pending/` for the outstanding probe debt.
+ * step, matching the fork's own `stepOver` field name) 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, reproduced identically across two independent live
+ * sessions.
  */
 export function advanceInstructionsBody({ stepOver = false, count = 1 }: AdvanceInstructionsBodyOptions = {}): Buffer {
   if (!Number.isInteger(count) || count < 1 || count > 0xffff) {
@@ -816,8 +821,8 @@ export interface ResetBodyOptions {
  * [CITED docs/phase0-binmon-findings.md §5]
  *
  * NOT the RESOURCE_SET (0x52) power-cycle hazard CLAUDE.md warns about
- * (`MachineVideoStandard`/`VICIIModel`/`MachinePowerFrequency`, Phase 6
- * territory) -- this is a distinct opcode, and an agent-requested hard
+ * (`MachineVideoStandard`/`VICIIModel`/`MachinePowerFrequency`, the CUT
+ * vice_machine_config_get/set pair's resources) -- a distinct opcode, and an agent-requested hard
  * reset via RESET is exactly what DIRECT-06 asks for. It needs no
  * deny-list. This is RESEARCH.md's Pitfall 1; this comment is what stops a
  * later reviewer from "fixing" it by adding one.

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

package/stock-registers.ts

@@ -68,12 +68,19 @@ export interface RegisterCatalog {
 /** The one module-level catalog map, keyed on the session object itself --
  * NOT on session.client -- so a fresh stockReconnect() (which returns a
  * brand-new session) is indistinguishable from "never fetched" and simply
- * fetches again, with no manual invalidation path required anywhere. */
+ * fetches again, with no manual invalidation path required anywhere.
+ *
+ * Caches the in-flight PROMISE, not the resolved catalog (15-04, IN-02):
+ * two handlers racing on a fresh session both read `catalogs.get(session)`
+ * before either write lands, so caching only the resolved value let both
+ * send their own REGISTERS_AVAILABLE. Caching the promise means the second
+ * caller awaits the SAME in-flight request. A rejected promise is evicted
+ * (see registerCatalogFor()) so a failed fetch is retried, never memoised. */
 // Single-line by design: the ONLY line in this file naming the garbage-
 // collectable, session-keyed map primitive directly (grep-gated -- see
 // this plan's own acceptance criteria). Every other reference goes
 // through this factory, never a second construction call site.
-function freshCatalogMap(): WeakMap<StockConnectSession, RegisterCatalog> { return new WeakMap<StockConnectSession, RegisterCatalog>(); }
+function freshCatalogMap(): WeakMap<StockConnectSession, Promise<RegisterCatalog>> { return new WeakMap<StockConnectSession, Promise<RegisterCatalog>>(); }
 
 let catalogs = freshCatalogMap();
 
@@ -86,15 +93,22 @@ export function resetRegisterCatalogsForTest(): void {
 
 /**
  * Resolves `session`'s register catalog, fetching it through
- * REGISTERS_AVAILABLE (0x83) exactly once and caching the result on the
- * session object. Every subsequent call for the SAME session object
- * returns the cached catalog with no further wire traffic.
+ * REGISTERS_AVAILABLE (0x83) exactly once and caching the IN-FLIGHT
+ * PROMISE on the session object -- not just the resolved value, so two
+ * concurrent callers on a fresh session (before either fetch has
+ * resolved) share the SAME REGISTERS_AVAILABLE round trip rather than
+ * each sending their own (15-04, IN-02). Every subsequent call for the
+ * SAME session object returns the same promise (and, once it settles,
+ * the same resolved catalog) with no further wire traffic.
  *
  * Refuses (throws a plain Error, converted by the caller through
  * convertWireError()) an empty enumeration rather than caching it: a
  * build that enumerates zero registers cannot support
  * vice_registers_set, and that failure must be visible on every call,
- * never silently cached as "zero registers, nothing to resolve".
+ * never silently cached as "zero registers, nothing to resolve". A
+ * rejected fetch, whether from an empty enumeration or a wire error, is
+ * evicted from the cache before this function returns, so the NEXT call retries instead
+ * of permanently memoising the failure.
  */
 export async function registerCatalogFor(session: StockConnectSession): Promise<RegisterCatalog> {
   const existing = catalogs.get(session);
@@ -102,30 +116,41 @@ export async function registerCatalogFor(session: StockConnectSession): Promise<
     return existing;
   }
 
-  const response = await session.client.send(CommandType.RegistersAvailable, memspaceBody({ memspace: 0x00 }));
-  if (response.type !== "registers_available") {
-    throw new Error(`registerCatalogFor: expected a registers_available reply, got "${response.type}"`);
-  }
-  if (response.registers.length === 0) {
-    throw new Error(
-      "registerCatalogFor: the connected VICE build enumerated zero registers via REGISTERS_AVAILABLE -- " +
-        "it cannot support vice_registers_set, and this failure must be named rather than cached as an empty catalog",
-    );
-  }
+  const pending = (async (): Promise<RegisterCatalog> => {
+    const response = await session.client.send(CommandType.RegistersAvailable, memspaceBody({ memspace: 0x00 }));
+    if (response.type !== "registers_available") {
+      throw new Error(`registerCatalogFor: expected a registers_available reply, got "${response.type}"`);
+    }
+    if (response.registers.length === 0) {
+      throw new Error(
+        "registerCatalogFor: the connected VICE build enumerated zero registers via REGISTERS_AVAILABLE -- " +
+          "it cannot support vice_registers_set, and this failure must be named rather than cached as an empty catalog",
+      );
+    }
 
-  const byName = new Map<string, { id: number; sizeBits: number; name: string }>();
-  const byId = new Map<number, { sizeBits: number; name: string }>();
-  for (const reg of response.registers) {
-    // reg.size is stock-protocol.ts's own field name for the wire's size
-    // byte (its parser is unchanged by this plan); this module renames it
-    // to sizeBits at the point it enters the catalog so every downstream
-    // reader sees the unit named in the type.
-    byName.set(reg.name.toUpperCase(), { id: reg.id, sizeBits: reg.size, name: reg.name });
-    byId.set(reg.id, { sizeBits: reg.size, name: reg.name });
-  }
-  const catalog: RegisterCatalog = { byName, byId };
-  catalogs.set(session, catalog);
-  return catalog;
+    const byName = new Map<string, { id: number; sizeBits: number; name: string }>();
+    const byId = new Map<number, { sizeBits: number; name: string }>();
+    for (const reg of response.registers) {
+      // reg.size is stock-protocol.ts's own field name for the wire's size
+      // byte (its parser is unchanged by this plan); this module renames it
+      // to sizeBits at the point it enters the catalog so every downstream
+      // reader sees the unit named in the type.
+      byName.set(reg.name.toUpperCase(), { id: reg.id, sizeBits: reg.size, name: reg.name });
+      byId.set(reg.id, { sizeBits: reg.size, name: reg.name });
+    }
+    return { byName, byId };
+  })();
+
+  catalogs.set(session, pending);
+  // Evict on rejection so a failed fetch is retried by the next call
+  // rather than memoised forever -- only if no newer promise has already
+  // replaced this one for the same session.
+  pending.catch(() => {
+    if (catalogs.get(session) === pending) {
+      catalogs.delete(session);
+    }
+  });
+  return pending;
 }
 
 // ---------------------------------------------------------------------------