@henols/c64-re-tools 0.2.1 → 0.2.3

package/README.md

@@ -43,7 +43,7 @@ you pass `--force`.
 ## Requirements
 
 - **This installer** runs on Node ≥ 18.
-- **The VICE MCP server** it wires up requires **Node ≥ 22.18** (or ≥ 23.6), and a
+- **The VICE MCP server** it wires up requires **Node ≥ 24**, and a
   host with VICE (`x64sc`) reachable from the MCP client. See the
   [`@henols/vice-mcp`](https://www.npmjs.com/package/@henols/vice-mcp) readme.
 

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,26 @@
+# Third-Party Notices for `@henols/c64-re-tools`
+
+This package is MIT-licensed, copyright Henrik Olsson (see `LICENSE` at the
+repository root). It ships the C64 reverse-engineering **skill playbooks**
+under `skills/` plus the installer CLI under `bin/`, and it declares one
+runtime dependency, `@henols/vice-mcp`, which carries its own notices file.
+
+This document covers only the third-party material that ships **in this
+package**. It is deliberately not a second, competing inventory: the canonical
+third-party notices for the whole repository — including the cc65 opcode-table
+transcription and the ACME/VICE not-incorporated scope notes, none of which
+ship here — live in the `@henols/vice-mcp` package at
+`src/mcp/vice/THIRD-PARTY-NOTICES.md` in the repository, and inside that
+package's own tarball as `THIRD-PARTY-NOTICES.md`. Read that file for the full
+inventory; read this one for what `@henols/c64-re-tools` itself carries.
+
+## Incorporated material
+
+None. The skill playbooks under `skills/` are this project's own prose,
+written against this project's own curated tool surface.
+
+## Runtime dependency
+
+- **`@henols/vice-mcp`** — this repository's own MCP server package, MIT. Its
+  own third-party notices ship inside it as `THIRD-PARTY-NOTICES.md`, and that
+  file is the canonical inventory referred to at the top of this document.

package/bin/cli.mjs

@@ -13,6 +13,9 @@
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve } from "node:path";
+// Entry-point dispatch guard (see the bottom of this file): the same idiom
+// `src/skills/c64-memory-mapping/scripts/driver.mjs` already uses, so a bare
+// `import` from a test file does not also execute the CLI.
 import {
   existsSync,
   readFileSync,
@@ -27,11 +30,11 @@ const PKG_ROOT = dirname(HERE);
 const SKILLS_SRC = join(PKG_ROOT, "skills");
 
 // The single version-resolution seam this repo maintains is
-// `.claude/mcp/vice/version.ts` (quick-260819-tsz, D-5). This package
+// `src/mcp/vice/version.ts` (quick-260819-tsz, D-5). This package
 // deliberately does NOT import it: it ships without the seam file (its
 // `files[]` is `bin/`, `skills/`, `README.md`) and targets node >= 18, which
 // cannot type-strip the seam's `.ts` the way the vice-mcp package's own
-// node >= 22.18 runtime can. What follows is exactly the seam's own
+// node >= 24 runtime can. What follows is exactly the seam's own
 // precedence step 1 -- "read my own package.json's `.version`, trust it
 // when it is a real published number" -- not a second, independent
 // implementation of the resolution algorithm; there is no template/`-`
@@ -45,11 +48,11 @@ const SELF_VERSION = typeof SELF.version === "string" ? SELF.version : "0.0.0";
 const MCP_PKG = "@henols/vice-mcp";
 // The dev placeholder every derived, publishable version string carries in
 // the working tree (R-2, quick-260819-tsz). Defined authoritatively as
-// `DEV_PLACEHOLDER` in `.claude/mcp/vice/version.ts` -- repeated here as a
+// `DEV_PLACEHOLDER` in `src/mcp/vice/version.ts` -- repeated here as a
 // literal, NOT imported, because this package deliberately ships without
 // that seam file (see the comment above) and targets node >= 18, which
 // cannot type-strip a `.ts` import the way the vice-mcp package's own
-// node >= 22.18 runtime can. This is the same disclosed divergence as
+// node >= 24 runtime can. This is the same disclosed divergence as
 // `SELF_VERSION` above: one literal, kept in sync by hand, documented here
 // so a future edit to the seam's placeholder is not missed.
 const MCP_DEV_PLACEHOLDER = "0.0.0-dev";
@@ -124,7 +127,7 @@ What it does:
   1. Copies bundled skills into <target>/.claude/skills/
   2. Adds a 'vice' server to <target>/.mcp.json (other servers are preserved)
 
-Requires Node >= 22.18 to RUN the vice MCP server (this installer runs on Node >= 18).`;
+Requires Node >= 24 to RUN the vice MCP server (this installer runs on Node >= 18).`;
 
 function viceServerEntry(vendor) {
   return {
@@ -262,8 +265,16 @@ function main() {
     console.error("Dry run -- nothing was written.");
   } else {
     console.error("Done. Restart Claude Code in this project so it picks up the skills and MCP server.");
-    console.error("Note: running the vice MCP server requires Node >= 22.18 (or >= 23.6).");
+    console.error("Note: running the vice MCP server requires Node >= 24.");
   }
 }
 
-main();
+// Only dispatch when this module is the process entry point -- i.e. run as
+// `node bin/cli.mjs ...` or via the `c64-re-tools` bin shim -- not when
+// imported by a test (installer/wire-mcp.test.mjs imports `wireMcp`/`readJson`
+// below and must not trigger a real install as a side effect).
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}
+
+export { wireMcp, readJson };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Installer that adds the C64 reverse-engineering skills and the VICE emulator MCP server (@henols/vice-mcp) to a project.",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   "files": [
     "bin/",
     "skills/",
-    "README.md"
+    "README.md",
+    "THIRD-PARTY-NOTICES.md"
   ],
   "engines": {
     "node": ">=18"
@@ -44,10 +45,11 @@
     "installer"
   ],
   "dependencies": {
-    "@henols/vice-mcp": "0.2.1"
+    "@henols/vice-mcp": "0.2.3"
   },
   "scripts": {
     "sync-skills": "node scripts/sync-skills.mjs",
-    "prepack": "node scripts/sync-skills.mjs"
+    "prepack": "node scripts/sync-skills.mjs",
+    "test": "node --test '*.test.mjs'"
   }
 }

