@henols/vice-mcp 0.2.2 → 0.2.4

package/resources/host-tool.mjs

@@ -0,0 +1,2533 @@
+// GENERATED FILE -- DO NOT EDIT.
+// Compiled by `tsc` from host-tool.mts. Edit the TypeScript source and rebuild;
+// changes made directly to this file are silently overwritten by the next build, and are never
+// deployed to the host on their own -- install-resources.mjs copies THIS file's on-disk contents
+// verbatim to .c64-re-tools/bin/, so an edit made only here reaches the host but is lost on the very next
+// rebuild.
+// host-tool.mts
+//
+// This is the host-bound executor for the host-tool control op. A
+// container-side caller (host-tool-client.ts) reaches this module over
+// broker-control.mts's `host_tool` op -- never directly -- and this module is
+// the ONE place that turns an untrusted wire request into a real child
+// process on the HOST, outside any container. Motivated by the project
+// owner's own rule, recorded once a skill script's own binaries (acme, and
+// later dxa/Ghidra/c1541/petcat/cartconv) turned out to need to live
+// host-side: a skill script runs container-side and there is no container
+// PATH to find them on.
+//
+// THIS IS THE ONE AUTHORITATIVE PLACE for three things, none of which may be
+// re-derived anywhere else:
+//   - the typed per-tool allowlist (HOST_TOOL_IDS / HOST_TOOL_ARG_KEYS /
+//     normaliseHostToolRequest()) -- mirrors broker-control.mts's own
+//     normaliseLaunchProfile() discipline: refuse unknown keys BY NAME, never
+//     coerce a type, never drop a key silently;
+//   - server-side argv construction (buildHostToolArgv()) -- argv is built
+//     ENTIRELY from typed, already-narrowed fields; a wire array or a wire
+//     string never reaches argv (T-34-01);
+//   - the async child-process invocation and its result digest (runHostTool())
+//     -- spawned via node:child_process's async `spawn`, never `spawnSync`,
+//     never a shell string, and bounded by a per-invocation timeout (T-34-02,
+//     T-34-05).
+//
+// WHAT NOT TO DO, each naming the prohibition it guards (recorded because a
+// fast sweep of this file could plausibly re-add any one of them):
+//   - No generic wire op that accepts a raw argv array or a raw command
+//     string for a host tool -- argv is constructed server-side from typed
+//     fields only (T-34-01).
+//   - No shell-form child process on any host-tool path: no command
+//     interpreter, no interpolated command string (T-34-02).
+//   - No host-tool output written outside the bind-mounted workspace tree --
+//     resolveWorkspacePath() is the only place a wire-supplied path becomes a
+//     real path. BOTH the workspace root and the candidate go through the
+//     same ancestor-realpath walk (realpathOfNearestExisting(), mirroring
+//     anno-types.ts's storePathWithinWorkspace() and its own incident
+//     history by name) before the prefix comparison, and the comparison is
+//     over the WALKED (real) paths, never the lexical join -- a purely
+//     lexical path.resolve() + startsWith() check is exactly what a live
+//     symlink test found: a symlink planted inside the workspace defeated
+//     it, satisfying the prefix check lexically while a real write through
+//     it landed outside the root. This covers EVERY path-bearing wire field
+//     on every tool, not only the ones present when this file was first
+//     written: acme.build's source/outDir AND each entry of its includes
+//     array, and ghidra.analyze's importPath AND its preScript/postScript.
+//     Two residuals recorded beside the guarantee, not hidden past it: the
+//     check-then-open window between this decision and the child process's
+//     own open is NOT closed here -- the child is a third-party binary
+//     handed a path string, so there is no descriptor-based route to making
+//     the check and the open one operation (T-34-52, accepted). And the
+//     comparison is byte-wise over the resolved strings with no Unicode
+//     normalisation, so two spellings differing only in normalisation form
+//     are two distinct paths here (same residual anno-confinement.test.ts
+//     records for the same comparison). A third residual, recorded rather
+//     than hidden: because the return value is now the REAL path, on a
+//     host whose workspace root is itself reached through a symlink the
+//     response `path` need not match any member of hostRootCandidates(),
+//     and containerPath() throws rather than passing an untranslatable
+//     path through -- HOST_WORKSPACE_PATH naming the real root is the
+//     pre-existing mitigation; this is a recorded limit, not a widened
+//     hostpath.ts consumer set.
+//   - No inline byte payload on a host-tool response, at any result size --
+//     every result crosses as `{ path, sha256, byteLength }`, never bytes.
+//   - No second copy of a tool's argv construction -- buildHostToolArgv() is
+//     the one place.
+//   - No synchronous child-process call on any path reachable from the
+//     broker process -- runHostTool() awaits an async spawn only.
+//   - No unbounded host-tool child process -- every invocation is bounded by
+//     a timeout that kills the child and reports a refusal on expiry.
+//
+// This module must never be added to package.json's `files[]` (mirrors
+// broker-control.mts's own precedent: shipped only as its compiled
+// `resources/host-tool.mjs` artifact, added to build.ts's HOST_BOUND_ARTIFACTS
+// and tsconfig.build.json's include[] in the same commit as this file).
+//
+// This module's first SIBLING import. `ghidra-project.mjs` is a VALUE
+// import (not type-only) because the rule must be enforced where
+// `analyzeHeadless` is actually spawned -- inside the broker process --
+// which is why `ghidra-project.mts` ships as a compiled `resources/*.mjs`
+// artifact exactly like this file does. A `.mjs`-specifier value import
+// only resolves once both siblings are compiled into resources/ (the same
+// reason host-tool.test.ts reaches THIS module as the committed artifact,
+// not the unbuilt source). The dot-segment rule and the per-run project
+// location are NEVER copied here -- this module reaches them through the
+// one place that owns them.
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve as resolvePath, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveGhidraProject, buildAnalyzeHeadlessArgv, hasDotPrefixedSegment, installedLanguageIds, GHIDRA_STOCK_6502_LANGUAGE_FILES, GHIDRA_IMPORT_ROUTES, importRouteBaseAddr, LANGUAGE_ID_PATTERN, LOADER_BASE_ADDR_PATTERN, RUN_ID_PATTERN, } from "./ghidra-project.mjs";
+// This module's SECOND sibling import. `resolvedBackend()` is the ONE
+// place that decides which x64sc build is on this host (backend-detect.mts's
+// own header) -- findSiblingBinary() below resolves c1541/petcat as siblings
+// of THAT resolved binary rather than by a bare-name spawn, which a host
+// carrying both a stock and a fork build (MEASURED live on this project's
+// own dev host: /usr/local/bin/x64sc is the fork, /usr/bin/x64sc is genuine
+// stock, and $PATH resolves the fork first) would otherwise silently answer
+// with whichever build's directory happens to sort first. A VALUE import,
+// exactly like ghidra-project.mjs above, for the same reason: it is invoked
+// where the sibling binary is actually resolved, inside this process.
+// resolvedBackend() is itself memoised at module scope (backend-detect.mts's
+// own `memoisedResult`) and this project's broker already calls it once at
+// startup before the control listener binds (vice-broker.mts's run()) -- for
+// the control-plane route this call below is therefore always a cache hit,
+// never a second probe. The host route (no broker in the loop) has no such
+// warm memo and pays one `--help` probe per invocation, mirroring the
+// existing, already-accepted cost vice-broker.mts's own startup call pays
+// once per broker lifetime -- never re-probed per c1541.* call within the
+// SAME process, per findSiblingBinary()'s own memo below.
+import { resolvedBackend } from "./backend-detect.mjs";
+// This module's own directory, used ONLY to compute the vendored dxa
+// binary's fixed path. Never an environment-variable override: dxa is
+// vendored AND built by this project (unlike ACME_BIN/GHIDRA_HOME, which
+// name a HOST PREREQUISITE a user installs anywhere), so an override could
+// only ever select a binary this project did not build and did not pin --
+// a substitution this seam must never allow.
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const HOST_TOOL_IDS = Object.freeze([
+    "acme.build",
+    "ghidra.analyze",
+    "oracle.probe",
+    "oracle.run",
+    "dxa.disassemble",
+    "ghidra.installExtension",
+    "c1541.bam",
+    "c1541.dir",
+    "c1541.entry",
+    "c1541.chain",
+    "c1541.read",
+    "petcat.decode",
+]);
+/** Per-tool accepted argument-key lists, built with `Object.create(null)`
+ * (the same prototype-null idiom vsf-slice.mjs uses) so no prototype key can
+ * ever resolve to a value here even if a future caller indexed it with an
+ * untrusted string directly -- belt-and-suspenders alongside the
+ * array-membership check above, which is what actually guards the lookup
+ * below.
+ *
+ * `ghidra.analyze`'s accepted keys carry no raw argv array and no raw
+ * command string. Per field (corrected from an earlier version of this
+ * comment, which wrongly claimed all four already flowed through a
+ * resolver -- that was false for the two script fields until it was fixed):
+ * `runId` is a bare name, never a path, and flows through
+ * `resolveGhidraProject()`'s own per-run-directory resolution; `importPath`,
+ * `preScript` and `postScript` each flow through `resolveWorkspacePath()` --
+ * the SAME workspace-boundary resolver `acme.build`'s `source`/`outDir`/
+ * `includes` use -- before any of the four ever reaches argv.
+ * `buildAnalyzeHeadlessArgv()` (ghidra-project.mts) also independently
+ * re-checks `preScript`/`postScript` for a parent-directory path segment,
+ * exactly as it already re-checks `projectLocation` for a dot-prefixed
+ * segment -- so both rules hold even for a caller that constructed these
+ * fields itself and skipped this module's own resolution sites entirely.
+ *
+ * `ghidra.analyze` gains `processor` (promoted from optional to required
+ * after early testing showed a caller must always name the language) -- a
+ * REQUIRED, non-path, language-id string. It is deliberately absent from
+ * `HOST_TOOL_PATH_ARG_KEYS` below and never flows through
+ * `resolveWorkspacePath()`; it is validated against `LANGUAGE_ID_PATTERN`
+ * instead (ghidra-project.mts). `ghidra.installExtension`'s two keys:
+ * `sourceDir` (workspace-relative, path-bearing) and `moduleName` (a
+ * non-path name validated against `RUN_ID_PATTERN`'s anchored shape, exactly
+ * like `ghidra.analyze`'s own `runId`). */
+export const HOST_TOOL_ARG_KEYS = Object.freeze(Object.assign(Object.create(null), {
+    "acme.build": Object.freeze(["source", "outDir", "format", "setpc", "defines", "includes", "noReport"]),
+    // Seven new fields close a measured seam-argv surface gap -- importRoute
+    // (required), loaderBaseAddr, noanalysis, scriptPath, entrypointsPath,
+    // exportPath, expectedClassificationLines.
+    // "dataRangesPath" is the ONE new field added after that -- an OPTIONAL
+    // path-bearing field naming a range file for the new DataRangeSeed.java
+    // pre-script. A run omitting it is accepted exactly as before this
+    // field existed: a first pass without graphics feedback must keep
+    // working unchanged.
+    "ghidra.analyze": Object.freeze([
+        "runId",
+        "importPath",
+        "processor",
+        "importRoute",
+        "loaderBaseAddr",
+        "noanalysis",
+        "scriptPath",
+        "preScript",
+        "postScript",
+        "entrypointsPath",
+        "exportPath",
+        "expectedClassificationLines",
+        "dataRangesPath",
+    ]),
+    // EMPTY -- the oracle's location is host-side configuration only
+    // (resolveOracleCommand(), below), never a wire value. No
+    // caller-supplied value may ever select what the host executes, even
+    // framed as merely reconfiguring an already-allowlisted tool.
+    "oracle.probe": Object.freeze([]),
+    "oracle.run": Object.freeze(["source"]),
+    // Frozen exactly as originally specified -- five path-bearing keys plus
+    // the one enum key (`imageKind`), never re-derived from
+    // ResolvedDxaDisassemblePaths below.
+    "dxa.disassemble": Object.freeze(["image", "imageKind", "entrypointsPath", "datablocksPath", "labelsPath", "outDir"]),
+    // `sourceDir` is the vendored extension tree; `moduleName` names the
+    // install target directory under <GHIDRA_HOME>/Ghidra/Extensions/.
+    "ghidra.installExtension": Object.freeze(["sourceDir", "moduleName"]),
+    // `image` is the `.d64` these five capabilities read; `outDir` defaults
+    // to `dirname(imagePath)`, exactly as `dxa.disassemble`'s own default
+    // does. `name` (entry/chain/read) is a CBM filename or glob pattern --
+    // never a path, never resolved through `resolveWorkspacePath()` (see
+    // HOST_TOOL_PATH_ARG_KEYS below).
+    "c1541.bam": Object.freeze(["image", "outDir"]),
+    "c1541.dir": Object.freeze(["image", "outDir"]),
+    "c1541.entry": Object.freeze(["image", "name", "outDir"]),
+    "c1541.chain": Object.freeze(["image", "name", "outDir"]),
+    "c1541.read": Object.freeze(["image", "name", "outDir"]),
+    // No dialect key here or anywhere else in this module -- the BASIC
+    // dialect is a fixed literal inside buildHostToolArgv()'s own
+    // petcat.decode branch, never a wire field. A caller has no way to
+    // request one, let alone a wrong one.
+    "petcat.decode": Object.freeze(["image", "outDir"]),
+}));
+/** The answer to ONE question -- which accepted argument keys, per tool,
+ * name a filesystem path and therefore MUST pass `resolveWorkspacePath()`
+ * before ever reaching argv. Built with the SAME
+ * `Object.freeze(Object.assign(Object.create(null), ...))` idiom
+ * `HOST_TOOL_ARG_KEYS` above uses. Consumed by `host-tool.test.ts`'s
+ * data-driven census, never by production code -- the census is what makes
+ * "no argv passthrough anywhere" a mechanism rather than three point fixes:
+ * a key added here without a matching resolution site is what the test
+ * proves, a key ADDED to `HOST_TOOL_ARG_KEYS` without being classified HERE
+ * (as path-bearing or not) is what the test's both-directions completeness
+ * check catches.
+ *
+ * Deliberately NOT included: `ghidra.analyze`'s `runId`. It is a validated
+ * opaque id bounded by its own anchored pattern (`RUN_ID_PATTERN`,
+ * ghidra-project.mts), turned into a path only by `resolveGhidraProject()`
+ * -- a DIFFERENT mechanism with its own guard, not `resolveWorkspacePath()`.
+ * `oracle.probe`'s entry is empty because that tool accepts no arguments at
+ * all.
+ *
+ * `ghidra.analyze`'s `processor` is deliberately NOT listed here -- it is a
+ * language-id string, not a path, and is validated against
+ * `LANGUAGE_ID_PATTERN` instead. `ghidra.installExtension`'s `sourceDir` IS
+ * path-bearing; `moduleName` is deliberately absent for the same reason
+ * `ghidra.analyze`'s own `runId` is: a validated opaque name
+ * (`RUN_ID_PATTERN`) turned into a path segment only inside
+ * `runHostTool()`'s own resolution branch below, never through
+ * `resolveWorkspacePath()`. */
+export const HOST_TOOL_PATH_ARG_KEYS = Object.freeze(Object.assign(Object.create(null), {
+    "acme.build": Object.freeze(["source", "outDir", "includes"]),
+    // scriptPath/entrypointsPath/exportPath join the pre-existing three --
+    // each resolved through resolveWorkspacePath() in runHostTool()'s ghidra
+    // branch, exactly like importPath/preScript/postScript already are.
+    // "dataRangesPath" joins the pre-existing six -- resolved through
+    // resolveWorkspacePath() in runHostTool()'s ghidra branch, exactly like
+    // every other script-adjacent path field.
+    "ghidra.analyze": Object.freeze(["importPath", "preScript", "postScript", "scriptPath", "entrypointsPath", "exportPath", "dataRangesPath"]),
+    "oracle.probe": Object.freeze([]),
+    "oracle.run": Object.freeze(["source"]),
+    // `imageKind` is deliberately absent -- it is a two-member enum, not a
+    // path, and is the one key HOST_TOOL_ARG_KEYS_REMAINDER (host-tool.test.ts)
+    // classifies for this tool.
+    "dxa.disassemble": Object.freeze(["image", "entrypointsPath", "datablocksPath", "labelsPath", "outDir"]),
+    "ghidra.installExtension": Object.freeze(["sourceDir"]),
+    // `image`/`outDir` are path-bearing on all five ids; `name`
+    // (entry/chain/read) is deliberately absent here -- it is a CBM
+    // filename/glob, not a path, and is the one key each of those three
+    // tools' own `HOST_TOOL_ARG_KEYS_REMAINDER` entry (host-tool.test.ts)
+    // classifies. `c1541.bam`/`c1541.dir` have no non-path keys at all, so
+    // their own remainder entries are empty.
+    "c1541.bam": Object.freeze(["image", "outDir"]),
+    "c1541.dir": Object.freeze(["image", "outDir"]),
+    "c1541.entry": Object.freeze(["image", "outDir"]),
+    "c1541.chain": Object.freeze(["image", "outDir"]),
+    "c1541.read": Object.freeze(["image", "outDir"]),
+    // Both of `petcat.decode`'s accepted keys are path-bearing -- there is
+    // no non-path key at all, so its own HOST_TOOL_ARG_KEYS_REMAINDER entry
+    // (host-tool.test.ts) is empty.
+    "petcat.decode": Object.freeze(["image", "outDir"]),
+}));
+const HOST_TOOL_SHAPE = `an object with a "tool" field naming one of ${HOST_TOOL_IDS.map((t) => JSON.stringify(t)).join(", ")}, and an optional "args" object`;
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function describe(value) {
+    try {
+        const json = JSON.stringify(value);
+        return json === undefined ? String(value) : json;
+    }
+    catch {
+        return String(value);
+    }
+}
+/** THIS IS THE ONE PLACE a `host_tool` request is narrowed. Never throws;
+ * answers a discriminated result naming the offending value or key AND the
+ * accepted shape, exactly as broker-control.mts's normaliseLaunchProfile()
+ * does. Never coerces a type (a string "true" for `noReport` is refused, not
+ * converted) and never drops a key silently. */
+export function normaliseHostToolRequest(raw) {
+    if (!isPlainObject(raw)) {
+        return { ok: false, message: `host_tool request must be ${HOST_TOOL_SHAPE}; got ${describe(raw)}` };
+    }
+    const toolRaw = raw.tool;
+    if (typeof toolRaw !== "string" || toolRaw === "") {
+        return {
+            ok: false,
+            message: `host_tool request "tool" field must be a non-empty string naming one of ${HOST_TOOL_IDS.join(", ")}; got ${describe(toolRaw)}`,
+        };
+    }
+    if (!HOST_TOOL_IDS.includes(toolRaw)) {
+        return { ok: false, message: `unknown host_tool "tool" value ${describe(toolRaw)}; accepted values are ${HOST_TOOL_IDS.join(", ")}` };
+    }
+    const tool = toolRaw;
+    const argsRaw = raw.args;
+    if (argsRaw !== undefined && !isPlainObject(argsRaw)) {
+        return { ok: false, message: `host_tool "args" must be a plain object or absent; got ${describe(argsRaw)}` };
+    }
+    const argsObj = argsRaw ?? {};
+    const acceptedKeys = HOST_TOOL_ARG_KEYS[tool];
+    const acceptedShape = acceptedKeys.length > 0 ? `an object with optional key(s) ${acceptedKeys.join("/")}` : "an object with no accepted keys -- this tool takes no arguments";
+    const unknownKeys = Object.keys(argsObj).filter((key) => !acceptedKeys.includes(key));
+    if (unknownKeys.length > 0) {
+        return { ok: false, message: `host_tool "${tool}" args has unknown key(s) ${unknownKeys.join(", ")}; accepted shape is ${acceptedShape}` };
+    }
+    if (tool === "acme.build") {
+        const source = argsObj.source;
+        if (typeof source !== "string" || source === "") {
+            return { ok: false, message: `host_tool "acme.build" requires a non-empty string "source"; got ${describe(source)}` };
+        }
+        const args = { source };
+        if ("outDir" in argsObj) {
+            const outDir = argsObj.outDir;
+            if (typeof outDir !== "string" || outDir === "") {
+                return { ok: false, message: `host_tool "acme.build" args.outDir must be a non-empty string; got ${describe(outDir)}` };
+            }
+            args.outDir = outDir;
+        }
+        if ("format" in argsObj) {
+            const format = argsObj.format;
+            if (typeof format !== "string" || format === "") {
+                return { ok: false, message: `host_tool "acme.build" args.format must be a non-empty string; got ${describe(format)}` };
+            }
+            args.format = format;
+        }
+        if ("setpc" in argsObj) {
+            const setpc = argsObj.setpc;
+            if (typeof setpc !== "string" || setpc === "") {
+                return { ok: false, message: `host_tool "acme.build" args.setpc must be a non-empty string; got ${describe(setpc)}` };
+            }
+            args.setpc = setpc;
+        }
+        if ("defines" in argsObj) {
+            const defines = argsObj.defines;
+            if (!Array.isArray(defines) || !defines.every((d) => typeof d === "string")) {
+                return { ok: false, message: `host_tool "acme.build" args.defines must be an array of strings; got ${describe(defines)}` };
+            }
+            args.defines = defines;
+        }
+        if ("includes" in argsObj) {
+            const includes = argsObj.includes;
+            // An empty-string entry is refused here rather than silently skipped
+            // or forwarded to resolveWorkspacePath() -- the same "must be an
+            // array of strings" message, tightened to reject the one string
+            // value that would otherwise slip through as "an array of strings"
+            // while carrying no real path.
+            if (!Array.isArray(includes) || !includes.every((i) => typeof i === "string" && i !== "")) {
+                return { ok: false, message: `host_tool "acme.build" args.includes must be an array of strings; got ${describe(includes)}` };
+            }
+            args.includes = includes;
+        }
+        if ("noReport" in argsObj) {
+            const noReport = argsObj.noReport;
+            if (typeof noReport !== "boolean") {
+                return { ok: false, message: `host_tool "acme.build" args.noReport must be a boolean; got ${describe(noReport)}` };
+            }
+            args.noReport = noReport;
+        }
+        return { ok: true, request: { tool, args } };
+    }
+    if (tool === "ghidra.analyze") {
+        const runIdRaw = argsObj.runId;
+        if (typeof runIdRaw !== "string" || runIdRaw === "") {
+            return { ok: false, message: `host_tool "ghidra.analyze" requires a non-empty string "runId"; got ${describe(runIdRaw)}` };
+        }
+        const importPathRaw = argsObj.importPath;
+        if (typeof importPathRaw !== "string" || importPathRaw === "") {
+            return { ok: false, message: `host_tool "ghidra.analyze" requires a non-empty string "importPath"; got ${describe(importPathRaw)}` };
+        }
+        // REQUIRED, non-defaulted -- the correction stated on the interface
+        // above. Refused absent, empty, non-string, and non-matching, each
+        // naming the field and the accepted shape; re-validated independently
+        // inside buildAnalyzeHeadlessArgv() (ghidra-project.mts) so the rule
+        // holds for a caller that bypassed this narrowing entirely. Byte-exact,
+        // case-sensitive comparison -- never case-folded.
+        const processorRaw = argsObj.processor;
+        if (typeof processorRaw !== "string" || processorRaw === "" || !LANGUAGE_ID_PATTERN.test(processorRaw)) {
+            return {
+                ok: false,
+                message: `host_tool "ghidra.analyze" requires a non-empty "processor" string matching ${LANGUAGE_ID_PATTERN.source} (a colon-separated Ghidra language id, alphanumeric-and-underscore segments, no path separator, no dot, length-capped); got ${describe(processorRaw)}`,
+            };
+        }
+        // REQUIRED, non-defaulted -- exact membership of a frozen two-member
+        // array, never a string passed through to argv. The loader itself
+        // ("BinaryLoader") is a fixed literal and never a wire field at all.
+        const importRouteRaw = argsObj.importRoute;
+        if (typeof importRouteRaw !== "string" || !GHIDRA_IMPORT_ROUTES.includes(importRouteRaw)) {
+            return {
+                ok: false,
+                message: `host_tool "ghidra.analyze" requires an "importRoute" matching one of ${GHIDRA_IMPORT_ROUTES.map((r) => JSON.stringify(r)).join(", ")}; got ${describe(importRouteRaw)}`,
+            };
+        }
+        const importRoute = importRouteRaw;
+        // loaderBaseAddr is a raw argv token, never a path -- validated against
+        // the anchored LOADER_BASE_ADDR_PATTERN rather than routed through
+        // resolveWorkspacePath(). On the "flat64k" route the base is the
+        // route's OWN; a differing supplied value is refused BY NAME rather
+        // than silently honoured. On "prg" an absent value defaults to the
+        // route's own base, since a .prg's load address is a property of the
+        // image, not of the route.
+        let loaderBaseAddr;
+        if ("loaderBaseAddr" in argsObj) {
+            const loaderBaseAddrRaw = argsObj.loaderBaseAddr;
+            if (typeof loaderBaseAddrRaw !== "string" || !LOADER_BASE_ADDR_PATTERN.test(loaderBaseAddrRaw)) {
+                return {
+                    ok: false,
+                    message: `host_tool "ghidra.analyze" args.loaderBaseAddr must match ${LOADER_BASE_ADDR_PATTERN.source} (a "0x" prefix followed by one to four lowercase hex digits); got ${describe(loaderBaseAddrRaw)}`,
+                };
+            }
+            if (importRoute === "flat64k" && loaderBaseAddrRaw !== importRouteBaseAddr("flat64k")) {
+                return {
+                    ok: false,
+                    message: `host_tool "ghidra.analyze" args.loaderBaseAddr (${loaderBaseAddrRaw}) conflicts with the "flat64k" route's own base address (${importRouteBaseAddr("flat64k")}) -- the route defines the base on this route; omit loaderBaseAddr or supply the matching value`,
+                };
+            }
+            loaderBaseAddr = loaderBaseAddrRaw;
+        }
+        else {
+            loaderBaseAddr = importRouteBaseAddr(importRoute);
+        }
+        // A typeof boolean check, never a truthiness coercion. Load-bearing
+        // rather than cosmetic: VolatileCarve.java's own run() calls
+        // analyzeAll(currentProgram) itself, so omitting -noanalysis would race
+        // Ghidra's own automatic post-preScript analysis against the manual
+        // call.
+        let noanalysis;
+        if ("noanalysis" in argsObj) {
+            const noanalysisRaw = argsObj.noanalysis;
+            if (typeof noanalysisRaw !== "boolean") {
+                return { ok: false, message: `host_tool "ghidra.analyze" args.noanalysis must be a boolean; got ${describe(noanalysisRaw)}` };
+            }
+            noanalysis = noanalysisRaw;
+        }
+        // A non-negative integer, refusing fractional, negative, NaN and string
+        // values by name -- this field exists so a verification gate can plant
+        // a deliberately wrong expectation and prove the check catches it.
+        let expectedClassificationLines;
+        if ("expectedClassificationLines" in argsObj) {
+            const linesRaw = argsObj.expectedClassificationLines;
+            if (typeof linesRaw !== "number" || !Number.isInteger(linesRaw) || linesRaw < 0) {
+                return {
+                    ok: false,
+                    message: `host_tool "ghidra.analyze" args.expectedClassificationLines must be a non-negative integer; got ${describe(linesRaw)}`,
+                };
+            }
+            expectedClassificationLines = linesRaw;
+        }
+        const args = { runId: runIdRaw, importPath: importPathRaw, processor: processorRaw, importRoute, loaderBaseAddr };
+        if (noanalysis !== undefined)
+            args.noanalysis = noanalysis;
+        if (expectedClassificationLines !== undefined)
+            args.expectedClassificationLines = expectedClassificationLines;
+        if ("preScript" in argsObj) {
+            const preScript = argsObj.preScript;
+            if (typeof preScript !== "string" || preScript === "") {
+                return { ok: false, message: `host_tool "ghidra.analyze" args.preScript must be a non-empty string; got ${describe(preScript)}` };
+            }
+            args.preScript = preScript;
+        }
+        if ("postScript" in argsObj) {
+            const postScript = argsObj.postScript;
+            if (typeof postScript !== "string" || postScript === "") {
+                return { ok: false, message: `host_tool "ghidra.analyze" args.postScript must be a non-empty string; got ${describe(postScript)}` };
+            }
+            args.postScript = postScript;
+        }
+        // Path-bearing -- resolved through resolveWorkspacePath() by
+        // runHostTool(), only validated here as a non-empty string, mirroring
+        // preScript/postScript above.
+        if ("scriptPath" in argsObj) {
+            const scriptPath = argsObj.scriptPath;
+            if (typeof scriptPath !== "string" || scriptPath === "") {
+                return { ok: false, message: `host_tool "ghidra.analyze" args.scriptPath must be a non-empty string; got ${describe(scriptPath)}` };
+            }
+            args.scriptPath = scriptPath;
+        }
+        if ("entrypointsPath" in argsObj) {
+            const entrypointsPath = argsObj.entrypointsPath;
+            if (typeof entrypointsPath !== "string" || entrypointsPath === "") {
+                return { ok: false, message: `host_tool "ghidra.analyze" args.entrypointsPath must be a non-empty string; got ${describe(entrypointsPath)}` };
+            }
+            args.entrypointsPath = entrypointsPath;
+        }
+        if ("exportPath" in argsObj) {
+            const exportPath = argsObj.exportPath;
+            if (typeof exportPath !== "string" || exportPath === "") {
+                return { ok: false, message: `host_tool "ghidra.analyze" args.exportPath must be a non-empty string; got ${describe(exportPath)}` };
+            }
+            args.exportPath = exportPath;
+        }
+        // Path-bearing -- resolved through resolveWorkspacePath() by
+        // runHostTool(), only validated here as a non-empty string, mirroring
+        // scriptPath/entrypointsPath/exportPath above. No cross-field
+        // requirement: unlike entrypointsPath (which is VolatileCarve.java's
+        // own positional argument and needs preScript to be present),
+        // dataRangesPath needs no OTHER script field to be useful.
+        if ("dataRangesPath" in argsObj) {
+            const dataRangesPath = argsObj.dataRangesPath;
+            if (typeof dataRangesPath !== "string" || dataRangesPath === "") {
+                return { ok: false, message: `host_tool "ghidra.analyze" args.dataRangesPath must be a non-empty string; got ${describe(dataRangesPath)}` };
+            }
+            args.dataRangesPath = dataRangesPath;
+        }
+        // "A script argument with no script" is refused BY NAME rather than
+        // silently dropped -- a dropped argument is how a run reports success
+        // having asserted nothing.
+        if (args.entrypointsPath !== undefined && args.preScript === undefined) {
+            return {
+                ok: false,
+                message: `host_tool "ghidra.analyze" args.entrypointsPath requires args.preScript to be present; got entrypointsPath with no preScript`,
+            };
+        }
+        if (args.postScript === undefined && (args.exportPath !== undefined || args.expectedClassificationLines !== undefined)) {
+            return {
+                ok: false,
+                message: `host_tool "ghidra.analyze" args.exportPath/args.expectedClassificationLines require args.postScript to be present; got one of them with no postScript`,
+            };
+        }
+        if (args.expectedClassificationLines !== undefined && args.exportPath === undefined) {
+            return {
+                ok: false,
+                message: `host_tool "ghidra.analyze" args.expectedClassificationLines requires args.exportPath to be present; got expectedClassificationLines with no exportPath`,
+            };
+        }
+        return { ok: true, request: { tool, args } };
+    }
+    if (tool === "oracle.probe") {
+        // No key is accepted at all -- the unknown-key check above already
+        // refused the retired "command" key (and any other key) by name, since
+        // HOST_TOOL_ARG_KEYS["oracle.probe"] is now empty. No new refusal code
+        // is needed here.
+        return { ok: true, request: { tool, args: {} } };
+    }
+    if (tool === "oracle.run") {
+        const source = argsObj.source;
+        if (typeof source !== "string" || source === "") {
+            return { ok: false, message: `host_tool "oracle.run" requires a non-empty string "source"; got ${describe(source)}` };
+        }
+        return { ok: true, request: { tool, args: { source } } };
+    }
+    if (tool === "dxa.disassemble") {
+        const image = argsObj.image;
+        if (typeof image !== "string" || image === "") {
+            return { ok: false, message: `host_tool "dxa.disassemble" requires a non-empty string "image"; got ${describe(image)}` };
+        }
+        const imageKindRaw = argsObj.imageKind;
+        // The enum is exact and case-sensitive -- "PRG" and "prg" never merge.
+        if (imageKindRaw !== "prg" && imageKindRaw !== "flat64k") {
+            return { ok: false, message: `host_tool "dxa.disassemble" args.imageKind must be "prg" or "flat64k"; got ${describe(imageKindRaw)}` };
+        }
+        const args = { image, imageKind: imageKindRaw };
+        if ("entrypointsPath" in argsObj) {
+            const entrypointsPath = argsObj.entrypointsPath;
+            if (typeof entrypointsPath !== "string" || entrypointsPath === "") {
+                return { ok: false, message: `host_tool "dxa.disassemble" args.entrypointsPath must be a non-empty string; got ${describe(entrypointsPath)}` };
+            }
+            args.entrypointsPath = entrypointsPath;
+        }
+        if ("datablocksPath" in argsObj) {
+            const datablocksPath = argsObj.datablocksPath;
+            if (typeof datablocksPath !== "string" || datablocksPath === "") {
+                return { ok: false, message: `host_tool "dxa.disassemble" args.datablocksPath must be a non-empty string; got ${describe(datablocksPath)}` };
+            }
+            args.datablocksPath = datablocksPath;
+        }
+        if ("labelsPath" in argsObj) {
+            const labelsPath = argsObj.labelsPath;
+            if (typeof labelsPath !== "string" || labelsPath === "") {
+                return { ok: false, message: `host_tool "dxa.disassemble" args.labelsPath must be a non-empty string; got ${describe(labelsPath)}` };
+            }
+            args.labelsPath = labelsPath;
+        }
+        if ("outDir" in argsObj) {
+            const outDir = argsObj.outDir;
+            if (typeof outDir !== "string" || outDir === "") {
+                return { ok: false, message: `host_tool "dxa.disassemble" args.outDir must be a non-empty string; got ${describe(outDir)}` };
+            }
+            args.outDir = outDir;
+        }
+        return { ok: true, request: { tool, args } };
+    }
+    if (tool === "ghidra.installExtension") {
+        const sourceDir = argsObj.sourceDir;
+        if (typeof sourceDir !== "string" || sourceDir === "") {
+            return { ok: false, message: `host_tool "ghidra.installExtension" requires a non-empty string "sourceDir"; got ${describe(sourceDir)}` };
+        }
+        const moduleName = argsObj.moduleName;
+        if (typeof moduleName !== "string" || moduleName === "" || !RUN_ID_PATTERN.test(moduleName)) {
+            return {
+                ok: false,
+                message: `host_tool "ghidra.installExtension" requires a non-empty "moduleName" string matching ${RUN_ID_PATTERN.source} (alphanumeric-first, alphanumeric/dash/underscore only, no separator, no dot, length-capped); got ${describe(moduleName)}`,
+            };
+        }
+        return { ok: true, request: { tool, args: { sourceDir, moduleName } } };
+    }
+    if (tool === "c1541.bam" || tool === "c1541.dir") {
+        const image = argsObj.image;
+        if (typeof image !== "string" || image === "") {
+            return { ok: false, message: `host_tool "${tool}" requires a non-empty string "image"; got ${describe(image)}` };
+        }
+        const args = { image };
+        if ("outDir" in argsObj) {
+            const outDir = argsObj.outDir;
+            if (typeof outDir !== "string" || outDir === "") {
+                return { ok: false, message: `host_tool "${tool}" args.outDir must be a non-empty string; got ${describe(outDir)}` };
+            }
+            args.outDir = outDir;
+        }
+        return { ok: true, request: { tool, args } };
+    }
+    if (tool === "c1541.entry" || tool === "c1541.chain" || tool === "c1541.read") {
+        const image = argsObj.image;
+        if (typeof image !== "string" || image === "") {
+            return { ok: false, message: `host_tool "${tool}" requires a non-empty string "image"; got ${describe(image)}` };
+        }
+        // `name` is a CBM filename or glob pattern -- REQUIRED, never a path --
+        // and refused BY NAME when its first character is a hyphen, before the
+        // child is ever spawned. The utility's own CLI would otherwise read
+        // such a value as a flag, an argument-injection route into a host
+        // process driven by container-side input.
+        const name = argsObj.name;
+        if (typeof name !== "string" || name === "") {
+            return { ok: false, message: `host_tool "${tool}" requires a non-empty string "name"; got ${describe(name)}` };
+        }
+        if (name.startsWith("-")) {
+            return {
+                ok: false,
+                message: `host_tool "${tool}" args.name must not begin with "-" -- c1541's own CLI would read it as a flag rather than a filename; got ${describe(name)}`,
+            };
+        }
+        const args = { image, name };
+        if ("outDir" in argsObj) {
+            const outDir = argsObj.outDir;
+            if (typeof outDir !== "string" || outDir === "") {
+                return { ok: false, message: `host_tool "${tool}" args.outDir must be a non-empty string; got ${describe(outDir)}` };
+            }
+            args.outDir = outDir;
+        }
+        return { ok: true, request: { tool, args } };
+    }
+    if (tool === "petcat.decode") {
+        const image = argsObj.image;
+        if (typeof image !== "string" || image === "") {
+            return { ok: false, message: `host_tool "petcat.decode" requires a non-empty string "image"; got ${describe(image)}` };
+        }
+        const args = { image };
+        if ("outDir" in argsObj) {
+            const outDir = argsObj.outDir;
+            if (typeof outDir !== "string" || outDir === "") {
+                return { ok: false, message: `host_tool "petcat.decode" args.outDir must be a non-empty string; got ${describe(outDir)}` };
+            }
+            args.outDir = outDir;
+        }
+        return { ok: true, request: { tool, args } };
+    }
+    // Unreachable while HOST_TOOL_IDS has exactly twelve members -- kept so a
+    // future tool added to HOST_TOOL_IDS without a matching narrowing arm
+    // fails loudly here rather than silently returning an under-typed request.
+    return { ok: false, message: `normaliseHostToolRequest: no narrowing arm for tool "${tool}"` };
+}
+// ---------------------------------------------------------------------------
+// Workspace-relative path resolution. A `host_tool` request never carries a
+// host-absolute path -- every path argument is workspace-relative and
+// resolved HERE, against the broker's own `--repo-root`, then re-checked to
+// be inside it. This is the ONLY place a wire-supplied path becomes a real
+// path.
+//
+// BOTH the workspace root and the candidate go through the SAME
+// ancestor-realpath walk (realpathOfNearestExisting(), below) before the
+// separator-appended prefix comparison, and the returned `ok: true` value is
+// the WALKED (real) path, never the lexical join. That is load-bearing
+// rather than a symmetry preference, for the two reasons
+// anno-types.ts:1159-1176 already names for its own two consumers of this
+// walk: a workspace root that does not yet exist is a legitimate input (a
+// bare realpath would throw a raw ENOENT), and resolving only the candidate
+// side makes every in-workspace path look foreign whenever the root itself
+// is reached through a symlink. A live symlink test is what a purely
+// lexical path.resolve() + startsWith() check missed: a symlink planted
+// inside the workspace, pointing outside it, lexically satisfied the prefix
+// check while a real write through it landed outside the root.
+//
+// BEHAVIOURAL CONSEQUENCE, intended: because this returns the real path, a
+// link pointing INSIDE the workspace is FOLLOWED and the request is
+// accepted at the link's real location -- the alternative, refusing every
+// symlink, is the over-broad fix host-tool.test.ts's discriminating cases
+// (34-10 Task 2) exist to redden.
+//
+// Two residuals recorded here, beside the guarantee rather than past it: (1)
+// the check-then-open window between this decision and the child process's
+// own open is not closed at this layer -- the child is a third-party binary
+// handed a path string, so there is no descriptor-based route to making the
+// check and the open one operation (T-34-52, accepted); (2) the comparison
+// is byte-wise over the resolved strings with the platform separator
+// appended and applies no Unicode normalisation, so two spellings differing
+// only in normalisation form are two distinct paths here (the same residual
+// anno-confinement.test.ts records for the same comparison).
+//
+// A recorded residual: because the return value is now the REAL path, on a
+// host whose workspace root is itself reached through a symlink the
+// response `path` need not match any member of hostRootCandidates()
+// (containerpath.ts), and containerPath() throws rather than passing an
+// untranslatable path through -- HOST_WORKSPACE_PATH naming the real root
+// is the pre-existing mitigation. This is a recorded limit, not a widened
+// hostpath.ts consumer set.
+// ---------------------------------------------------------------------------
+/**
+ * The maximum number of DANGLING-symlink hops `realpathOfNearestExisting`
+ * will take before refusing. 40 is deliberately the same value
+ * anno-types.ts:971 uses -- Linux's own `MAXSYMLINKS`, so a chain this walk
+ * refuses is one the kernel would refuse too. Task 2's equivalence case
+ * (against anno-types.ts's storePathWithinWorkspace()) is what keeps the two
+ * copies from drifting apart. The bound exists because a cycle (`a -> b`,
+ * `b -> a`) is otherwise an infinite loop inside a function whose input
+ * arrives unvalidated from the transport.
+ */
+const MAX_SYMLINK_HOPS = 40;
+/**
+ * Does the path ENTRY `entry` exist -- does this NAME exist in its
+ * directory -- without following a symlink at the leaf, and without
+ * throwing. Mirrors anno-types.ts's own `pathEntryExists`, with one
+ * deliberate difference: this returns a refusal where that version throws,
+ * because `resolveWorkspacePath()`'s contract is a result object and this
+ * module's own never-throw discipline must not be widened by adding
+ * filesystem access.
+ *
+ * `throwIfNoEntry: false` suppresses `ENOENT` and NOTHING ELSE
+ * (anno-types.ts:985-1000's own REVERSED-2026-08-28 note) -- a permission
+ * error or any other stat failure on an ancestor becomes a named refusal
+ * here rather than escaping as a bare thrown error.
+ */
+function pathEntryExists(entry, forPath) {
+    try {
+        return { ok: true, exists: lstatSync(entry, { throwIfNoEntry: false }) !== undefined };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            message: `cannot stat ${JSON.stringify(entry)} while confining ${JSON.stringify(forPath)} (${e.message})`,
+        };
+    }
+}
+/**
+ * Returns the REAL absolute path of `p`, resolved through the deepest
+ * ancestor whose path ENTRY exists on disk, with the non-existent tail
+ * re-joined after it -- or a refusal naming the path when the walk cannot
+ * answer.
+ *
+ * Mirrors anno-types.ts:1082's `realpathOfNearestExisting()` exactly, with
+ * the same deliberate difference `pathEntryExists()` above states: this
+ * RETURNS a refusal where that version THROWS `AnnoStorePathError`. Walks up
+ * while the path ENTRY does not exist, unshifting each `basename` onto a
+ * `tail` array; when the walk reaches the filesystem root
+ * (`dirname(current) === current`) answers from `current` plus `tail`
+ * rather than from the pre-walk resolved string, because after a hop the
+ * pre-walk string describes a location the walk is no longer on; when the
+ * stopping entry is a symlink whose target does not exist, counts a hop,
+ * refuses past `MAX_SYMLINK_HOPS` naming the bound, and resolves the link's
+ * target against the LINK'S OWN DIRECTORY -- never the process cwd, since a
+ * relative target (`../outside/x`) is the common form. Otherwise
+ * `realpathSync(current)`, joined with `tail`. Every `lstatSync`,
+ * `readlinkSync` and `realpathSync` failure becomes a refusal naming the
+ * path, never a throw.
+ */
+function realpathOfNearestExisting(p) {
+    const resolved = resolvePath(p);
+    const tail = [];
+    let current = resolved;
+    let hops = 0;
+    for (;;) {
+        let reachedFilesystemRoot = false;
+        for (;;) {
+            const entryCheck = pathEntryExists(current, resolved);
+            if (!entryCheck.ok)
+                return { ok: false, message: entryCheck.message };
+            if (entryCheck.exists)
+                break;
+            const parent = dirname(current);
+            if (parent === current) {
+                reachedFilesystemRoot = true;
+                break;
+            }
+            tail.unshift(basename(current));
+            current = parent;
+        }
+        if (reachedFilesystemRoot) {
+            return { ok: true, path: tail.length === 0 ? current : join(current, ...tail) };
+        }
+        // The stopping ENTRY exists. Is it a symlink whose target does not?
+        // That is the one class a resolve-following existence predicate cannot
+        // see, and the only one needing a hop.
+        let stoppedAtDanglingLink;
+        try {
+            stoppedAtDanglingLink = lstatSync(current).isSymbolicLink() && !existsSync(current);
+        }
+        catch (e) {
+            return {
+                ok: false,
+                message: `cannot stat ${JSON.stringify(current)} while confining ${JSON.stringify(resolved)} (${e.message})`,
+            };
+        }
+        if (stoppedAtDanglingLink) {
+            hops += 1;
+            if (hops > MAX_SYMLINK_HOPS) {
+                return {
+                    ok: false,
+                    message: `cannot resolve ${JSON.stringify(resolved)}: more than ${MAX_SYMLINK_HOPS} symbolic-link hops while resolving ` +
+                        `${JSON.stringify(current)} -- a symlink cycle or an over-long chain, refused rather than followed`,
+                };
+            }
+            let link;
+            try {
+                link = readlinkSync(current);
+            }
+            catch (e) {
+                return {
+                    ok: false,
+                    message: `cannot read the symbolic link ${JSON.stringify(current)} while confining ${JSON.stringify(resolved)} (${e.message})`,
+                };
+            }
+            // Against the LINK'S directory, never the process cwd.
+            current = resolvePath(dirname(current), link);
+            continue;
+        }
+        let real;
+        try {
+            real = realpathSync(current);
+        }
+        catch (e) {
+            return {
+                ok: false,
+                message: `cannot resolve the real path of ${JSON.stringify(current)} while confining ${JSON.stringify(resolved)} (${e.message})`,
+            };
+        }
+        return { ok: true, path: tail.length === 0 ? real : join(real, ...tail) };
+    }
+}
+export function resolveWorkspacePath(repoRoot, relative) {
+    if (typeof relative !== "string" || relative === "") {
+        return { ok: false, message: `workspace path must be a non-empty relative string; got ${describe(relative)}` };
+    }
+    if (isAbsolute(relative)) {
+        return { ok: false, message: `workspace path must be relative to the workspace root, not absolute: ${describe(relative)}` };
+    }
+    const rootAbs = resolvePath(repoRoot);
+    const walkedRoot = realpathOfNearestExisting(rootAbs);
+    if (!walkedRoot.ok) {
+        return { ok: false, message: `cannot resolve the workspace root ${JSON.stringify(rootAbs)}: ${walkedRoot.message}` };
+    }
+    const walkedCandidate = realpathOfNearestExisting(resolvePath(walkedRoot.path, relative));
+    if (!walkedCandidate.ok) {
+        return { ok: false, message: walkedCandidate.message };
+    }
+    // A bug fix: when the workspace root walks to the filesystem root itself
+    // (`walkedRoot.path === sep`, e.g. "/"), appending `sep` a second time
+    // produces "//" -- a prefix no real absolute path ever starts with
+    // (`resolvePath()`/`realpathSync()` always normalise to a single leading
+    // separator), so EVERY candidate under root "/" was wrongly refused as
+    // "escaping" a root that in fact contains it. A root this broad is a
+    // legitimate input -- c1541.mjs's own commonAncestorDir() (mirroring
+    // acme.mjs's) collapses to "/" whenever a committed fixture inside the
+    // repo and a scratch --out-dir outside it share no smaller ancestor.
+    const requiredPrefix = walkedRoot.path === sep ? walkedRoot.path : walkedRoot.path + sep;
+    if (walkedCandidate.path !== walkedRoot.path && !walkedCandidate.path.startsWith(requiredPrefix)) {
+        return {
+            ok: false,
+            message: `workspace path escapes the workspace root: ${describe(relative)} resolves to ${walkedCandidate.path}, outside ${walkedRoot.path}`,
+        };
+    }
+    return { ok: true, path: walkedCandidate.path };
+}
+/** Deterministic: the same typed request and the same resolved paths yield
+ * a byte-identical argv array on two successive calls -- no randomness, no
+ * timestamp, no environment-dependent ordering. `log` is OPTIONAL and used
+ * ONLY by the c1541.dir branch to report a PATH-fallback binary resolution
+ * -- every pre-existing branch ignores it, exactly as they already ignore
+ * any parameter they do not need. */
+export function buildHostToolArgv(request, resolved, log) {
+    if (request.tool === "acme.build") {
+        const { args } = request;
+        const { sourcePath, outDirPath, includePaths } = resolved;
+        const stem = join(outDirPath, basename(sourcePath).replace(/\.(a|asm|s)$/i, ""));
+        const prg = `${stem}.prg`;
+        // Overridable local variable named for what it holds -- never `binPath`/
+        // `viceBin`/`VICE_BIN`/`x64sc`, which spawn-seam.test.ts's
+        // EMULATOR_BIN_SHAPE would misclassify as an emulator spawn site.
+        const acmePath = process.env.ACME_BIN && process.env.ACME_BIN !== "" ? process.env.ACME_BIN : "acme";
+        // Fixed flags first, in the SAME order src/skills/acme-build/scripts/
+        // acme.mjs's build() uses today, then one -D per define and one -I pair
+        // per include in caller-given order, then --setpc if given, then the
+        // resolved source path LAST.
+        const argv = [
+            "--cpu",
+            "6510",
+            "-f",
+            args.format ?? "cbm",
+            "-Wtype-mismatch",
+            "--strict-segments",
+            "--msvc",
+            "-v1",
+            "-o",
+            prg,
+            "-l",
+            `${stem}.sym`,
+            "--vicelabels",
+            `${stem}.vs`,
+        ];
+        if (!args.noReport)
+            argv.push("-r", `${stem}.rep`);
+        for (const define of args.defines ?? [])
+            argv.push(`-D${define}`);
+        // Reads ONLY from resolved.includePaths -- never from
+        // request.args.includes -- so argv never carries a raw wire string for
+        // this field. Defensively defaults to [] so a caller that omits
+        // includePaths entirely still yields a valid, empty-include argv rather
+        // than throwing on an undefined iterable.
+        for (const include of includePaths ?? [])
+            argv.push("-I", include);
+        if (args.setpc)
+            argv.push("--setpc", args.setpc);
+        argv.push(sourcePath);
+        // The directory holding the resolved ROOT SOURCE, never `outDirPath`:
+        // `outDir` governs where the `.prg` lands and a caller may point it
+        // elsewhere, while `!source` resolution is about where the SOURCES live,
+        // beside `sourcePath` itself. See `BuildHostToolArgvResult.cwd`'s own
+        // doc-comment for the measured reason this field exists at all.
+        return { ok: true, toolPath: acmePath, argv, outputs: [prg], cwd: dirname(sourcePath) };
+    }
+    if (request.tool === "ghidra.analyze") {
+        const { importPath, projectLocation, projectName, preScriptPath, postScriptPath, scriptPathResolved, entrypointsPathResolved, exportPathResolved, dataRangesPathResolved, } = resolved;
+        // Named environment variable, never a guessed install location and
+        // never this repository's own local probe directory (T-34-16).
+        const ghidraHome = process.env.GHIDRA_HOME;
+        if (ghidraHome === undefined || ghidraHome === "") {
+            return {
+                ok: false,
+                message: `host_tool "ghidra.analyze" requires the GHIDRA_HOME environment variable to name a Ghidra installation directory; it is unset`,
+            };
+        }
+        // Overridable local variable named for what it holds -- never `binPath`/
+        // `viceBin`/`VICE_BIN`/`x64sc`, which spawn-seam.test.ts's
+        // EMULATOR_BIN_SHAPE would misclassify as an emulator spawn site.
+        const ghidraPath = join(ghidraHome, "support", "analyzeHeadless");
+        if (!existsSync(ghidraPath)) {
+            return {
+                ok: false,
+                message: `host_tool "ghidra.analyze" refuses: GHIDRA_HOME's resolved launcher does not exist on disk (${ghidraPath})`,
+            };
+        }
+        // The checked, NON-MATERIALISING language preflight -- refuses by
+        // name, before any child process is spawned, when the requested
+        // processor is not declared by any .ldefs Ghidra would load, or is
+        // declared but its slafile does not exist on disk. This is what makes a
+        // language that cannot load a named refusal instead of a green run on
+        // whatever .sla happens to be in place. The preflight CHECKS and NEVER
+        // FIXES: it must never create a directory, copy a file, invoke
+        // support/sleigh, or fall back to another language -- doing so would
+        // mask exactly the failure this check exists to catch.
+        const installedLanguages = installedLanguageIds(ghidraHome);
+        const requestedProcessor = request.args.processor;
+        const matchedLanguage = installedLanguages.find((lang) => lang.id === requestedProcessor);
+        if (!matchedLanguage) {
+            const declaredIds = installedLanguages.map((lang) => lang.id);
+            return {
+                ok: false,
+                message: `host_tool "ghidra.analyze" refuses: the requested processor ${JSON.stringify(requestedProcessor)} is not declared by any ` +
+                    `installed Ghidra language; declared id(s): ${declaredIds.length > 0 ? declaredIds.join(", ") : "(none)"}`,
+            };
+        }
+        if (!matchedLanguage.slafileExists) {
+            const missingSlaPath = join(dirname(matchedLanguage.ldefsPath), matchedLanguage.slafile);
+            return {
+                ok: false,
+                message: `host_tool "ghidra.analyze" refuses: processor ${JSON.stringify(requestedProcessor)} is declared by ${matchedLanguage.ldefsPath} ` +
+                    `but its slafile ${missingSlaPath} does not exist on disk -- run ghidra.installExtension to build it`,
+            };
+        }
+        // Argv construction and the dot-segment re-check both live in
+        // ghidra-project.mts's buildAnalyzeHeadlessArgv() -- never re-derived
+        // here.
+        // Reads ONLY from resolved.preScriptPath/postScriptPath/
+        // scriptPathResolved/entrypointsPathResolved/exportPathResolved -- never
+        // from request.args's own path-shaped fields -- so argv never carries a
+        // raw, unresolved wire string for any of them.
+        // `processor`/`loaderBaseAddr`/`noanalysis`/`expectedClassificationLines`
+        // come straight from request.args -- each is a validated non-path value
+        // (language id, hex string, boolean, integer), never a path, so none
+        // flows through resolveWorkspacePath() and none appears in `resolved`
+        // (ResolvedGhidraAnalyzePaths carries paths only).
+        const argvInput = {
+            projectLocation,
+            projectName,
+            importPath,
+            processor: request.args.processor,
+            loaderBaseAddr: request.args.loaderBaseAddr,
+        };
+        if (request.args.noanalysis !== undefined)
+            argvInput.noanalysis = request.args.noanalysis;
+        if (scriptPathResolved !== undefined)
+            argvInput.scriptPath = scriptPathResolved;
+        if (preScriptPath !== undefined)
+            argvInput.preScript = preScriptPath;
+        if (entrypointsPathResolved !== undefined)
+            argvInput.entrypointsPath = entrypointsPathResolved;
+        if (postScriptPath !== undefined)
+            argvInput.postScript = postScriptPath;
+        if (exportPathResolved !== undefined)
+            argvInput.exportPath = exportPathResolved;
+        if (request.args.expectedClassificationLines !== undefined)
+            argvInput.expectedClassificationLines = request.args.expectedClassificationLines;
+        // Reads ONLY from resolved.dataRangesPathResolved -- never from
+        // request.args.dataRangesPath -- so argv never carries a raw,
+        // unresolved wire string for this field.
+        if (dataRangesPathResolved !== undefined)
+            argvInput.dataRangesPath = dataRangesPathResolved;
+        const built = buildAnalyzeHeadlessArgv(argvInput);
+        if (!built.ok)
+            return { ok: false, message: built.message };
+        // outputs[0] is ALWAYS the run log for ghidra.analyze -- a SIBLING of
+        // the reserved project directory (never a child of it), because
+        // -deleteProject operates INSIDE projectLocation. runHostTool()'s
+        // ghidra.analyze branch below writes the child's stdout followed by its
+        // stderr here, before the digest loop runs (MEASURED:
+        // analyzeHeadless's "Using Language/Compiler:" line arrives on stdout).
+        const runLogPath = join(dirname(projectLocation), `${projectName}.ghidra-run.log`);
+        // When exportPath is present, it is a SECOND outputs[] entry --
+        // digested by the existing digestOutputFile() loop with no new digest
+        // code. outputs[0] stays the run log unconditionally.
+        const outputs = exportPathResolved !== undefined ? [runLogPath, exportPathResolved] : [runLogPath];
+        return { ok: true, toolPath: ghidraPath, argv: built.argv, outputs };
+    }
+    if (request.tool === "dxa.disassemble") {
+        const { args } = request;
+        const { imagePath, outDirPath, entrypointsPath, datablocksPath, labelsPath } = resolved;
+        // A-01: fixed, computed path -- never an env-var override (see the HERE
+        // and findDxaBinary() comments above). Refuses BY NAME when the vendored
+        // binary does not exist at EITHER candidate location, naming build.bash
+        // as the remedy, per PLAN.md item 6.
+        const dxaFound = findDxaBinary(HERE);
+        if (dxaFound.path === null) {
+            return {
+                ok: false,
+                message: `host_tool "dxa.disassemble" refuses: the vendored dxa binary does not exist (tried: ${dxaFound.tried.join(", ")}) -- run "bash vendor/dxa/build.bash build" to produce it`,
+            };
+        }
+        const dxaPath = dxaFound.path;
+        // Fixed flags first, in a fixed order (A-02): -g 0000 ONLY for a flat
+        // 64K capture, never for a .prg, whose own 2-byte load address dxa reads
+        // unassisted. Then -R/-B/-l for whichever optional resolved paths are
+        // present, in that order, then -a dump, then the resolved image path
+        // LAST. Deterministic: the same typed request and resolved paths yield a
+        // byte-identical argv array on two successive calls.
+        const argv = ["-p", "all-nmos6502", "-d", "skip-scanning", "-t", "detect-internal"];
+        if (args.imageKind === "flat64k")
+            argv.push("-g", "0000");
+        if (entrypointsPath !== undefined)
+            argv.push("-R", entrypointsPath);
+        if (datablocksPath !== undefined)
+            argv.push("-B", datablocksPath);
+        if (labelsPath !== undefined)
+            argv.push("-l", labelsPath);
+        argv.push("-a", "dump");
+        argv.push(imagePath);
+        // A-03: dxa has NO output-file option -- every listing line is
+        // fprintf(stdout, ...) (vendor/dxa/dump.c). The seam captures stdout and
+        // writes it to this single outputs[] path, then digests the FILE --
+        // never the dxa process's own exit status, which is not the pass/fail
+        // signal for a listing (must_haves.prohibitions).
+        const imageStem = basename(imagePath).replace(/\.[^./]+$/, "");
+        const listingPath = join(outDirPath, `${imageStem}.dxa-dump.lst`);
+        return { ok: true, toolPath: dxaPath, argv, outputs: [listingPath] };
+    }
+    if (request.tool === "ghidra.installExtension") {
+        const { moduleName } = resolved;
+        // Independently re-derived rather than threaded through `resolved` --
+        // mirrors ghidra.analyze's own branch above, which reads GHIDRA_HOME
+        // itself instead of accepting it as a resolved field. Both existence
+        // checks were already performed (and, for the copy, already acted on)
+        // by runHostTool()'s own resolution branch before this function was
+        // ever called; re-checking here is defense in depth, the same posture
+        // buildAnalyzeHeadlessArgv()'s own independent dot-segment re-check
+        // takes for a caller that bypassed the resolution branch entirely.
+        const ghidraHome = process.env.GHIDRA_HOME;
+        if (ghidraHome === undefined || ghidraHome === "") {
+            return {
+                ok: false,
+                message: `host_tool "ghidra.installExtension" requires the GHIDRA_HOME environment variable to name a Ghidra installation directory; it is unset`,
+            };
+        }
+        const sleighPath = join(ghidraHome, "support", "sleigh");
+        if (!existsSync(sleighPath)) {
+            return {
+                ok: false,
+                message: `host_tool "ghidra.installExtension" refuses: GHIDRA_HOME's resolved "support/sleigh" does not exist on disk (${sleighPath})`,
+            };
+        }
+        const installLanguagesDir = join(ghidraHome, "Ghidra", "Extensions", moduleName, "data", "languages");
+        const slaspecPath = join(installLanguagesDir, "6502_nmos.slaspec");
+        const slaPath = join(installLanguagesDir, "6502_nmos.sla");
+        // Argv stays an ARRAY of individually-validated entries -- never a
+        // string-concatenated single argument (must_haves.prohibitions).
+        return { ok: true, toolPath: sleighPath, argv: [slaspecPath, slaPath], outputs: [slaPath] };
+    }
+    if (request.tool === "c1541.bam" ||
+        request.tool === "c1541.dir" ||
+        request.tool === "c1541.entry" ||
+        request.tool === "c1541.chain" ||
+        request.tool === "c1541.read") {
+        const { imagePath, outDirPath } = resolved;
+        // Resolved as a SIBLING of whichever x64sc backend-detect.mts already
+        // resolved -- never a bare-name spawn, which a host carrying both a
+        // stock and a fork build would silently answer with whichever build's
+        // directory happens to sort first on $PATH (MEASURED live on this
+        // project's own dev host, see the import comment above).
+        // `resolvedBackend()` with no `supervisorDir` never touches the on-disk
+        // cache; it still memoises in-process, which is what keeps a
+        // long-running broker's SECOND call here free -- see the import
+        // comment's own memoisation posture.
+        const c1541Found = findSiblingBinary("c1541", resolvedBackend().binPath, log);
+        if (c1541Found.path === null) {
+            return {
+                ok: false,
+                message: `host_tool "${request.tool}" refuses: "c1541" does not exist (tried: ${c1541Found.tried.join(", ")})`,
+            };
+        }
+        const c1541Path = c1541Found.path;
+        const imageStem = basename(imagePath).replace(/\.[^./]+$/, "");
+        // A-02-style fixed flags: `-attach <imagePath> <verb-flag> [name]`,
+        // argv as an ARRAY of individually-validated entries, never a shell
+        // string (must_haves.prohibitions). Deterministic: the same resolved
+        // paths (and, for entry/chain/read, the same already-validated `name`)
+        // yield a byte-identical argv array on two successive calls. c1541 has
+        // NO output-file option for `-dir`/`-bam`/`-entry`/`-chain` -- every
+        // listing line is printed to its OWN stdout (MEASURED against the real
+        // committed fixture, fixtures/c1541/README.md); the seam captures
+        // stdout and writes it to a single outputs[] path (TOOLS_WHOSE_OUTPUT_IS_STDOUT
+        // above), then digests the FILE -- never c1541's own exit status, which
+        // is 0 even on a genuine failure (MEASURED: "Error - Cannot open
+        // file ..." exits 0) and is therefore never the pass/fail signal for a
+        // listing. `-read` is the one exception: the child writes the output
+        // file itself, so its argv passes the produced host path as its own
+        // final positional argument.
+        if (request.tool === "c1541.dir") {
+            return { ok: true, toolPath: c1541Path, argv: ["-attach", imagePath, "-dir"], outputs: [join(outDirPath, `${imageStem}.dir.txt`)] };
+        }
+        if (request.tool === "c1541.bam") {
+            return { ok: true, toolPath: c1541Path, argv: ["-attach", imagePath, "-bam"], outputs: [join(outDirPath, `${imageStem}.bam.txt`)] };
+        }
+        // c1541.entry / c1541.chain / c1541.read: `name` is a CBM filename or
+        // glob pattern, already validated (non-empty, no leading hyphen) by
+        // normaliseHostToolRequest() -- never re-derived here. `slug` is
+        // `name` with every character outside [A-Za-z0-9] replaced by `_`,
+        // truncated to 32 characters (interface_contract), so an arbitrary CBM
+        // name never becomes an unsafe or over-long filesystem path segment.
+        const { name } = request.args;
+        const slug = name.replace(/[^A-Za-z0-9]/g, "_").slice(0, 32);
+        if (request.tool === "c1541.entry") {
+            return {
+                ok: true,
+                toolPath: c1541Path,
+                argv: ["-attach", imagePath, "-entry", name],
+                outputs: [join(outDirPath, `${imageStem}.${slug}.entry.txt`)],
+            };
+        }
+        if (request.tool === "c1541.chain") {
+            return {
+                ok: true,
+                toolPath: c1541Path,
+                argv: ["-attach", imagePath, "-chain", name],
+                outputs: [join(outDirPath, `${imageStem}.${slug}.chain.txt`)],
+            };
+        }
+        // request.tool === "c1541.read": the single-file byte-extraction route,
+        // mirroring extractEntry(image, entryName), the now-deleted MCP-side
+        // pure-parse module's own signature, one-for-one. The produced host
+        // path is the child's OWN output argument -- c1541
+        // writes it directly, so this tool is deliberately absent from
+        // TOOLS_WHOSE_OUTPUT_IS_STDOUT and the existing digest loop picks the
+        // file up unchanged.
+        const outputPath = join(outDirPath, `${imageStem}.${slug}.bin`);
+        return { ok: true, toolPath: c1541Path, argv: ["-attach", imagePath, "-read", name, outputPath], outputs: [outputPath] };
+    }
+    if (request.tool === "petcat.decode") {
+        const { imagePath, outDirPath } = resolved;
+        // Resolved as a SIBLING of whichever x64sc backend-detect.mts already
+        // resolved, never a bare-name spawn, with a logged $PATH-fallback
+        // warning -- the same mechanism c1541.* already use above.
+        const petcatFound = findSiblingBinary("petcat", resolvedBackend().binPath, log);
+        if (petcatFound.path === null) {
+            return {
+                ok: false,
+                message: `host_tool "petcat.decode" refuses: "petcat" does not exist (tried: ${petcatFound.tried.join(", ")})`,
+            };
+        }
+        const petcatPath = petcatFound.path;
+        // The BASIC dialect is a FIXED literal here, server-side -- "-2"
+        // (BASIC V2.0, every stock C64's own dialect), first in argv, ahead of
+        // the resolved image path LAST. There is no wire field that selects it
+        // (HOST_TOOL_ARG_KEYS["petcat.decode"] carries no such key), nothing
+        // validates it, and no caller can request a different one.
+        const argv = ["-2", imagePath];
+        // petcat has no output-file option for a plain decode -- every
+        // listing line is printed to its own stdout (MEASURED, a scratch run
+        // against both committed fixtures, see fixtures/petcat/README.md). The
+        // seam captures stdout and writes it to this single outputs[] path,
+        // then digests the FILE -- never petcat's own exit status, which is 0
+        // even on garbage input (MEASURED) and therefore never the pass/fail
+        // signal for a listing.
+        const imageStem = basename(imagePath).replace(/\.[^./]+$/, "");
+        const listingPath = join(outDirPath, `${imageStem}.bas.txt`);
+        return { ok: true, toolPath: petcatPath, argv, outputs: [listingPath] };
+    }
+    return { ok: false, message: `buildHostToolArgv: no argv builder for tool "${request.tool}"` };
+}
+// ---------------------------------------------------------------------------
+// Async child-process invocation and result digest. NEVER `spawnSync` --
+// broker-kill.mts's uncaughtException/unhandledRejection handlers kill the
+// ENTIRE VICE pool on any unhandled throw in this process, and a
+// synchronous spawn for a multi-second tool run would block the
+// single-threaded event loop for its whole duration, starving acquires,
+// the launching -> ready promotion sweep (the warm floor this comment used
+// to name alongside it was later retired), and monitor claims.
+// ---------------------------------------------------------------------------
+/** Fallback per-invocation timeout for a tool id absent from
+ * HOST_TOOL_TIMEOUT_MS below -- unreachable today, since every
+ * HOST_TOOL_IDS member has an explicit table entry, but this constant
+ * stays exported and consulted as the honest bottom of the resolver's
+ * fallback chain. It is also the value acme.build/oracle.probe/oracle.run's
+ * own table entries hold today (20s, the same value packer-finding.mjs's
+ * own ORACLE_TIMEOUT_MS convention already used) -- no longer the ceiling
+ * for EVERY invocation: a single default governing every tool is exactly
+ * how a real incident happened -- a number chosen for a stateless
+ * assembler silently governed a JVM. */
+export const DEFAULT_HOST_TOOL_TIMEOUT_MS = 20_000;
+/** The per-tool SERVER-side budget table, built with the SAME
+ * `Object.freeze(Object.assign(Object.create(null), ...))` idiom
+ * HOST_TOOL_ARG_KEYS uses, with an entry for EVERY HOST_TOOL_IDS member --
+ * completeness enforced by host-tool.test.ts's own completeness case,
+ * never assumed silently. `acme.build`, `oracle.probe` and `oracle.run`
+ * keep the value DEFAULT_HOST_TOOL_TIMEOUT_MS already held (20_000ms) --
+ * none of their measured costs approach the fixed ceiling. `ghidra.analyze`
+ * gets 600_000ms (10 minutes), justified from this project's own recorded
+ * numbers rather than a round guess: the documented JVM startup range is
+ * 12.6-17.4s, live testing measured 12407ms and 11160ms for a *refusal*
+ * alone, and the same measurement record states a real analysis run takes
+ * multiple minutes -- 10 minutes clears startup plus a realistic analysis
+ * budget with headroom, while staying a finite, stated ceiling: raising a
+ * budget must never mean removing the kill-on-expiry bound --
+ * spawnHostTool()'s timer below still kills and reports a refusal on
+ * expiry, unchanged. */
+export const HOST_TOOL_TIMEOUT_MS = Object.freeze(Object.assign(Object.create(null), {
+    "acme.build": DEFAULT_HOST_TOOL_TIMEOUT_MS,
+    "ghidra.analyze": 600_000,
+    "oracle.probe": DEFAULT_HOST_TOOL_TIMEOUT_MS,
+    "oracle.run": DEFAULT_HOST_TOOL_TIMEOUT_MS,
+    // DEFAULT_HOST_TOOL_TIMEOUT_MS, justified from a measurement rather
+    // than a round guess -- the pinned dxa disassembles a full 65,536-byte
+    // image in 21ms wall-clock (MEASURED), a 950x headroom against this 20s
+    // ceiling. host-tool-client.ts's request-deadline table gains NO entry
+    // for this tool, because DEFAULT_HOST_TOOL_REQUEST_TIMEOUT_MS (30_000)
+    // already exceeds this value -- the cross-seam ordering test stays
+    // satisfied by construction.
+    "dxa.disassemble": DEFAULT_HOST_TOOL_TIMEOUT_MS,
+    // DEFAULT_HOST_TOOL_TIMEOUT_MS, justified from a measurement rather
+    // than a round guess -- `support/sleigh` compiled this extension's
+    // whole vendored tree in 1763ms wall-clock (MEASURED, a scratch run),
+    // an ~11x headroom against this 20s ceiling. host-tool-client.ts's
+    // request-deadline table gains NO entry for this tool, for the same
+    // reason dxa.disassemble's own comment above states:
+    // DEFAULT_HOST_TOOL_REQUEST_TIMEOUT_MS (30_000) already exceeds this
+    // value.
+    "ghidra.installExtension": DEFAULT_HOST_TOOL_TIMEOUT_MS,
+    // DEFAULT_HOST_TOOL_TIMEOUT_MS, justified from a measurement rather
+    // than a round guess -- `c1541 -attach fixtures/c1541/synthetic.d64
+    // -dir` completed in 15ms wall-clock (MEASURED, a scratch run against
+    // the committed fixture), a >1300x headroom against this 20s ceiling.
+    // host-tool-client.ts's request-deadline table gains NO entry for this
+    // tool, for the same reason dxa.disassemble's own comment above states:
+    // DEFAULT_HOST_TOOL_REQUEST_TIMEOUT_MS (30_000) already exceeds this
+    // value.
+    "c1541.dir": DEFAULT_HOST_TOOL_TIMEOUT_MS,
+    // DEFAULT_HOST_TOOL_TIMEOUT_MS for all four, justified from a
+    // measurement rather than a round guess -- each of `c1541 -attach
+    // fixtures/c1541/synthetic.d64 -bam`, `-entry basicstub`, `-chain
+    // basicstub` and `-read basicstub <out>` completed in 14-16ms
+    // wall-clock (MEASURED, a scratch run against the committed fixture),
+    // a >1200x headroom against this 20s ceiling. host-tool-client.ts's
+    // request-deadline table gains NO entry for any of these, for the same
+    // reason c1541.dir's own comment above states.
+    "c1541.bam": DEFAULT_HOST_TOOL_TIMEOUT_MS,
+    "c1541.entry": DEFAULT_HOST_TOOL_TIMEOUT_MS,
+    "c1541.chain": DEFAULT_HOST_TOOL_TIMEOUT_MS,
+    "c1541.read": DEFAULT_HOST_TOOL_TIMEOUT_MS,
+    // DEFAULT_HOST_TOOL_TIMEOUT_MS, justified from a measurement rather
+    // than a round guess -- `petcat -2` completed in 1-2ms wall-clock
+    // against both committed fixtures (MEASURED, a scratch run), a
+    // >10000x headroom against this 20s ceiling. host-tool-client.ts's
+    // request-deadline table gains NO entry for this tool, for the same
+    // reason c1541.dir's own comment above states:
+    // DEFAULT_HOST_TOOL_REQUEST_TIMEOUT_MS (30_000) already exceeds this
+    // value.
+    "petcat.decode": DEFAULT_HOST_TOOL_TIMEOUT_MS,
+}));
+/** The resolver every spawn site reads its budget from: an explicit
+ * override (`deps.timeoutMs` -- the in-process test seam) always wins;
+ * else the table entry above for `tool`; else DEFAULT_HOST_TOOL_TIMEOUT_MS
+ * as the fallback for a tool id with no table entry (unreachable today, but
+ * keeps this function total rather than partial). This is the ONE place a
+ * budget is decided -- runHostTool()'s acme.build/ghidra.analyze branch,
+ * runOracleProbe() and runOracleRun() all call it rather than reading
+ * DEFAULT_HOST_TOOL_TIMEOUT_MS or the table directly. */
+export function hostToolTimeoutMs(tool, override) {
+    if (override !== undefined)
+        return override;
+    return HOST_TOOL_TIMEOUT_MS[tool] ?? DEFAULT_HOST_TOOL_TIMEOUT_MS;
+}
+/** stderrTail's byte cap -- diagnostics only, never a result. */
+const STDERR_TAIL_CAP_BYTES = 64 * 1024;
+/** oracle.run's stdout cap -- the SAME measured bound as
+ * packer-finding.mjs's own (unmoved, still exported there) MAX_ORACLE_STDOUT_BYTES.
+ * The executor enforces the bound on what it accumulates; the script keeps
+ * exporting the number for its own parser and its own tests -- not a
+ * duplicated maintenance burden, the same measured constant on both sides. */
+const ORACLE_STDOUT_CAP_BYTES = 64 * 1024;
+/** The hard ceiling spawnHostTool()'s own stdout/stderr accumulation
+ * enforces, independent of the DEFAULT_HOST_TOOL_TIMEOUT_MS wall-clock kill
+ * below -- previously the ONLY bound on a runaway child was the timeout,
+ * so a pathological process could grow an unbounded in-memory string for
+ * its full allotted budget. c1541.chain/c1541.bam are run directly against
+ * untrusted, possibly-corrupt disk images (this project's own audit
+ * tooling exists specifically to detect fabricated/cyclic directory
+ * structures), and c1541 has no documented guard of its own against a
+ * cyclic DATA sector chain.
+ *
+ * Deliberately NOT set to STDOUT_CLASSIFY_CAP_BYTES (64KiB) or "a slightly
+ * larger" ceiling close to it, even though a smaller cap was the initial
+ * suggestion: TOOLS_WHOSE_OUTPUT_IS_STDOUT tools (dxa.disassemble, all
+ * four stdout-shaped c1541.* ids, petcat.decode) write the FULL captured
+ * stdout verbatim to their declared output file below (the
+ * writeFileSync() call right after the spawn) -- a full dxa.disassemble
+ * listing for a real 64KB-image fixture already measures well past 64KiB
+ * of text, so a cap anywhere near that size would silently truncate a
+ * legitimate disassembly into a corrupt, incomplete listing every time it
+ * ran, not just on a malicious input. This ceiling is sized purely as a
+ * runaway-memory guard against a pathological/looping child, far above any
+ * legitimate output this seam produces today. */
+const SPAWN_ACCUMULATION_HARD_CAP_BYTES = 64 * 1024 * 1024;
+/** Which tool ids write NO output file of their own -- their "output" IS
+ * the captured stdout, so runHostTool() turns it into a file itself before
+ * the digest loop runs (see the usage site below). Replaces the condition
+ * that used to name only "dxa.disassemble" directly -- a future addition
+ * is one entry in this frozen set, never a near-duplicate `if` branch.
+ * `c1541.read` is deliberately ABSENT -- its argv passes the produced host
+ * path as the child's own output argument (`-read <name> <outputPath>`),
+ * so the child writes that file itself and the existing digest loop picks
+ * it up unchanged. */
+const TOOLS_WHOSE_OUTPUT_IS_STDOUT = new Set([
+    "dxa.disassemble",
+    "c1541.bam",
+    "c1541.dir",
+    "c1541.entry",
+    "c1541.chain",
+    // petcat.decode has no output-file option for a plain decode -- every
+    // listing line is printed to its own stdout, exactly like
+    // dxa.disassemble/c1541.* above.
+    "petcat.decode",
+]);
+/** The byte cap this module's c1541.bam/c1541.entry/c1541.chain
+ * classifiers apply to the captured text BEFORE testing it against a
+ * declared shape -- spawnHostTool()'s own stdout accumulation has no
+ * explicit bound today, and a sector chain (c1541.chain) is the first
+ * disk-image-driven input that could make it large. Same value and the
+ * same tail/cap convention (tailBytes(), keep the END, not the start)
+ * STDERR_TAIL_CAP_BYTES below already applies. */
+const STDOUT_CLASSIFY_CAP_BYTES = 64 * 1024;
+/** Total `Readonly<Record<HostToolId, HostToolOutputClassifier | null>>` --
+ * built with the SAME `Object.freeze(Object.assign(Object.create(null),
+ * ...))` idiom HOST_TOOL_ARG_KEYS uses. Pre-existing ids map to `null`,
+ * meaning "no declared shape, behaviour unchanged" -- NEVER absent, so a
+ * tool id never falls through to an implicit success. `host-tool.test.ts`'s
+ * completeness case asserts every HOST_TOOL_IDS member has an own
+ * property here. */
+export const HOST_TOOL_OUTPUT_CLASSIFIERS = Object.freeze(Object.assign(Object.create(null), {
+    "acme.build": null,
+    "ghidra.analyze": null,
+    "oracle.probe": null,
+    "oracle.run": null,
+    "dxa.disassemble": null,
+    "ghidra.installExtension": null,
+    // Declared shape (MEASURED against the committed fixture): a
+    // `<N> blocks free` trailer. MEASURED also: c1541 prints an "OPENCBM:
+    // opening dynamic library libopencbm.so failed!" complaint to stdout on
+    // EVERY call on this host -- a negative stderr oracle would be wrong
+    // here, since the complaint lands on stdout, not stderr, and is
+    // unrelated to whether the listing itself succeeded.
+    "c1541.dir": ((ctx) => classifyC1541DirOutput(ctx.stdout)),
+    // Declared shape (MEASURED against the committed fixture): at least
+    // one per-sector allocation row -- a digit-prefixed line followed by
+    // a run of `*`/`.` characters.
+    "c1541.bam": ((ctx) => classifyC1541BamOutput(ctx.stdout)),
+    // Declared shape (MEASURED against the committed fixture): a
+    // `T/S: <t>/<s>, <n> blocks` line.
+    "c1541.entry": ((ctx) => classifyC1541EntryOutput(ctx.stdout)),
+    // Declared shape (MEASURED against the committed fixture): at least
+    // one `(track,sector) ->` arrow pair. MEASURED: a single-sector file's
+    // chain output does NOT repeat a second (track,sector) tuple on the
+    // right of the arrow -- the LAST hop prints only the byte count used
+    // in the final sector, a plain integer -- so this classifier matches
+    // on "at least one (t,s) followed by an arrow", not on a
+    // tuple-on-both-sides shape (see fixtures/c1541/README.md).
+    "c1541.chain": ((ctx) => classifyC1541ChainOutput(ctx.stdout)),
+    // Declared shape: `results` contains exactly one entry whose
+    // `byteLength` is greater than zero -- reads `results`, not captured
+    // text, since c1541.read is absent from TOOLS_WHOSE_OUTPUT_IS_STDOUT
+    // (the child writes its own output file).
+    "c1541.read": ((ctx) => classifyC1541ReadOutput(ctx.results)),
+    // Declared shape (MEASURED against both committed fixtures): the
+    // leading banner line petcat -2 prints for a recognised BASIC program,
+    // `;<path> ==<hex>==`. MEASURED also: petcat exits 0 on garbage input,
+    // and its output for a truly non-BASIC file carries no such banner at
+    // all -- confirmed live against 64 random bytes.
+    "petcat.decode": ((ctx) => classifyPetcatDecodeOutput(ctx.stdout)),
+}));
+/** The declared success shape for c1541.dir's captured stdout: at least one
+ * numeric block-count trailer of the form `<N> blocks free` (MEASURED
+ * against the committed fixture, fixtures/c1541/README.md). A `-dir`
+ * listing is small and bounded by the disk's own directory-sector budget,
+ * so this classifier tests the FULL captured text -- c1541.bam/entry/chain
+ * below, whose input can grow with a disk image's sector-chain contents,
+ * classify over a capped prefix instead. */
+export function classifyC1541DirOutput(stdout) {
+    if (/\d+\s+blocks\s+free/i.test(stdout))
+        return { ok: true };
+    return { ok: false, reason: `c1541.dir: captured stdout carries no "<N> blocks free" trailer -- got: ${describe(tailBytes(stdout, 512))}` };
+}
+/** The declared success shape for c1541.bam's captured stdout: at least one
+ * per-sector allocation row (MEASURED against the committed fixture,
+ * fixtures/c1541/README.md) -- a digit-prefixed line ("  1  ........
+ * ........ .....", "17  **...... ........ .....") followed by a run of at
+ * least two `*`/`.` characters. */
+export function classifyC1541BamOutput(stdout) {
+    const capped = tailBytes(stdout, STDOUT_CLASSIFY_CAP_BYTES);
+    if (/^\s*\d{1,2}\s+[*.]{2,}/m.test(capped))
+        return { ok: true };
+    return { ok: false, reason: `c1541.bam: captured stdout carries no per-sector allocation row -- got: ${describe(capped.slice(0, 512))}` };
+}
+/** The declared success shape for c1541.entry's captured stdout: a `T/S:
+ * <t>/<s>, <n> blocks` line (MEASURED against the committed fixture,
+ * fixtures/c1541/README.md -- e.g. "T/S: 17/0,  1 blocks", note the double
+ * space before the count). */
+export function classifyC1541EntryOutput(stdout) {
+    const capped = tailBytes(stdout, STDOUT_CLASSIFY_CAP_BYTES);
+    if (/T\/S:\s*\d+\/\d+,\s*\d+\s*blocks/.test(capped))
+        return { ok: true };
+    return { ok: false, reason: `c1541.entry: captured stdout carries no "T/S: <t>/<s>, <n> blocks" line -- got: ${describe(capped.slice(0, 512))}` };
+}
+/** The declared success shape for c1541.chain's captured stdout: at least
+ * one `(track,sector) ->` arrow pair (MEASURED against the committed
+ * fixture, fixtures/c1541/README.md -- a single-sector file's chain reads
+ * `(17, 0) -> 19`; a multi-sector file's reads `(17, 2) -> (17,12) -> 28`).
+ * Matches on a track/sector tuple immediately followed by an arrow, NOT on
+ * a tuple appearing on BOTH sides of the arrow -- the committed fixture's
+ * own single-sector files never produce the latter shape. */
+export function classifyC1541ChainOutput(stdout) {
+    const capped = tailBytes(stdout, STDOUT_CLASSIFY_CAP_BYTES);
+    if (/\(\s*\d+\s*,\s*\d+\s*\)\s*->/.test(capped))
+        return { ok: true };
+    return { ok: false, reason: `c1541.chain: captured stdout carries no "(track,sector) ->" arrow pair -- got: ${describe(capped.slice(0, 512))}` };
+}
+/** The declared success shape for c1541.read: `results` (the digest loop's
+ * own output, not captured text) contains exactly one entry whose
+ * `byteLength` is greater than zero. */
+export function classifyC1541ReadOutput(results) {
+    if (results.length === 1 && results[0].byteLength > 0)
+        return { ok: true };
+    return {
+        ok: false,
+        reason: `c1541.read: expected exactly one result with a byteLength greater than zero; got ${results.length} result(s)${results.length === 1 ? ` (byteLength ${results[0].byteLength})` : ""}`,
+    };
+}
+/** The declared success shape for petcat.decode's captured stdout: the
+ * leading banner line `petcat -2` prints for a recognised BASIC program,
+ * `;<path> ==<hex>==` (MEASURED against both committed fixtures --
+ * `;.../basic-stub.prg ==0801==`, `;.../computed-sys.prg ==0801==`).
+ * Absence of it means the file was not recognised as a BASIC program at
+ * all -- MEASURED against 64 random bytes, whose captured output carries a
+ * leading `;<path> ` but never the `==<hex>==` pair that follows it for a
+ * real BASIC program. petcat exits 0 either way -- this classifier, not
+ * the exit code, is what decides success here. */
+export function classifyPetcatDecodeOutput(stdout) {
+    if (/;\S+\s+==[0-9a-fA-F]+==/.test(stdout))
+        return { ok: true };
+    return {
+        ok: false,
+        reason: `petcat.decode: captured stdout carries no ";<path> ==<hex>==" banner -- the file was not recognised as a BASIC program -- got: ${describe(tailBytes(stdout, 512))}`,
+    };
+}
+/** Parses `petcat -2`'s own detokenized BASIC listing for the program's own
+ * machine-code handover instruction (`SYS`). Pure and total -- never
+ * throws -- reading ONLY the classifier-accepted captured stdout, called
+ * host-side immediately after the classifier above accepts. Three cases,
+ * ALL successes -- `ok: false` is reserved for the classifier's own shape
+ * refusal above, never for an unresolved SYS argument:
+ *   - an all-decimal-digit argument resolves to a numeric entry point,
+ *     named by the BASIC line it came from (the literal fast path);
+ *   - anything else is a named decline quoting the unresolved expression
+ *     verbatim, so a reader sees exactly what could not be resolved (the
+ *     computed case, whose own fixture exercises it);
+ *   - no SYS token at all is a named decline saying so.
+ * Matches the FIRST BASIC line whose statement (immediately after the line
+ * number) is the `sys` keyword -- petcat's own detokenized output always
+ * prints a line as `<blanks><line number> <statement>`, MEASURED against
+ * both committed fixtures (fixtures/dxa/basic-stub.prg, "10 sys2064";
+ * fixtures/petcat/computed-sys.prg, "10 sys peek(43)+256*peek(44)"). */
+export function derivePetcatEntrypoint(detokenizedText) {
+    for (const line of detokenizedText.split(/\r?\n/)) {
+        const m = line.match(/^\s*(\d+)\s+sys\s*(\S.*?)\s*$/i);
+        if (!m)
+            continue;
+        const basicLine = m[1];
+        const argument = m[2];
+        if (/^\d+$/.test(argument)) {
+            // A fix for a real bug: an all-decimal-digit SYS argument used to be
+            // accepted as a literal entry point with no upper-bound check --
+            // `Number()` converts an arbitrarily long digit string (with silent
+            // precision loss past 2^53) and a BASIC program can legally contain
+            // `SYS 999999` or larger. The C64's real address space is 0..65535;
+            // anything outside that range (or that loses precision on the way to
+            // a safe integer) is reported through the SAME named-decline path the
+            // non-literal ("computed") case below already uses, rather than
+            // passed through as a real entry point.
+            const value = Number(argument);
+            if (Number.isSafeInteger(value) && value >= 0 && value <= 0xffff) {
+                return {
+                    entrypoint: value,
+                    entrypointReason: `literal SYS argument on BASIC line ${basicLine}: sys${argument}`,
+                };
+            }
+            return {
+                entrypoint: null,
+                entrypointReason: `SYS argument on BASIC line ${basicLine} (${argument}) is outside the C64's 16-bit address space and cannot be a real entry point`,
+            };
+        }
+        return {
+            entrypoint: null,
+            entrypointReason: `SYS argument on BASIC line ${basicLine} is not a literal decimal value and cannot be resolved to an address: sys ${argument}`,
+        };
+    }
+    return { entrypoint: null, entrypointReason: "the listing contains no handover instruction" };
+}
+/** Digests one produced output file: byte size from a filesystem stat, sha256
+ * over its real bytes. A zero-byte file yields `byteLength: 0` and the
+ * sha256 of the empty byte string -- never an omitted or null entry. Returns
+ * `null` only when the file does not exist / is unreadable, so a tool run
+ * that never produced this output reports no entry for it at all (distinct
+ * from a produced-but-empty file). */
+function digestOutputFile(path) {
+    try {
+        // byteLength must describe the SAME bytes sha256 was computed over --
+        // derived from the buffer actually read, never from a separate
+        // statSync() call, which could observe a different byte string if the
+        // file is written to between the two reads.
+        const contents = readFileSync(path);
+        const sha256 = createHash("sha256").update(contents).digest("hex");
+        return { path, sha256, byteLength: contents.length };
+    }
+    catch {
+        return null;
+    }
+}
+/** Caps `text` to its LAST `capBytes` bytes (UTF-8), never its first --
+ * diagnostics from the tail of a long run are what a caller actually needs. */
+function tailBytes(text, capBytes) {
+    const buf = Buffer.from(text, "utf8");
+    if (buf.length <= capBytes)
+        return text;
+    return buf.subarray(buf.length - capBytes).toString("utf8");
+}
+/** Spawns `toolPath` with `argv` (an ARRAY, never a shell string; the
+ * command interpreter is never enabled) and resolves -- NEVER rejects --
+ * once the child exits, errors, or is killed on timeout expiry. This is the
+ * ONE spawn call in this module -- oracle.probe/oracle.run reuse it rather
+ * than adding a second. `env` defaults to the broker process's own
+ * environment (`spawn()`'s own default) when omitted; acme.build overrides
+ * it to inject a probed `ACME` library directory (see `findAcmeLib()`
+ * below). `stdout` is captured (not just `stderr`) because oracle.run's
+ * contract is "the oracle's stdout", not a file digest -- acme.build/
+ * ghidra.analyze simply ignore the field, exactly as they ignored stdout
+ * before it was piped (ACME writes nothing to stdout; verified
+ * empirically). `cwd` defaults to the broker process's own working
+ * directory (`spawn()`'s own default) when omitted -- exactly `env`'s
+ * existing default shape; only `acme.build` passes one, and every other
+ * tool's spawn is therefore byte-identical to before this parameter
+ * existed. */
+function spawnHostTool(toolPath, argv, timeoutMs, env, cwd) {
+    return new Promise((resolvePromise) => {
+        let settled = false;
+        let timedOut = false;
+        let stdout = "";
+        let stderr = "";
+        let child;
+        try {
+            child = spawn(toolPath, argv, { stdio: ["ignore", "pipe", "pipe"], ...(env ? { env } : {}), ...(cwd ? { cwd } : {}) });
+        }
+        catch (e) {
+            resolvePromise({
+                exitCode: null,
+                timedOut: false,
+                spawnErrorMessage: e instanceof Error ? e.message : String(e),
+                stdout: "",
+                stderr: "",
+            });
+            return;
+        }
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, timeoutMs);
+        if (typeof timer.unref === "function")
+            timer.unref();
+        // Stop appending once the hard ceiling is reached, rather than capping
+        // via tailBytes()'s "keep the end" convention used elsewhere in this
+        // module -- unlike stderrTail/the classifier window (diagnostics only),
+        // this accumulated string doubles as the literal file content for
+        // TOOLS_WHOSE_OUTPUT_IS_STDOUT tools, so preserving the HEAD (the
+        // already-received, in-order prefix) rather than an arbitrary tail
+        // fragment keeps a capped run's written output internally coherent (a
+        // truncated-but-ordered listing) instead of discarding its beginning.
+        // The ceiling itself is set far above any legitimate output this seam
+        // produces (see SPAWN_ACCUMULATION_HARD_CAP_BYTES above), so this
+        // branch is never taken on a normal, successful run.
+        child.stdout?.on("data", (chunk) => {
+            if (stdout.length < SPAWN_ACCUMULATION_HARD_CAP_BYTES) {
+                stdout += chunk.toString("utf8");
+            }
+        });
+        child.stderr?.on("data", (chunk) => {
+            if (stderr.length < SPAWN_ACCUMULATION_HARD_CAP_BYTES) {
+                stderr += chunk.toString("utf8");
+            }
+        });
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolvePromise({ exitCode: null, timedOut, spawnErrorMessage: err.message, stdout, stderr });
+        });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolvePromise({ exitCode: code, timedOut, spawnErrorMessage: null, stdout, stderr });
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// The ACME library probe. Moved server-side from acme.mjs's own
+// findAcmeLib(): the project owner's rule is that a container has no PATH
+// to a host binary, and these five candidates are HOST paths -- so probing
+// them belongs on the host side of the seam, not in the container-side
+// skill script. Behaviourally identical to the removed client-side
+// function: same candidate order, same marker file, same "first candidate
+// whose marker exists wins" rule.
+// ---------------------------------------------------------------------------
+/** The marker file used to validate a candidate ACME library directory --
+ * the layout fact `acme.mjs`'s own troubleshooting hint names. */
+const ACME_LIB_MARKER = join("cbm", "c64", "vic.a");
+// ---------------------------------------------------------------------------
+// The vendored dxa binary probe. This module ships two ways: as unbuilt
+// source (src/mcp/vice/host-tool.mts, HERE == src/mcp/vice/) and as the
+// compiled artifact this project actually runs
+// (src/mcp/vice/resources/host-tool.mjs, HERE == src/mcp/vice/resources/).
+// ghidra-project.mjs's own sibling-ness to host-tool.mjs survives that move
+// because BOTH are compiled into resources/ together (build.ts's
+// HOST_BOUND_ARTIFACTS). vendor/dxa/dxa does NOT survive it -- it is a real
+// binary, never copied anywhere by build.ts, always at
+// src/mcp/vice/vendor/dxa/dxa. So "vendor/dxa/dxa relative to
+// import.meta.url" means two DIFFERENT candidate locations depending on
+// which form of this module is executing: same-directory for the unbuilt
+// source, one level up for the compiled artifact. Mirrors findAcmeLib()'s
+// own "candidate list, first existing wins" idiom, immediately below.
+// ---------------------------------------------------------------------------
+export function findDxaBinary(here) {
+    const tried = [join(here, "vendor", "dxa", "dxa"), join(here, "..", "vendor", "dxa", "dxa")];
+    for (const candidate of tried) {
+        if (existsSync(candidate))
+            return { path: candidate, tried };
+    }
+    return { path: null, tried };
+}
+function findAcmeLib() {
+    const tried = [];
+    const candidates = [
+        process.env.ACME,
+        "/usr/local/share/acme",
+        "/usr/share/acme",
+        "/usr/lib/acme",
+        process.env.HOME ? join(process.env.HOME, ".acme") : undefined,
+    ].filter((c) => typeof c === "string" && c !== "");
+    for (const c of candidates) {
+        tried.push(c);
+        if (existsSync(join(c, ACME_LIB_MARKER)))
+            return { path: c, tried };
+    }
+    return { path: null, tried };
+}
+// ---------------------------------------------------------------------------
+// The c1541/petcat sibling-binary probe. Follows findDxaBinary()'s own
+// candidate-list idiom: try the most-trustworthy candidate first, fall back
+// only when it does not exist, and return every candidate tried so a
+// refusal can name them all. Unlike findDxaBinary() (a FIXED,
+// project-vendored path) and findAcmeLib() (a FIXED list of well-known
+// host install locations), this probe's first candidate is COMPUTED per
+// call, from whichever x64sc backend-detect.mts already resolved -- see
+// the resolvedBackend() import comment above for why that call is cheap
+// here. No version probe: deliberately withdrawn by the project owner --
+// this stays a name-and-location probe only and must not gain one back.
+// ---------------------------------------------------------------------------
+/** Memoised per binary name for the process lifetime -- mirrors
+ * backend-detect.mts's own stated posture of resolving once per process,
+ * never re-probing per call. A `null` (not found) answer is memoised too: a
+ * transient host misconfiguration that resolves differently mid-process is
+ * not a case this module has ever handled for any of its other binary
+ * probes (findDxaBinary()/findAcmeLib() are also called fresh per
+ * buildHostToolArgv() invocation but read a fixed, unchanging candidate set
+ * -- this probe's OWN per-binary-name memo exists because its first
+ * candidate is computed from a resolvedBackend() call that is itself
+ * memoised, so re-deriving it per call would just re-walk $PATH for no new
+ * information). */
+const siblingBinaryMemo = new Map();
+function findSiblingBinary(binaryName, resolvedX64scPath, log) {
+    const memoised = siblingBinaryMemo.get(binaryName);
+    if (memoised)
+        return memoised;
+    const tried = [];
+    // First candidate: the SAME directory the resolved x64sc itself lives in.
+    const siblingCandidate = join(dirname(resolvedX64scPath), binaryName);
+    tried.push(siblingCandidate);
+    if (existsSync(siblingCandidate)) {
+        const result = { path: siblingCandidate, tried };
+        siblingBinaryMemo.set(binaryName, result);
+        return result;
+    }
+    // Fallback: a $PATH walk (mirrors defaultResolveBinPath()'s own algorithm,
+    // backend-detect.mts), logging a warning naming the resolved x64sc path,
+    // the PATH match, and that this MAY be a DIFFERENT VICE build than the
+    // emulator -- never a silent PATH fallback.
+    const pathEnv = process.env.PATH ?? "";
+    for (const dir of pathEnv.split(":")) {
+        if (!dir)
+            continue;
+        const candidate = join(dir, binaryName);
+        tried.push(candidate);
+        if (existsSync(candidate)) {
+            log?.(`host_tool: "${binaryName}" was not found alongside the resolved x64sc (${resolvedX64scPath}); ` +
+                `falling back to a $PATH match at ${candidate} -- this may be a DIFFERENT VICE build than the emulator`);
+            const result = { path: candidate, tried };
+            siblingBinaryMemo.set(binaryName, result);
+            return result;
+        }
+    }
+    const result = { path: null, tried };
+    siblingBinaryMemo.set(binaryName, result);
+    return result;
+}
+/** Narrows, resolves, builds argv, then spawns the child ASYNCHRONOUSLY.
+ * NOTHING throws out of this function -- every failure path (refusal,
+ * launch error, timeout, non-zero exit, unreadable output) resolves to a
+ * response object, because broker-kill.mts's uncaughtException/
+ * unhandledRejection handlers kill the whole VICE pool on an unhandled
+ * throw in this process. Emits exactly one `log()` line per ATTEMPTED
+ * invocation (i.e. once argv construction succeeded and a child was
+ * actually spawned) naming the tool id, the exit status, the elapsed
+ * milliseconds and the budget that was actually applied
+ * (`timeout_ms=<n>`, from hostToolTimeoutMs()) -- so which budget governed
+ * a run is observable off the log line rather than inferred. A request
+ * refused before a child is ever spawned emits no log line -- there is no
+ * invocation to record. */
+export async function runHostTool(raw, deps) {
+    const narrowed = normaliseHostToolRequest(raw);
+    if (!narrowed.ok)
+        return { ok: false, message: narrowed.message };
+    const { request } = narrowed;
+    // oracle.probe/oracle.run do not fit the "spawn a tool that writes files,
+    // then digest them" shape below -- their contract is the SPAWNED
+    // PROCESS'S OWN stdout (a version banner, or the oracle's unpacked-output
+    // text), not a produced-file digest. Handled as their own branch, reusing
+    // spawnHostTool() (the one spawn call) rather than adding a second.
+    if (request.tool === "oracle.probe")
+        return runOracleProbe(deps);
+    if (request.tool === "oracle.run")
+        return runOracleRun(request.args, deps);
+    const repoRootAbs = resolvePath(deps.repoRoot);
+    let built;
+    let acmeLib = null;
+    // resolveGhidraProject() (below, in the ghidra.analyze branch) RESERVES
+    // the run directory (creates it on disk) before buildHostToolArgv()'s own
+    // GHIDRA_HOME/launcher/language preflight checks ever run -- those checks
+    // can still fail for a completely ordinary, fixable reason (unset
+    // GHIDRA_HOME, processor not yet installed). Recorded here so the shared
+    // `!built.ok` check below can clean up the orphaned reservation rather
+    // than burning the runId permanently.
+    let ghidraReservedProjectLocation;
+    if (request.tool === "acme.build") {
+        const sourceResolved = resolveWorkspacePath(repoRootAbs, request.args.source);
+        if (!sourceResolved.ok)
+            return { ok: false, message: sourceResolved.message };
+        let outDirPath;
+        if (request.args.outDir !== undefined) {
+            const outDirResolved = resolveWorkspacePath(repoRootAbs, request.args.outDir);
+            if (!outDirResolved.ok)
+                return { ok: false, message: outDirResolved.message };
+            outDirPath = outDirResolved.path;
+        }
+        else {
+            outDirPath = dirname(sourceResolved.path);
+        }
+        // Every `includes` entry resolved through the SAME
+        // resolveWorkspacePath() site source/outDir just used. The FIRST
+        // refusal returns unchanged -- the whole request fails, the offending
+        // entry is never dropped and the remaining entries are never resolved
+        // (no partial-success degradation). An absent or empty `includes`
+        // yields an empty array, which buildHostToolArgv() emits as no -I
+        // flags at all.
+        const includePaths = [];
+        for (const entry of request.args.includes ?? []) {
+            const includeResolved = resolveWorkspacePath(repoRootAbs, entry);
+            if (!includeResolved.ok)
+                return { ok: false, message: includeResolved.message };
+            includePaths.push(includeResolved.path);
+        }
+        built = buildHostToolArgv(request, { sourcePath: sourceResolved.path, outDirPath, includePaths });
+        acmeLib = findAcmeLib();
+    }
+    else if (request.tool === "ghidra.analyze") {
+        // Converted from a previous `if (acme.build) … else (ghidra.analyze)`
+        // shape into an explicit per-tool branch -- the `else`'s own comment
+        // claiming ghidra.analyze was the only remaining member stopped being
+        // true the moment dxa.disassemble (below) was added; leaving the
+        // implicit shape would have routed a dxa.disassemble request into
+        // Ghidra's own resolver. `importPath` is workspace-relative, resolved
+        // through the SAME resolveWorkspacePath() site acme.build's `source`
+        // uses; the project location itself comes from ghidra-project.mts's
+        // resolveGhidraProject() -- never computed here.
+        const importResolved = resolveWorkspacePath(repoRootAbs, request.args.importPath);
+        if (!importResolved.ok)
+            return { ok: false, message: importResolved.message };
+        // preScript/postScript resolved through the SAME resolveWorkspacePath()
+        // site, BEFORE resolveGhidraProject()'s own directory RESERVATION below
+        // -- a refusal here must never leave a reserved-but-unused run
+        // directory behind.
+        let preScriptPath;
+        if (request.args.preScript !== undefined) {
+            const preScriptResolved = resolveWorkspacePath(repoRootAbs, request.args.preScript);
+            if (!preScriptResolved.ok)
+                return { ok: false, message: preScriptResolved.message };
+            preScriptPath = preScriptResolved.path;
+        }
+        let postScriptPath;
+        if (request.args.postScript !== undefined) {
+            const postScriptResolved = resolveWorkspacePath(repoRootAbs, request.args.postScript);
+            if (!postScriptResolved.ok)
+                return { ok: false, message: postScriptResolved.message };
+            postScriptPath = postScriptResolved.path;
+        }
+        // scriptPath/entrypointsPath/exportPath resolved through the SAME
+        // resolveWorkspacePath() site, BEFORE resolveGhidraProject()'s own
+        // directory RESERVATION below -- a refusal here must never leave a
+        // reserved-but-unused run directory behind, exactly as preScript/
+        // postScript already are.
+        let scriptPathResolved;
+        if (request.args.scriptPath !== undefined) {
+            const scriptPathResult = resolveWorkspacePath(repoRootAbs, request.args.scriptPath);
+            if (!scriptPathResult.ok)
+                return { ok: false, message: scriptPathResult.message };
+            scriptPathResolved = scriptPathResult.path;
+        }
+        let entrypointsPathResolved;
+        if (request.args.entrypointsPath !== undefined) {
+            const entrypointsPathResult = resolveWorkspacePath(repoRootAbs, request.args.entrypointsPath);
+            if (!entrypointsPathResult.ok)
+                return { ok: false, message: entrypointsPathResult.message };
+            entrypointsPathResolved = entrypointsPathResult.path;
+        }
+        let exportPathResolved;
+        if (request.args.exportPath !== undefined) {
+            const exportPathResult = resolveWorkspacePath(repoRootAbs, request.args.exportPath);
+            if (!exportPathResult.ok)
+                return { ok: false, message: exportPathResult.message };
+            exportPathResolved = exportPathResult.path;
+        }
+        // Resolved through the SAME site, BEFORE resolveGhidraProject()'s own
+        // directory RESERVATION below -- a refusal here must never leave a
+        // reserved-but-unused run directory behind, exactly as every other
+        // script-adjacent path field above.
+        let dataRangesPathResolved;
+        if (request.args.dataRangesPath !== undefined) {
+            const dataRangesPathResult = resolveWorkspacePath(repoRootAbs, request.args.dataRangesPath);
+            if (!dataRangesPathResult.ok)
+                return { ok: false, message: dataRangesPathResult.message };
+            dataRangesPathResolved = dataRangesPathResult.path;
+        }
+        const projectResolved = resolveGhidraProject({ repoRoot: repoRootAbs, runId: request.args.runId });
+        if (!projectResolved.ok)
+            return { ok: false, message: projectResolved.message };
+        ghidraReservedProjectLocation = projectResolved.projectLocation;
+        built = buildHostToolArgv(request, {
+            importPath: importResolved.path,
+            projectLocation: projectResolved.projectLocation,
+            projectName: projectResolved.projectName,
+            preScriptPath,
+            postScriptPath,
+            scriptPathResolved,
+            entrypointsPathResolved,
+            exportPathResolved,
+            dataRangesPathResolved,
+        });
+    }
+    else if (request.tool === "dxa.disassemble") {
+        // (35-01, item 7). `image` and each present optional path resolved
+        // through the SAME resolveWorkspacePath() site acme.build's `source`
+        // uses; `outDir` defaults to dirname(imagePath) exactly as acme.build's
+        // own default does. The FIRST refusal returns unchanged -- no
+        // partial-success degradation, no dropped key.
+        const imageResolved = resolveWorkspacePath(repoRootAbs, request.args.image);
+        if (!imageResolved.ok)
+            return { ok: false, message: imageResolved.message };
+        let outDirPath;
+        if (request.args.outDir !== undefined) {
+            const outDirResolved = resolveWorkspacePath(repoRootAbs, request.args.outDir);
+            if (!outDirResolved.ok)
+                return { ok: false, message: outDirResolved.message };
+            outDirPath = outDirResolved.path;
+        }
+        else {
+            outDirPath = dirname(imageResolved.path);
+        }
+        let entrypointsPath;
+        if (request.args.entrypointsPath !== undefined) {
+            const entrypointsResolved = resolveWorkspacePath(repoRootAbs, request.args.entrypointsPath);
+            if (!entrypointsResolved.ok)
+                return { ok: false, message: entrypointsResolved.message };
+            entrypointsPath = entrypointsResolved.path;
+        }
+        let datablocksPath;
+        if (request.args.datablocksPath !== undefined) {
+            const datablocksResolved = resolveWorkspacePath(repoRootAbs, request.args.datablocksPath);
+            if (!datablocksResolved.ok)
+                return { ok: false, message: datablocksResolved.message };
+            datablocksPath = datablocksResolved.path;
+        }
+        let labelsPath;
+        if (request.args.labelsPath !== undefined) {
+            const labelsResolved = resolveWorkspacePath(repoRootAbs, request.args.labelsPath);
+            if (!labelsResolved.ok)
+                return { ok: false, message: labelsResolved.message };
+            labelsPath = labelsResolved.path;
+        }
+        built = buildHostToolArgv(request, {
+            imagePath: imageResolved.path,
+            outDirPath,
+            entrypointsPath,
+            datablocksPath,
+            labelsPath,
+        });
+    }
+    else if (request.tool === "ghidra.installExtension") {
+        // `sourceDir`
+        // resolved through the SAME resolveWorkspacePath() site every other
+        // tool's path argument uses. The materialisation side effects (create
+        // the install directory, copy the vendored tree, copy the three stock
+        // 6502 language files) happen HERE, in the resolution branch -- mirroring
+        // resolveGhidraProject()'s own "reservation" side effect above -- so
+        // buildHostToolArgv() stays the one place argv/outputs are DERIVED from
+        // already-materialised, typed fields (never the place a filesystem
+        // mutation happens).
+        const sourceDirResolved = resolveWorkspacePath(repoRootAbs, request.args.sourceDir);
+        if (!sourceDirResolved.ok)
+            return { ok: false, message: sourceDirResolved.message };
+        // `sourceDir` is otherwise accepted as ANY workspace-relative directory
+        // and copied wholesale (via cpSync below) into
+        // `<GHIDRA_HOME>/Ghidra/Extensions/<moduleName>/` -- a shared, host-wide
+        // location outside this project's own workspace. Refuse by name unless
+        // it resolves to exactly this project's own vendored extension tree,
+        // mirroring the "checked, non-materialising preflight" discipline
+        // ghidra.analyze's own language check already applies (never a
+        // materialising fix, only a refusal).
+        const vendoredGhidraExtResolved = resolveWorkspacePath(repoRootAbs, join("src", "mcp", "vice", "vendor", "ghidra-ext"));
+        if (!vendoredGhidraExtResolved.ok || sourceDirResolved.path !== vendoredGhidraExtResolved.path) {
+            return {
+                ok: false,
+                message: `host_tool "ghidra.installExtension" refuses: "sourceDir" must resolve to this project's own vendored ` +
+                    `extension tree (src/mcp/vice/vendor/ghidra-ext), which is copied wholesale into a shared, host-wide Ghidra ` +
+                    `installation; got ${JSON.stringify(request.args.sourceDir)}, which resolves to ${sourceDirResolved.path}`,
+            };
+        }
+        const ghidraHome = process.env.GHIDRA_HOME;
+        if (ghidraHome === undefined || ghidraHome === "") {
+            return {
+                ok: false,
+                message: `host_tool "ghidra.installExtension" requires the GHIDRA_HOME environment variable to name a Ghidra installation directory; it is unset`,
+            };
+        }
+        const sleighPath = join(ghidraHome, "support", "sleigh");
+        if (!existsSync(sleighPath)) {
+            return {
+                ok: false,
+                message: `host_tool "ghidra.installExtension" refuses: GHIDRA_HOME's resolved "support/sleigh" does not exist on disk (${sleighPath})`,
+            };
+        }
+        const stockLanguagesDir = join(ghidraHome, "Ghidra", "Processors", "6502", "data", "languages");
+        const missingStockFiles = GHIDRA_STOCK_6502_LANGUAGE_FILES.filter((name) => !existsSync(join(stockLanguagesDir, name)));
+        if (missingStockFiles.length > 0) {
+            return {
+                ok: false,
+                message: `host_tool "ghidra.installExtension" refuses: the stock 6502 language file(s) ${missingStockFiles.join(", ")} do not exist at ${stockLanguagesDir} -- this Ghidra installation is missing its own 6502 processor module`,
+            };
+        }
+        const installDir = join(ghidraHome, "Ghidra", "Extensions", request.args.moduleName);
+        const installLanguagesDir = join(installDir, "data", "languages");
+        try {
+            mkdirSync(installLanguagesDir, { recursive: true });
+            cpSync(sourceDirResolved.path, installDir, { recursive: true });
+            for (const name of GHIDRA_STOCK_6502_LANGUAGE_FILES) {
+                cpSync(join(stockLanguagesDir, name), join(installLanguagesDir, name));
+            }
+        }
+        catch (e) {
+            return {
+                ok: false,
+                message: `host_tool "ghidra.installExtension" failed to materialise the extension at ${installDir}: ${e instanceof Error ? e.message : String(e)}`,
+            };
+        }
+        built = buildHostToolArgv(request, { sourceDirPath: sourceDirResolved.path, moduleName: request.args.moduleName });
+    }
+    else {
+        // request.tool is one of the five c1541.* ids or petcat.decode -- every
+        // remaining id resolves the SAME two fields, so this one branch covers
+        // all six. `image` resolved through the SAME resolveWorkspacePath()
+        // site every other tool's path argument uses; `outDir` defaults to
+        // dirname(imagePath) exactly as dxa.disassemble's own default does.
+        // `name` (c1541.entry/chain/read only) is NOT resolved here -- it is a
+        // validated, non-path CBM filename/glob, read straight from
+        // request.args by buildHostToolArgv() (mirrors ghidra.analyze's own
+        // processor/runId split); petcat.decode has no such field at all.
+        const imageResolved = resolveWorkspacePath(repoRootAbs, request.args.image);
+        if (!imageResolved.ok)
+            return { ok: false, message: imageResolved.message };
+        let outDirPath;
+        if (request.args.outDir !== undefined) {
+            const outDirResolved = resolveWorkspacePath(repoRootAbs, request.args.outDir);
+            if (!outDirResolved.ok)
+                return { ok: false, message: outDirResolved.message };
+            outDirPath = outDirResolved.path;
+        }
+        else {
+            outDirPath = dirname(imageResolved.path);
+        }
+        built = buildHostToolArgv(request, { imagePath: imageResolved.path, outDirPath }, deps.log);
+    }
+    if (!built.ok) {
+        // buildHostToolArgv()'s own GHIDRA_HOME/launcher/language preflight
+        // checks can still fail here even though resolveGhidraProject() already
+        // reserved (created) the run directory above -- clean it up,
+        // best-effort, so a caller who retries the same runId after fixing the
+        // underlying problem (setting GHIDRA_HOME, running
+        // ghidra.installExtension) gets a fresh reservation instead of
+        // resolveGhidraProject()'s unrelated "refuses to reuse an existing run
+        // directory" refusal.
+        if (ghidraReservedProjectLocation !== undefined) {
+            try {
+                rmSync(ghidraReservedProjectLocation, { recursive: true, force: true });
+            }
+            catch {
+                // Best-effort only -- the original buildHostToolArgv() refusal below
+                // is always returned regardless of whether cleanup itself succeeded.
+            }
+        }
+        return { ok: false, message: built.message };
+    }
+    const timeoutMs = hostToolTimeoutMs(request.tool, deps.timeoutMs);
+    const startedAt = Date.now();
+    // acme.build only: inject the probed ACME library directory as the child's
+    // `ACME` env var, exactly as acme.mjs's own removed findAcmeLib() call
+    // used to (T-34's own "same behaviour, moved" requirement) -- undefined
+    // when no candidate matched, which spawnHostTool() treats identically to
+    // "no override" (inherits the broker's own environment unchanged).
+    const spawnEnv = acmeLib?.path ? { ...process.env, ACME: acmeLib.path } : undefined;
+    // c1541.read's output file is written by the CHILD process itself
+    // (`-read <name> <outputPath>`), never pre-cleared before
+    // this module's own spawn -- so a colliding slug (two different CBM names
+    // that agree on their first 32 alphanumeric characters) could leave a
+    // PRIOR successful read's bytes at `outputPath`, and a later, genuinely
+    // failing call for the colliding name would then digest that stale file
+    // and report `ok: true`. Best-effort unlink immediately before spawning
+    // removes any stale file so a failed run can never be mistaken for a
+    // fresh success; `force: true` makes a missing file a no-op (never an
+    // ENOENT throw).
+    if (request.tool === "c1541.read") {
+        try {
+            rmSync(built.outputs[0], { force: true });
+        }
+        catch {
+            // Best-effort only -- if the unlink itself fails for some other
+            // reason (e.g. permissions), the spawn below proceeds unchanged and
+            // classifyC1541ReadOutput() still digests whatever c1541 produces.
+        }
+    }
+    const spawnResult = await spawnHostTool(built.toolPath, built.argv, timeoutMs, spawnEnv, built.cwd);
+    const elapsedMs = Date.now() - startedAt;
+    if (spawnResult.spawnErrorMessage !== null) {
+        deps.log?.(`host_tool tool=${request.tool} exit=spawn_error elapsed_ms=${elapsedMs} timeout_ms=${timeoutMs} bin=${built.toolPath}`);
+        return { ok: false, message: `runHostTool: failed to launch "${built.toolPath}": ${spawnResult.spawnErrorMessage}` };
+    }
+    if (spawnResult.timedOut) {
+        deps.log?.(`host_tool tool=${request.tool} exit=timeout elapsed_ms=${elapsedMs} timeout_ms=${timeoutMs} bin=${built.toolPath}`);
+        return { ok: false, message: `runHostTool: "${request.tool}" timed out after ${timeoutMs}ms and was killed` };
+    }
+    // `bin=` names the RESOLVED absolute binary path that answered this call
+    // -- for every tool, not only c1541.* -- `built.toolPath` is already the
+    // resolved path every branch above produces, so this is a pure addition
+    // to an existing field, never a new resolution. A transcript read in
+    // isolation can now say which build answered, which matters most for a
+    // host carrying two VICE builds (MEASURED live on this project's own dev
+    // host).
+    deps.log?.(`host_tool tool=${request.tool} exit=${spawnResult.exitCode ?? "null"} elapsed_ms=${elapsedMs} timeout_ms=${timeoutMs} bin=${built.toolPath}`);
+    // dxa.disassemble: dxa has NO output-file option -- every listing line is
+    // fprintf(stdout, ...) (vendor/dxa/dump.c). c1541.dir: c1541 -dir has no
+    // output-file option either -- every listing line is printed to its own
+    // stdout (MEASURED against the committed fixture, fixtures/c1541/
+    // README.md). Every other tool's outputs[] entries are already real
+    // files the child process wrote itself; TOOLS_WHOSE_OUTPUT_IS_STDOUT
+    // names the ones whose "output" IS the captured stdout, so this is the
+    // one place that stdout is turned into a file before the digest loop
+    // below ever runs. No second spawn call is added.
+    if (TOOLS_WHOSE_OUTPUT_IS_STDOUT.has(request.tool) && built.outputs.length > 0) {
+        try {
+            writeFileSync(built.outputs[0], spawnResult.stdout, "utf8");
+        }
+        catch {
+            // Falls through to the digest loop below, whose digestOutputFile()
+            // returns null for a file that does not exist -- an empty results[]
+            // rather than a thrown error, consistent with this module's
+            // never-throw discipline.
+        }
+    }
+    // ghidra.analyze's outputs[0] is ALWAYS the run log.
+    // `HostToolClientResult` carries no stdout field at all, so this is the
+    // ONE place the run log becomes reachable from the container side.
+    // MEASURED against real Ghidra 12.1.3: analyzeHeadless's own "Using
+    // Language/Compiler:" line arrives on STDOUT; stderr is appended after
+    // it so no line can be lost.
+    if (request.tool === "ghidra.analyze" && built.outputs.length > 0) {
+        try {
+            writeFileSync(built.outputs[0], `${spawnResult.stdout}${spawnResult.stderr}`, "utf8");
+        }
+        catch {
+            // Falls through to the digest loop below, whose digestOutputFile()
+            // returns null for a file that does not exist -- an empty results[]
+            // rather than a thrown error, consistent with this module's
+            // never-throw discipline.
+        }
+    }
+    const results = [];
+    for (const outputPath of built.outputs) {
+        const digested = digestOutputFile(outputPath);
+        if (digested)
+            results.push(digested);
+    }
+    // The classifier table entry for this tool id, run immediately after the
+    // digest loop and before the success envelope is constructed.
+    // Pre-existing ids map to `null` -- "no declared shape, behaviour
+    // unchanged" -- so this is a no-op for every tool that predates this
+    // mechanism. Absence of the declared success shape IS the failure; exit
+    // status stays recorded in the log line only and is never consulted
+    // here.
+    const classifier = HOST_TOOL_OUTPUT_CLASSIFIERS[request.tool];
+    if (classifier) {
+        const verdict = classifier({ stdout: spawnResult.stdout, stderr: spawnResult.stderr, results });
+        if (!verdict.ok) {
+            return { ok: false, message: `host_tool "${request.tool}" refuses: ${verdict.reason}` };
+        }
+    }
+    // petcat.decode's handover verdict, computed HOST-SIDE immediately after
+    // the classifier above accepts and before the response envelope below is
+    // constructed. All three cases (literal/computed/no-SYS-token) are
+    // successes -- the classifier's own shape refusal above is the only
+    // `ok: false` this tool ever reports; conflating the two would make a
+    // genuine tool failure and a merely-unresolved SYS argument
+    // indistinguishable.
+    const petcatVerdict = request.tool === "petcat.decode" ? derivePetcatEntrypoint(spawnResult.stdout) : null;
+    // acme.build only: ACME's own "for <...> includes..." complaint names no
+    // directory it tried -- append a note line (in the plain, non-MSVC shape
+    // acme.mjs's own parseDiagnostics() already treats as a "note" entry)
+    // naming every candidate this probe tried, exactly as the removed
+    // client-side hint used to. A line appended here, rather than reported as
+    // a separate field, keeps acme.mjs's diagnostics parsing untouched -- it
+    // already scans the combined text for exactly this shape.
+    let stderrText = spawnResult.stderr;
+    if (acmeLib && /ACME.*environment variable/i.test(stderrText)) {
+        stderrText += `\nfor <...> includes, set $ACME to the directory holding ${ACME_LIB_MARKER} (looked in: ${acmeLib.tried.join(", ")})`;
+    }
+    // The two verdict fields attach ONLY to petcat.decode's own response,
+    // never to the shared envelope below -- every other tool id's response
+    // key set is byte-for-byte what it was before this field existed
+    // (dxa-seam.test.ts's own exact-key-set assertion is the committed guard
+    // on that).
+    if (request.tool === "petcat.decode") {
+        // Non-null by construction: petcatVerdict was computed from THIS SAME
+        // `request.tool === "petcat.decode"` check above; TypeScript cannot
+        // correlate the two independent expressions, so the assertion is
+        // narrowing-only, never a runtime risk.
+        const verdict = petcatVerdict;
+        return {
+            ok: true,
+            tool: "petcat.decode",
+            exitStatus: spawnResult.exitCode,
+            results,
+            stderrTail: tailBytes(stderrText, STDERR_TAIL_CAP_BYTES),
+            entrypoint: verdict.entrypoint,
+            entrypointReason: verdict.entrypointReason,
+        };
+    }
+    return {
+        ok: true,
+        tool: request.tool,
+        exitStatus: spawnResult.exitCode,
+        results,
+        stderrTail: tailBytes(stderrText, STDERR_TAIL_CAP_BYTES),
+    };
+}
+// ---------------------------------------------------------------------------
+// oracle.probe / oracle.run. Migrated from packer-finding.mjs's own
+// probeUnp64()/runUnp64(): everything about the BINARY (locating it, the
+// version-banner probe, the scratch output location, the argument array,
+// the runtime bound) lives here now; the script keeps everything about the
+// FINDING (the name parser, the accepted character set, the caps, the
+// packedness threshold, the never-throw return shapes). Response shapes
+// are NOT the generic `{ ok, tool, exitStatus, results, stderrTail }`
+// envelope above -- they mirror packer-finding.mjs's OWN pre-existing
+// `{ available, command, version, reason }` / `{ ok, stdout, reason }`
+// contracts directly, so the migrated client-side functions can return the
+// seam's response with no field renaming.
+// ---------------------------------------------------------------------------
+/** Default command name when no host-side configuration is present -- the
+ * same default packer-finding.mjs's own (removed) DEFAULT_ORACLE_COMMAND
+ * used. */
+const DEFAULT_ORACLE_COMMAND = "unp64";
+/** The two environment variables the oracle's location is read from, in this
+ * order -- the SAME variable order and names packer-finding.mjs's own
+ * (client-side, container-facing) `ORACLE_ENV_VARS` declares, so a
+ * container-side hint naming one of these two variables always describes
+ * where this host-side resolver actually looked. */
+const ORACLE_ENV_VARS = Object.freeze(["UNP64", "UNP64_PATH"]);
+/** THE ONE PLACE the oracle binary's location is decided, consulted by
+ * BOTH `runOracleProbe()` and `runOracleRun()` -- mirrors `findAcmeLib()`
+ * above, moved host-side for exactly this reason: the container has no
+ * PATH to a host binary, so probing host locations belongs on the host
+ * side of the seam. Reads the BROKER PROCESS'S OWN environment -- never a
+ * wire value, because `HOST_TOOL_ARG_KEYS["oracle.probe"]` accepts no keys
+ * at all. When a variable is set, two checks apply in order: the
+ * configured path's base name must equal `DEFAULT_ORACLE_COMMAND` (a
+ * second layer over the wire-key removal), and the path must exist on
+ * disk. Each refusal reason names WHICH variable was set and NEVER
+ * interpolates the configured value. With no variable set, answers the
+ * bare `DEFAULT_ORACLE_COMMAND` -- the existing search-path behaviour,
+ * unchanged. */
+function resolveOracleCommand() {
+    for (const varName of ORACLE_ENV_VARS) {
+        const raw = process.env[varName];
+        if (typeof raw !== "string" || raw.trim() === "")
+            continue;
+        const configured = raw.trim();
+        if (basename(configured) !== DEFAULT_ORACLE_COMMAND) {
+            return {
+                ok: false,
+                reason: `the oracle configured via ${varName} is not named "${DEFAULT_ORACLE_COMMAND}" -- treated as oracle-absent`,
+            };
+        }
+        if (!existsSync(configured)) {
+            return {
+                ok: false,
+                reason: `the oracle configured via ${varName} does not exist on disk -- treated as oracle-absent`,
+            };
+        }
+        return { ok: true, command: configured };
+    }
+    return { ok: true, command: DEFAULT_ORACLE_COMMAND };
+}
+async function runOracleProbe(deps) {
+    const resolved = resolveOracleCommand();
+    if (!resolved.ok) {
+        // No child is spawned on this branch -- WITHOUT echoing the configured
+        // value anywhere (T-19-18); resolved.reason already names the variable,
+        // never the value.
+        deps.log?.(`host_tool tool=oracle.probe exit=absent_configured_path`);
+        return { ok: true, tool: "oracle.probe", available: false, command: null, version: null, reason: resolved.reason };
+    }
+    const command = resolved.command;
+    const timeoutMs = hostToolTimeoutMs("oracle.probe", deps.timeoutMs);
+    const spawnResult = await spawnHostTool(command, ["--version"], timeoutMs);
+    if (spawnResult.spawnErrorMessage !== null) {
+        deps.log?.(`host_tool tool=oracle.probe exit=spawn_error timeout_ms=${timeoutMs}`);
+        return {
+            ok: true,
+            tool: "oracle.probe",
+            available: false,
+            command: null,
+            version: null,
+            reason: `no "${DEFAULT_ORACLE_COMMAND}" packer identifier could be launched`,
+        };
+    }
+    if (spawnResult.timedOut) {
+        deps.log?.(`host_tool tool=oracle.probe exit=timeout timeout_ms=${timeoutMs}`);
+        return {
+            ok: true,
+            tool: "oracle.probe",
+            available: false,
+            command: null,
+            version: null,
+            reason: "the packer identifier timed out during the version probe",
+        };
+    }
+    deps.log?.(`host_tool tool=oracle.probe exit=${spawnResult.exitCode ?? "null"} timeout_ms=${timeoutMs}`);
+    const banner = `${spawnResult.stdout}${spawnResult.stderr}`.trim();
+    if (banner === "") {
+        return {
+            ok: true,
+            tool: "oracle.probe",
+            available: false,
+            command: null,
+            version: null,
+            reason: "the packer identifier produced no version banner, so it was not accepted as an oracle",
+        };
+    }
+    return { ok: true, tool: "oracle.probe", available: true, command, version: banner.slice(0, 200), reason: null };
+}
+async function runOracleRun(args, deps) {
+    const repoRootAbs = resolvePath(deps.repoRoot);
+    const sourceResolved = resolveWorkspacePath(repoRootAbs, args.source);
+    if (!sourceResolved.ok) {
+        return { ok: false, tool: "oracle.run", stdout: "", reason: sourceResolved.message };
+    }
+    if (!existsSync(sourceResolved.path)) {
+        return { ok: false, tool: "oracle.run", stdout: "", reason: "the input file does not exist" };
+    }
+    // The SAME resolver oracle.probe consults -- never a bare
+    // DEFAULT_ORACLE_COMMAND argument at the spawn site below. Before this
+    // fix a host-side configured oracle was honoured by the probe and
+    // silently ignored by the run, so a working probe could be followed by a
+    // failing run; resolving here closes that gap as a real defect fix.
+    const resolvedCommand = resolveOracleCommand();
+    if (!resolvedCommand.ok) {
+        deps.log?.(`host_tool tool=oracle.run exit=absent_configured_path`);
+        return { ok: false, tool: "oracle.run", stdout: "", reason: resolvedCommand.reason };
+    }
+    // The oracle's unpacked output goes to a scratch location INSIDE the
+    // workspace tree -- never the system temp directory, which cannot be
+    // translated back across the container boundary -- removed after this
+    // function returns, mirroring packer-finding.mjs's own (removed)
+    // "removed before this function returns" property (T-19-24).
+    //
+    // MOVED 2026-09-08: this used to be `<repoRoot>/tools/oracle-runs/...`.
+    // This scratch directory is one of several writers consolidated onto a
+    // single tool-written root -- it now lives under `runs/oracle` beneath
+    // the root `repo-root.ts`'s `toolsDir()` owns. This module is host-bound
+    // (compiled by build.ts) and must not import the container-side
+    // repo-root.ts, so the two segments are joined directly here --
+    // ".c64-re-tools" and "runs"/"oracle" must stay equal to
+    // `join(toolsDir(), "runs", "oracle")`, the same convention
+    // install-resources.ts's installTargetDir() uses.
+    //
+    // CORRECTED 2026-09-08: this used to also describe ghidra-project.mts's
+    // runs root as following "the same convention", full stop. That is now
+    // true of the PHYSICAL location -- both this directory and the Ghidra
+    // runs root land under the same `.c64-re-tools/runs/<subdir>` shape --
+    // but it is NOT true of how the location is REACHED. This scratch
+    // directory is joined DIRECTLY, exactly as written above. The Ghidra
+    // runs root is joined the same way internally (`ghidraRunsRealRoot()`),
+    // but Ghidra itself is never handed that direct path -- it is handed a
+    // path through `ghidraRunsRoot()`'s non-dotted ALIAS HANDLE
+    // (`<repoRoot>/c64-re-tools`, a symlink to `.c64-re-tools`), because
+    // Ghidra's own project-location check refuses a dot-prefixed segment in
+    // the path it is handed, while this scratch directory's caller (this
+    // project's own oracle spawn) has no such refusal and is handed the
+    // direct path unchanged.
+    const scratchDir = join(repoRootAbs, ".c64-re-tools", "runs", "oracle", `run-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    try {
+        // A fix: scratch-directory creation moved INSIDE this try block -- a
+        // full disk or an unwritable parent now resolves to the function's
+        // existing refusal shape instead of throwing synchronously out of
+        // runHostTool(), which sits outside any try/catch of its own.
+        mkdirSync(scratchDir, { recursive: true });
+        const scratchOut = join(scratchDir, "unpacked.out");
+        const timeoutMs = hostToolTimeoutMs("oracle.run", deps.timeoutMs);
+        const spawnResult = await spawnHostTool(resolvedCommand.command, [sourceResolved.path, scratchOut], timeoutMs);
+        if (spawnResult.spawnErrorMessage !== null) {
+            deps.log?.(`host_tool tool=oracle.run exit=spawn_error timeout_ms=${timeoutMs}`);
+            return { ok: false, tool: "oracle.run", stdout: "", reason: "the oracle could not be run against the input file" };
+        }
+        if (spawnResult.timedOut) {
+            deps.log?.(`host_tool tool=oracle.run exit=timeout timeout_ms=${timeoutMs}`);
+            return { ok: false, tool: "oracle.run", stdout: "", reason: "the oracle timed out" };
+        }
+        deps.log?.(`host_tool tool=oracle.run exit=${spawnResult.exitCode ?? "null"} timeout_ms=${timeoutMs}`);
+        // Capped the same way packer-finding.mjs's own MAX_ORACLE_STDOUT_BYTES
+        // caps it client-side -- the executor enforces the bound on what it
+        // accumulates; the script still exports the number for its own parser
+        // and its own tests, so the value is not duplicated as a maintained pair,
+        // only as the same measured constant on both sides of the seam.
+        const stdout = spawnResult.stdout.length > ORACLE_STDOUT_CAP_BYTES ? spawnResult.stdout.slice(0, ORACLE_STDOUT_CAP_BYTES) : spawnResult.stdout;
+        return { ok: true, tool: "oracle.run", stdout, reason: null };
+    }
+    catch (err) {
+        // The only synchronous throw this block can produce is mkdirSync()
+        // above (a full disk or an unwritable scratch parent) -- resolved here
+        // to the function's own refusal shape, naming the directory, rather
+        // than propagating out of runHostTool()'s never-throw boundary.
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, tool: "oracle.run", stdout: "", reason: `could not create the oracle scratch directory ${scratchDir}: ${message}` };
+    }
+    finally {
+        try {
+            rmSync(scratchDir, { recursive: true, force: true });
+        }
+        catch {
+            // Best effort -- a leftover empty scratch directory is not worth
+            // failing a read-only recon finding over (mirrors packer-finding.mjs's
+            // own removed comment to the same effect).
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// CLI entry point (guarded on being the process entry point, the
+// check-npm-packages.mjs:159 IS_ENTRY_POINT idiom). Needed for the
+// host-local route (no broker in the loop). `node resources/host-tool.mjs
+// run --repo-root <path> --request <json>` prints the response as one JSON
+// line on stdout and exits non-zero on a refusal.
+// ---------------------------------------------------------------------------
+function parseCliArgs(argv) {
+    let repoRoot;
+    let request;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--repo-root") {
+            repoRoot = argv[i + 1];
+            i++;
+        }
+        else if (argv[i] === "--request") {
+            request = argv[i + 1];
+            i++;
+        }
+    }
+    return { repoRoot, request };
+}
+const IS_ENTRY_POINT = process.argv[1] !== undefined && resolvePath(process.argv[1]) === fileURLToPath(import.meta.url);
+if (IS_ENTRY_POINT) {
+    const [, , cliCommand, ...cliRest] = process.argv;
+    if (cliCommand !== "run") {
+        process.stderr.write("usage: host-tool.mjs run --repo-root <path> --request <json>\n");
+        process.exitCode = 1;
+    }
+    else {
+        const { repoRoot, request } = parseCliArgs(cliRest);
+        if (!repoRoot || !request) {
+            process.stderr.write("usage: host-tool.mjs run --repo-root <path> --request <json>\n");
+            process.exitCode = 1;
+        }
+        else {
+            let raw;
+            try {
+                raw = JSON.parse(request);
+            }
+            catch {
+                raw = null;
+            }
+            // TEST-ONLY escape hatch for the CLI's own promise-rejection
+            // handling (host-tool.test.ts): every fs call reachable from
+            // runHostTool()'s real business logic is deliberately guarded, so
+            // there is no organic wire input that makes the real function reject
+            // its promise today -- proving that is a GOOD thing, not a gap, but
+            // it also means the CLI's own `.catch()` below has no
+            // naturally-reachable trigger to regression-test against. This reads
+            // the BROKER PROCESS'S OWN environment, never a wire value, mirroring
+            // `resolveOracleCommand()`'s own "broker env, never wire" convention
+            // above -- a caller can never reach this by shaping `--request`.
+            // Unset in every real invocation; only host-tool.test.ts's own
+            // spawned subprocess ever sets it.
+            const runHostToolOrForcedRejectForTest = process.env.HOST_TOOL_TEST_FORCE_CLI_REJECT === "1"
+                ? Promise.reject(new Error("HOST_TOOL_TEST_FORCE_CLI_REJECT: simulated runHostTool() rejection for CLI never-throw regression testing"))
+                : runHostTool(raw, { repoRoot });
+            runHostToolOrForcedRejectForTest
+                .then((response) => {
+                process.stdout.write(`${JSON.stringify(response)}\n`);
+                process.exitCode = response.ok ? 0 : 1;
+            })
+                // A rejection from runHostTool() used to become an unhandled
+                // rejection with NO stdout at all, surfacing to the caller as the
+                // opaque "host-tool.mjs produced no output on stdout",
+                // indistinguishable from a hang. Mirrors host-tool-client.ts's own
+                // never-reject CLI entry point field-for-field: same envelope shape
+                // ({ ok: false, message }), same stdout-not-stderr destination, same
+                // non-zero exit-code convention.
+                .catch((err) => {
+                process.stdout.write(`${JSON.stringify({ ok: false, message: err instanceof Error ? err.message : String(err) })}\n`);
+                process.exitCode = 1;
+            });
+        }
+    }
+}