@henols/c64-re-tools 0.2.2 → 0.2.3

package/skills/c64-program-recon/scripts/packer-finding.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // packer-finding.mjs -- the ONE place this project answers "which packer was
 // used on this binary", as a project-owned recon finding with an ordered
-// oracle chain and a hard, reasoned unknown (SURF-03).
+// oracle chain and a hard, reasoned unknown.
 //
 // ---------------------------------------------------------------------------
 // WHY THIS FILE EXISTS
@@ -96,10 +96,102 @@
 // a measurement. Installing the identifier and running it against a genuinely
 // packed fixture is the experiment that would settle it; until then the
 // oracle-route test SKIPS with a visible reason and never reads as a pass.
-import { spawnSync } from "node:child_process";
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+
+import { resolveMcpModule, refusalMessage } from "../../c64-ram-capture/scripts/mcp-module.mjs";
+
+// ---------------------------------------------------------------------------
+// The oracle's own child-process spawn.
+// ---------------------------------------------------------------------------
+// Both `probeUnp64()` and `runUnp64()` used to spawn `unp64` directly
+// (`spawnSync`, and a `mkdtempSync()`-created scratch directory for the
+// unpacked output). Both spawn sites are now behind the host-tool execution
+// seam (`src/mcp/vice/host-tool.mts`'s `oracle.probe`/`oracle.run` allowlist
+// entries) -- the project owner's rule of 2026-08-28 is that this script
+// runs container-side, the oracle binary lives host-side, and there is no
+// container PATH to find it on. Everything about the BINARY (locating it
+// from `ORACLE_ENV_VARS`, the version-banner probe, the scratch output
+// location, the argument array, the runtime bound, the standard-output cap)
+// now lives in host-tool.mts; this file keeps everything about the FINDING
+// (the name parser, the accepted character set, the caps below, the
+// packedness threshold, and both functions' never-throw contract).
+
+// SYNCHRONOUS ON PURPOSE: `execFileSync`, not the async `spawn` acme.mjs's
+// own migration uses. `probeUnp64()`/`runUnp64()` are called synchronously,
+// with no `await`, throughout this module's own colocated test file
+// (`packer-finding.test.mjs`, unmodified by this migration) -- including at
+// module scope (`const PROBED = probeUnp64();`). Converting them to
+// async/Promise-returning functions would silently break every one of those
+// call sites (a Promise is not the finding object the assertions expect),
+// so the OUTER call into the seam's CLI wrapper must itself be synchronous.
+// The asynchronous work (the actual child-process spawn of the oracle
+// binary) still happens -- inside the SPAWNED subprocess, in
+// host-tool.mts's own async `runHostTool()` -- `execFileSync` merely blocks
+// this function until that subprocess exits, exactly as `spawnSync` used to
+// block until `unp64` itself exited.
+const HOST_TOOL_CLIENT_FILE = "host-tool-client.ts";
+
+/**
+ * Synchronously invokes the host-tool execution seam for `tool`/`args`,
+ * optionally rooted at `repoRoot` for workspace-relative path resolution.
+ * NEVER throws: an unresolvable ladder, a spawn failure, a timeout, or
+ * unparseable output all return `{ ok: false, message }` -- the SAME shape
+ * a tool's own transport-level refusal uses, so callers translate a failure
+ * here identically to a `{ ok: false }` response from the seam itself.
+ */
+function invokeSeamSync(tool, args, repoRoot) {
+  const resolved = resolveMcpModule(HOST_TOOL_CLIENT_FILE);
+  if (!resolved.ok) {
+    return { ok: false, message: refusalMessage(HOST_TOOL_CLIENT_FILE, resolved.rungs) };
+  }
+
+  const cliArgs = [resolved.path, "run", "--tool", tool, "--args", JSON.stringify(args)];
+  if (repoRoot) cliArgs.push("--repo-root", repoRoot);
+
+  let stdout;
+  try {
+    stdout = execFileSync(process.execPath, cliArgs, {
+      encoding: "utf8",
+      timeout: ORACLE_TIMEOUT_MS + 5_000,
+      shell: false,
+      windowsHide: true,
+    });
+  } catch (err) {
+    // execFileSync throws on a non-zero exit, a timeout, or a genuine spawn
+    // failure -- but a non-zero exit is the NORMAL signal for a tool-level
+    // `{ ok: false }` result (host-tool-client.ts's own CLI wrapper always
+    // prints its one JSON line before exiting non-zero), so recover it from
+    // the error object rather than treating every non-zero exit as a
+    // transport failure.
+    const recovered = typeof err.stdout === "string" ? err.stdout : err.stdout ? err.stdout.toString("utf8") : "";
+    if (recovered.trim() === "") {
+      return { ok: false, message: err instanceof Error ? err.message : String(err) };
+    }
+    stdout = recovered;
+  }
+
+  const lines = stdout.split("\n").filter((line) => line.trim() !== "");
+  const last = lines[lines.length - 1];
+  if (last === undefined) return { ok: false, message: "host-tool-client.ts produced no output" };
+  try {
+    return JSON.parse(last);
+  } catch {
+    return { ok: false, message: `host-tool-client.ts produced non-JSON output: ${last}` };
+  }
+}
+
+/** Splits an arbitrary (absolute or cwd-relative) file path into a workspace
+ * root + a plain relative name, so a single-file oracle.run request can
+ * satisfy the seam's workspace-relative path requirement (`resolveWorkspacePath()`
+ * in host-tool.mts refuses an absolute path outright) without needing the
+ * caller's actual project root at all -- the smallest possible root for a
+ * single file is its own containing directory. */
+function toWorkspaceRelative(anyPath) {
+  const abs = resolve(anyPath);
+  return { repoRoot: dirname(abs), source: basename(abs) };
+}
 
 // ---------------------------------------------------------------------------
 // Vocabulary. Exactly four verdicts, frozen. Rule 4.