package/skills/acme-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: acme-build
-description: Assemble Commodore 64 6510 assembly with the ACME cross assembler. Use when asked to assemble, build, compile or link .a/.asm 6502/6510 source, produce a C64 .prg, scaffold a new C64 program, or list the symbols a program uses.
+description: Assemble Commodore 64 6510 assembly with the ACME cross assembler. Use when asked to assemble, build, compile or link .a/.asm 6502/6510 source, produce a C64 .prg, scaffold a new C64 program, or list which symbols an assembled build actually used from its symbol file.
 ---
 
 # Assembling C64 source with ACME
@@ -8,7 +8,7 @@ description: Assemble Commodore 64 6510 assembly with the ACME cross assembler.
 Source in, `.prg` out. Everything goes through one script:
 
 ```bash
-A=.claude/skills/acme-build/scripts/acme.mjs   # from the repo root
+A=src/skills/acme-build/scripts/acme.mjs   # from the repo root
 
 node $A new game.asm          # scaffold a C64 program
 node $A build game.asm        # assemble -> .prg .sym .vs .rep
@@ -22,6 +22,13 @@ absent `run` verb is not an omission). It contacts nothing.
 Options: `-o FILE` `--out-dir DIR` `-f FORMAT` `--setpc ADDR` `-DSYM=VAL`
 `-I DIR` `--no-report` `--json`.
 
+`-I DIR` is resolved **workspace-relative** to the project root the host
+broker was launched with — the same resolution `source`/`--out-dir` already
+go through — before it ever reaches the assembler. An absolute or escaping
+`-I` directory is refused by the seam rather than passed to ACME; this is a
+documented contract change from earlier releases, when an absolute include
+reached the assembler unchecked.
+
 ## Build
 
 ```bash
@@ -132,38 +139,81 @@ you also assemble by hand, so these stay recognised as mnemonics.
 
 ## Disassembly
 
