@henols/c64-re-tools 0.2.4 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +2 -2
- package/skills/acme-build/SKILL.md +22 -22
- package/skills/c64-disk-access/SKILL.md +49 -46
- package/skills/c64-memory-mapping/SKILL.md +71 -70
- package/skills/c64-petcat/SKILL.md +11 -11
- package/skills/c64-program-recon/SKILL.md +109 -105
- package/skills/c64-program-recon/references/control-flow.md +13 -13
- package/skills/c64-program-recon/references/graphics.md +6 -6
- package/skills/c64-program-recon/references/observation-hazards.md +7 -7
- package/skills/c64-program-recon/references/reconstruction.md +6 -6
- package/skills/c64-program-recon/references/sound-and-input.md +8 -8
- package/skills/c64-program-recon/references/tool-selection.md +11 -11
- package/skills/c64-program-recon/templates/memory-map.template.md +16 -12
- package/skills/c64-provenance-diff/SKILL.md +43 -43
- package/skills/c64-ram-capture/SKILL.md +96 -45
- package/skills/c64-ram-capture/scripts/compare-cross-binary.mjs +525 -0
- package/skills/c64-ram-capture/templates/capture-record.template.md +11 -11
- package/skills/c64-ram-capture/transients/README.md +11 -10
- package/skills/routine-queue-walker/SKILL.md +205 -176
- package/skills/vice-wedge-triage/SKILL.md +48 -48
|
@@ -5,8 +5,8 @@ description: Decide whether a VICE emulator that has stopped responding is genui
|
|
|
5
5
|
|
|
6
6
|
# Triage a VICE that stopped moving
|
|
7
7
|
|
|
8
|
-
**Five states look identical from outside, and the intuitive
|
|
9
|
-
more than one of them.** Work the order below. Do not start with a remedy.
|
|
8
|
+
**Five states look identical from outside, and the intuitive correction destroys a healthy machine
|
|
9
|
+
in more than one of them.** Work the order below. Do not start with a remedy.
|
|
10
10
|
|
|
11
11
|
| State | Cheap tell | Safe action |
|
|
12
12
|
|---|---|---|
|
|
@@ -24,10 +24,10 @@ mcp__plugin_c64-re-tools_vice__vice_diagnose # one call, no arguments, an
|
|
|
24
24
|
`vice_diagnose`'s verdict vocabulary is `restarted`, `checkpoint_trap`, `wedged`,
|
|
25
25
|
`monitor_held_elsewhere`, `live`. The binary monitor services exactly one client, so a second
|
|
26
26
|
connection sits unserviced in the backlog with no reply and no EOF — a state that looks exactly
|
|
27
|
-
like a wedge unless
|
|
28
|
-
the exact contract: `tools/list`'s advertised schema is the real manifest entry.
|
|
29
|
-
can also answer a `diagnosis_unavailable` outcome when no verdict could be
|
|
30
|
-
|
|
27
|
+
like a wedge unless `vice_diagnose` names it as `monitor_held_elsewhere`. Read the tool's own
|
|
28
|
+
schema for the exact contract: `tools/list`'s advertised schema is the real manifest entry.
|
|
29
|
+
`vice_diagnose` can also answer a `diagnosis_unavailable` outcome when no verdict could be
|
|
30
|
+
established at all. That is **not** a sixth verdict. See the table below.
|
|
31
31
|
|
|
32
32
|
## The order
|
|
33
33
|
|
|
@@ -38,15 +38,15 @@ that is **not** a sixth verdict; see the table below.
|
|
|
38
38
|
below. A verdict is not a suggestion to try things.
|
|
39
39
|
3. **`diagnose` leaves the machine paused** when it ran a bracket. Resuming is your own next call.
|
|
40
40
|
Do not treat "still paused afterwards" as a symptom. Every established verdict also reports
|
|
41
|
-
`machinePaused` plus `machinePausedSource` (07-15)
|
|
42
|
-
an inference
|
|
43
|
-
state
|
|
44
|
-
not
|
|
45
|
-
`monitor_held_elsewhere` verdict, or a `diagnosis_unavailable`
|
|
46
|
-
about pause state
|
|
41
|
+
`machinePaused` plus `machinePausedSource` (07-15). These fields let you tell an actual
|
|
42
|
+
observation from an inference. `observed` means a wire `stopped`/`resumed`/`jam` event directly
|
|
43
|
+
reported the state. `structural` means the diagnosis inferred the state. It used the fact that
|
|
44
|
+
every stock read stops the machine, not a specific event. `no_session` means no session was
|
|
45
|
+
ever obtained — for example, the `monitor_held_elsewhere` verdict, or a `diagnosis_unavailable`
|
|
46
|
+
acquisition failure. In that case, the answer makes no claim about pause state at all.
|
|
47
47
|
4. **If the verdict is `wedged`, capture evidence before recovering.** `vice_recycle` requires a
|
|
48
|
-
`reason
|
|
49
|
-
`.c64-re-tools/incidents/` **before
|
|
48
|
+
`reason`. It writes that string verbatim into a permanent incident record under
|
|
49
|
+
`.c64-re-tools/incidents/` **before the recycle kills anything**. That record is the evidence
|
|
50
50
|
capture — there is no separate ritual to perform, and a lazy `reason` is a lost incident.
|
|
51
51
|
5. **Recycling changes the restart epoch.** Any run in flight is void. Resume from the last
|
|
52
52
|
recorded milestone snapshot, never from where the wedge happened.
|
|
@@ -60,7 +60,7 @@ that is **not** a sixth verdict; see the table below.
|
|
|
60
60
|
| `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` |
|
|
61
61
|
| `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 |
|
|
62
62
|
| `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 |
|
|
63
|
-
| `diagnosis_unavailable` **(non-verdict outcome — not one of the five)** | No verdict could be established at all
|
|
63
|
+
| `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 |
|
|
64
64
|
|
|
65
65
|
### `evidence.jamObserved` — read it before acting on `wedged` *or* `live`
|
|
66
66
|
|
|
@@ -77,7 +77,7 @@ rather than a sixth verdict:
|
|
|
77
77
|
| `-jamaction 2` (Monitor) | `wedged` | The machine stopped, so both brackets read zero advance | **`vice_machine_reset`, not `vice_recycle`.** Recycling destroys an instance a reset recovers — the same trap as `checkpoint_trap` |
|
|
78
78
|
| default (continue) | `live` | The emulator keeps burning cycles refetching the same opcode, so both brackets **advance** | **`vice_machine_reset`.** "Cycles advanced" is true and irrelevant: the machine will never execute another instruction |
|
|
79
79
|
|
|
80
|
-
**`jamObserved: true` is never a reason to recycle.** A
|
|
80
|
+
**`jamObserved: true` is never a reason to recycle.** A reset recovers a jam. The instance
|
|
81
81
|
itself is healthy. Treat a `live` verdict with `jamObserved: true` as a false negative on liveness,
|
|
82
82
|
and a `wedged` verdict with it as a false positive on wedging.
|
|
83
83
|
|
|
@@ -87,18 +87,18 @@ Every `vice_diagnose` verdict carries `evidence.channelContention` (always prese
|
|
|
87
87
|
omitted). `held` is `true` when the **other** monitor channel — the binary monitor or the
|
|
88
88
|
`-remotemonitor` text channel, whichever this call is not — currently holds this instance's halt
|
|
89
89
|
authority. When `held` is `true` the verdict is always `live`, with `evidence.bracketsRun: 0` —
|
|
90
|
-
meaning **no cycle bracket
|
|
90
|
+
meaning **no cycle bracket ran at all**, not that a bracket ran and read zero. The four detail
|
|
91
91
|
fields name the holder: `channel` (`"binary"` or `"text"`), `operation`, `grantId`, and `heldMs` (a
|
|
92
92
|
non-negative whole-millisecond duration) — all four are `null` when `held` is `false`.
|
|
93
93
|
|
|
94
|
-
**`channelContention.held: true` is never a reason to call `vice_recycle
|
|
95
|
-
healthy and is answering
|
|
94
|
+
**`channelContention.held: true` is never a reason to call `vice_recycle`.** The instance is
|
|
95
|
+
healthy and is answering. The remedy is to wait for the other channel's operation to finish, or to
|
|
96
96
|
find its holder, exactly as the opening table's contention row says.
|
|
97
97
|
|
|
98
|
-
Deliberate asymmetry with `jamObserved`, worth stating so a later reader does not "
|
|
98
|
+
Deliberate asymmetry with `jamObserved`, worth stating so a later reader does not "correct" it:
|
|
99
99
|
`jamObserved` qualifies `wedged` in this prose above and still lets that verdict return — the caller
|
|
100
|
-
has to read the evidence and choose not to recycle. `
|
|
101
|
-
`
|
|
100
|
+
has to read the evidence and choose not to recycle. `vice_diagnose`'s own handler guards
|
|
101
|
+
`channelContention` in **code** and makes `wedged` structurally unreachable while a foreign hold is
|
|
102
102
|
live — the only route to `wedged` is through a liveness bracket, and a bracket only runs when this
|
|
103
103
|
instance's own diagnose call actually held the lock. The two are different on purpose: the cost of
|
|
104
104
|
being wrong about contention is a destructive recycle of a healthy instance, not merely a
|
|
@@ -117,12 +117,12 @@ its own next move:
|
|
|
117
117
|
|---|---|---|
|
|
118
118
|
| `connection_lost` | The socket died mid-session | Retry once. If it recurs, treat as a real transport problem, not a wedge |
|
|
119
119
|
| `request_timeout` | The wire went silent past the request bound | Retry once. If it recurs, fall to the manual cycle bracket below |
|
|
120
|
-
| `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.
|
|
121
|
-
| `session_refused` | The broker/lease itself refused the session | Read the raw detail in the message
|
|
122
|
-
| `protocol_decode_failure` | This build answered a frame the client cannot decode | Report it as a tool defect
|
|
123
|
-
| `evidence_gathering_failed` |
|
|
120
|
+
| `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. The system writes its real outcome to stderr |
|
|
121
|
+
| `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 |
|
|
122
|
+
| `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. Then fall back to the manual cycle bracket below |
|
|
123
|
+
| `evidence_gathering_failed` | `vice_diagnose` obtained a session, but a read needed to build the verdict failed | `vice_execution_run` may be needed to unstick a stalled read path, then retry |
|
|
124
124
|
| `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 |
|
|
125
|
-
| `unknown` | None of the above classified the failure | Read the raw detail in the message
|
|
125
|
+
| `unknown` | None of the above classified the failure | Read the raw detail in the message. Retry once before escalating |
|
|
126
126
|
|
|
127
127
|
## What is not recoverable
|
|
128
128
|
|
|
@@ -133,10 +133,10 @@ the machine frozen, in sequence. Deleting the checkpoint is not guaranteed to un
|
|
|
133
133
|
If a bracket still reads zero after the checkpoint is gone, the verdict becomes `wedged` and
|
|
134
134
|
recycle is the fallback after all.
|
|
135
135
|
|
|
136
|
-
**A stalled session cannot be
|
|
136
|
+
**A stalled session cannot be corrected from inside.** The instance is granted on the session's
|
|
137
137
|
first forwarded call and is that session's for its whole life, so a subagent inherits the same
|
|
138
|
-
stalled instance. Before `vice_recycle` existed, the only exit was abandoning the session
|
|
139
|
-
still the exit if recycle itself cannot land.
|
|
138
|
+
stalled instance. Before `vice_recycle` existed, the only exit was abandoning the session. That
|
|
139
|
+
is still the exit if recycle itself cannot land.
|
|
140
140
|
|
|
141
141
|
## Two traps that read as a wedge and are not
|
|
142
142
|
|
|
@@ -147,17 +147,17 @@ at a checkpoint — VICE's flag flips before the trap fires. Checkpoint bookkeep
|
|
|
147
147
|
throughout a real wedge, so "the tools respond" proves nothing.
|
|
148
148
|
|
|
149
149
|
**A `vice_run_until` on an address that is never reached looks exactly like a wedge.** Its
|
|
150
|
-
`cycles` parameter is *"not yet implemented"*, and
|
|
150
|
+
`cycles` parameter is *"not yet implemented"*, and the tool REFUSES it rather than ignoring it —
|
|
151
151
|
including alongside `address`, where it used to be silently dropped while the answer still
|
|
152
|
-
reported `reached: true`.
|
|
152
|
+
reported `reached: true`. The tool refuses unexpected argument names by name too, so a
|
|
153
153
|
`timeoutMs`/`timeout_ms` typo can no longer run with the default bound in silence. **This is
|
|
154
|
-
bounded:** pass `timeout_ms` (default 30000, clamped to a ceiling of 600000)
|
|
154
|
+
bounded:** pass `timeout_ms` (default 30000, clamped to a ceiling of 600000). An unreachable
|
|
155
155
|
address returns an explicit, bounded `timedOut: true` answer — with the temporary checkpoint
|
|
156
156
|
already cleaned up — rather than looking like a wedge. **Two further behaviours:** every
|
|
157
157
|
non-error answer, hit or timeout, carries `machineHalted` plus a `machineHaltedNote` naming the
|
|
158
158
|
resume call — the tool halts the machine on every read and says so explicitly. **`machineHalted`
|
|
159
|
-
is `true` on a hit and on a timeout whose cleanup delete
|
|
160
|
-
`"already_gone"`)
|
|
159
|
+
is `true` on a hit and on a timeout whose cleanup delete got an answer** (`cleanup: "deleted"` /
|
|
160
|
+
`"already_gone"`). **It is `false` when `cleanup: "delete_failed"` or the socket is already gone**
|
|
161
161
|
and the run-state projection does not say `"stopped"`. **Do not read `machineHalted: false` as
|
|
162
162
|
"still running"** — it means nothing here could establish the state, `machineHaltedNote` says so,
|
|
163
163
|
and the next call should be `vice_diagnose`, not `vice_execution_run` (which may not reach the
|
|
@@ -166,16 +166,16 @@ asserts `reached: false` outright: it reads the program counter and resolves the
|
|
|
166
166
|
(`raceResolved: "pc_at_address"` / `"pc_elsewhere"`), or, if the PC read itself fails, omits
|
|
167
167
|
`reached` entirely and reports `reachedUnknown: true` (`raceResolved: "unresolved"`). **An absent
|
|
168
168
|
`reached` is not "false"** — check `reachedUnknown` before assuming a miss. The underlying
|
|
169
|
-
judgement
|
|
169
|
+
judgement stays the same and is still the right first question: before concluding anything, check
|
|
170
170
|
whether you asked the machine to run to an address it cannot reach. **Confidence: HIGH for the
|
|
171
|
-
reach/timeout mechanism** — live-
|
|
171
|
+
reach/timeout mechanism** — live-checked against genuine, unmodified `/usr/bin/x64sc` (VICE
|
|
172
172
|
3.9) and `/usr/local/bin/x64sc` (VICE 3.10): a real KERNAL address ($EA31) reached within its
|
|
173
173
|
timeout, an unreached one ($C000) timing out with the checkpoint deleted. **MEDIUM for the
|
|
174
174
|
honesty fields above** (`machineHalted`, `raceResolved`, `reachedUnknown`) — unit-proven
|
|
175
175
|
(`stock-run-until.test.ts`, 21/21) but not independently re-exercised against a real emulator.
|
|
176
176
|
|
|
177
177
|
**A second binary-monitor client is contention, not a wedge, and it has a cheap tell.** The
|
|
178
|
-
binary monitor services exactly one client
|
|
178
|
+
binary monitor services exactly one client. A second `connect()` sits
|
|
179
179
|
unserviced in the backlog with no reply and no EOF. The discriminator: a socket that *accepts* the
|
|
180
180
|
connection but never answers is contention, not a hung emulator — and the broker itself already
|
|
181
181
|
knows whether it holds a lease on that port, which is the thing a human or agent can actually go
|
|
@@ -208,8 +208,8 @@ calls during the wait**:
|
|
|
208
208
|
|
|
209
209
|
**Exactly `0`, twice in a row, is a wedge.** Cycles advancing but far below the expected rate for
|
|
210
210
|
a real wait is a third thing — merely slow, a separate documented hazard measured at ~6,000/s
|
|
211
|
-
when a loop polls without re-resuming instead of waiting clean. Never poll with a state read
|
|
212
|
-
|
|
211
|
+
when a loop polls without re-resuming instead of waiting clean. Never poll with a state read.
|
|
212
|
+
Those pause and do not resume.
|
|
213
213
|
|
|
214
214
|
`vice_diagnose` already runs exactly this bracket internally, so the manual fallback above is
|
|
215
215
|
only for when the broker itself is unreachable and `vice_diagnose` cannot be called at all.
|
|
@@ -225,18 +225,18 @@ session, the last three all on that call).
|
|
|
225
225
|
|
|
226
226
|
| Claim | Evidence | Confidence |
|
|
227
227
|
|---|---|---|
|
|
228
|
-
| 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
|
|
229
|
-
| `vice_ping`'s `execution` field is not liveness |
|
|
228
|
+
| 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 |
|
|
229
|
+
| `vice_ping`'s `execution` field is not liveness | Checked twice independently | HIGH |
|
|
230
230
|
| 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 |
|
|
231
|
-
| Epoch drift is surfaced automatically, and self-heals on the next call | Live, twice
|
|
231
|
+
| Epoch drift is surfaced automatically, and self-heals on the next call | Live, twice. Both incidents self-healed within the session | HIGH |
|
|
232
232
|
| Checkpoint delete / reset / step can all fail to recover | One recorded incident, all four attempts in sequence | HIGH, single incident |
|
|
233
233
|
| A checkpoint trap explains all three recorded "silent stalls" | Cross-read, 3/3 correlation, mechanism consistent with every symptom — **not reproduced** | MEDIUM |
|
|
234
234
|
| `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 |
|
|
235
|
-
| 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`
|
|
236
|
-
| `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
|
|
235
|
+
| 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`, and `wedged`, and also for `restarted`. The first three were checked on both capability routes — `frame_position` on 3.9, `cpu_history` on 3.10. `monitor_held_elsewhere`'s **socket-level** contention bound is live-proven (~1501-1502ms against a 1500ms bound). This was **UPDATED 2026-08-18**, using `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 first is the **broker-mediated** `monitor_held_elsewhere` verdict. It is a real second `claimMonitor()` refusal from a genuine host broker daemon, naming the other real grant's id. It settled in 1ms against the 10000ms bound. The second is 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 |
|
|
236
|
+
| `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. This covers the `live`-with-`bracketsRun:0` answer on a foreign hold, and the fact that `wedged` is never reached while contended. It also covers 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, using 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}}`, showing 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). It is not proven against a second binary, the way the neighbouring HIGH row above is |
|
|
237
237
|
|
|
238
238
|
**Log a new incident in your own project notes at the moment you hit it**, graded the same way
|
|
239
|
-
(`Evidence:` and `Confidence:`)
|
|
239
|
+
(`Evidence:` and `Confidence:`). Promote a grade by re-logging, never by editing the old entry in
|
|
240
240
|
place. A defect in the `vice` MCP tools themselves is worth filing as a bug rather than working
|
|
241
241
|
around inline — the workaround outlives the memory of why it was needed.
|
|
242
242
|
|
|
@@ -255,7 +255,7 @@ others carry.
|
|
|
255
255
|
|
|
256
256
|
## Troubleshooting
|
|
257
257
|
|
|
258
|
-
| Symptom |
|
|
258
|
+
| Symptom | Correct |
|
|
259
259
|
|---|---|
|
|
260
260
|
| `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 |
|
|
261
261
|
| The machine is still paused after `vice_diagnose` | Expected — it leaves it paused after a bracket. Resume with `vice_execution_run` |
|
|
@@ -263,7 +263,7 @@ others carry.
|
|
|
263
263
|
| The checkpoint never fired | Most state reads pause the emulator. Resume exactly once after every read |
|
|
264
264
|
| Zero cycles, and a checkpoint is armed on the IRQ handler | `checkpoint_trap`, not a wedge. Do not recycle |
|
|
265
265
|
| Zero cycles, nothing armed, epoch unchanged | A wedge. `vice_recycle` with a reason that names the evidence |
|
|
266
|
-
| A run "survived a reset" | Distrust it. You cannot read the epoch to
|
|
266
|
+
| A run "survived a reset" | Distrust it. You cannot read the epoch to check. But an unintended respawn inside the bracket would have raised a drift error on the next forwarded call. So the absence of that error is the only evidence available |
|
|
267
267
|
| `vice_recycle` refused for a missing reason | It is required, by design — the reason *is* the incident record |
|
|
268
268
|
| `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 |
|
|
269
269
|
</content>
|