@henols/c64-re-tools 0.2.2 → 0.2.3

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

@@ -5,9 +5,8 @@ description: Decide whether a VICE emulator that has stopped responding is genui
 
 # Triage a VICE that stopped moving
 
-**On the fork, four states look identical from outside; on stock, it is five, and the intuitive
-fix destroys a healthy machine in more than one of them.** Work the order below. Do not start with
-a remedy.
+**Five states look identical from outside, and the intuitive fix destroys a healthy machine in
+more than one of them.** Work the order below. Do not start with a remedy.
 
 | State | Cheap tell | Safe action |
 |---|---|---|
@@ -15,22 +14,20 @@ a remedy.
 | **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 |
-| **Monitor held elsewhere (stock only)** | A second client already holds this instance's single binary-monitor socket | Find the other holder. **Never recycle** — the instance is healthy, just claimed elsewhere |
+| **Contended between the two channels** | Two brackets would read zero, but `evidence.channelContention.held` is true and `bracketsRun` is 0 | Wait for the other channel's operation to finish, or find its holder. **Never recycle** — the instance is healthy and is answering |
+| **Monitor held elsewhere** | A second client already holds this instance's single binary-monitor socket | Find the other holder. **Never recycle** — the instance is healthy, just claimed elsewhere |
 
 ```
 mcp__plugin_c64-re-tools_vice__vice_diagnose        # one call, no arguments, answers which state it is
 ```
 
-`vice_diagnose`'s verdict vocabulary differs by backend, because stock VICE's binary monitor
-services exactly one client and the fork's non-pausing `vice_ping` has no stock equivalent (see
-`docs/stock-vice-parity.md` D-03 for the full reasoning). The fork answers `restarted`,
-`checkpoint_trap`, `wedged`, `stale_read_path`, `live`; stock answers `restarted`,
-`checkpoint_trap`, `wedged`, `monitor_held_elsewhere`, `live`. Read the tool's own schema for the
-exact contract on whichever backend is active — as of **07-16 (WR-07)** this instruction is
-finally sound: `tools/list`'s advertised stock schema is the corrected stock manifest entry, not
-the fork's synthetic literal it was silently overwritten by before. Stock `vice_diagnose` can also
-answer a `diagnosis_unavailable` outcome when no verdict could be established at all — that is
-**not** a sixth verdict; see the table below.
+`vice_diagnose`'s verdict vocabulary is `restarted`, `checkpoint_trap`, `wedged`,
+`monitor_held_elsewhere`, `live`. The binary monitor services exactly one client, so a second
+connection sits unserviced in the backlog with no reply and no EOF — a state that looks exactly
+like a wedge unless it is named, hence `monitor_held_elsewhere`. Read the tool's own schema for
+the exact contract: `tools/list`'s advertised schema is the real manifest entry. `vice_diagnose`
+can also answer a `diagnosis_unavailable` outcome when no verdict could be established at all —
+that is **not** a sixth verdict; see the table below.
 
 ## The order
 
@@ -44,12 +41,12 @@ answer a `diagnosis_unavailable` outcome when no verdict could be established at
    `machinePaused` plus `machinePausedSource` (07-15), so you can tell an actual observation from
    an inference: `observed` means a wire `stopped`/`resumed`/`jam` event directly reported the
    state; `structural` means it was inferred from the fact that every stock read halts the machine