-This skill does not disassemble. Static disassembly of a `.prg` or flat 64K image
-is a **required prerequisite** of this plugin, not an optional accelerator:
-regenerator2000, reached through
+This skill does not disassemble. The route that does is `anno export-asm`, and
+it lives in the `anno` CLI rather than here.
+
+**Dated withdrawal 2026-08-29, dated return 2026-08-31 — both halves are kept,
+because the withdrawal is the record of why the route is shaped the way it is.**
+Whole-program static disassembly was WITHDRAWN on 2026-08-29 rather than left standing on an unverified reassembly claim: the removed route
+settled correctness with a transcript parser, and the recorded false pass that
+discipline exists against read `ACME not found in PATH (skipped)` / `All
+roundtrip verifications passed.` / `EXIT=0` — exit zero, an aggregate line
+reading as a full pass, and the one assembler this project cares about never
+having run. On **2026-08-31 the route returned**, rebuilt over the annotation
+store as `anno export-asm`. It is not a rename of what was removed: its
+correctness is settled by **assembling the output with a real ACME and diffing
+the bytes against the input** — never by an exit code, and never by a string
+match on the exporter's own output.
+
+**The live invocation:**
 
 ```bash
-npx -y @henols/vice-mcp r2000 export-asm game.prg          # npm installs
-node <plugin-root>/.claude/mcp/vice/vice-proxy.ts r2000 export-asm game.prg  # in-repo/plugin
+npx -y @henols/vice-mcp anno export-asm game.prg --store game.annostore --out game-src
+node <plugin-root>/src/mcp/vice/vice-proxy.ts anno export-asm game.prg --store game.annostore
 ```
 
-A recursive-descent disassembler with an auto-analyzer does not render strings,
-tables and the BASIC stub as instructions, so there are no out-of-range labels
-to hand-define and no illegal-opcode lines to re-indent — the caveats this
-section used to carry were structural to a flat linear decoder and do not
-apply here. The exported source is verified reassemblable by a real ACME
-via `vice-mcp r2000 verify` (evidence:
-`.planning/phases/10-adoption-boundaries-automated-bootstrap-and-the-removal/evidence/10-verify-transcript.txt`).
-`c64-program-recon` points at this same route; it is not restated there.
+`<image>` and `--store` are **two separate arguments and neither is derived from
+the other** — the image supplies the bytes, the store supplies the names, ranges,
+typed regions and comments, and naming one does not name the other. `--out` names
+a **directory** the whole export is written into, defaulting to the image's
+basename stem beside the **store**, not beside the image, because the export is a
+generated view of the annotations. The directory holds a root file that sources
+the rest, one file per annotation scope, and an `unscoped.a` for anything inside
+no scope. A non-empty destination is refused rather than overwritten unless you
+pass `--force`.
 
-## Setup
+**The verb writes source text and runs no assembler.** Its own second output line
+says so, in as many words:
+
+```
+export-asm: this file has NOT been assembled -- this command writes source text and runs no assembler.
+```
+
+The real-ACME byte-diff oracle is **test-only** — it lives in
+`src/mcp/vice/acme-verify.ts`, is exercised by `acme-verify.test.ts` (hard-failed
+in CI with `VICE_REQUIRE_ACME=1`), and is deliberately absent from the published
+package, so nothing on the runtime path can reach it. A clean `export-asm` run is
+therefore evidence that source was written and nothing more; it is not an
+assembler verdict. If you need to know the emitted source reassembles, assemble
+it yourself — that is what this skill's own build route is for.
 
-`acme` on `$PATH` is the **only** requirement. The scaffold that `new` writes
-assembles against a bare install with no standard hardware-register library —
-that's deliberate: neither a plain `~/.local/bin/acme` build nor the Debian
-trixie `apt` candidate ships one, so a scaffold that depended on it would fail
-to assemble on a fresh install (Phase 8.1 FINDING-A1).
+**Reading one range at a time is still the right move for a single routine.**
+`anno_read_region` and `anno_disassemble` render an explicit inclusive range out
+of the image on demand, capped at 4096 bytes per call and REFUSED by name above
+the cap rather than truncated. `c64-program-recon` documents that route and this
+history together; it is not restated there.
+
+## Setup
 