@@ -215,73 +307,78 @@ export function shannonEntropy(bytes) {
 // ---------------------------------------------------------------------------
 
 /**
- * Locates and probes the external packer identifier, WITHOUT touching any
- * input file.
- *
- * Resolution order: the two environment variables, then the bare command name
- * on the search path. A CONFIGURED path that does not exist on disk is
- * reported as absent and is deliberately not echoed back in the reason
- * (T-19-18: an attacker-influenceable value is never placed into a command,
- * and not into a message a later step might paste into one either).
+ * Turns a container-side environment record
+ * into a DIAGNOSTIC HINT, never a configuration value. This script's own
+ * filesystem is not the filesystem the oracle runs on -- host-tool.mts's
+ * `resolveOracleCommand()` decides the oracle's location from the HOST
+ * BROKER PROCESS'S OWN environment now, so a variable set in THIS
+ * (container-side) environment can only ever explain a possibly-surprising
+ * absent result, never select what actually runs.
  *
- * Never throws. A launch error, a non-zero status or a timeout are all
- * "absent", never a failure -- absence of the oracle is an expected state.
+ * Answers `null` when no oracle variable is set in `env`. Otherwise answers
+ * a non-empty string naming WHICH variable was set and stating that the
+ * seam consults the host broker process's own environment instead --
+ * NEVER interpolating the variable's value (T-19-18, unchanged by this
+ * migration).
  */
-export function probeUnp64(env = process.env) {
+export function oracleConfigurationHint(env = process.env) {
   const source = env ?? {};
-  let configuredVar = null;
-  let configured = null;
   for (const name of ORACLE_ENV_VARS) {
     const value = source[name];
     if (typeof value === "string" && value.trim() !== "") {
-      configuredVar = name;
-      configured = value.trim();
-      break;
+      return (
+        `${name} is set in this container-side environment, but it is not consulted: the host-tool ` +
+        "execution seam reads the oracle's location from the HOST BROKER PROCESS'S OWN environment, " +
+        `not this script's -- point ${name} at the oracle in the environment the host broker process sees`
+      );
     }
   }
+  return null;
+}
 
-  if (configured !== null && !existsSync(configured)) {
-    return {
-      available: false,
-      command: null,
-      version: null,
-      reason:
-        `the packer identifier configured through ${configuredVar} does not exist on disk -- ` +
-        "treated as oracle-absent, and the configured value was not placed into any command",
-    };
-  }
-
-  const command = configured ?? DEFAULT_ORACLE_COMMAND;
-  const probe = spawnSync(command, ["--version"], {
-    encoding: "utf8",
-    timeout: ORACLE_TIMEOUT_MS,
-    shell: false,
-    windowsHide: true,
-  });
+/** Appends `hint` to `reason` when both are present, returns whichever of the
+ * two is non-null when only one is, and returns `null` when neither is. Kept
+ * as its own function so the "when absent, append the hint" rule in
+ * `probeUnp64()` below is one small, testable operation rather than inlined
+ * string-concatenation logic repeated at every call site. */
+function appendHint(reason, hint) {
+  if (hint === null) return reason ?? null;
+  if (reason === null || reason === undefined) return hint;
+  return `${reason} ${hint}`;
+}
 
-  if (probe.error) {
-    return {
-      available: false,
-      command: null,
-      version: null,
-      reason:
-        configuredVar === null
-          ? `no "${DEFAULT_ORACLE_COMMAND}" packer identifier was found on the search path`
-          : `the packer identifier configured through ${configuredVar} could not be launched`,
-    };
-  }
+/**
+ * Locates and probes the external packer identifier, WITHOUT touching any
+ * input file.
+ *
+ * This function decides NOTHING about the
+ * binary any more -- it sends the seam call UNCONDITIONALLY, with an empty
+ * argument object, whether or not a container-side oracle variable is set.
+ * There is no filesystem existence check on an oracle path here (the removed
+ * check answered the wrong question: this script's own filesystem is not the
+ * filesystem the oracle runs on). A container-side variable can only ever
+ * add a diagnostic hint to an ABSENT result -- see `oracleConfigurationHint()`
+ * -- never select what the host executes.
+ *
+ * Never throws. A launch error, a non-zero status or a timeout are all
+ * "absent", never a failure -- absence of the oracle is an expected state.
+ */
+export function probeUnp64(env = process.env) {
+  const hint = oracleConfigurationHint(env);
+  const response = invokeSeamSync("oracle.probe", {});
 
-  const banner = `${probe.stdout ?? ""}${probe.stderr ?? ""}`.trim();
-  if (banner === "") {
-    return {
-      available: false,
-      command: null,
-      version: null,
-      reason: "the packer identifier produced no version banner, so it was not accepted as an oracle",
-    };
+  if (!response || response.ok !== true) {
+    const reason = (response && response.message) || "the packer identifier oracle.probe seam call failed";
+    return { available: false, command: null, version: null, reason: appendHint(reason, hint) };
   }
 
-  return { available: true, command, version: banner.slice(0, 200), reason: null };
+  const available = response.available === true;
+  return {
+    available,
+    command: available ? response.command : null,
+    version: available ? response.version : null,
+    reason: available ? null : appendHint(response.reason, hint),
+  };
 }
 
 /**
@@ -307,35 +404,16 @@ export function runUnp64(probe, filePath) {
     return { ok: false, stdout: "", reason: "the input file does not exist" };
   }
 
-  let scratch = null;
-  try {
-    scratch = mkdtempSync(join(tmpdir(), "packer-finding-"));
-    const scratchOut = join(scratch, "unpacked.out");
-    const run = spawnSync(probe.command, [filePath, scratchOut], {
-      encoding: "utf8",
-      timeout: ORACLE_TIMEOUT_MS,
-      shell: false,
-      windowsHide: true,
-      maxBuffer: MAX_ORACLE_STDOUT_BYTES,
-    });
-    if (run.error) {
-      return { ok: false, stdout: "", reason: "the oracle could not be run against the input file" };
-    }
-    return { ok: true, stdout: `${run.stdout ?? ""}`, reason: null };
-  } catch {
-    // A scratch directory that could not be created is an absent oracle, not
-    // an error a recon pass should stop for.
-    return { ok: false, stdout: "", reason: "a scratch directory for the oracle's output could not be created" };
-  } finally {
-    if (scratch !== null) {
-      try {
-        rmSync(scratch, { recursive: true, force: true });
-      } catch {
-        // Best effort. A leftover empty scratch directory is not worth
-        // failing a read-only recon finding over.
-      }
-    }
+  // The scratch output location, the argument array, the runtime bound and
+  // the input file's absolute/relative form are all resolved host-side now;
+  // this file only ever hands the seam a workspace-relative `source`, rooted
+  // at the smallest root that can express it -- the file's own directory.
+  const { repoRoot, source } = toWorkspaceRelative(filePath);
+  const response = invokeSeamSync("oracle.run", { source }, repoRoot);
+  if (!response || typeof response.ok !== "boolean") {
+    return { ok: false, stdout: "", reason: (response && response.message) || "the oracle.run seam call failed" };
   }
+  return { ok: response.ok, stdout: typeof response.stdout === "string" ? response.stdout : "", reason: response.reason ?? null };
 }
 
 /**

package/skills/c64-program-recon/templates/memory-map.template.md

@@ -1,6 +1,6 @@
 # Memory map generation
 
-**The memory map is GENERATED, not hand-authored (D-24).** The store — labels, comments, block
+**The memory map is GENERATED, not hand-authored.** The store — labels, comments, block
 types and scopes written through the `anno_*` tools described in `../SKILL.md` — is canonical. This
 file used to be a fill-in-the-rows document; it is now the schema for the one input the generator
 needs beyond the store itself, plus the confidence vocabulary that store comments carry.
@@ -36,7 +36,7 @@ one-time, self-clearing banner correction — not a bug, and not a migration.
 ## The provenance sidecar
 
 Some facts belong to the **run** (which capture, which `$01`, which video standard) rather than to
-any address, and the store has no address-keyed shape for them (D-27). They are supplied to the
+any address, and the store has no address-keyed shape for them. They are supplied to the
 renderer as a small JSON sidecar, hand-authored from `c64-ram-capture`'s and `derive.mjs`'s own
 outputs and validated by the renderer — a missing or malformed key is a named error listing every
 problem at once, never a `<placeholder>` silently rendered into a published document.

package/skills/c64-provenance-diff/SKILL.md

@@ -126,9 +126,44 @@ The two seeds are where this goes wrong, and both failure modes are on record:
 `io` (`$D000-$DFFF`) and `unused` (contiguous `$00`/`$FF` power-on runs) are
 assigned at capture time and kept verbatim. Everything the trace reaches is `game`.
 
-Per D-05 the `.bin` files are **never** edited or zeroed. Classification lives in
+The `.bin` files are **never** edited or zeroed. Classification lives in
 the manifests; the bytes stay verbatim evidence.
 
+## Carrying the verdict into the rebuild
+
+A verdict recorded here does not stay here. `anno export-asm`'s `--ledger` flag
+reads THIS skill's generated `recovery/PROVENANCE.md` — never
+re-deriving anything — and carries every covered range's Verdict and Confidence
+into the exported ACME source as an inline comment on the block that range
+overlaps:
+
+```
+anno export-asm game.prg --store game.annostore --ledger recovery/PROVENANCE.md
+```
+
+The `<image>` positional wants one of `.prg`/`.raw`/`.bin`, `--store` an
+`.annostore`/`.store` file, and `--ledger` the `.md` this skill's own `ledger`
+verb writes.
+
+**The flag makes the verdict VISIBLE and decides nothing.** Every byte in
+scope is still emitted, whatever the verdict says — a `CRACKER-PATCH` row does
+not drop, filter or alter a single byte, it only makes the evidence readable
+at the point of use. What gets reversed, kept or left out remains the
+end-user's decision, never the tool's. `--ledger` is optional: omitting it
+exports exactly as before, with no provenance comment anywhere in the output.
+
+**When the operator, reading the ledger, decides a range genuinely should be
+left out of the rebuild output** — a trainer patch, a cracktro block, anything
+they choose — the round trip runs entirely on the `anno_*` MCP surface, never
+by editing the ledger or the export: `anno_exclude_range` records the span
+WITH the reason the operator gave, and `anno_include_range` takes the record
+back if the decision changes. Recording an exclusion changes nothing about
+which bytes the export emits — the exported block still carries every byte
+of that span, now with a visible marker naming the exclusion and its reason,
+so nothing is removed and no gap appears in the output. The ledger's verdict
+is information the operator reads at this point; it is never wired as an
+input to an automatic exclusion, here or anywhere else on this surface.
+
 ## A `CRACKER-PATCH` in `game` code is a trainer until proven otherwise
 
 `count-patches` counts exactly one intersection — verdict `CRACKER-PATCH`, kind
@@ -234,10 +269,10 @@ addresses.
 | Assembling | `acme-build` |
 | **Whether a byte is original, cracker-changed, or unknown** | here |
 
-Findings that make RE faster go in `.planning/RE-FINDINGS.md` **at the moment you
-find them**, graded with `Evidence:` and `Confidence:`. Promote by re-logging with
-the new evidence, never by editing a grade in place. File-changing work enters
-through a GSD command (`/gsd-quick`).
+Record findings that make RE faster in your own project notes **at the moment you
+find them**, graded with `Evidence:` and `Confidence:`. Promote a finding by
+re-logging it with the new evidence, never by editing an old grade in place — the
+grade is only worth anything if it says what was actually known when it was written.
 
 ## Troubleshooting
 

package/skills/c64-provenance-diff/scripts/diff-images.mjs

@@ -5,7 +5,7 @@
 // an already-committed file (a release's primary `.bin` dump, its
 // `.map.json` range manifest, and `recovery/RELEASES.json`) and every tool
 // is pure Node over those files -- nothing in this module contacts the
-// emulator, ever (D-18: zero third-party dependencies, `Buffer.indexOf` and
+// emulator, ever (zero third-party dependencies, `Buffer.indexOf` and
 // `node:crypto` are sufficient).
 //
 // This is the step the objective calls "the one most able to produce
@@ -373,7 +373,7 @@ export function diffRanges(images, { gapTolerance = 16 } = {}) {
         // one address's value would be both wrong for the range and would
         // silently defeat collapsing (no two addresses would ever compare
         // equal on evidence text, discovered live while running this tool
-        // against the real dumps -- see .planning/RE-FINDINGS.md).
+        // against the real dumps).
         rec = {
           verdict: "ORIGINAL",
           agreeing_releases: available.length,
@@ -519,7 +519,7 @@ function mergeGroup(group) {
   // `swallowedGap` below. Deduplicated (via Set) so a coalesced range with
   // many same-reason singleton addresses doesn't repeat identical
   // boilerplate once per address -- found live while running this against
-  // the real dumps (see .planning/RE-FINDINGS.md).
+  // the real dumps.
   const constituentNotes = [...new Set(nonOriginal.map((r) => r.evidence || r.reason).filter(Boolean))];
   const swallowedGap = group.length > nonOriginal.length;
   const note =
@@ -599,11 +599,11 @@ export function splitRangeByManifestKind(range, manifestRanges) {
 
 /**
  * Promote one manifest from `ranges-only` to `bucketed`: `unused`/`io`
- * ranges are kept verbatim (D-02's byte-level classification already
+ * ranges are kept verbatim (the byte-level classification already
  * stands); every `unclassified` range is re-partitioned against the
  * release's earned `loader_ranges` (never NOTES.md prose) and this image's
  * own cracktro printable-run scan, with the remainder -- reached by the
- * trace/entry point -- bucketed `game`. Per D-05 the underlying bytes are
+ * trace/entry point -- bucketed `game`. The underlying bytes are
  * never edited; only the manifest's own `kind` field changes.
  */
 export function bucketManifest(image, manifest, { loaderRanges, cracktroMinLength = 8 } = {}) {
@@ -614,7 +614,7 @@ export function bucketManifest(image, manifest, { loaderRanges, cracktroMinLengt
     note: lr.note ?? "",
     evidence: lr.evidence ?? "",
   }));
-  // Keep every already-classified range verbatim (unused/io from D-02's
+  // Keep every already-classified range verbatim (unused/io from the
   // byte-level pass, or -- on a re-run of an already-bucketed manifest --
   // game/loader/cracktro from a prior run of this same function). Only
   // "unclassified" is ever re-partitioned. Filtering "kept" down to just
@@ -693,9 +693,9 @@ export function renderLedger({ generatedRanges, gapTolerance, prose }) {
     throw new Error(`renderLedger: refusing to emit -- generated tier stops at ${hex4(expected - 1)}, does not reach $FFFF`);
   }
 
-  // NOTE (plans 16-01, 16-10): the embedded invocation path below is deliberately the
+  // NOTE: the embedded invocation path below is deliberately the
   // CONSUMER's installed location (`.claude/skills/...`), not this repository's
-  // source-tree location (`src/skills/...`) -- pinned by diff-images.test.mjs and skill-consumer-paths.test.ts (16-REVIEW.md CR-01).
+  // source-tree location (`src/skills/...`) -- pinned by diff-images.test.mjs and skill-consumer-paths.test.ts.
   let generated = `<!-- GENERATED, DO NOT HAND-EDIT. Regenerate with: node .claude/skills/c64-provenance-diff/scripts/diff-images.mjs ledger --gap-tolerance ${gapTolerance} -->\n\n`;
   generated += `| Start | End | Kind | Verdict | Confidence | Agreeing releases | Evidence / Reason |\n`;
   generated += `|---|---|---|---|---|---|---|\n`;

package/skills/c64-provenance-diff/scripts/recovery-schema.mjs

@@ -4,7 +4,7 @@
 // Node/filesystem checks over `recovery/RELEASES.json` and the files it
 // references, run entirely offline.
 //
-// This is the mechanical enforcement of 01-01-PLAN.md's assumption_delta
+// This is the mechanical enforcement of the assumption_delta
 // decision: the registry is release-CENTRIC (N releases, each a full field
 // set, `canonical` demoted to a boolean on one entry), never
 // canonical-image-centric again. A future plan that quietly reintroduces a
@@ -31,9 +31,11 @@ const die = (m) => { console.error(`error: ${m}`); process.exit(1); };
 // The parameterisation gate must cover EVERY module of the recovery pipeline, not
 // just the ones sitting next to this file. When the six modules moved out of
 // `tools/` into the two skills that use them (2026-08-04), a `HERE`-only scan
-// silently stopped covering `d64-parse.mjs` and `dump-artifacts.mjs` -- a static
-// guard that keeps passing while checking less is worse than one that fails.
-// 2026-08-22 (plan 16-01): the second entry used to be built project-root-relative,
+// silently stopped covering the disk-image reader that used to live in the
+// sibling skill's `scripts/` directory (since deleted)
+// and `dump-artifacts.mjs` -- a static guard that keeps passing while
+// checking less is worse than one that fails.
+// 2026-08-22: the second entry used to be built project-root-relative,
 // naming the skills tree's pre-relocation auto-discovery location by hand -- which
 // stopped resolving the moment the skills tree moved to its current source-tree
 // location. Rebuilt `HERE`-relative instead -- correct in both this dev checkout
@@ -141,7 +143,7 @@ function runBaseChecks(registry) {
       for (const field of REQUIRED_DUMP_FILE_FIELDS) {
         const value = d[field];
         if (!value) {
-          errors.push(`release "${r.id}" dump "${d.label}": field "${field}" is not set (a dump is a four-file set, per D-04/D-02)`);
+          errors.push(`release "${r.id}" dump "${d.label}": field "${field}" is not set (a dump is a four-file set)`);
           continue;
         }
         const filePath = join(REPO_ROOT, value);