-   (D-05), not from a specific event; `no_session` means no session was ever obtained (e.g. the
+   not from a specific event; `no_session` means no session was ever obtained (e.g. the
    `monitor_held_elsewhere` verdict, or a `diagnosis_unavailable` acquisition failure) so no claim
    about pause state is being made at all.
 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
+   `reason`, and that string is written verbatim into a permanent incident record under
+   `.c64-re-tools/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.
@@ -58,17 +55,16 @@ answer a `diagnosis_unavailable` outcome when no verdict could be established at
 
 | Verdict | What it means | Do |
 |---|---|---|
-| `live` | Cycles advanced | Resume and carry on. Suspect your own checkpoint conditions, not the emulator — **unless `evidence.jamObserved` is true** (below) |
+| `live` | Cycles advanced | Resume and carry on. Suspect your own checkpoint conditions, not the emulator — **unless `evidence.jamObserved` is true, or `evidence.channelContention.held` is true** (both below) |
 | `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` **(fork only)** | Some reads move while others do not | Do not trust any measurement taken across the boundary. Treat as void and re-derive |
-| `monitor_held_elsewhere` **(stock only)** | A different client already holds this instance's single binary-monitor slot | Release or identify the other holder. **Never a reason to recycle** — recycling here destroys an instance that is not even wedged |
-| `wedged` | Two brackets, zero cycles, no epoch change | Last resort: `vice_recycle` with a real reason — **but check `evidence.jamObserved` first** (below) |
-| `diagnosis_unavailable` **(stock only, non-verdict outcome — not one of the five)** | No verdict could be established at all; the message starts `vice_diagnose: diagnosis_unavailable (<reason>)`. The machine's state is **UNKNOWN**, not any of the five above | **Do not recycle on this answer alone.** Read the reason class in the message and act on it — see below |
+| `monitor_held_elsewhere` | A different client already holds this instance's single binary-monitor slot | Release or identify the other holder. **Never a reason to recycle** — recycling here destroys an instance that is not even wedged |
+| `wedged` | Two brackets, zero cycles, no epoch change | Last resort: `vice_recycle` with a real reason — **but check `evidence.jamObserved` first** (below). `wedged` is structurally unreachable while `evidence.channelContention.held` is true — reaching `wedged` at all means no monitor channel held halt authority when the brackets ran |
+| `diagnosis_unavailable` **(non-verdict outcome — not one of the five)** | No verdict could be established at all; the message starts `vice_diagnose: diagnosis_unavailable (<reason>)`. The machine's state is **UNKNOWN**, not any of the five above | **Do not recycle on this answer alone.** Read the reason class in the message and act on it — see below |
 
-### `evidence.jamObserved` — read it before acting on `wedged` *or* `live` (stock only, 07-REVIEW WR-04)
+### `evidence.jamObserved` — read it before acting on `wedged` *or* `live`
 
-Every stock `vice_diagnose` verdict carries `evidence.jamObserved` (always present, never omitted).
+Every `vice_diagnose` verdict carries `evidence.jamObserved` (always present, never omitted).
 It is `true` once a `JAM` (0x61) event has arrived on this instance's wire — the 6510 executed an
 illegal opcode and **the CPU is dead regardless of the verdict above**. The flag latches: it stays
 true for the rest of the session.
@@ -85,31 +81,53 @@ rather than a sixth verdict:
 itself is healthy. Treat a `live` verdict with `jamObserved: true` as a false negative on liveness,
 and a `wedged` verdict with it as a false positive on wedging.
 
+### `evidence.channelContention` — read it before acting on `wedged` or `live`
+
+Every `vice_diagnose` verdict carries `evidence.channelContention` (always present, never
+omitted). `held` is `true` when the **other** monitor channel — the binary monitor or the
+`-remotemonitor` text channel, whichever this call is not — currently holds this instance's halt
+authority. When `held` is `true` the verdict is always `live`, with `evidence.bracketsRun: 0` —
+meaning **no cycle bracket was run at all**, not that a bracket ran and read zero. The four detail
+fields name the holder: `channel` (`"binary"` or `"text"`), `operation`, `grantId`, and `heldMs` (a
+non-negative whole-millisecond duration) — all four are `null` when `held` is `false`.
+
+**`channelContention.held: true` is never a reason to call `vice_recycle`** — the instance is
+healthy and is answering; the remedy is to wait for the other channel's operation to finish, or to
+find its holder, exactly as the opening table's contention row says.
+
+Deliberate asymmetry with `jamObserved`, worth stating so a later reader does not "fix" it:
+`jamObserved` qualifies `wedged` in this prose above and still lets that verdict return — the caller
+has to read the evidence and choose not to recycle. `channelContention` is guarded in **code**, in
+`vice_diagnose`'s own handler, and makes `wedged` structurally unreachable while a foreign hold is
+live — the only route to `wedged` is through a liveness bracket, and a bracket only runs when this
+instance's own diagnose call actually held the lock. The two are different on purpose: the cost of
+being wrong about contention is a destructive recycle of a healthy instance, not merely a
+misdiagnosis.
+
 ### `diagnosis_unavailable` — reason classes and response (07-15)
 
 `diagnosis_unavailable` is what `vice_diagnose` answers, on the `isError:true` channel, when it
-could not reach any of the five verdicts above — including a CR-01-class decode failure. It is
+could not reach any of the five verdicts above — including a protocol-decode failure. It is
 never added to the verdict enum and is never grounds to `vice_recycle` by itself: the message says
 so explicitly. **Every** `isError:true` answer this tool can produce carries this prefix — there is
-no unclassified no-verdict path left (07-REVIEW.md WR-02). Eight reason classes exist, each with
+no unclassified no-verdict path left. Eight reason classes exist, each with
 its own next move:
 
 | Reason | What it means | Do |
 |---|---|---|
 | `connection_lost` | The socket died mid-session | Retry once. If it recurs, treat as a real transport problem, not a wedge |
 | `request_timeout` | The wire went silent past the request bound | Retry once. If it recurs, fall to the manual cycle bracket below |
-| `monitor_acquisition_timeout` | Another client holds the monitor and the wait bound expired | Wait for the current holder to release, then retry — this is the bounded sibling of `monitor_held_elsewhere`, not a wedge. **The abandoned acquisition is not cancelled** (07-REVIEW WR-19): a session may be established moments after this answer, so a later-appearing held session is not a ghost. Its real outcome is written to stderr |
+| `monitor_acquisition_timeout` | Another client holds the monitor and the wait bound expired | Wait for the current holder to release, then retry — this is the bounded sibling of `monitor_held_elsewhere`, not a wedge. **The abandoned acquisition is not cancelled**: a session may be established moments after this answer, so a later-appearing held session is not a ghost. Its real outcome is written to stderr |
 | `session_refused` | The broker/lease itself refused the session | Read the raw detail in the message; this is a broker-level problem, not an emulator state |
 | `protocol_decode_failure` | This build answered a frame the client cannot decode | Report it as a tool defect — check `docs/stock-vice-parity.md`'s `CPUHISTORY_GET` history for a known class of this — and fall back to the manual cycle bracket below |
 | `evidence_gathering_failed` | A session was obtained but a read needed to build the verdict failed | `vice_execution_run` may be needed to unstick a stalled read path, then retry |
-| `liveness_unmeasurable` | The liveness bracket could not be **measured at all** — no `CPUHISTORY_GET` (needs VICE ≥ 3.10) and no `LIN`/`CYC` enumerated. **The expected outcome on a stock 3.9-class build**, e.g. every current Debian/Ubuntu package | **Not a wedge and not a tool defect.** A bracket that cannot measure is not one that measured zero. Judge liveness from outside the monitor (screenshot, process state), or use the fork backend. Retrying will produce the same answer |
+| `liveness_unmeasurable` | The liveness bracket could not be **measured at all** — no `CPUHISTORY_GET` (needs VICE ≥ 3.10) and no `LIN`/`CYC` enumerated. **The expected outcome on a stock 3.9-class build**, e.g. every current Debian/Ubuntu package | **Not a wedge and not a tool defect.** A bracket that cannot measure is not one that measured zero. Judge liveness from outside the monitor (screenshot, process state). Retrying will produce the same answer |
 | `unknown` | None of the above classified the failure | Read the raw detail in the message; retry once before escalating |
 
 ## 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
+**A checkpoint trap may be the onset without being the whole story.** In the one recorded
+incident of this kind, 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
@@ -128,40 +146,36 @@ at a checkpoint — VICE's flag flips before the trap fires. Checkpoint bookkeep
 (`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 — on the fork,
-still without a bound.** Its `cycles` parameter is *"not yet implemented"* on both backends, and the
-fork has no timeout to bound the wait for an address either — an unreachable address there is
-unbounded and indistinguishable from a wedge. **On stock, passing `cycles` is now REFUSED rather
-than ignored** (07-REVIEW WR-18) — including alongside `address`, where it used to be silently
-dropped while the answer still reported `reached: true`. Unexpected argument names are refused by
-name too, so a `timeoutMs`/`timeout_ms` typo can no longer run with the default bound in silence.
-**On stock, this is now bounded (D-02):** pass `timeout_ms` (default 30000, clamped to a ceiling of
-600000); an unreachable address returns an explicit, bounded `timedOut: true` answer — with the
-temporary checkpoint already cleaned up — rather than looking like a wedge. **Two further
-behaviours (07-14, closing WR-01/WR-02):** every non-error answer, hit or timeout, carries
-`machineHalted` plus a `machineHaltedNote` naming the resume call — the tool halts the machine on
-every read and says so explicitly. **`machineHalted` is `true` on a hit and on a timeout whose
-cleanup delete was answered (`cleanup: "deleted"` / `"already_gone"`); it is `false` when
-`cleanup: "delete_failed"` or the socket is already gone** and the run-state projection does not
-say `"stopped"`. **Do not read `machineHalted: false` as "still running"** — it means nothing here
-could establish the state, `machineHaltedNote` says so, and the next call should be
-`vice_diagnose`, not `vice_execution_run` (which may not reach the instance at all). And a timeout whose cleanup
-delete lands on an already-gone race no longer asserts `reached: false` outright: it reads the
-program counter and resolves the race (`raceResolved: "pc_at_address"` / `"pc_elsewhere"`), or, if
-the PC read itself fails, omits `reached` entirely and reports `reachedUnknown: true`
-(`raceResolved: "unresolved"`). **An absent `reached` is not "false"** — check `reachedUnknown`
-before assuming a miss. The underlying judgement is unchanged and still the right first question on
-either backend: before concluding anything, check whether you asked the machine to run to an
-address it cannot reach. **Confidence: HIGH on stock for the reach/timeout mechanism** —
-live-confirmed against genuine, unmodified `/usr/bin/x64sc` (VICE 3.9) and `/usr/local/bin/x64sc`
-(VICE 3.10): a real KERNAL address ($EA31) reached within its timeout, an unreached one ($C000)
-timing out with the checkpoint deleted (07-10's live pass). **MEDIUM for the WR-01/WR-02 honesty
-fields above** — unit-proven (`stock-run-until.test.ts`, 21/21, 07-14) but not independently
-re-exercised against a real emulator by this gap-closure batch. **MEDIUM on the fork** — read off
-the tool schema, not reproduced.
-
-**A second binary-monitor client is contention, not a wedge, and it has a cheap tell — stock
-only.** Stock VICE's binary monitor services exactly one client; a second `connect()` sits
+**A `vice_run_until` on an address that is never reached looks exactly like a wedge.** Its
+`cycles` parameter is *"not yet implemented"*, and passing it is REFUSED rather than ignored —
+including alongside `address`, where it used to be silently dropped while the answer still
+reported `reached: true`. Unexpected argument names are refused by name too, so a
+`timeoutMs`/`timeout_ms` typo can no longer run with the default bound in silence. **This is
+bounded:** pass `timeout_ms` (default 30000, clamped to a ceiling of 600000); an unreachable
+address returns an explicit, bounded `timedOut: true` answer — with the temporary checkpoint
+already cleaned up — rather than looking like a wedge. **Two further behaviours:** every
+non-error answer, hit or timeout, carries `machineHalted` plus a `machineHaltedNote` naming the
+resume call — the tool halts the machine on every read and says so explicitly. **`machineHalted`
+is `true` on a hit and on a timeout whose cleanup delete was answered (`cleanup: "deleted"` /
+`"already_gone"`); it is `false` when `cleanup: "delete_failed"` or the socket is already gone**
+and the run-state projection does not say `"stopped"`. **Do not read `machineHalted: false` as
+"still running"** — it means nothing here could establish the state, `machineHaltedNote` says so,
+and the next call should be `vice_diagnose`, not `vice_execution_run` (which may not reach the
+instance at all). And a timeout whose cleanup delete lands on an already-gone race no longer
+asserts `reached: false` outright: it reads the program counter and resolves the race
+(`raceResolved: "pc_at_address"` / `"pc_elsewhere"`), or, if the PC read itself fails, omits
+`reached` entirely and reports `reachedUnknown: true` (`raceResolved: "unresolved"`). **An absent
+`reached` is not "false"** — check `reachedUnknown` before assuming a miss. The underlying
+judgement is unchanged and still the right first question: before concluding anything, check
+whether you asked the machine to run to an address it cannot reach. **Confidence: HIGH for the
+reach/timeout mechanism** — live-confirmed against genuine, unmodified `/usr/bin/x64sc` (VICE
+3.9) and `/usr/local/bin/x64sc` (VICE 3.10): a real KERNAL address ($EA31) reached within its
+timeout, an unreached one ($C000) timing out with the checkpoint deleted. **MEDIUM for the
+honesty fields above** (`machineHalted`, `raceResolved`, `reachedUnknown`) — unit-proven
+(`stock-run-until.test.ts`, 21/21) but not independently re-exercised against a real emulator.
+
+**A second binary-monitor client is contention, not a wedge, and it has a cheap tell.** The
+binary monitor services exactly one client; a second `connect()` sits
 unserviced in the backlog with no reply and no EOF. The discriminator: a socket that *accepts* the
 connection but never answers is contention, not a hung emulator — and the broker itself already
 knows whether it holds a lease on that port, which is the thing a human or agent can actually go
@@ -183,29 +197,22 @@ exists, that is a **host action for a human** — say so and stop. Nothing conta
 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. **On the fork**, 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.
-
-**On stock, there is no non-pausing call at all — any inbound byte halts the machine — so the
-`vice_ping` ×3 poll measures nothing there and is fork-only.** The stock equivalent is the same
-bracket shape with zero calls during the wait:
+liveness test. There is no non-pausing call at all — any inbound byte halts the machine, so a
+`vice_ping` poll during the wait would measure nothing. The procedure is four calls with **zero
+calls during the wait**:
 
 1. `vice_cycles_stopwatch` `{action: "reset"}`
 2. `vice_execution_run`
 3. A real wall-clock wait, with **no calls at all** during it
 4. `vice_cycles_stopwatch` `{action: "read"}`
 
-`vice_diagnose` already runs exactly this bracket internally on stock, so the manual fallback above
-is only for when the broker itself is unreachable and `vice_diagnose` cannot be called at all.
+**Exactly `0`, twice in a row, is a wedge.** Cycles advancing but far below the expected rate for
+a real wait is a third thing — merely slow, a separate documented hazard measured at ~6,000/s
+when a loop polls without re-resuming instead of waiting clean. Never poll with a state read;
+those pause and do not resume.
+
+`vice_diagnose` already runs exactly this bracket internally, so the manual fallback above is
+only for when the broker itself is unreachable and `vice_diagnose` cannot be called at all.
 
 **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).
@@ -225,13 +232,13 @@ session, the last three all on that call).
 | 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 **(fork only)** | Its schema says `cycles` is "not yet implemented"; the fork has no `timeout_ms` bound | MEDIUM |
