@henols/vice-mcp 0.2.3 → 0.2.5

package/stock-derived.ts

@@ -106,6 +106,7 @@ export const STOCK_DERIVED_TOOLS: ReadonlySet<string> = new Set([
   "vice_profile_flat", // Plan 42-07, PARSE-02 -- text-channel flat-profile tool, needsSession:false (text-tools.ts)
   "vice_backtrace", // Plan 42-07, PARSE-02/D-42-4 -- text-channel backtrace tool, shares the fork's own name, needsSession:false (text-tools.ts)
   "vice_io_registers", // Plan 42-07, PARSE-02 -- text-channel register-decode tool, needsSession:false (text-tools.ts)
+  "vice_program_load", // Plan 50-04, route-d -- text-channel program-load tool for the committed hazard-subject fixture, needsSession:false (text-tools.ts)
 ]);
 
 /**

package/stock-dispatch.ts

@@ -75,7 +75,7 @@ import { handleCyclesStopwatch, forgetTimingForOtherTargets } from "./stock-timi
 import { handleRunUntil } from "./stock-run-until.ts";
 import { handleDiagnoseStock } from "./stock-diagnose.ts";
 import { handleRecycleStock } from "./stock-recycle.ts";
-import { handleDeviceConsole, handleWarpSet, handleMemmapShow, handleMemmapZap, handleCpuHistory, handleProfileFlat, handleBacktrace, handleIoRegisters } from "./text-tools.ts";
+import { handleDeviceConsole, handleWarpSet, handleMemmapShow, handleMemmapZap, handleCpuHistory, handleProfileFlat, handleBacktrace, handleIoRegisters, handleProgramLoad } from "./text-tools.ts";
 
 // Re-exported so Phase 2's existing import surface (and its 921-line test
 // file) keeps working unchanged -- these four names used to be DEFINED
@@ -832,6 +832,10 @@ const STOCK_DISPATCH_TABLE: Record<string, StockHandler> = {
   vice_profile_flat: withDerivedTool("vice_profile_flat", { needsSession: false }, handleProfileFlat),
   vice_backtrace: withDerivedTool("vice_backtrace", { needsSession: false }, handleBacktrace),
   vice_io_registers: withDerivedTool("vice_io_registers", { needsSession: false }, handleIoRegisters),
+  // Plan 50-04 (route-d): reaches text-protocol.ts's widened `load` verb --
+  // same needsSession:false reasoning as its five siblings above (each
+  // resolves its own lease and takes only the text channel's own lock).
+  vice_program_load: withDerivedTool("vice_program_load", { needsSession: false }, handleProgramLoad),
 };
 
 /** Looks up the table entry for `name` -- `undefined` on a miss, never a

package/text-protocol.ts

@@ -51,24 +51,33 @@
 //     outbound command must come from TEXT_COMMAND_ALLOWLIST below;
 //     command() refuses anything else BY NAME, before a single byte reaches
 //     the socket (D-01). The ONE stated, bounded exception (D-42-1, plan
-//     42-04): TEXT_COMMAND_PARAM_SPECS lets exactly three of those eight
-//     verbs also carry a caller-chosen value, but that value is always a
-//     typed, bounded number -- never a string, never a rest-of-line
-//     passthrough, never a `params` field -- validated and rendered by
-//     buildTextCommand(), the ONE place such a string is built, and
-//     accepted as dialable only when isDialableTextCommandForVerb()'s own
-//     re-render round trip reproduces it byte-for-byte. This does not
+//     42-04, widened plan 50-04): TEXT_COMMAND_PARAM_SPECS lets exactly
+//     four of the allowlisted verbs also carry a caller-chosen value, but
+//     that value is always a typed, bounded number -- never a string, never
+//     a rest-of-line passthrough, never a `params` field -- validated and
+//     rendered by buildTextCommand(), the ONE place such a string is built,
+//     and accepted as dialable only when isDialableTextCommandForVerb()'s
+//     own re-render round trip reproduces it byte-for-byte. This does not
 //     widen what "free-text command" means above; it narrows one bounded
-//     numeric slot per verb.
+//     numeric slot per verb. Plan 50-04's `load` entry is the sole
+//     exception to "never a string": the FILENAME half of that one entry is
+//     not a caller-supplied string at all -- it is baked into the verb's
+//     own frozen identity, a reviewed literal chosen by this file, never a
+//     value a caller passes in. Only the device NUMBER is the caller's
+//     bounded value, exactly like every other entry in this table. See
+//     TEXT_COMMAND_PARAM_SPECS's own `load` entry below for the full
+//     rationale.
 //   - Never frame a response by a timeout, a byte count, or any fallback
 //     that hands back a plausible-looking partial payload. A response that
 //     cannot be honestly framed refuses by name (TextFramingError), naming
 //     what was actually observed -- never a guess.
 import { EventEmitter } from "node:events";
 import net from "node:net";
+import { join } from "node:path";
 
 import { ViceError } from "./vice-errors.ts";
 import { acquireChannelLock, currentChannelLockHolder } from "./channel-lock.ts";
+import { repoRoot } from "./repo-root.ts";
 
 // ---------------------------------------------------------------------------
 // The prompt terminator and the closed command allowlist.
@@ -117,10 +126,38 @@ export const PROMPT_RE = /\(C:\$[0-9A-Fa-f]{4}\)\s*$/;
  * subtracting a prior baseline after the fact. The sibling verb `memmapsave`
  * is deliberately NOT added here -- it writes a host file, and this
  * allowlist's own membership test (`text-protocol.test.ts`) refuses any
- * entry whose name matches the pattern that spells the words `load` or
- * `save`, the same file-touching-verb rule `device c:`, `warp on/off`,
+ * entry whose name matches the pattern that spells the word `save`, the
+ * same file-touching-WRITE-verb rule `device c:`, `warp on/off`,
  * `memmapshow`, `prof flat`, `chis`, `bt`, `io` and `prof on/off` already
  * satisfy.
+ *
+ * `load` (plan 50-04, 2026-09-15, a conscious, measured widening, and the
+ * FIRST one that reverses part of the load/save refusal rather than adding
+ * a fresh always-safe verb): Phase 50 needed a way to get a committed
+ * `.prg` into a running stock VICE for a live capture, and the project's
+ * only other route -- `vice_autostart` against a bare `.prg` -- was
+ * MEASURED to fail with monitor error `0x8f` (see
+ * `fixtures/hazard-subject/FIXTURE-DESIGN.md`), with no committed `.d64`
+ * writer anywhere in this tree to fall back to. The developer was shown
+ * three routes that added no capability, a hand-authored disk image, or a
+ * new file-WRITING host-tool capability -- and chose a FOURTH: the text
+ * monitor's own `load` command (`load "<filename>" <device> [<address>]`,
+ * VICE Manual ch. 12, `mon_parse.y`'s `disk_rules` grammar), because it
+ * READS a host file and writes nothing back to the host. That is the
+ * load-bearing distinction this widening rests on: this allowlist's own
+ * rule above was never "no `load` or `save`" in principle, it was "no verb
+ * that touches a host file" -- and `memmapsave`'s rejection above is a
+ * WRITE. `load` is a READ, and the developer judged the original rule to
+ * have over-reached for the read direction (recorded in
+ * `.planning/phases/50-equivalence-and-modifiability/evidence/LOAD-ROUTE.md`).
+ * This is NOT a general "load anything" capability: the entry added to
+ * TEXT_COMMAND_PARAM_SPECS below bakes in the ONE committed fixture path
+ * this phase's tracer plan targets as part of the verb's own frozen
+ * identity, never a caller-supplied filename -- and, since plan 50-05, one
+ * such frozen entry per member of the closed HAZARD_SUBJECT_PRG_RELPATHS
+ * table, still never a caller-supplied filename. See those entries' own
+ * comment for why a caller still cannot choose what gets loaded. `save`
+ * remains refused exactly as before; only the read direction moved.
  */
 export const TEXT_COMMAND_ALLOWLIST = Object.freeze([
   "device c:",
@@ -139,17 +176,24 @@ export const TEXT_COMMAND_ALLOWLIST = Object.freeze([
 export type TextCommand = (typeof TEXT_COMMAND_ALLOWLIST)[number];
 
 // ---------------------------------------------------------------------------
-// Parameterized commands (D-42-1, plan 42-04). Three of the eight
-// allowlisted verbs -- "chis", "prof flat", "io" -- were captured on the
+// Parameterized commands (D-42-1, plan 42-04, widened plan 50-04). Three of
+// the allowlisted verbs -- "chis", "prof flat", "io" -- were captured on the
 // real wire carrying a caller-chosen value ("chis 4", "prof flat 5",
 // "io $d020" -- see fixtures/textmon/{cpu-history,flat-profile,
 // register-decode}-stock.json's own "command" field), so a bare literal
 // alone cannot reach them meaningfully. TEXT_COMMAND_ALLOWLIST above is NOT
-// widened for this: it stays exactly the eight frozen literals, and its own
-// membership assertion is unaffected. TEXT_COMMAND_PARAM_SPECS is a SIBLING
-// table describing, for the subset of verbs that take one, the bounded
-// typed value each accepts and the ONE renderer that turns a validated
-// value into the exact command string VICE was captured accepting.
+// widened for this: its own membership assertion is unaffected by any entry
+// here. TEXT_COMMAND_PARAM_SPECS is a SIBLING table describing, for the
+// subset of verbs that take one, the bounded typed value each accepts and
+// the ONE renderer that turns a validated value into the exact command
+// string VICE accepts. Plan 50-04 adds a "load" entry, and plan 50-05 turns
+// that single entry into one DERIVED entry per committed subject (see
+// HAZARD_SUBJECT_PRG_RELPATHS) -- see those entries' own comment below and
+// TEXT_COMMAND_ALLOWLIST's doc comment above for the full
+// rationale; unlike the first three, this one is not sourced from a
+// committed live-captured fixture (no live capture was run to add it -- the
+// syntax is sourced directly from VICE's own upstream grammar and manual,
+// cited on the entry itself).
 // ---------------------------------------------------------------------------
 
 /** The parameter kind a spec entry declares. "count" bounds a decimal
@@ -175,16 +219,241 @@ function renderAddressParam(verb: string, value: number): string {
   return `${verb} $${value.toString(16).padStart(4, "0")}`;
 }
 
+/**
+ * The CLOSED set of committed fixtures the `load` widening below may load,
+ * as an id -> BASENAME table (plan 50-04 committed the first member; plan
+ * 50-05 turned the single constant into this table).
+ *
+ * WHY A TABLE AND NOT ONE CONSTANT PER SUBJECT. Plan 50-04's own note here
+ * said a later plan adding a second committed subject would add "its OWN new
+ * constant and its OWN new TEXT_COMMAND_PARAM_SPECS entry". Plan 50-05 is
+ * that later plan, and plan 50-06 needs two more. Three hand-copied
+ * constants, three hand-copied spec entries and three hand-copied verb
+ * strings in text-tools.ts is three chances to mis-copy a path and load the
+ * WRONG subject into a capture that then silently becomes evidence for the
+ * wrong binary. The table removes that class of mistake: adding a subject is
+ * ONE reviewed row here, and every spec entry, every verb string and the
+ * tool's own accepted id set are all derived from it.
+ *
+ * WHAT DID NOT CHANGE, AND MUST NOT. Every path here is still a reviewed
+ * literal chosen by THIS file. A caller never supplies a path, a basename or
+ * any fragment of one. The tool's `subject` argument (text-tools.ts) is an
+ * enumerated ID that is looked up in this frozen table by exact membership
+ * and is NEVER concatenated into a command string -- an id this table does
+ * not carry is refused BY NAME, so the set of loadable files stays exactly
+ * as closed as it was when it held one entry. TextCommandParamKind is
+ * likewise untouched: the only caller-supplied VALUE is still the bounded
+ * device NUMBER, and no parameter kind in this module accepts a string
+ * domain (text-protocol.test.ts pins both facts, at runtime and at source
+ * level).
+ *
+ * WHAT NOT TO DO: do not add a function that builds a path from caller
+ * input, and do not widen a row into anything a caller can steer. Every row
+ * below is a REVIEWED LITERAL spelled out in this file, whole.
+ *
+ * WHY THE ROWS CARRY A WHOLE REPO-RELATIVE PATH AND NOT A BARE BASENAME
+ * (plan 50-06). Plan 50-05 wrote each row as a basename and joined a single
+ * fixed `src/mcp/vice/fixtures/hazard-subject` directory onto it, and said
+ * in this very comment that a build artifact outside that directory "gets a
+ * reviewed row of its own, spelled out here the same way". Plan 50-06 is the
+ * plan with that artifact: its rebuild `.prg` is produced from the committed
+ * annotation store and lands under the PHASE EVIDENCE directory, not the
+ * fixture directory, because it is an output of this phase rather than a
+ * committed fixture. A basename-plus-fixed-directory row cannot spell that,
+ * so the row now carries the whole repo-relative path as an array of
+ * reviewed segments. Nothing about the CLOSURE changed: the path is still
+ * chosen entirely by this file, a caller still supplies no path, no
+ * basename, no directory and no fragment of one, and the only thing a
+ * caller ever names is an id this table's own keys define.
+ *
+ * `misaligned` is deliberately ABSENT: `hazard-subject-misaligned.prg` is a
+ * committed fixture, but no plan loads it into a running emulator -- it is
+ * consumed offline by the hazard-report gate. The set is what is actually
+ * dialed, not every fixture that happens to exist, and a committed test
+ * asserts it stays undialable so the boundary is this table rather than a
+ * directory.
+ */
+export const HAZARD_SUBJECT_PRG_RELPATHS = Object.freeze({
+  /** Plan 50-04's tracer-slice subject -- the original. */
+  original: Object.freeze(["src", "mcp", "vice", "fixtures", "hazard-subject", "hazard-subject.prg"]),
+  /** Plan 50-02's regressed twin: three planted single-bit regressions at
+   * the immediates feeding $D020, $D015 and $D018. Plan 50-05's red
+   * control. */
+  regressed: Object.freeze(["src", "mcp", "vice", "fixtures", "hazard-subject", "hazard-subject-regressed.prg"]),
+  /** Plan 50-02's modified subject: one behaviour removed and one added.
+   * Plan 50-06's modifiability observation. */
+  modified: Object.freeze(["src", "mcp", "vice", "fixtures", "hazard-subject", "hazard-subject-modified.prg"]),
+  /** Plan 50-06's REBUILD: the committed subject re-produced from its own
+   * committed annotation store through importStoreDocument() ->
+   * exportAsmTree() -> verifyAcmeAssemblesTree(), recorded in
+   * `.planning/phases/50-equivalence-and-modifiability/evidence/REBUILD.md`.
+   * The only row that is not a committed fixture, and the reason the rows
+   * carry a whole repo-relative path -- see this table's own comment. */
+  rebuild: Object.freeze([
+    ".planning",
+    "phases",
+    "50-equivalence-and-modifiability",
+    "evidence",
+    "hazard-subject-rebuild.prg",
+  ]),
+  /** Plan 50-08's exported-edit subject: the same one-behaviour-removed,
+   * one-behaviour-added pair `modified` carries, made this time in a file
+   * `exportAsmTree()` itself emitted (`scope_087a.a`) rather than in the
+   * hand-written `modified` fixture family, reassembled through the same
+   * single oracle against a pre-registered byte manifest committed at
+   * `fixtures/hazard-subject/exported-edit.manifest.json`. See
+   * `docs/phase50-exported-edit-findings.md` and
+   * `docs/phase50-exported-modifiability-transcript.md`. */
+  "exported-edit": Object.freeze([
+    "src",
+    "mcp",
+    "vice",
+    "fixtures",
+    "hazard-subject",
+    "hazard-subject-exported-edit.prg",
+  ]),
+} as const);
+
+/** The id half of HAZARD_SUBJECT_PRG_RELPATHS -- the only thing a caller
+ * ever names, and never a path. */
+export type HazardSubjectId = keyof typeof HAZARD_SUBJECT_PRG_RELPATHS;
+
+/** The frozen id list, in table order. Exported so text-tools.ts can state
+ * the accepted set in its refusal message without re-typing it. */
+export const HAZARD_SUBJECT_IDS: readonly HazardSubjectId[] = Object.freeze(
+  Object.keys(HAZARD_SUBJECT_PRG_RELPATHS) as HazardSubjectId[],
+);
+
+/** Each row's own last segment, DERIVED from the table above rather than
+ * spelled a second time. Preserved by name because committed tests already
+ * bind it, and because "which file does this id name" is a question worth
+ * answering without re-walking the path. */
+export const HAZARD_SUBJECT_PRG_BASENAMES: Readonly<Record<HazardSubjectId, string>> = Object.freeze(
+  Object.fromEntries(
+    HAZARD_SUBJECT_IDS.map((id) => {
+      const segments = HAZARD_SUBJECT_PRG_RELPATHS[id];
+      return [id, segments[segments.length - 1]] as const;
+    }),
+  ) as Record<HazardSubjectId, string>,
+);
+
+/** True only for an id this table actually carries. The ONE membership test
+ * -- `Object.keys`-derived rather than a prototype lookup, so an inherited
+ * name ("constructor", "__proto__", "toString") can never test true. */
+export function isHazardSubjectId(value: unknown): value is HazardSubjectId {
+  return typeof value === "string" && (HAZARD_SUBJECT_IDS as readonly string[]).includes(value);
+}
+
+/**
+ * Absolute host path to one member of the closed table above. Three members
+ * are committed fixtures; `rebuild` is plan 50-06's own build artifact under
+ * the phase evidence directory, which is why the table's rows carry a whole
+ * repo-relative path rather than a basename joined onto one fixed directory.
+ *
+ * Resolved through repoRoot() rather than hard-coded as a relative string:
+ * `broker-launch.mts` spawns `x64sc` with no explicit `cwd` (checked
+ * directly in this session -- no `cwd` option anywhere in that file), so a
+ * repo-relative string would resolve against whatever directory the broker
+ * process itself happened to be started from, not necessarily this
+ * repository. An absolute path removes that ambiguity. Residual, stated
+ * risk (not solved here): this is the CONTAINER-side path as seen by this
+ * Node process; on a genuinely containerized deployment (this project has
+ * none today -- host-developed, no devcontainer) the host process actually
+ * running `x64sc` would need this translated through `hostpath.ts` first.
+ * That translation is deliberately NOT added here, matching this project's
+ * existing "solve the general host/container case only where it is
+ * actually exercised" discipline -- a later plan that runs this widening
+ * through a real container split adds it then.
+ */
+export function hazardSubjectPrgPath(id: HazardSubjectId): string {
+  return join(repoRoot(), ...HAZARD_SUBJECT_PRG_RELPATHS[id]);
+}
+
+/** THE ONE place a `load "<path>"` verb string is spelled, for any subject.
+ * Both the TEXT_COMMAND_PARAM_SPECS keys below and text-tools.ts's own
+ * lookup go through this function, so the table key and the dialed verb can
+ * never drift apart into two literals that differ by a character. */
+export function hazardSubjectLoadVerb(id: HazardSubjectId): string {
+  return `load "${hazardSubjectPrgPath(id)}"`;
+}
+
+/** Plan 50-04's original constant, preserved by name and by value: it is
+ * exactly the `original` member of the table above. Kept because several
+ * committed tests and text-tools.ts already bind this name, and because the
+ * default subject is still the original. */
+export const HAZARD_SUBJECT_PRG_PATH: string = hazardSubjectPrgPath("original");
+
+/**
+ * One frozen `load "<path>"` spec per member of HAZARD_SUBJECT_PRG_RELPATHS,
+ * derived from that closed table rather than hand-copied per subject (plan
+ * 50-05). Every entry is identical except for the reviewed path baked into
+ * its own key: same "count" kind, same 0-11 device bound, same renderer. The
+ * DERIVATION is the point -- a hand-copied entry per subject is how a path
+ * and its renderer drift apart, and a renderer that disagrees with its own
+ * key fails isDialableTextCommandForVerb()'s round trip and refuses the
+ * command outright, which is a confusing way to discover a typo.
+ */
+const HAZARD_SUBJECT_LOAD_SPECS: Readonly<Record<string, TextCommandParamSpec>> = Object.freeze(
+  Object.fromEntries(
+    HAZARD_SUBJECT_IDS.map((id) => {
+      const verb = hazardSubjectLoadVerb(id);
+      return [
+        verb,
+        Object.freeze({
+          kind: "count",
+          min: 0,
+          max: 11,
+          render: (value: number) => renderCountParam(verb, value),
+        } satisfies TextCommandParamSpec),
+      ] as const;
+    }),
+  ),
+);
+
 /**
  * Frozen, per-verb parameter specs (D-42-1). Keyed by the verb exactly as
- * it appears in TEXT_COMMAND_ALLOWLIST above. A verb with no entry here
- * takes no parameter -- it keeps dialing its bare frozen literal, unchanged
- * (the three no-parameter verbs -- "device c:", "warp on", "warp off" --
- * are deliberately absent). The count bound is 1 through 65535: one because
- * a zero-row request is not a request, and 65535 because that is the same
- * 16-bit domain the CPU-history count lives in on this machine
- * (CPUHISTORY_GET's own count field, monitor_binary.c:1492). The address
- * bound is 0 through 65535, the full 16-bit machine address space.
+ * it appears in TEXT_COMMAND_ALLOWLIST above -- with ONE exception, the
+ * `load` family (plan 50-04, one entry per committed subject since plan
+ * 50-05), whose keys are full frozen literals that already embed their own
+ * filename argument (see below); none of them ever appears in
+ * TEXT_COMMAND_ALLOWLIST as a bare entry, because `load "<file>"` with no
+ * device number is not valid VICE syntax on its own (`mon_parse.y`'s
+ * `disk_rules: CMD_LOAD filename device_num opt_address` requires the
+ * device number) -- unlike "chis"/"prof flat"/"io", which ARE independently
+ * valid bare and so are also listed in TEXT_COMMAND_ALLOWLIST.
+ *
+ * A verb with no entry here takes no parameter -- it keeps dialing its bare
+ * frozen literal, unchanged (the three no-parameter verbs -- "device c:",
+ * "warp on", "warp off" -- are deliberately absent). The count bound is 1
+ * through 65535 for "chis"/"prof flat": one because a zero-row request is
+ * not a request, and 65535 because that is the same 16-bit domain the
+ * CPU-history count lives in on this machine (CPUHISTORY_GET's own count
+ * field, monitor_binary.c:1492). The address bound for "io" is 0 through
+ * 65535, the full 16-bit machine address space.
+ *
+ * `load "<one committed subject path>"` (plan 50-04, 2026-09-15; one entry
+ * per subject since plan 50-05): the single bounded value is still the
+ * DEVICE NUMBER, per VICE's own documented syntax
+ * (`load "<filename>" <device> [<address>]`, VICE Manual ch. 12 -- "If
+ * device is 0, the file is read from the file system"). The address
+ * argument is deliberately never offered here: omitting it makes VICE use
+ * the load address embedded in the `.prg` file's own two-byte header, which
+ * is exactly what a committed machine-code fixture needs and removes a
+ * second numeric slot this project would otherwise have to bound and
+ * justify for no present use. This reuses the SAME "count" kind and the
+ * SAME `${verb} ${value}` rendering `renderCountParam()` already produces
+ * for "chis"/"prof flat" -- no new TextCommandParamKind, no new render
+ * shape; only the verb string itself is new, and it is a reviewed literal,
+ * never a caller-supplied string, and the SUBJECT is chosen by an
+ * enumerated id looked up in that same frozen table, never by a path a
+ * caller passes in (see TEXT_COMMAND_ALLOWLIST's own `load` paragraph above
+ * and HAZARD_SUBJECT_PRG_RELPATHS). Bound 0 through 11: 0 is the one value this phase
+ * exercises (host filesystem, per the manual quote above); 1 through 11
+ * spans this project's own documented device-number range elsewhere
+ * (CLAUDE.md's wire memspace note: units 8-11 are the four IEC disk
+ * drives this codebase ever names) -- a deliberately narrow bound, not the
+ * full addressable device range VICE itself accepts, because nothing in
+ * this project has a reason to dial anything wider yet.
  */
 export const TEXT_COMMAND_PARAM_SPECS: Readonly<Record<string, TextCommandParamSpec>> = Object.freeze({
   chis: Object.freeze({
@@ -205,6 +474,7 @@ export const TEXT_COMMAND_PARAM_SPECS: Readonly<Record<string, TextCommandParamS
     max: 65535,
     render: (value: number) => renderAddressParam("io", value),
   }),
+  ...HAZARD_SUBJECT_LOAD_SPECS,
 } satisfies Record<string, TextCommandParamSpec>);
 
 function isSafeIntegerNumber(value: unknown): value is number {

package/text-tools.ts

@@ -69,7 +69,15 @@
 //     withChannelLockHeld()'s own discipline in stock-dispatch.ts.
 //   - Never embed a phase number in any string or template literal here.
 import { textConnect, textDisconnect } from "./text-connect.ts";
-import { withTextChannelLock, buildTextCommand, type TextMonitorClient } from "./text-protocol.ts";
+import {
+  withTextChannelLock,
+  buildTextCommand,
+  hazardSubjectLoadVerb,
+  isHazardSubjectId,
+  HAZARD_SUBJECT_IDS,
+  type HazardSubjectId,
+  type TextMonitorClient,
+} from "./text-protocol.ts";
 import { MonitorOwnershipError } from "./vice-broker-client.ts";
 import { ChannelLockTimeoutError } from "./channel-lock.ts";
 import { isErrorText, derivedAnswer, convertHandshakeError, convertWireError, type StockToolResult } from "./stock-handler.ts";
@@ -776,3 +784,100 @@ export async function handleIoRegisters(args: Record<string, unknown>, deps: Sto
     });
   });
 }
+
+// ---------------------------------------------------------------------------
+// Plan 50-04 (route-d): the tool that reaches text-protocol.ts's widened
+// `load` verb. See TEXT_COMMAND_ALLOWLIST's own `load` paragraph and
+// TEXT_COMMAND_PARAM_SPECS's own `load` entry (both text-protocol.ts) for
+// the full rationale this handler leans on without repeating it.
+// ---------------------------------------------------------------------------
+
+/**
+ * The subject loaded when the caller names none. Plan 50-04's behaviour,
+ * unchanged: an omitted `subject` dials exactly the path that plan's single
+ * frozen entry dialed.
+ */
+const DEFAULT_SUBJECT: HazardSubjectId = "original";
+
+/**
+ * Resolve the caller's `subject` argument to one of text-protocol.ts's own
+ * frozen ids, or to `null` for anything else.
+ *
+ * WHY THIS IS NOT A FILENAME PARAMETER, AND MUST NEVER BECOME ONE. The value
+ * a caller supplies here is an ID, checked for exact membership in
+ * HAZARD_SUBJECT_IDS and then used only as a LOOKUP KEY -- it is never
+ * concatenated into a command string, never joined onto a path, and never
+ * reaches the socket in any form. The dialed verb is built by
+ * hazardSubjectLoadVerb() from the reviewed literal text-protocol.ts's own
+ * closed table carries. So the set of host files this tool can ever load is
+ * exactly that table, whatever a caller sends. An unrecognised id is refused
+ * BY NAME before any text-monitor byte is written, the same way
+ * buildTextCommand() refuses an out-of-bounds device.
+ */
+function resolveSubjectId(raw: unknown): HazardSubjectId | null {
+  if (raw === undefined) return DEFAULT_SUBJECT;
+  return isHazardSubjectId(raw) ? raw : null;
+}
+
+/**
+ * `vice_program_load` -- the shipped tool that reaches plan 50-04's widened
+ * `load` verb (route-d, `.planning/phases/50-equivalence-and-modifiability/evidence/LOAD-ROUTE.md`).
+ * Dials VICE's text-monitor `load "<file>" <device>` command for ONE member
+ * of text-protocol.ts's closed HAZARD_SUBJECT_PRG_RELPATHS table, each
+ * baked into its own frozen allowlist identity -- this handler takes NO
+ * filename argument at all, so there is nothing here for a caller to
+ * inject; the loaded path can never be anything other than a reviewed
+ * literal that table already carries.
+ *
+ * Takes two OPTIONAL parameters. `subject` is an enumerated id from that
+ * table ("original", "regressed", "modified", "rebuild"). It defaults to
+ * "original", which is exactly plan 50-04's behaviour, and an id the table
+ * does not carry is refused by name (see resolveSubjectId() above for why an
+ * id is not a filename). "rebuild" (plan 50-06) is the one id whose row
+ * resolves outside the fixture directory -- a build artifact under the phase
+ * evidence directory -- which is why the table's rows carry a whole
+ * repo-relative path. `device`: an omitted device defaults
+ * to 0 ("the file is read from the file system", VICE Manual ch. 12).
+ * `buildTextCommand()` alone validates and bounds the device (0 through 11,
+ * TEXT_COMMAND_PARAM_SPECS's own entry for this verb) -- this handler
+ * duplicates no bound, mirroring `handleCpuHistory()`'s own discipline of
+ * never re-stating a spec's own bound in a second place.
+ *
+ * No address argument is offered, and none ever will be through this tool:
+ * omitting it makes VICE use the load address embedded in the `.prg` file's
+ * own two-byte header, which is exactly what a committed machine-code
+ * fixture needs -- text-protocol.ts's own `load` entry documents this same
+ * choice and why a second numeric slot is not worth bounding for no present
+ * use.
+ */
+export async function handleProgramLoad(args: Record<string, unknown>, deps: StockDispatchDeps): Promise<StockToolResult> {
+  const { device, subject } = args;
+  const subjectId = resolveSubjectId(subject);
+  if (subjectId === null) {
+    return isErrorText(
+      `vice_program_load: "subject" must be one of ${HAZARD_SUBJECT_IDS.map((id) => JSON.stringify(id)).join(", ")} ` +
+        `(got ${JSON.stringify(subject)}) -- refusing before any text-monitor byte is written; this tool never accepts a filename`,
+    );
+  }
+  const resolvedDevice = device === undefined ? 0 : device;
+  const built = buildTextCommand(hazardSubjectLoadVerb(subjectId), resolvedDevice);
+  if (!built.ok) {
+    return isErrorText(`vice_program_load: ${built.message} -- refusing before any text-monitor byte is written`);
+  }
+  const command = built.command;
+
+  return withTextTool("vice_program_load", deps, async (client) => {
+    const response = await client.command(command);
+    return derivedAnswer({
+      command,
+      device: resolvedDevice,
+      subject: subjectId,
+      response,
+      note:
+        `loads the reviewed Phase 50 hazard subject "${subjectId}", baked into this verb's own frozen ` +
+        "identity (plan 50-04 route-d; one frozen verb per subject since plan 50-05) -- no filename is ever " +
+        "caller-supplied, only an enumerated subject id; the load address comes from the .prg file's own " +
+        "two-byte header, since no address argument is offered",
+    });
+  });
+}

package/tools-manifest.stock.json

@@ -4505,6 +4505,69 @@
           "runState"
         ]
       }