-`$ACME` and the wrapper's auto-probe (`$ACME`, `/usr/local/share/acme`,
-`/usr/share/acme`, `/usr/lib/acme`, `~/.acme`) still exist and still matter —
-but only for **your own** sources that use angle-bracket includes (see
-"Writing source" above), not for the scaffold. If you have that library
-somewhere, point `$ACME` at its directory and angle-bracket includes work as
-before; if you don't, the scaffold doesn't need it.
+`acme` on `$PATH` — **on the host**, never inside a container — is the **only**
+requirement. The scaffold that `new` writes assembles against a bare install
+with no standard hardware-register library — that's deliberate: neither a
+plain `~/.local/bin/acme` build nor the Debian trixie `apt` candidate ships
+one, so a scaffold that depended on it would fail to assemble on a fresh
+install.
+
+**Route:** `scripts/acme.mjs` never spawns `acme` itself
+and never probes a container PATH for it — a container has no such PATH to
+probe (the project owner's rule of 2026-08-28). The script reaches the
+assembler only through the host-tool execution seam
+(`src/mcp/vice/host-tool.mts`'s `acme.build` allowlist entry), which runs on
+the HOST and probes the library there — the same handful of conventional
+install locations `acme.mts`'s own `findAcmeLib()` names, none of them
+documented a second time here. `$ACME` still matters for **your own** sources
+that use angle-bracket includes (see "Writing source" above), not for the
+scaffold — but set it in the environment the **host** broker process sees, not
+this script's own environment, since the probe now runs host-side inside the
+seam's executor. If you don't have that library, the scaffold doesn't need it.
 
 Re-checked against ACME release 0.97 "Zem" (31 Jan 2021). CI now assembles
 the shipped scaffold on every build with `$ACME` cleared (the "Assemble the
@@ -171,7 +221,7 @@ acme-build scaffold (library-free)" step in `.github/workflows/ci.yml`), so
 this claim is re-checkable rather than a one-machine observation.
 
 Copy `acme.mjs` into any project's `.claude/skills/acme-build/scripts/`, and
-`template.a` into `.claude/skills/acme-build/`, to use this elsewhere.
+`template.a` into `.claude/skills/acme-build/`, to use this elsewhere (the path Claude Code auto-discovers and `installSkills()` deploys to).
 
 ## Which skill does what
 
@@ -182,7 +232,7 @@ This one turns source into bytes. It does not restate what the others carry.
 | Where to start on an unknown program, and which address to read next | `c64-program-recon` |
 | What a specific address or bit means, or annotating a listing | `c64-memory-mapping` — `node … lookup '$D018'` |
 | A verified 64K image, or comparing two captures | `c64-ram-capture` |
-| Static disassembly of a `.prg` or flat image | `vice-mcp r2000 export-asm` (see Disassembly above) |
+| Static disassembly of a `.prg` or flat image | **`anno export-asm`** — withdrawn 2026-08-29, returned 2026-08-31 behind a real-ACME byte-diff oracle that is test-only, so the verb writes source and assembles nothing (see Disassembly above) |
 | **Source in, `.prg` out** | here |
 
 ## References
@@ -192,10 +242,10 @@ This one turns source into bytes. It does not restate what the others carry.
 | `scripts/acme.mjs` | The driver. Its comments are the contract for every flag above |
 | `template.a` | The scaffold `new` writes: BASIC stub with a computed `SYS`, five local hardware constants (no library needed), no `!to` |
 
-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/acme-build/scripts/acme.mjs

@@ -2,30 +2,114 @@
 // ACME -> C64 assembler driver.  Target is fixed: C64, 6510 CPU, cbm output.
 // Scope is assembling only: source in, .prg + symbol files out.  Running the
 // result on a C64 belongs to the emulator skill.
-import { spawnSync } from "node:child_process";
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { dirname, join, basename, relative, isAbsolute } from "node:path";
+//
+// The assembler is reached ONLY through the host-tool execution seam -- the
+// project owner's rule of 2026-08-28 is that this script runs container-side,
+// `acme` lives host-side, and there is no container PATH to find it on. This file used to spawn `acme` directly (a synchronous
+// `spawnSync("acme", args, { env })`) and probed FOUR fixed HOST paths
+// (`/usr/local/share/acme`, `/usr/share/acme`, `/usr/lib/acme`, `~/.acme`)
+// for its `<...>`-include library -- both are exactly what the owner's rule
+// says cannot work from inside a container. The spawn and the library probe
+// both moved to `src/mcp/vice/host-tool.mts`'s `acme.build` allowlist entry;
+// this file now only constructs a TYPED request and reads the produced files
+// back off the shared workspace tree.
+//
+// WHAT NOT TO DO: never reintroduce a local child-process call to the
+// assembler as a fallback when the seam is unreachable -- a fallback that
+// works on the developer's own host and silently fails inside a container is
+// the exact failure this seam exists to remove. A seam refusal is reported
+// and the build fails; it is never retried by spawning `acme` here.
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from "node:fs";
+import { dirname, join, basename, relative, isAbsolute, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+import { resolveMcpModule, refusalMessage } from "../../c64-ram-capture/scripts/mcp-module.mjs";
 
 const SELF = fileURLToPath(import.meta.url);
 const HERE = dirname(SELF);
 
-// The ACME library (<cbm/c64/vic.a> and friends) lives wherever the package put
-// it.  Probe instead of assuming; validated by a file we actually include.
-const LIB_MARKER = join("cbm", "c64", "vic.a");
-function findAcmeLib() {
-  const tried = [];
-  for (const c of [
-    process.env.ACME,
-    "/usr/local/share/acme", "/usr/share/acme", "/usr/lib/acme",
-    process.env.HOME && join(process.env.HOME, ".acme"),
-  ].filter(Boolean)) {
-    tried.push(c);
-    if (existsSync(join(c, LIB_MARKER))) return { path: c, tried };
+/** The MCP-side module this script reaches -- never imported statically
+ * (cross-package: this file ships in `@henols/c64-re-tools`, the seam client
+ * ships in `@henols/vice-mcp`), only located via the ladder and invoked with
+ * `process.execPath`, the interpreter already running this script, on an
+ * in-tree module -- not an external host binary. */
+const HOST_TOOL_CLIENT_FILE = "host-tool-client.ts";
+
+/**
+ * Invokes the host-tool execution seam for `tool`/`args`, rooted at
+ * `repoRoot` for THIS invocation's workspace-relative path resolution.
+ * Never rejects: a resolution failure, a spawn failure, or unparseable
+ * output all resolve to `{ ok: false, message }` -- the same shape a tool's
+ * own refusal uses, so a caller never needs a try/catch.
+ */
+function invokeSeam(tool, args, repoRoot) {
+  return new Promise((resolvePromise) => {
+    const resolved = resolveMcpModule(HOST_TOOL_CLIENT_FILE);
+    if (!resolved.ok) {
+      resolvePromise({ ok: false, message: refusalMessage(HOST_TOOL_CLIENT_FILE, resolved.rungs) });
+      return;
+    }
+
+    const cliArgs = [resolved.path, "run", "--tool", tool, "--args", JSON.stringify(args), "--repo-root", repoRoot];
+    let child;
+    try {
+      child = spawn(process.execPath, cliArgs, { stdio: ["ignore", "pipe", "pipe"] });
+    } catch (e) {
+      resolvePromise({ ok: false, message: e instanceof Error ? e.message : String(e) });
+      return;
+    }
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += chunk.toString("utf8"); });
+    child.stderr.on("data", (chunk) => { stderr += chunk.toString("utf8"); });
+    child.on("error", (err) => resolvePromise({ ok: false, message: err.message }));
+    child.on("close", () => {
+      const lines = stdout.split("\n").filter((line) => line.trim() !== "");
+      const last = lines[lines.length - 1];
+      if (last === undefined) {
+        resolvePromise({ ok: false, message: `host-tool-client.ts produced no output${stderr ? ` (stderr: ${stderr})` : ""}` });
+        return;
+      }
+      try {
+        resolvePromise(JSON.parse(last));
+      } catch {
+        resolvePromise({ ok: false, message: `host-tool-client.ts produced non-JSON output: ${last}` });
+      }
+    });
+  });
+}
+
+/** The smallest common ancestor directory of two absolute paths -- computed,
+ * never a fixed guess, so the request's `--repo-root` for THIS invocation is
+ * always exactly big enough to contain both the source and the output
+ * directory, and no bigger. This is what keeps a build entirely outside this
+ * project's own tree (this repo's `skill-acme-build-cli.test.ts`'s own
+ * scratch directories under the SYSTEM temp dir, and CI's own
+ * `RUNNER_TEMP`-rooted scaffold check) working after the migration: the
+ * seam's `resolveWorkspacePath()` refuses any path outside its given root, so
+ * the root for one invocation is chosen to be wherever that invocation's own
+ * files actually live, never a client-supplied absolute path sent as-is. */
+function commonAncestorDir(a, b) {
+  const partsA = resolve(a).split(sep);
+  const partsB = resolve(b).split(sep);
+  const common = [];
+  for (let i = 0; i < Math.min(partsA.length, partsB.length); i++) {
+    if (partsA[i] === partsB[i]) common.push(partsA[i]);
+    else break;
   }
-  return { path: null, tried };
+  const joined = common.join(sep);
+  return joined === "" ? sep : joined;
+}
+
+/** `path.relative()`, except the "same directory" case yields `"."` rather
+ * than `""` -- the seam's `resolveWorkspacePath()` refuses an empty string,
+ * but accepts `"."` as a no-op relative reference to its own root. */
+function toRel(root, abs) {
+  const r = relative(root, abs);
+  return r === "" ? "." : r;
 }
-const ACME_LIB = findAcmeLib();
 
 // How to refer to this script in hints, from wherever we were run.
 function selfPath() {
@@ -90,54 +174,65 @@ function curateLabels(vsPath, symbols) {
   return { kept: kept.length, dropped };
 }
 
-function build(src, opts) {
+async function build(src, opts) {
   if (!existsSync(src)) die(`no such source file: ${src}`);
+
+  const srcAbs = resolve(src);
   // Side files follow the .prg, not the source: two -DVARIANT builds of one
   // source must not overwrite each other's symbol tables.
-  const prg = opts.out || join(opts.outDir || dirname(src),
-    basename(src).replace(/\.(a|asm|s)$/i, "") + ".prg");
-  const outDir = dirname(prg);
-  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
-  const stem = prg.replace(/\.prg$/i, "");
-
-  const args = [
-    "--cpu", "6510",              // C64: enables the 6510 illegal opcodes
-    "-f", opts.format || "cbm",   // cbm = 2-byte load address, what LOAD wants
-    "-Wtype-mismatch",            // catches a missing '#' on an immediate
-    "--strict-segments",          // overlapping segments are reported as errors
-    "--msvc",                     // machine-parseable diagnostics
-    "-v1",                        // report the address range actually emitted
-    "-o", prg,
-    "-l", `${stem}.sym`,
-    "--vicelabels", `${stem}.vs`,
-  ];
-  if (!opts.noReport) args.push("-r", `${stem}.rep`);
-  for (const d of opts.defines) args.push(`-D${d}`);
-  for (const i of opts.includes) args.push("-I", i);
-  if (opts.setpc) args.push("--setpc", opts.setpc);
-  args.push(src);
-
-  // `<cbm/c64/vic.a>` style includes resolve through the ACME env var, so set
-  // it here rather than depending on the shell environment carrying it.
-  const env = { ...process.env };
-  if (ACME_LIB.path) env.ACME = ACME_LIB.path;
-  const r = spawnSync("acme", args, { encoding: "utf8", env });
-  if (r.error) {
-    die(r.error.code === "ENOENT"
-      ? "install the ACME cross assembler and put `acme` on PATH"
-      : String(r.error));
+  const desiredPrg = opts.out
+    ? resolve(opts.out)
+    : join(resolve(opts.outDir || dirname(src)), basename(src).replace(/\.(a|asm|s)$/i, "") + ".prg");
+  const desiredOutDirAbs = dirname(desiredPrg);
+  if (!existsSync(desiredOutDirAbs)) mkdirSync(desiredOutDirAbs, { recursive: true });
+  const desiredStem = desiredPrg.replace(/\.prg$/i, "");
+
+  // Workspace-relative request construction (A-03): the root for THIS
+  // invocation is the smallest ancestor containing both the source and the
+  // output directory -- see commonAncestorDir()'s own header.
+  const repoRoot = commonAncestorDir(dirname(srcAbs), desiredOutDirAbs);
+  const autoOutDirAbs = dirname(srcAbs); // the executor's own default when outDir is omitted
+
+  const args = { source: toRel(repoRoot, srcAbs) };
+  if (desiredOutDirAbs !== autoOutDirAbs) args.outDir = toRel(repoRoot, desiredOutDirAbs);
+  if (opts.format) args.format = opts.format;
+  if (opts.setpc) args.setpc = opts.setpc;
+  if (opts.defines && opts.defines.length) args.defines = opts.defines;
+  if (opts.includes && opts.includes.length) args.includes = opts.includes;
+  if (opts.noReport) args.noReport = true;
+
+  const response = await invokeSeam("acme.build", args, repoRoot);
+
+  if (!response.ok) {
+    // A seam-level refusal (unresolvable seam, unreachable broker, a bad
+    // request) -- never a local fallback that spawns the assembler itself.
+    die(response.message);
   }
 
-  const diags = parseDiagnostics(((r.stderr || "") + (r.stdout || "")).trim());
-  if (diags.some((d) => /ACME.*environment variable/i.test(d.message))) {
-    diags.push({
-      file: null, line: null, severity: "note", zone: null,
-      message: `for <...> includes, set $ACME to the directory holding ${LIB_MARKER} ` +
-               `(looked in: ${ACME_LIB.tried.join(", ")})`,
-    });
+  // The executor always names outputs after the SOURCE's own basename (never
+  // a caller-chosen stem) -- see host-tool.mts's buildHostToolArgv(). When
+  // `-o`/`--out-dir` asked for a DIFFERENT stem (a rename, not just a
+  // different directory), the produced files are moved here to the exact
+  // requested names -- a workspace file operation, not a second copy of
+  // argv construction.
+  const autoStem = join(desiredOutDirAbs, basename(srcAbs).replace(/\.(a|asm|s)$/i, ""));
+  if (autoStem !== desiredStem) {
+    for (const ext of [".prg", ".sym", ".vs", ".rep"]) {
+      const from = `${autoStem}${ext}`;
+      const to = `${desiredStem}${ext}`;
+      if (existsSync(from) && from !== to) {
+        mkdirSync(dirname(to), { recursive: true });
+        renameSync(from, to);
+      }
+    }
   }
+
+  const stem = desiredStem;
+  const prg = desiredPrg;
+
+  const diags = parseDiagnostics((response.stderrTail || "").trim());
   const errors = diags.filter((d) => d.severity.endsWith("error"));
-  const ok = r.status === 0 && existsSync(prg);
+  const ok = response.exitStatus === 0 && existsSync(prg);
 
   let range = null, size = null, symbols = [], labels = null;
   if (ok) {
@@ -176,16 +271,16 @@ function reportBuild(res, { json }) {
 
 // -------------------------------------------------------------------- verbs
 
-function cmdBuild(argv) {
+async function cmdBuild(argv) {
   const o = parseOpts(argv);
-  const res = build(o.src, o);
+  const res = await build(o.src, o);
   reportBuild(res, o);
   process.exit(res.ok ? 0 : 1);
 }
 
-function cmdSym(argv) {
+async function cmdSym(argv) {
   const o = parseOpts(argv);
-  const res = build(o.src, { ...o, noReport: true });
+  const res = await build(o.src, { ...o, noReport: true });
   if (!res.ok) { reportBuild(res, o); process.exit(1); }
   const used = res.symbols.filter((s) => s.used).sort((a, b) => a.name.localeCompare(b.name));
   if (o.json) { console.log(JSON.stringify(used, null, 2)); return; }
@@ -199,7 +294,7 @@ function cmdNew(argv) {
   if (!path) die("usage: new <file.a>");
   if (existsSync(path)) die(`${path} already exists`);
   // template.a lives at the skill root, one level up from scripts/, by
-  // decision (D-03): only .mjs modules move into scripts/.
+  // decision: only .mjs modules move into scripts/.
   writeFileSync(path, readFileSync(join(HERE, "..", "template.a"), "utf8"));
   console.log(`wrote ${path}`);
   console.log(`next: node ${selfPath()} build ${path}`);
@@ -243,4 +338,4 @@ options: -o FILE  --out-dir DIR  -f FORMAT  --setpc ADDR  -DSYM=VAL  -I DIR
          --no-report  --json`);
   process.exit(cmd ? 1 : 0);
 }
-VERBS[cmd](rest);
+await VERBS[cmd](rest);

package/skills/acme-build/template.a

@@ -6,7 +6,7 @@
 ; No angle-bracket library includes here on purpose. Neither documented ACME
 ; provisioning route ships the standard hardware-register library - a bare
 ; `~/.local/bin/acme` install and the Debian trixie `apt` candidate were both
-; verified to lack it (Phase 8.1 FINDING-A1) - so a scaffold that depends on
+; verified to lack it - so a scaffold that depends on
 ; it fails to assemble on a fresh install. The five constants below are
 ; exactly what this scaffold's body uses, defined locally instead. If you
 ; want the full library for your own sources' angle-bracket includes, set