-| Stock's five-verdict path (`restarted`, `checkpoint_trap`, `wedged`, `monitor_held_elsewhere`, `live`) and its bounded `vice_run_until` | Unit-proven (40/40 `stock-diagnose.test.ts`, 21/21 `stock-run-until.test.ts`, 07-15/07-14). **Live-proven** against genuine `/usr/bin/x64sc` (VICE 3.9) and `/usr/local/bin/x64sc` (VICE 3.10) for `live` (07-10), `checkpoint_trap`, `wedged` (confirmed on both capability routes — `frame_position` on 3.9, `cpu_history` on 3.10) and `restarted` (07-17). `monitor_held_elsewhere`'s **socket-level** contention bound is live-proven (07-13, ~1501-1502ms against a 1500ms bound). **UPDATED 2026-08-18 (quick task 260818-obc, `stock-live-broker-monitor.test.ts`, command `VICE_LIVE_BROKER_BIN=/usr/bin/x64sc` (or `/usr/local/bin/x64sc`) `node --test stock-live-broker-monitor.test.ts`):** both remaining unit-only residuals are now ALSO live-proven, on both binaries, in one real run — the **broker-mediated** `monitor_held_elsewhere` verdict (a real second `claimMonitor()` refusal from a genuine host broker daemon, naming the other real grant's id, settling in 1ms against the 10000ms bound) and the **broker-supervised** (not test-performed) `restarted` respawn (the host broker's OWN crash supervision relaunched the killed instance; `vice_diagnose` answered `restarted` with `baselineEpoch:1`/`currentEpoch:2` at zero-to-minimal emulator cost). `vice_run_until`'s reach/timeout mechanism is live-proven against both binaries (07-10); its WR-01/WR-02 honesty fields (`machineHalted`, `raceResolved`, `reachedUnknown`) remain unit-proven only (07-14) — NOT re-exercised live by this task, no blanket claim made here | HIGH for the five verdicts (including both the broker-mediated `monitor_held_elsewhere` path and the broker-supervised `restarted` path, both now live-proven) and the run_until reach/timeout mechanism; MEDIUM for the run_until honesty fields only, which stay unit-only |
+| Stock's five-verdict path (`restarted`, `checkpoint_trap`, `wedged`, `monitor_held_elsewhere`, `live`) and its bounded `vice_run_until` | Unit-proven (40/40 `stock-diagnose.test.ts`, 21/21 `stock-run-until.test.ts`). **Live-proven** against genuine `/usr/bin/x64sc` (VICE 3.9) and `/usr/local/bin/x64sc` (VICE 3.10) for `live`, `checkpoint_trap`, `wedged` (confirmed on both capability routes — `frame_position` on 3.9, `cpu_history` on 3.10) and `restarted`. `monitor_held_elsewhere`'s **socket-level** contention bound is live-proven (~1501-1502ms against a 1500ms bound). **UPDATED 2026-08-18** (`stock-live-broker-monitor.test.ts`, command `VICE_LIVE_BROKER_BIN=/usr/bin/x64sc` (or `/usr/local/bin/x64sc`) `node --test stock-live-broker-monitor.test.ts`): both remaining unit-only residuals are now ALSO live-proven, on both binaries, in one real run — the **broker-mediated** `monitor_held_elsewhere` verdict (a real second `claimMonitor()` refusal from a genuine host broker daemon, naming the other real grant's id, settling in 1ms against the 10000ms bound) and the **broker-supervised** (not test-performed) `restarted` respawn (the host broker's OWN crash supervision relaunched the killed instance; `vice_diagnose` answered `restarted` with `baselineEpoch:1`/`currentEpoch:2` at zero-to-minimal emulator cost). `vice_run_until`'s reach/timeout mechanism is live-proven against both binaries; its honesty fields (`machineHalted`, `raceResolved`, `reachedUnknown`) remain unit-proven only — NOT re-exercised live, no blanket claim made here | HIGH for the five verdicts (including both the broker-mediated `monitor_held_elsewhere` path and the broker-supervised `restarted` path, both now live-proven) and the run_until reach/timeout mechanism; MEDIUM for the run_until honesty fields only, which stay unit-only |
+| `evidence.channelContention`: always present, `wedged` unreachable while contended, verdict `live` with `bracketsRun:0` while a foreign hold is live | Unit-proven in `stock-diagnose.test.ts` (65/65) — the always-present field on every verdict including both `session === null` paths, the `live`-with-`bracketsRun:0` answer on a foreign hold, `wedged` never reached while contended, and the discriminating-power case where an uncontended double-zero still answers `wedged`. **Live-reproduced against genuine stock `/usr/bin/x64sc` (VICE 3.9) only** — 2026-09-09, command `VICE_LIVE_STOCK_BIN=/usr/bin/x64sc node --test text-monitor-live.test.ts`: with the text channel holding a real `device c:` command, a concurrent `vice_diagnose` answered `verdict=live, evidence={"bracketsRun":0,"jamObserved":false,"channelContention":{"held":true,"channel":"text","operation":"device c:","grantId":"unknown","heldMs":3499}}`; after release, the same call answered `verdict=live, evidence={"bracketsRun":1,...,"channelContention":{"held":false,"channel":null,"operation":null,"grantId":null,"heldMs":null}}`, confirming a real bracket ran once uncontended | **MEDIUM** — a single binary's basis: the text channel is a stock-backend-only capability, so it is proven where it ships (genuine stock `/usr/bin/x64sc`, VICE 3.9), not against a second binary the way the neighbouring HIGH row above is |
 