+    },
+    {
+      "name": "vice_program_load",
+      "description": "Stock-only, no fork counterpart -- reaches VICE's text monitor over the -remotemonitor channel and halts the machine for the duration of the command, exactly as a binary-monitor command does. Issues \"load \\\"<path>\\\" <device>\" for ONE member of a closed, reviewed Phase 50 hazard-subject table -- four committed fixtures under fixtures/hazard-subject/ plus the rebuild produced under the phase evidence directory. Every loadable path is baked into this tool's own frozen dialed verbs and is never a caller-supplied argument, so there is nothing here for a caller to inject. Takes an OPTIONAL \"subject\", an enumerated subject id, defaulting to \"original\". Takes an OPTIONAL \"device\" number, 0 through 11; an omitted device defaults to 0 (\"the file is read from the file system\", VICE Manual ch. 12). No address argument is offered -- omitting it makes VICE use the load address embedded in the .prg file's own two-byte header, which is exactly what these committed machine-code fixtures need.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "device": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 11,
+            "description": "OPTIONAL. IEC device number VICE loads from. Defaults to 0 (the host filesystem) when omitted. 1 through 11 span this project's own documented device-number range elsewhere; this tool never accepts a filename."
+          },
+          "subject": {
+            "type": "string",
+            "enum": [
+              "original",
+              "regressed",
+              "modified",
+              "rebuild",
+              "exported-edit"
+            ],
+            "description": "OPTIONAL. Which reviewed Phase 50 hazard subject to load, named by id, never by path. \"original\" is the tracer-slice subject and is the default. \"regressed\" is its three-single-bit-regression twin. \"modified\" is the one-behaviour-removed, one-behaviour-added variant made by hand in the fixture's own source. \"rebuild\" is the original re-produced from its own committed annotation store, and is the one id that resolves outside the fixture directory. \"exported-edit\" is the same one-behaviour-removed, one-behaviour-added pair made instead in a file exportAsmTree() itself emitted, reassembled against a pre-registered byte manifest. This tool never accepts a filename."
+          }
+        },
+        "additionalProperties": false
+      },
+      "outputSchema": {
+        "type": "object",
+        "properties": {
+          "command": {
+            "type": "string"
+          },
+          "device": {
+            "type": "integer"
+          },
+          "response": {
+            "type": "string"
+          },
+          "note": {
+            "type": "string"
+          },
+          "runState": {
+            "type": "string",
+            "enum": [
+              "running",
+              "stopped",
+              "unknown"
+            ]
+          },
+          "subject": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "command",
+          "device",
+          "subject",
+          "response",
+          "note",
+          "runState"
+        ]
+      }
     }
   ]
 }