@henols/c64-re-tools 0.1.4

package/skills/c64-ram-capture/scripts/watch-loads.test.mjs

@@ -0,0 +1,339 @@
+// Coverage for the on-demand-load detector's pure logic (01-04 Task 1).
+// Every test here runs with no emulator present -- small synthetic fixtures
+// for the boundary/attribution/ordering behaviour, plus two cases that read
+// the real committed sidecars to prove the pure functions reproduce
+// already-recorded evidence. The import-purity guard test at the bottom is
+// the durable, mechanical statement of the one-permitted-route rule: this
+// whole file runs to completion with the emulator absent, and the guard
+// keeps it that way.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+
+import {
+  WATCH_SET,
+  attributeAddress,
+  reportHits,
+  idleGate,
+  classifyHit,
+  screenSignature,
+  addrNum,
+  hex4,
+} from "./watch-loads.mjs";
+import { buildChipState, buildRangeManifest } from "./dump-artifacts.mjs";
+import { firstDumpArtifact, skipUnless } from "./test-corpus.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(HERE, "..", "..", "..", "..");  // scripts -> skill -> skills -> .claude -> repo root
+
+// ----------------------------------------------------------------- addrNum
+
+test("addrNum parses $-hex, 0x-hex, decimal strings and numbers", () => {
+  assert.equal(addrNum("$08B1"), 0x08b1);
+  assert.equal(addrNum("0x08b1"), 0x08b1);
+  assert.equal(addrNum("2225"), 2225);
+  assert.equal(addrNum(2225), 2225);
+});
+
+test("hex4 formats a 4-digit uppercase $ address", () => {
+  assert.equal(hex4(0x08b1), "$08B1");
+  assert.equal(hex4(0), "$0000");
+});
+
+// -------------------------------------------------------------- WATCH_SET
+
+function fakeRegistry(loaderRanges) {
+  return {
+    releases: [
+      {
+        id: "fake",
+        loader_ranges: loaderRanges,
+        dumps: [{ label: "run1", range_manifest: "recovery/fake/dumps/fake-run1.map.json" }],
+      },
+    ],
+  };
+}
+
+const FAKE_MANIFEST = {
+  ranges: [
+    { start: 0, end: 15, kind: "unclassified" },
+    { start: 16, end: 31, kind: "unused", note: "power-on pattern" },
+    { start: 32, end: 63, kind: "unclassified" },
+  ],
+};
+
+test("WATCH_SET assigns tier stopping to loader-reentry ranges and tier counting to never-populated ranges and the register sentinel", () => {
+  const reg = fakeRegistry([{ start: "$0900", end: "$0901", note: "cracktro poll", evidence: "LDA $DC00" }]);
+  const set = WATCH_SET("fake", { registry: reg, manifest: FAKE_MANIFEST });
+  const tiers = new Map(set.map((s) => [s.kind, s.tier]));
+  assert.equal(tiers.get("loader-reentry"), "stopping");
+  assert.equal(tiers.get("never-populated"), "counting");
+  assert.equal(tiers.get("register"), "counting");
+  const dd00 = set.find((s) => s.name === "reg:$DD00");
+  assert.ok(dd00, "register sentinel present");
+});
+
+test("WATCH_SET throws an actionable message when the release has no loader_ranges recorded", () => {
+  const reg = fakeRegistry([]);
+  assert.throws(() => WATCH_SET("fake", { registry: reg, manifest: FAKE_MANIFEST }), /no loader_ranges recorded/);
+});
+
+// --------------------------------------------------------- attributeAddress
+
+test("attributeAddress resolves the first and last byte of every declared range", () => {
+  const sentinels = [
+    { name: "a", start: 0x0900, end: 0x0910 },
+    { name: "b", start: 0x1000, end: 0x1fff },
+  ];
+  assert.equal(attributeAddress(0x0900, sentinels).name, "a");
+  assert.equal(attributeAddress(0x0910, sentinels).name, "a");
+  assert.equal(attributeAddress(0x1000, sentinels).name, "b");
+  assert.equal(attributeAddress(0x1fff, sentinels).name, "b");
+});
+
+test("attributeAddress keeps abutting ranges separate -- exactly one owner at the shared boundary", () => {
+  const sentinels = [
+    { name: "a", start: 0x1000, end: 0x1fff },
+    { name: "b", start: 0x2000, end: 0x2fff },
+  ];
+  const atBoundaryEnd = attributeAddress(0x1fff, sentinels);
+  const atBoundaryStart = attributeAddress(0x2000, sentinels);
+  assert.equal(atBoundaryEnd.name, "a");
+  assert.equal(atBoundaryStart.name, "b");
+  assert.notEqual(atBoundaryEnd.name, atBoundaryStart.name);
+});
+
+test("attributeAddress throws naming both sentinels for an overlapping resolved set", () => {
+  const sentinels = [
+    { name: "a", start: 0x1000, end: 0x1fff },
+    { name: "b", start: 0x1800, end: 0x2000 },
+  ];
+  assert.throws(() => attributeAddress(0x1900, sentinels), (err) => {
+    return /overlapping or duplicate/.test(err.message) && err.message.includes("a") && err.message.includes("b");
+  });
+});
+
+test("attributeAddress returns an explicit unmatched result for an out-of-range address, never the nearest neighbour", () => {
+  const sentinels = [{ name: "a", start: 0x1000, end: 0x1fff }];
+  const result = attributeAddress(0x5000, sentinels);
+  assert.equal(result.matched, false);
+  assert.equal(result.name, null);
+});
+
+// ------------------------------------------------------------- reportHits
+
+test("reportHits orders by cycle, then address, then sentinel name -- swapping input order is stable", () => {
+  const hits = [
+    { cycle: 5, address: "$1000", sentinel: "z" },
+    { cycle: 5, address: "$1000", sentinel: "a" },
+    { cycle: 3, address: "$2000", sentinel: "m" },
+  ];
+  const a = reportHits(hits);
+  const b = reportHits([...hits].reverse());
+  assert.deepEqual(a, b);
+  assert.equal(a[0].cycle, 3);
+  assert.equal(a[1].sentinel, "a");
+  assert.equal(a[2].sentinel, "z");
+});
+
+test("reportHits over an empty hit log returns an empty result rather than throwing", () => {
+  assert.deepEqual(reportHits({ hits: [] }), []);
+  assert.deepEqual(reportHits([]), []);
+  assert.doesNotThrow(() => reportHits({}));
+});
+
+test("reportHits is idempotent -- calling twice on the same log produces identical output", () => {
+  const log = { hits: [{ cycle: 1, address: "$1000", sentinel: "a" }, { cycle: 1, address: "$1000", sentinel: "b" }] };
+  assert.deepEqual(reportHits(log), reportHits(log));
+});
+
+// --------------------------------------------------------------- idleGate
+
+test("idleGate accepts a calibration in which every stopping-tier sentinel recorded zero hits", () => {
+  const cal = {
+    cycles_advanced: 12345,
+    sentinels: [
+      { name: "loader:a", tier: "stopping", hits: 0 },
+      { name: "unused:b", tier: "counting", hits: 3 },
+    ],
+  };
+  assert.equal(idleGate(cal).ok, true);
+});
+
+test("idleGate rejects a calibration in which a stopping-tier sentinel recorded a non-zero count, naming it", () => {
+  const cal = {
+    cycles_advanced: 12345,
+    sentinels: [{ name: "loader:a", tier: "stopping", hits: 113 }],
+  };
+  const result = idleGate(cal);
+  assert.equal(result.ok, false);
+  assert.equal(result.violations[0].name, "loader:a");
+  assert.equal(result.violations[0].hits, 113);
+});
+
+test("idleGate rejects a calibration whose cycles_advanced is zero even when every hit count is zero", () => {
+  const cal = { cycles_advanced: 0, sentinels: [{ name: "loader:a", tier: "stopping", hits: 0 }] };
+  const result = idleGate(cal);
+  assert.equal(result.ok, false);
+  assert.match(result.reasons.join(" "), /cycles_advanced/);
+});
+
+// -------------------------------------------------------------- classifyHit
+
+test("classifyHit returns unattributed when pc, backtrace or disassembly is missing", () => {
+  assert.equal(classifyHit({}), "unattributed");
+  assert.equal(classifyHit({ pc: "$8E9D", backtrace: [], disassembly: "STA ($04),Y" }), "unattributed");
+  assert.equal(classifyHit({ pc: "$8E9D", backtrace: ["$0800"], disassembly: "" }), "unattributed");
+});
+
+test("classifyHit returns the recorded classification only when pc, backtrace and disassembly are all present", () => {
+  const hit = { pc: "$8E9D", backtrace: ["$0800"], disassembly: "STA ($04),Y", classification: "gameplay-write" };
+  assert.equal(classifyHit(hit), "gameplay-write");
+  const loadHit = { ...hit, classification: "load-candidate" };
+  assert.equal(classifyHit(loadHit), "load-candidate");
+});
+
+// ---------------------------------------------------------- screenSignature
+
+test("screenSignature hashes exactly 1000 bytes and carries the sprite-enable value through", () => {
+  const hex = "00".repeat(1000);
+  const result = screenSignature(hex, 60);
+  assert.equal(result.sprite_enable, 60);
+  assert.equal(typeof result.digest, "string");
+  assert.equal(result.digest.length, 64);
+});
+
+test("screenSignature throws for a screen matrix that is not exactly 1000 bytes", () => {
+  assert.throws(() => screenSignature("00".repeat(999), 0), /expected 1000 bytes/);
+});
+
+// ------------------------------------------------ real committed sidecars
+
+const CHIP_STATE = firstDumpArtifact("chip_state");
+
+test("buildChipState reproduces a committed sidecar's recorded derivations from that file's own raw readings",
+  { skip: skipUnless(CHIP_STATE, "a committed chip-state sidecar") }, () => {
+  const committed = JSON.parse(readFileSync(CHIP_STATE.path, "utf8"));
+  const raw = {
+    dd00_raw: committed.derived.dd00_raw,
+    d018_raw: committed.derived.d018_raw,
+    port01_raw: committed.derived.port01.raw,
+    sprite_pointers: committed.derived.sprite_pointers,
+    registers: committed.registers,
+    sprites: committed.sprites,
+    cpu: committed.cpu,
+  };
+  const result = buildChipState(raw);
+  assert.equal(result.derived.vic_bank, committed.derived.vic_bank);
+  assert.equal(result.derived.screen_base, committed.derived.screen_base);
+  assert.equal(result.derived.charset_base, committed.derived.charset_base);
+  assert.deepEqual(result.derived.sprite_data_addresses, committed.derived.sprite_data_addresses);
+});
+
+const BIN = firstDumpArtifact("bin");
+
+test("buildRangeManifest over a committed image produces ranges whose union covers all 65536 addresses",
+  { skip: skipUnless(BIN, "a committed 64K image") }, () => {
+  const image = readFileSync(BIN.path);
+  const manifest = buildRangeManifest(image, { release: BIN.release, label: BIN.label });
+  assert.equal(manifest.classification_state, "ranges-only");
+  let expected = 0;
+  for (const r of manifest.ranges) {
+    assert.equal(r.start, expected, `gap or overlap before ${r.start}`);
+    expected = r.end + 1;
+  }
+  assert.equal(expected, 65536);
+});
+
+// ------------------------------------------------- import-purity guard (T-01-25)
+
+function stripComments(src) {
+  return src.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1");
+}
+
+function importSpecifiers(src) {
+  const specs = [];
+  const re = /import\s+(?:[^'"]+?\s+from\s+)?["']([^"']+)["']/g;
+  let m;
+  while ((m = re.exec(src))) specs.push(m[1]);
+  return specs;
+}
+
+test("every import specifier in watch-loads.mjs and dump-artifacts.mjs is a node: built-in or a sibling file inside tools/ -- the mechanical proof of the one permitted route", () => {
+  const files = ["watch-loads.mjs", "dump-artifacts.mjs"];
+  let totalSpecifiers = 0;
+  for (const f of files) {
+    const src = stripComments(readFileSync(join(HERE, f), "utf8"));
+    const specs = importSpecifiers(src);
+    assert.ok(specs.length > 0, `${f} should have at least one import specifier (this assertion fails if removed, so it cannot pass vacuously)`);
+    totalSpecifiers += specs.length;
+    for (const spec of specs) {
+      const isNodeBuiltin = spec.startsWith("node:");
+      const isSiblingPath = spec.startsWith("./") || spec.startsWith("../");
+      assert.ok(
+        isNodeBuiltin || isSiblingPath,
+        `${f} imports "${spec}", which is neither a node: built-in nor a relative path -- this module must never acquire an outside dependency`
+      );
+      if (isSiblingPath) {
+        const resolved = resolve(HERE, spec);
+        assert.ok(resolved.startsWith(HERE), `${f}'s import "${spec}" resolves outside tools/ (${resolved})`);
+      }
+    }
+  }
+  assert.ok(totalSpecifiers > 0, "at least one specifier must have been checked across both modules");
+});
+
+// ----------------------------------------------------------------- renderLoading
+
+test("renderLoading flags a blocked run's zero count as unevidenced rather than rendering it as a plain zero", async () => {
+  const { renderLoading } = await import("./watch-loads.mjs");
+  const blockedLog = {
+    machine: "C64SC",
+    video_standard: "PAL",
+    vice_version: "3.10",
+    run_status: "blocked",
+    run_status_note: "Boot never progressed past its pre-loader state; two independent cycles_advanced brackets both measured zero.",
+    armed: [],
+    idle_calibration: { cycles_advanced: 0, sentinels: [] },
+    hits: [],
+  };
+  const md = renderLoading([{ id: "example", log: blockedLog }]);
+  assert.match(md, /NOT AN EVIDENCED ZERO/, "a blocked run must not render its zero count as a plain, unqualified result");
+  assert.match(md, /never progressed past its pre-loader state/, "the blocked-run reason must be surfaced in the rendered document");
+});
+
+test("renderLoading flags a blocked run's NON-zero count as a partial result, not a plain evidenced count", async () => {
+  const { renderLoading } = await import("./watch-loads.mjs");
+  const partialLog = {
+    machine: "C64SC",
+    video_standard: "PAL",
+    vice_version: "3.10",
+    run_status: "blocked",
+    run_status_note: "Play-through halted by a genuine silent host VICE stall after 2 of the required milestones.",
+    armed: [],
+    idle_calibration: { cycles_advanced: 100, sentinels: [] },
+    hits: [
+      { sentinel: "reg:$DD00", address: "$DD00", cycle: 1, pc: "$07DB", backtrace: [{ return_address: 1 }], disassembly: "STA $DD00", classification: "gameplay-write" },
+    ],
+  };
+  const md = renderLoading([{ id: "example", log: partialLog }]);
+  assert.match(md, /PARTIAL RESULT, NOT A COMPLETED COVERAGE CLAIM/, "a blocked run with a non-zero count must not be rendered with the zero-specific warning text");
+  assert.doesNotMatch(md, /The count above is `0` only because/, "must not claim the count is 0 when it is not");
+  assert.match(md, /halted by a genuine silent host VICE stall/, "the blocked-run reason must still be surfaced");
+});
+
+test("renderLoading does NOT add the blocked-run warning for an ordinary (non-blocked) log", async () => {
+  const { renderLoading } = await import("./watch-loads.mjs");
+  const normalLog = {
+    machine: "C64SC",
+    video_standard: "PAL",
+    vice_version: "3.10",
+    armed: [],
+    idle_calibration: { cycles_advanced: 100, sentinels: [] },
+    hits: [],
+  };
+  const md = renderLoading([{ id: "example", log: normalLog }]);
+  assert.doesNotMatch(md, /NOT AN EVIDENCED ZERO/, "an ordinary log must not be flagged as a blocked run");
+});

package/skills/c64-ram-capture/templates/capture-record.template.md

@@ -0,0 +1,59 @@
+# Capture record — `<release>-<checkpoint>-run<N>`
+
+One record per capture. Every field is recorded **in the same step as the
+capture**, before the machine is resumed — a value read later describes a
+different machine.
+
+## Identity
+
+| Field | Value | How obtained |
+|---|---|---|
+| image path | `recovery/<release>/dumps/<name>.bin` | — |
+| size | `65536` bytes | must be exact; anything else is not a full image |
+| sha256 | `<64 hex chars>` | `node scripts/compare.mjs digest <name>.bin` |
+| checkpoint / trigger address | `$____` | the address armed for this capture |
+| release | the registry id this capture belongs to | — |
+| run | `<N>` of `<total>` | three runs is this project's minimum for a verified capture |
+
+## Machine state at the capture instant
+
+Read these *before* resuming, in the same paused window as the memory reads.
+
+| Field | Value | Source |
+|---|---|---|
+| `$01` (processor port) | `$__` `%________` | `vice_memory_read` — decides which vectors are live |
+| video standard | PAL \| NTSC | `vice_vicii_get_state` |
+| registers (PC, A, X, Y, SP, flags) | | `vice_registers_get` |
+| epoch-drift errors during the capture | `none` | the proxy raises these itself, before and after every forwarded call — no tool reads the epoch on demand |
+| checkpoints armed at exit | `0` | `vice_checkpoint_list` — accept only this enumeration as proof |
+
+## Verdict
+
+- [ ] Size is exactly 65536 bytes.
+- [ ] No epoch-drift error appeared at any point during the capture.
+- [ ] `vice_checkpoint_list` reported zero checkpoints before resuming.
+- [ ] Machine resumed exactly once, at the end.
+
+If any box is unchecked, void the run: rename each artifact to
+`<name>.VOID-<UTC timestamp>`, write a sibling note giving the reason and — when a
+drift error was the cause — both epoch values quoted from that error's own text,
+and keep the voided artifacts on disk.
+
+## Comparison against sibling runs
+
+`node scripts/compare.mjs compare <a>.bin <b>.bin` for each pairing, and
+`node scripts/compare.mjs floor <a>.bin <b>.bin <c>.bin` across the set.
+
+| Pairing | volatile | drift (1 bit) | divergence (2+ bits) | verdict |
+|---|---|---|---|---|
+| run1 vs run2 | | | | |
+| run1 vs run3 | | | | |
+| run2 vs run3 | | | | |
+
+Record the drift floor address count, and state it as a floor rather than a
+complete set — more captures of the same checkpoint can only widen it.
+
+**Any divergence inside `$D000-$DFFF` is not a divergence.** That range is
+register images, not RAM: reading it samples live hardware, so it can never be
+stable across two captures. Classify it as volatile and say so in the record
+rather than voiding a good capture over it.

package/skills/vice-wedge-triage/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: vice-wedge-triage
+description: Decide whether a VICE emulator that has stopped responding is genuinely wedged, stopped itself at your own checkpoint, crashed and respawned, or merely paused — and what is safe to do about each. Use when asked why the emulator is stuck, frozen, hung, wedged, dead or not advancing, when a cycle bracket reads zero, when vice_ping says running but nothing happens, when a checkpoint never fires, when deciding whether to recycle or restart VICE, or when a run has to be voided and its evidence recorded.
+---
+
+# Triage a VICE that stopped moving
+
+**Four states look identical from outside, and the intuitive fix destroys a healthy machine in
+one of them.** Work the order below. Do not start with a remedy.
+
+| State | Cheap tell | Safe action |
+|---|---|---|
+| **Merely paused** | Any state read pauses the machine and does not resume it | Resume once. Nothing is wrong |
+| **Stopped itself at your checkpoint** | An armed *stopping* checkpoint on the live IRQ path | Delete/disable the checkpoint. **Never recycle** |
+| **Crashed and respawned** | The proxy raises epoch drift on the next forwarded call | Void the run, reboot from scratch. Already handled for you |
+| **Genuinely wedged** | Two consecutive cycle brackets read exactly `0` | `vice_recycle` with a reason, as a last resort |
+
+```
+mcp__plugin_c64-re-tools_vice__vice_diagnose        # one call, no arguments, answers which of the five it is
+```
+
+`vice_diagnose` returns a closed five-verdict vocabulary — `restarted`, `checkpoint_trap`,
+`wedged`, `stale_read_path`, `live` — with the evidence that produced it. Read its schema for the
+contract; this skill is the judgement around it.
+
+## The order
+
+1. **Call `vice_diagnose` first.** It runs the checks in the cheap-to-expensive order and stops at
+   the first that fires: the epoch comparison costs zero emulator calls, the checkpoint-trap check
+   costs three reads and **no resume**, and only then does it measure a cycle bracket.
+2. **Read the verdict, not the vibe.** Each verdict has exactly one correct response — the table
+   below. A verdict is not a suggestion to try things.
+3. **`diagnose` leaves the machine paused** when it ran a bracket. Resuming is your own next call.
+   Do not treat "still paused afterwards" as a symptom.
+4. **If the verdict is `wedged`, capture evidence before recovering.** `vice_recycle` requires a
+   `reason`, and that string is written verbatim into a permanent, repo-tracked incident record
+   under `.planning/incidents/` **before anything is killed**. That record is the evidence
+   capture — there is no separate ritual to perform, and a lazy `reason` is a lost incident.
+5. **Recycling changes the restart epoch.** Any run in flight is void. Resume from the last
+   recorded milestone snapshot, never from where the wedge happened.
+
+## Verdict → response
+
+| Verdict | What it means | Do |
+|---|---|---|
+| `live` | Cycles advanced | Resume and carry on. Suspect your own checkpoint conditions, not the emulator |
+| `checkpoint_trap` | The machine stopped **itself** at an armed checkpoint | `vice_checkpoint_delete` or `vice_checkpoint_toggle` it, or `vice_execution_step` past it, then re-run `diagnose`. **Recycling here destroys a healthy instance** |
+| `restarted` | The epoch changed — a crash-and-respawn already happened | The run is void. `c64-ram-capture` § Void a run gives the artifact procedure. Reboot from `vice_disk_attach` |
+| `stale_read_path` | Some reads move while others do not | Do not trust any measurement taken across the boundary. Treat as void and re-derive |
+| `wedged` | Two brackets, zero cycles, no epoch change | Last resort: `vice_recycle` with a real reason |
+
+## What is not recoverable
+
+**A checkpoint trap may be the onset without being the whole story.** In the recorded incident
+(`.planning/todos/pending/2026-08-01-vice-registers-frozen-after-reset-during-01-04-task2.md`)
+checkpoint delete, then a soft reset, then a hard reset, then an explicit single step **all** left
+the machine frozen, in sequence. Deleting the checkpoint is not guaranteed to unfreeze anything.
+
+If a bracket still reads zero after the checkpoint is gone, the verdict becomes `wedged` and
+recycle is the fallback after all.
+
+**A stalled session cannot be repaired from inside.** The instance is granted on the session's
+first forwarded call and is that session's for its whole life, so a subagent inherits the same
+stalled instance. Before `vice_recycle` existed, the only exit was abandoning the session; that is
+still the exit if recycle itself cannot land.
+
+## Two traps that read as a wedge and are not
+
+**`vice_ping`'s `execution` field is not a liveness signal.** A stalled host VICE answers
+`status: "ok", execution: "running"` continuously and indefinitely. So does a machine that stopped
+at a checkpoint — VICE's flag flips before the trap fires. Checkpoint bookkeeping
+(`vice_checkpoint_add`/`list`/`delete`) also keeps returning healthy, self-consistent responses
+throughout a real wedge, so "the tools respond" proves nothing.
+
+**A `vice_run_until` on an address that is never reached looks exactly like a wedge.** Its `cycles`
+parameter is documented in its own schema as *"not yet implemented"*, so there is no working
+timeout to bound it. Before concluding anything, check whether you asked the machine to run to an
+address it cannot reach. **Confidence: MEDIUM** — read off the tool schema, not reproduced.
+
+## The manual fallback, when `vice_diagnose` cannot answer
+
+`vice_diagnose` needs the host broker running. When it reports that no `broker.json` record
+exists, that is a **host action for a human** — say so and stop. Nothing container-side may reach
+the emulator by another route.
+
+When the broker is up but you want the raw measurement, the cycle bracket is the only trustworthy
+liveness test, and it is four calls:
+
+1. `vice_cycles_stopwatch` `{action: "reset"}`
+2. `vice_execution_run`
+3. `vice_ping` ×3 — the one call measured non-pausing (986,693 cycles/s while polling vs 991,569
+   fully quiet). Never poll with a state read; those pause and do not resume
+4. `vice_cycles_stopwatch` `{action: "read"}`
+
+**Exactly `0`, twice in a row, is a wedge.** Cycles advancing but far below ~991,000/s is a third
+thing — merely slow, a separate documented hazard measured at ~6,000/s when a loop polls without
+re-resuming. Read all state first, poll with `vice_ping`, resume exactly once at the end.
+
+**Enumerate your own checkpoints before running any bracket.** `vice_checkpoint_list`, then
+resolve the live IRQ handler (`$0314/$0315`, or `$FFFE/$FFFF` when `$01` has the ROMs banked out).
+An armed stopping checkpoint at or inside the live IRQ path, with the PC pinned at or just past
+it, is the trap signature — and reaching that verdict needs **no `vice_execution_run`**, which
+matters because `vice_execution_run` is this project's leading crash suspect (six outages in one
+session, the last three all on that call).
+
+## Provenance
+
+| Claim | Evidence | Confidence |
+|---|---|---|
+| The wedge signature: zero cycles, `ping` says running, PC byte-identical across pause/resume/step | Four live incidents across two disk images and two sessions; three independent zero-cycle brackets in one | HIGH |
+| `vice_ping`'s `execution` field is not liveness | Confirmed twice independently | HIGH |
+| The cycle bracket is the only trustworthy liveness test | Measured both ways — 21,551,860 cycles on a healthy instance, exactly 0 twice on a stalled one | HIGH |
+| Epoch drift is surfaced automatically, and self-heals on the next call | Live, twice; both incidents self-healed within the session | HIGH |
+| Checkpoint delete / reset / step can all fail to recover | One recorded incident, all four attempts in sequence | HIGH, single incident |
+| A checkpoint trap explains all three recorded "silent stalls" | Cross-read, 3/3 correlation, mechanism consistent with every symptom — **not reproduced** | MEDIUM |
+| `vice_diagnose`'s five-verdict path behaves as its schema says | Schema read, and cross-checked against the tracked implementation's own report builders. **Not exercised end to end** | MEDIUM |
+| `vice_run_until` has no working timeout | Its schema says `cycles` is "not yet implemented" | MEDIUM |
+
+Full provenance in `.planning/RE-FINDINGS.md`. **Log a new incident there at the moment you hit
+it**, graded with `Evidence:` and `Confidence:`; promote by re-logging, never by editing a grade.
+VICE MCP defects go to `.planning/todos/pending/` rather than being fixed inline. File-changing
+work enters through a GSD command (`/gsd-quick`).
+
+## Which skill does what
+
+This one owns "is the machine alive, and what may I do to it". It does not restate what the
+others carry.
+
+| Need | Go to |
+|---|---|
+| Every way a live *read* gives a wrong answer | `c64-program-recon` — `references/observation-hazards.md` |
+| Which address to read next, and what the answer rules out | `c64-program-recon` |
+| Voiding a capture, and the artifact rename procedure | `c64-ram-capture` — § Void a run |
+| What a specific address or bit means | `c64-memory-mapping` |
+| **Whether the emulator is wedged, and whether to recycle** | here |
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `vice_diagnose` reports no `broker.json` record exists | The host broker was never started. A human must start it on the host. There is no container-side workaround |
+| The machine is still paused after `vice_diagnose` | Expected — it leaves it paused after a bracket. Resume with `vice_execution_run` |
+| `vice_ping` says `running`, nothing advances | Not liveness. Run a bracket, or call `vice_diagnose` |
+| The checkpoint never fired | Most state reads pause the emulator. Resume exactly once after every read |
+| Zero cycles, and a checkpoint is armed on the IRQ handler | `checkpoint_trap`, not a wedge. Do not recycle |
+| Zero cycles, nothing armed, epoch unchanged | A wedge. `vice_recycle` with a reason that names the evidence |
+| A run "survived a reset" | Distrust it. You cannot read the epoch to confirm — but an unintended respawn inside the bracket would have raised a drift error on the next forwarded call, so absence of that error is the only evidence available |
+| `vice_recycle` refused for a missing reason | It is required, by design — the reason *is* the incident record |
+</content>