-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`).
+**Log a new incident in your own project notes at the moment you hit it**, graded the same way
+(`Evidence:` and `Confidence:`); promote a grade by re-logging, never by editing the old entry in
+place. A defect in the `vice` MCP tools themselves is worth filing as a bug rather than working
+around inline — the workaround outlives the memory of why it was needed.
 
 ## Which skill does what
 
@@ -258,5 +265,5 @@ others carry.
 | 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 |
-| `vice_diagnose` answers `monitor_held_elsewhere`, or a call hangs with no reply and no EOF (stock only) | Not a wedge. Find the other client holding this instance's single binary-monitor slot |
+| `vice_diagnose` answers `monitor_held_elsewhere`, or a call hangs with no reply and no EOF | Not a wedge. Find the other client holding this instance's single binary-monitor slot |
 </content>

package/skills/c64-ram-capture/scripts/d64-parse.mjs

@@ -1,243 +0,0 @@
-#!/usr/bin/env node
-// Direct byte-level .d64 parser -- the permanent, sanctioned replacement for
-// the forbidden vice_disk_list tool (T-01-03). Never calls any vice_* tool
-// or touches the emulator at all: this is pure Node over the disk-image
-// bytes, which is why it works whether or not VICE happens to be up.
-//
-// Standard 35-track 1541 layout: BAM at track 18 sector 0, directory chain
-// from track 18 sector 1, four sector-count zones (21/19/18/17 sectors per
-// track). Plain 174848-byte, 35-track, no-error-info images are assumed
-// are plain 174848-byte, 35-track, no-error-info images -- no extended
-// (40-track) or error-byte variants to handle.
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { resolve } from "node:path";
-
-const die = (m) => { console.error(`error: ${m}`); process.exit(1); };
-
-export function readImage(path) {
-  return readFileSync(path);
-}
-
-/** The four sector-count zones of a standard 35-track 1541 image. */
-export function sectorsPerTrack(track) {
-  if (!Number.isInteger(track) || track < 1 || track > 35) {
-    throw new Error(`sectorsPerTrack: track ${track} out of range 1-35`);
-  }
-  if (track <= 17) return 21;
-  if (track <= 24) return 19;
-  if (track <= 30) return 18;
-  return 17;
-}
-
-/** Byte offset of the start of {track, sector} in a flat 35-track image. */
-export function tsToOffset(track, sector) {
-  if (!Number.isInteger(track) || track < 1 || track > 35) {
-    throw new Error(`tsToOffset: track ${track} out of range 1-35`);
-  }
-  const spt = sectorsPerTrack(track);
-  if (!Number.isInteger(sector) || sector < 0 || sector >= spt) {
-    throw new Error(`tsToOffset: sector ${sector} out of range for track ${track} (0-${spt - 1}, this track has ${spt} sectors)`);
-  }
-  let offset = 0;
-  for (let t = 1; t < track; t++) offset += sectorsPerTrack(t) * 256;
-  return offset + sector * 256;
-}
-
-function isInImage(track, sector) {
-  if (!Number.isInteger(track) || track < 1 || track > 35) return false;
-  if (!Number.isInteger(sector) || sector < 0) return false;
-  return sector < sectorsPerTrack(track);
-}
-
-/**
- * Directory/disk-name bytes are PETSCII, padded with $A0. Every byte this
- * project's two disks actually use in a name (A-Z, digits, space, parens)
- * sits at the same code point in PETSCII as in ASCII/Latin-1, so only the
- * $A0 padding needs stripping -- there is no general PETSCII<->ASCII table
- * here, on purpose, since one is not needed for what these disks contain.
- */
-function petsciiName(bytes) {
-  let end = bytes.length;
-  while (end > 0 && bytes[end - 1] === 0xa0) end--;
-  return Buffer.from(bytes.subarray(0, end)).toString("latin1");
-}
-
-const FILE_TYPES = { 0: "DEL", 1: "SEQ", 2: "PRG", 3: "USR", 4: "REL" };
-
-/** Read track 18 sector 0: disk name/id, DOS type, and per-track free counts. */
-export function parseBam(buffer) {
-  const off = tsToOffset(18, 0);
-  const bam = buffer.subarray(off, off + 256);
-
-  const perTrack = [];
-  for (let t = 1; t <= 35; t++) {
-    const eoff = 4 + (t - 1) * 4;
-    perTrack.push({
-      track: t,
-      free: bam[eoff],
-      sectors_per_track: sectorsPerTrack(t),
-      bitmap: [bam[eoff + 1], bam[eoff + 2], bam[eoff + 3]],
-    });
-  }
-
-  const occupiedTracks = perTrack.filter((t) => t.free < t.sectors_per_track).map((t) => t.track);
-  const occupiedRanges = [];
-  for (const t of occupiedTracks) {
-    const last = occupiedRanges[occupiedRanges.length - 1];
-    if (last && last.end === t - 1) last.end = t;
-    else occupiedRanges.push({ start: t, end: t });
-  }
-
-  return {
-    first_dir_track: bam[0],
-    first_dir_sector: bam[1],
-    dos_version: bam[2],
-    disk_name: petsciiName(bam.subarray(0x90, 0x90 + 16)),
-    disk_id: Buffer.from(bam.subarray(0xa2, 0xa2 + 2)).toString("latin1"),
-    dos_type: Buffer.from(bam.subarray(0xa5, 0xa5 + 2)).toString("latin1"),
-    per_track: perTrack,
-    occupied_tracks: occupiedTracks,
-    occupied_ranges: occupiedRanges,
-  };
-}
-
-function isTrackFullyFree(bam, track) {
-  const entry = bam.per_track.find((t) => t.track === track);
-  return !!entry && entry.free === entry.sectors_per_track;
-}
-
-/**
- * Walk the directory chain from track 18 sector 1 (by default). Guards
- * against a malicious or corrupt next-sector pointer with a visited set: a
- * sector, once processed, can never be re-entered, so even a
- * self-referential or cyclic pointer stops the walk (reported in
- * `chain_error`) rather than looping forever.
- *
- * Each entry is flagged `suspicious` -- with the specific reason(s) named,
- * never a bare boolean -- when its block count is 0, when its first
- * track/sector falls outside the image, or when its first track/sector
- * points into a track the BAM reports as entirely free (0 sectors
- * allocated): exactly the signature of a faked directory entry that claims
- * a file that was never actually written to disk.
- */
-export function parseDirectory(buffer, { startTrack = 18, startSector = 1 } = {}) {
-  const bam = parseBam(buffer);
-  const entries = [];
-  const visited = new Set();
-  let track = startTrack;
-  let sector = startSector;
-  let chainError = null;
-
-  for (;;) {
-    const key = `${track}/${sector}`;
-    if (visited.has(key)) {
-      chainError = `directory chain revisited ${key} -- stopped to avoid an infinite loop (self-referential or cyclic next-sector pointer)`;
-      break;
-    }
-    visited.add(key);
-    if (!isInImage(track, sector)) {
-      chainError = `directory chain pointer ${key} is outside the image -- stopped`;
-      break;
-    }
-
-    const off = tsToOffset(track, sector);
-    const sec = buffer.subarray(off, off + 256);
-    const nextTrack = sec[0];
-    const nextSector = sec[1];
-
-    for (let i = 0; i < 8; i++) {
-      const e = sec.subarray(i * 32, i * 32 + 32);
-      const typeByte = e[2];
-      const firstTrack = e[3];
-      const firstSector = e[4];
-      const nameBytes = e.subarray(5, 21);
-      const blocks = e[30] | (e[31] << 8);
-
-      // An all-zero type byte with a blank/padded name is an unused slot,
-      // not a file -- never listed as an entry.
-      const isEmptySlot =
-        typeByte === 0 && firstTrack === 0 && firstSector === 0 &&
-        [...nameBytes].every((b) => b === 0xa0 || b === 0x00);
-      if (isEmptySlot) continue;
-
-      const reasons = [];
-      if (blocks === 0) reasons.push("block count is 0");
-      if (!isInImage(firstTrack, firstSector)) {
-        reasons.push(`first track/sector ${firstTrack}/${firstSector} is outside the image`);
-      } else if (isTrackFullyFree(bam, firstTrack)) {
-        reasons.push(`first track ${firstTrack} is reported entirely free by the BAM (0 sectors allocated) -- the file cannot really start there`);
-      }
-
-      entries.push({
-        dir_track: track,
-        dir_sector: sector,
-        entry_index: i,
-        type: FILE_TYPES[typeByte & 0x0f] ?? `unknown(0x${(typeByte & 0x0f).toString(16)})`,
-        closed: !!(typeByte & 0x80),
-        locked: !!(typeByte & 0x40),
-        name: petsciiName(nameBytes),
-        first_track: firstTrack,
-        first_sector: firstSector,
-        blocks,
-        suspicious: reasons.length > 0,
-        suspicious_reasons: reasons,
-      });
-    }
-
-    if (nextTrack === 0) break; // end of chain, by DOS convention
-    track = nextTrack;
-    sector = nextSector;
-  }
-
-  return { entries, chain_error: chainError };
-}
-
-// -------------------------------------------------------------------- CLI
-
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  const [cmd, ...rest] = process.argv.slice(2);
-  const opt = (name, fallback) => {
-    const i = rest.indexOf(`--${name}`);
-    return i === -1 ? fallback : rest[i + 1];
-  };
-  const jsonFlag = rest.includes("--json");
-
-  function run() {
-    if (cmd !== "directory" && cmd !== "bam") {
-      console.log(`usage: node ${fileURLToPath(import.meta.url)} <directory|bam> --image <path.d64> [--json]`);
-      process.exitCode = cmd ? 1 : 0;
-      return;
-    }
-    const imagePath = opt("image");
-    if (!imagePath) die(`usage: ${cmd} --image <path.d64> [--json]`);
-    const buffer = readImage(resolve(imagePath));
-
-    if (cmd === "directory") {
-      const result = parseDirectory(buffer);
-      if (jsonFlag) {
-        console.log(JSON.stringify(result, null, 2));
-      } else {
-        for (const e of result.entries) {
-          const flag = e.suspicious ? ` SUSPICIOUS: ${e.suspicious_reasons.join("; ")}` : "";
-          console.log(`${e.type} "${e.name}" first=${e.first_track}/${e.first_sector} blocks=${e.blocks}${flag}`);
-        }
-        if (result.chain_error) console.log(`chain error: ${result.chain_error}`);
-      }
-      return;
-    }
-
-    const bam = parseBam(buffer);
-    if (jsonFlag) {
-      console.log(JSON.stringify(bam, null, 2));
-    } else {
-      console.log(`disk name: "${bam.disk_name}"  id: ${bam.disk_id}  dos type: ${bam.dos_type}`);
-      console.log(`first dir sector: ${bam.first_dir_track}/${bam.first_dir_sector}`);
-      console.log(
-        `occupied track ranges: ${bam.occupied_ranges.map((r) => (r.start === r.end ? `${r.start}` : `${r.start}-${r.end}`)).join(", ")}`
-      );
-    }
-  }
-
-  run();
-}