@henols/c64-re-tools 2.0.0-rc.2 → 2.0.0-rc.21

package/src/graphics.ts

@@ -0,0 +1,158 @@
+// Indexed images: the PNG encoder of emulator frames, and the C64 graphics
+// in memory as images for the documentation (D80). A region of the knowledge
+// gives no display mode and no colours, so a sprite, a bitmap or a charset is read
+// both in hires and in multicolour, with fixed pattern palettes.
+
+import { crc32, deflateSync } from "node:zlib";
+
+export interface IndexedFrame {
+  width: number;
+  height: number;
+  /** One palette index per pixel, row by row. */
+  pixels: Uint8Array;
+}
+
+export type Rgb = readonly [number, number, number];
+
+function chunk(type: string, data: Uint8Array): Buffer {
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(data.length, 0);
+  const body = Buffer.concat([Buffer.from(type, "latin1"), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body), 0);
+  return Buffer.concat([length, body, crc]);
+}
+
+/** Encodes an indexed frame as an 8-bit palette PNG. */
+export function encodePng(frame: IndexedFrame, palette: ReadonlyArray<Rgb>): Buffer {
+  for (const index of frame.pixels) {
+    if (index >= palette.length) throw new Error(`pixel colour ${index} is not in the ${palette.length}-colour palette`);
+  }
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(frame.width, 0);
+  header.writeUInt32BE(frame.height, 4);
+  header[8] = 8; // bit depth
+  header[9] = 3; // indexed colour
+  const rows = Buffer.alloc((frame.width + 1) * frame.height);
+  for (let row = 0; row < frame.height; row++) {
+    // Filter byte 0 (none), then the row.
+    rows.set(frame.pixels.subarray(row * frame.width, (row + 1) * frame.width), row * (frame.width + 1) + 1);
+  }
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk("IHDR", header),
+    chunk("PLTE", Buffer.from(palette.flat())),
+    chunk("IDAT", deflateSync(rows)),
+    chunk("IEND", new Uint8Array(0)),
+  ]);
+}
+
+export type GraphicsMode = "hires" | "multicolour";
+
+/**
+ * The pattern palettes: the index is the pixel value (hires: the bit; multicolour:
+ * the bit pair, 0 = background $d021, 1 = $d022 or screen high nibble, 2 = $d023 or
+ * screen low nibble, 3 = colour RAM), and the last index is the gap between sprites.
+ */
+export const PATTERN_PALETTES: Record<GraphicsMode, readonly Rgb[]> = {
+  hires: [
+    [0x00, 0x00, 0x00],
+    [0xff, 0xff, 0xff],
+    [0x35, 0x28, 0x79],
+  ],
+  multicolour: [
+    [0x00, 0x00, 0x00],
+    [0xad, 0xad, 0xad],
+    [0x6c, 0x6c, 0x6c],
+    [0xed, 0xf1, 0x71],
+    [0x35, 0x28, 0x79],
+  ],
+};
+
+/** The pixel values of one byte, left to right: 8 hires pixels, or 4 multicolour pixels of 2 each. */
+function bytePixels(byte: number, mode: GraphicsMode): number[] {
+  if (mode === "hires") return Array.from({ length: 8 }, (_, bit) => (byte >> (7 - bit)) & 1);
+  return Array.from({ length: 8 }, (_, pixel) => (byte >> (6 - 2 * (pixel >> 1))) & 3);
+}
+
+export const SPRITE = { width: 24, height: 21, bytes: 63 } as const;
+
+/**
+ * The sprites of `bytes` as one sheet, `perRow` sprites wide with a gap of one
+ * pixel. Each sprite takes `stride` bytes (64 in a VIC bank, 63 when packed).
+ */
+export function spriteSheet(bytes: Uint8Array, mode: GraphicsMode, stride = 64, perRow = 8): IndexedFrame {
+  const count = Math.max(1, Math.floor((bytes.length + stride - SPRITE.bytes) / stride));
+  const columns = Math.min(count, perRow);
+  const rows = Math.ceil(count / perRow);
+  const width = columns * (SPRITE.width + 1) + 1;
+  const height = rows * (SPRITE.height + 1) + 1;
+  const gap = PATTERN_PALETTES[mode].length - 1;
+  const pixels = new Uint8Array(width * height).fill(gap);
+  for (let sprite = 0; sprite < count; sprite++) {
+    const left = (sprite % perRow) * (SPRITE.width + 1) + 1;
+    const top = Math.floor(sprite / perRow) * (SPRITE.height + 1) + 1;
+    for (let row = 0; row < SPRITE.height; row++) {
+      for (let column = 0; column < 3; column++) {
+        const values = bytePixels(bytes[sprite * stride + row * 3 + column] ?? 0, mode);
+        values.forEach((value, x) => (pixels[(top + row) * width + left + column * 8 + x] = value));
+      }
+    }
+  }
+  return { width, height, pixels };
+}
+
+/** Cells of 8 bytes as 8x8 pixels, `perRow` cells to a row, cell 0 at the top left. */
+function cellFrame(bytes: Uint8Array, mode: GraphicsMode, perRow: number): IndexedFrame {
+  const cells = Math.ceil(bytes.length / 8);
+  const width = Math.min(cells, perRow) * 8;
+  const height = Math.ceil(cells / perRow) * 8;
+  const pixels = new Uint8Array(width * height);
+  for (let cell = 0; cell < cells; cell++) {
+    const left = (cell % perRow) * 8;
+    const top = Math.floor(cell / perRow) * 8;
+    for (let row = 0; row < 8; row++) {
+      bytePixels(bytes[cell * 8 + row] ?? 0, mode).forEach((value, x) => (pixels[(top + row) * width + left + x] = value));
+    }
+  }
+  return { width, height, pixels };
+}
+
+/** A bitmap of 8x8 cells of 8 bytes, 40 cells to a row, as the VIC reads it. */
+export function bitmapFrame(bytes: Uint8Array, mode: GraphicsMode): IndexedFrame {
+  return cellFrame(bytes, mode, 40);
+}
+
+/** A character set: characters of 8 bytes, 16 to a row, so character N is in row N / 16 and column N % 16. */
+export function charsetFrame(bytes: Uint8Array, mode: GraphicsMode): IndexedFrame {
+  return cellFrame(bytes, mode, 16);
+}
+
+/** Each pixel as a square of `factor` pixels, so a small image is readable on a page. */
+export function scaleFrame(frame: IndexedFrame, factor: number): IndexedFrame {
+  const width = frame.width * factor;
+  const height = frame.height * factor;
+  const pixels = new Uint8Array(width * height);
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) pixels[y * width + x] = frame.pixels[Math.floor(y / factor) * frame.width + Math.floor(x / factor)]!;
+  }
+  return { width, height, pixels };
+}
+
+/**
+ * Screen codes as text rows of 40, as the character ROM shows the upper-case
+ * set: @, A-Z, the signs and digits; a reversed code (bit 7) shows as its
+ * code without bit 7, and a graphics code as a dot.
+ */
+export function screenText(bytes: Uint8Array): string[] {
+  const rows: string[] = [];
+  for (let start = 0; start < bytes.length; start += 40) {
+    let row = "";
+    for (const code of bytes.subarray(start, start + 40)) {
+      const plain = code & 0x7f;
+      row += plain === 0 ? "@" : plain <= 26 ? String.fromCharCode(0x40 + plain) : plain <= 31 ? "[£]^<"[plain - 27]! : plain <= 63 ? String.fromCharCode(plain) : ".";
+    }
+    rows.push(row);
+  }
+  return rows;
+}

package/src/host/main.ts

@@ -5,31 +5,39 @@ import { parseArgs } from "node:util";
 import { DEFAULT_HOST_PORT } from "../protocol/messages.ts";
 import { ProcessSupervisor } from "../native/processes.ts";
 import { startTrace, trace } from "../trace.ts";
-import { isLoopback, ListenError, parsePort, startHostServer, stopSignal } from "./server.ts";
+import { ListenError, parsePort, startHostServer, stopSignal } from "./server.ts";
+import { viceFlaws, type ViceVersion } from "../native/discover.ts";
+import { inspect } from "./tools/c1541.ts";
 import { createToolDispatcher } from "./tools/index.ts";
 import { checkViceStarts, findVice } from "./vice/process.ts";
 import { viceSessionFactory } from "./vice/session.ts";
+import { PACKAGE } from "../package.ts";
 
 const HELP = `c64-re-tools-host
 
 Usage:
-  npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host [--port <port>] [--listen <address> ...]
+  npx -y --package=${PACKAGE.name}@${PACKAGE.tag} c64-re-tools-host [--port <port>] [--log-console] [--log-dir <directory>]
   c64-re-tools-host --help
 
 Runs the c64-re-tools Host Runtime in the foreground. It first starts VICE
 once (x64sc on PATH, or C64RT_VICE) and does not start if VICE cannot run.
-It listens on 127.0.0.1:${DEFAULT_HOST_PORT}, starts one VICE emulator for each
+It listens on port ${DEFAULT_HOST_PORT} on every address, so a dev container
+reaches it as host.docker.internal. It starts one VICE emulator for each
 connected c64-re-tools-mcp process, and runs the tools that come with VICE
 (c1541, petcat) for skill scripts. Stop it with Ctrl+C; that stops every
 emulator and tool it started.
 
 Options:
-  --port <port>       Listen on this port instead (0 picks a free port).
-  --listen <address>  Also listen on this address, on the same port, for
-                      example the container bridge (172.17.0.1). An address
-                      that is not loopback needs C64RT_HOST_TOKEN: set it to
-                      the same secret for this program and for the clients.
-  --help              Show this help.`;
+  --port <port>            Listen on this port instead (0 picks a free port).
+  --log-console            Also print each request with its result, and each run
+                           of c1541 or petcat, to the console.
+  --log-dir <directory>    Write the same events as JSON lines to a file in this
+                           directory, with a copy of each VICE log.
+  --help                   Show this help.
+
+The host always logs its start and stop, connections, failures, and each call
+from a skill script (c1541, petcat) with its outcome. --log-console adds the
+calls of the MCP server and the tool runs. C64RT_TRACE does not apply to the host.`;
 
 function log(line: string): void {
   process.stderr.write(`c64-re-tools-host: ${line}\n`);
@@ -37,9 +45,12 @@ function log(line: string): void {
 }
 
 async function main(): Promise<number> {
-  let values: { help?: boolean; port?: string; listen?: string[] };
+  let values: { help?: boolean; port?: string; "log-console"?: boolean; "log-dir"?: string };
   try {
-    ({ values } = parseArgs({ options: { help: { type: "boolean" }, port: { type: "string" }, listen: { type: "string", multiple: true } }, strict: true }));
+    ({ values } = parseArgs({
+      options: { help: { type: "boolean" }, port: { type: "string" }, "log-console": { type: "boolean" }, "log-dir": { type: "string" } },
+      strict: true,
+    }));
   } catch (error) {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n\n${HELP}\n`);
     return 2;
@@ -48,7 +59,18 @@ async function main(): Promise<number> {
     process.stdout.write(`${HELP}\n`);
     return 0;
   }
-  startTrace("host", { warn: log });
+  const logDir = values["log-dir"];
+  if (logDir === "") {
+    process.stderr.write("--log-dir needs a directory.\n");
+    return 2;
+  }
+  startTrace("host", {
+    target: {
+      ...(logDir === undefined ? {} : { dir: { path: logDir, given: `--log-dir ${logDir}` } }),
+      ...(values["log-console"] ? { echo: (line: string) => process.stderr.write(`c64-re-tools-host: ${line}\n`) } : {}),
+    },
+    warn: log,
+  });
 
   const port = values.port === undefined ? DEFAULT_HOST_PORT : parsePort(values.port);
   if (port === undefined) {
@@ -56,12 +78,8 @@ async function main(): Promise<number> {
     return 2;
   }
 
-  const extraHosts = values.listen ?? [];
-  const token = process.env.C64RT_HOST_TOKEN;
-  if (extraHosts.some((address) => !isLoopback(address)) && (token === undefined || token.length < 16)) {
-    process.stderr.write("--listen with an address that is not loopback needs C64RT_HOST_TOKEN with at least 16 characters, so that only your clients can connect.\n");
-    return 2;
-  }
+  // First, so that every start, also a refused one, tells which runtime runs.
+  log(`${PACKAGE.name} ${PACKAGE.version} (Node.js ${process.version}, ${process.platform} ${process.arch})`);
 
   // Without an emulator the runtime is useless: refuse to start, by name and with the remedy.
   try {
@@ -78,39 +96,47 @@ async function main(): Promise<number> {
   supervisor.startWatchdog("host");
 
   // Finding x64sc is not enough: VICE without its ROM files exits at once.
+  let vice: ViceVersion;
   try {
-    await checkViceStarts({ supervisor });
+    vice = await checkViceStarts({ supervisor });
   } catch (error) {
     process.stderr.write(`${(error as Error).message}\n`);
     await supervisor.stopAll();
     return 1;
   }
-  log("VICE starts");
+  log(`VICE ${vice.major}.${vice.minor}${vice.revision === undefined ? "" : ` r${vice.revision}`} starts`);
+  const flaws = viceFlaws(vice);
+  // A known VICE flaw is named, not worked around (D56).
+  for (const flaw of flaws) log(`Known VICE flaw: ${flaw}`);
 
   let server;
   try {
     server = await startHostServer({
+      host: "0.0.0.0",
       port,
-      extraHosts,
-      ...(token === undefined || token === "" ? {} : { token }),
       log,
-      createViceSession: viceSessionFactory({ supervisor, log }),
-      tools: createToolDispatcher({ supervisor, log }),
+      createViceSession: viceSessionFactory({
+        supervisor,
+        log,
+        flaws,
+        // c1541 lists the disk, so an autostart index selects a program (R2-08).
+        directory: async (imageType, image) => {
+          const { result } = await inspect({ action: "directory", imageType }, image, { supervisor, signal: new AbortController().signal, log });
+          return result.action === "directory" ? result.entries : [];
+        },
+      }),
+      tools: createToolDispatcher({ supervisor, log, vice }),
     });
   } catch (error) {
     if (error instanceof ListenError && error.code === "EADDRINUSE") {
       process.stderr.write(`Port ${error.port} on ${error.address} is in use. Is another c64-re-tools-host running?\n`);
       return 1;
     }
-    if (error instanceof ListenError && error.code === "EADDRNOTAVAIL") {
-      process.stderr.write(`The address ${error.address} in --listen does not belong to this machine.\n`);
-      return 1;
-    }
     throw error;
   }
-  const addresses = [server.host, ...extraHosts].map((address) => `${address}:${server.port}`);
-  process.stdout.write(`c64-re-tools-host listening on ${addresses.join(", ")}\n`);
-  trace().event("host.listening", { addresses });
+  const address = `${server.host}:${server.port}`;
+  process.stdout.write(`c64-re-tools-host listening on ${address}\n`);
+  trace().event("host.listening", { addresses: [address] });
 
   trace().event("host.stop", { signal: await stopSignal(log) });
   await server.close();

package/src/host/server.ts

@@ -1,26 +1,26 @@
-import { createHash, timingSafeEqual } from "node:crypto";
 import { createServer, type Server, type Socket } from "node:net";
 
 import { encodeFrame, MessageReader } from "../protocol/framing.ts";
 import { checkHello, isOneOf, HEARTBEAT_TIMEOUT_MS, parseClientMessage, ProtocolError, type HostMessage, type ReceivedRequest, type VideoStandard, type WireError, WireFailure } from "../protocol/messages.ts";
 import { TOOL_OPERATIONS, validateToolParams, type ToolOperation, type ToolOperations } from "../protocol/tools.ts";
 import { attachmentCount, VICE_OPERATIONS, validateViceParams, type ViceOperation, type ViceOperations } from "../protocol/vice.ts";
-import { elapsedMs, trace } from "../trace.ts";
+import { elapsedMs, summarize, trace } from "../trace.ts";
 
 /** One live VICE session, owned by one connection. */
 export interface ViceSessionHandle {
   /**
    * Runs one operation. The session serializes its own work. Throws
    * WireFailure for domain failures. `attachments` holds the bytes the
-   * operation takes (see attachmentCount).
+   * operation takes (see attachmentCount); bytes the operation sends back go
+   * into `reply`.
    */
-  handle<O extends ViceOperation>(op: O, params: ViceOperations[O]["params"], attachments?: Buffer[]): Promise<ViceOperations[O]["result"]>;
+  handle<O extends ViceOperation>(op: O, params: ViceOperations[O]["params"], attachments?: Buffer[], reply?: Buffer[]): Promise<ViceOperations[O]["result"]>;
   /** Stops the emulator and drops queued work. Safe to call more than once. */
   close(): Promise<void>;
 }
 
 /** Starts a VICE session. Throws WireFailure with an actionable code when it cannot. */
-export type ViceSessionFactory = (options: { videoStandard: VideoStandard }) => Promise<ViceSessionHandle>;
+export type ViceSessionFactory = (options: { videoStandard: VideoStandard; log?: (line: string) => void }) => Promise<ViceSessionHandle>;
 
 /**
  * Runs one native-tool request. `signal` aborts when the client goes away; the
@@ -37,16 +37,8 @@ export interface HostServerOptions {
   createViceSession: ViceSessionFactory;
   /** Native-tool requests on "tool" connections; without it they are refused. */
   tools?: ToolDispatcher;
-  /** Defaults to 127.0.0.1. More addresses listen on the same port, for example a container bridge. */
+  /** Defaults to 127.0.0.1; 0.0.0.0 listens on every address, so a container reaches it too. */
   host?: string;
-  /** Extra addresses to listen on, on the same port as `host`. */
-  extraHosts?: string[];
-  /**
-   * The shared secret. A connection that arrives on an address that is
-   * not loopback must send it in its hello; without a token such a
-   * connection is refused.
-   */
-  token?: string;
   /** 0 picks a free port. */
   port: number;
   /** How long a new connection may stay silent before it must send hello. */
@@ -67,10 +59,6 @@ const DEFAULT_HANDSHAKE_TIMEOUT_MS = 10_000;
 /** How long a refused client may keep its side of the connection open after the host has ended its side. */
 const REFUSED_CLOSE_MS = 1_000;
 
-function digest(text: string): Buffer {
-  return createHash("sha256").update(text, "utf8").digest();
-}
-
 /** A caught value for the log, with its stack when it has one. */
 function describe(error: unknown): string {
   return error instanceof Error ? (error.stack ?? error.message) : String(error);
@@ -95,18 +83,6 @@ class Connection {
   #isTool = false;
   readonly #reader = new MessageReader();
 
-  /** A connection on a loopback address needs no token; any other needs the host's token. */
-  #checkToken(token: string | undefined): WireError | undefined {
-    if (isLoopback(this.#socket.localAddress ?? "")) return undefined;
-    const expected = this.#options.token;
-    // Equal-length digests: the comparison takes the same time for any token, also one with multibyte characters.
-    const matches = expected !== undefined && token !== undefined && timingSafeEqual(digest(token), digest(expected));
-    if (matches) return undefined;
-    return {
-      code: "installation-incomplete",
-      message: "The c64-re-tools host runtime refused this client: a connection from outside the host needs C64RT_HOST_TOKEN with the same value on both sides.",
-    };
-  }
   readonly #socket: Socket;
   readonly #options: HostServerOptions;
   readonly #log: (line: string) => void;
@@ -119,9 +95,12 @@ class Connection {
   constructor(socket: Socket, options: HostServerOptions, log: (line: string) => void) {
     this.#socket = socket;
     this.#options = options;
-    this.#log = log;
+    // Every line names its connection, so the console shows which client starts and stops what.
+    this.#log = (line) => log(`connection ${this.#id}: ${line}`);
     this.closed = new Promise((resolve) => (this.#resolveClosed = resolve));
-    trace().event("connection.open", { connection: this.#id, remote: `${socket.remoteAddress}:${socket.remotePort}`, local: socket.localAddress });
+    const remote = `${socket.remoteAddress}:${socket.remotePort}`;
+    this.#log(`opened from ${remote}`);
+    trace().event("connection.open", { connection: this.#id, remote, local: socket.localAddress });
     this.#handshakeTimer = setTimeout(
       () => this.#abort("no hello before the handshake timeout"),
       options.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS,
@@ -191,7 +170,7 @@ class Connection {
     if (this.#state === "handshake") {
       if (message.type !== "hello") throw new ProtocolError("first message is not hello");
       clearTimeout(this.#handshakeTimer);
-      const mismatch = checkHello(message) ?? this.#checkToken(message.token);
+      const mismatch = checkHello(message);
       if (mismatch !== undefined) {
         this.#log(`refusing a client: ${mismatch.message}`);
         trace().event("connection.refused", { connection: this.#id, role: message.role, ...mismatch });
@@ -204,11 +183,13 @@ class Connection {
         this.#isTool = true;
         this.#state = "open";
         this.#send({ type: "ready" });
+        this.#log("ready for tool requests");
         trace().event("connection.ready", { connection: this.#id, role: "tool" });
         this.#restartHeartbeat();
         return;
       }
       this.#state = "starting";
+      this.#log(`starts a VICE session (${message.videoStandard ?? "pal"})`);
       this.#contain(this.#startSession(message.videoStandard ?? "pal"));
       return;
     }
@@ -230,6 +211,7 @@ class Connection {
     this.#session = session;
     this.#state = "open";
     this.#send({ type: "ready" });
+    this.#log(`VICE session ready after ${Math.round(performance.now() - started)} ms`);
     trace().event("connection.ready", { connection: this.#id, role: "vice-session", videoStandard, ms: elapsedMs(started) });
     this.#restartHeartbeat();
   }
@@ -237,7 +219,7 @@ class Connection {
   /** The new session, or undefined after the failure is sent to the client. Never rejects, also when the factory throws at once. */
   async #createSession(videoStandard: VideoStandard): Promise<ViceSessionHandle | undefined> {
     try {
-      return await this.#options.createViceSession({ videoStandard });
+      return await this.#options.createViceSession({ videoStandard, log: this.#log });
     } catch (error) {
       this.#log(`VICE session failed to start: ${error instanceof Error ? error.message : String(error)}`);
       trace().event("connection.session-failed", { connection: this.#id, error });
@@ -252,8 +234,15 @@ class Connection {
 
   async #answer(request: ReceivedRequest, attachments: Buffer[]): Promise<void> {
     const started = performance.now();
-    const record = (outcome: Record<string, unknown>) =>
-      trace().event("request", { connection: this.#id, op: request.op, id: request.id, params: request.params, attachments: attachments.length, ms: elapsedMs(started), ...outcome });
+    const record = (outcome: Record<string, unknown>) => {
+      const ms = elapsedMs(started);
+      trace().event("request", { connection: this.#id, op: request.op, id: request.id, params: request.params, attachments: attachments.length, ms, ...outcome });
+      // A call from a skill script (c1541, petcat, status) is always logged; the many calls of a VICE session only in the trace.
+      if (this.#isTool) {
+        const what = outcome.ok === true ? "ok" : `${String(outcome.code)}: ${String(outcome.message)}`;
+        this.#log(`${request.op} ${JSON.stringify(summarize(request.params) ?? {})}: ${what} (${ms} ms)`);
+      }
+    };
     try {
       let result: unknown;
       let replyAttachments: Buffer[] = [];
@@ -270,10 +259,10 @@ class Connection {
         const session = this.#session;
         if (session === undefined || !isOneOf(VICE_OPERATIONS, op)) throw new WireFailure("invalid-input", `unknown operation: ${op}`);
         const params = validateViceParams(op, request.params);
-        if (attachments.length !== attachmentCount(op)) {
-          throw new WireFailure("invalid-input", `${op} takes ${attachmentCount(op)} file attachment(s)`);
+        if (attachments.length !== attachmentCount(op, params)) {
+          throw new WireFailure("invalid-input", `${op} takes ${attachmentCount(op, params)} file attachment(s)`);
         }
-        result = await session.handle(op, params, attachments);
+        result = await session.handle(op, params, attachments, replyAttachments);
       }
       this.#send({ type: "reply", id: request.id, result }, replyAttachments);
       record({ ok: true, result });
@@ -299,21 +288,17 @@ class Connection {
     this.#toolAbort.abort();
     const session = this.#session ?? (await this.#starting);
     this.#session = undefined;
+    if (session !== undefined) this.#log("the client is gone; stopping its VICE session");
     try {
       await session?.close();
     } catch (error) {
       this.#log(`session close failed: ${error instanceof Error ? error.message : String(error)}`);
     }
+    this.#log("closed");
     this.#resolveClosed();
   }
 }
 
-/** True for 127.0.0.0/8 and ::1, also in their IPv4-mapped IPv6 form. */
-export function isLoopback(address: string): boolean {
-  const plain = address.startsWith("::ffff:") ? address.slice(7) : address;
-  return plain === "::1" || /^127\.\d+\.\d+\.\d+$/.test(plain);
-}
-
 /** A port as the user gives it: decimal digits only, 0 to 65535. Anything else gives undefined. */
 export function parsePort(text: string): number | undefined {
   if (!/^\d{1,5}$/.test(text)) return undefined;
@@ -386,8 +371,6 @@ export async function startHostServer(options: HostServerOptions): Promise<HostS
   let port: number;
   try {
     port = await listen(host, options.port);
-    // The extra addresses share the port, so one endpoint setting reaches every address.
-    for (const extra of options.extraHosts ?? []) await listen(extra, port);
   } catch (error) {
     await Promise.all(servers.map((server) => new Promise<void>((resolve) => server.close(() => resolve()))));
     throw error;

package/src/host/tools/c1541.ts

@@ -37,11 +37,23 @@ const LAYOUTS: Record<string, Layout> = {
   "1581": { header: { track: 40, sector: 0 }, name: 0x04, id: 0x16, dos: 0x19 },
 };
 
+/** Used sectors of the format outside the header and directory chain: the 1571 BAM track 53, the two 1581 BAM blocks. */
+const RESERVED: Record<string, DiskSector[]> = {
+  "1541": [],
+  "1571": Array.from({ length: 19 }, (_, sector) => ({ track: 53, sector })),
+  "1581": [
+    { track: 40, sector: 1 },
+    { track: 40, sector: 2 },
+  ],
+};
+
 export interface DiskEntry extends DiskFile {
   /** The name's PETSCII bytes, up to the first shifted space ($a0). */
   nameBytes: Uint8Array;
   startTrack: number;
   startSector: number;
+  /** REL only: the first side sector. */
+  sideStart?: DiskSector;
 }
 
 const damaged = (message: string) => new WireFailure("media-error", `The disk image is damaged: ${message}`);
@@ -115,7 +127,7 @@ export function parseDirectory(blocks: Buffer[], layout: Layout): { diskName: st
       // Type 0 is an empty or scratched slot; the DOS lists no file there.
       if (typeByte === 0) continue;
       const nameBytes = nameField(block, offset + 5, 16);
-      entries.push({
+      const entry: DiskEntry = {
         name: petsciiNameToText(nameBytes),
         nameBytes,
         type: fileType(typeByte),
@@ -124,7 +136,10 @@ export function parseDirectory(blocks: Buffer[], layout: Layout): { diskName: st
         locked: (typeByte & 0x40) !== 0,
         startTrack: block.readUInt8(offset + 3),
         startSector: block.readUInt8(offset + 4),
-      });
+      };
+      const side = { track: block.readUInt8(offset + 0x15), sector: block.readUInt8(offset + 0x16) };
+      if (entry.type === "rel" && side.track !== 0) entry.sideStart = side;
+      entries.push(entry);
     }
   }
   return {
@@ -151,6 +166,13 @@ export function fileData(blocks: Buffer[], chain: DiskSector[]): Buffer {
   return Buffer.concat(parts);
 }
 
+/** The used sectors of the BAM that are not in `referenced`, in track and sector order. */
+export function unreferencedSectors(tracks: ReadonlyArray<{ track: number; usedSectors: number[] }>, referenced: Iterable<DiskSector>): DiskSector[] {
+  const known = new Set<string>();
+  for (const at of referenced) known.add(`${at.track}/${at.sector}`);
+  return tracks.flatMap(({ track, usedSectors }) => usedSectors.filter((sector) => !known.has(`${track}/${sector}`)).map((sector) => ({ track, sector })));
+}
+
 const toFile = (entry: DiskEntry): DiskFile => ({ name: entry.name, type: entry.type, blocks: entry.blocks, closed: entry.closed, locked: entry.locked });
 
 const sameBytes = (a: Uint8Array, b: Uint8Array) => a.length === b.length && a.every((byte, index) => byte === b[index]);
@@ -226,11 +248,18 @@ export async function inspect(params: C1541Params, image: Buffer, context: ToolC
     const layout = LAYOUTS[info.format];
     if (layout === undefined) throw new WireFailure("media-error", `The disk image has the drive format ${info.format}; only 1541, 1571 and 1581 disks are supported.`);
 
-    if (params.action === "bam") {
-      return { result: { action: "bam", tracks: parseBam(await c1541.run(["-bam"]), info.tracks) } };
-    }
     const headerChain = await c1541.chain(layout.header);
     const directory = parseDirectory(await c1541.blocks(headerChain), layout);
+    if (params.action === "bam") {
+      const tracks = parseBam(await c1541.run(["-bam"]), info.tracks);
+      // Every sector that the header, the directory or a file holds; a file without blocks has no chain.
+      const referenced = [...headerChain, ...(RESERVED[info.format] ?? [])];
+      for (const entry of directory.entries) {
+        if (entry.startTrack !== 0) referenced.push(...(await c1541.chain({ track: entry.startTrack, sector: entry.startSector })));
+        if (entry.sideStart !== undefined) referenced.push(...(await c1541.chain(entry.sideStart)));
+      }
+      return { result: { action: "bam", tracks, unreferenced: unreferencedSectors(tracks, referenced) } };
+    }
     if (params.action === "directory") {
       const { diskName, diskId, dosType, entries } = directory;
       return { result: { action: "directory", diskName, diskId, dosType, freeBlocks: parseFreeBlocks(overview), entries: entries.map(toFile) } };

package/src/host/tools/index.ts

@@ -3,6 +3,7 @@
 // ACME, DXA and Ghidra themselves. One entry per operation, never a
 // generic executable route.
 
+import type { ViceVersion } from "../../native/discover.ts";
 import type { ProcessSupervisor } from "../../native/processes.ts";
 import type { ToolContext } from "../../native/run.ts";
 import type { ToolOperation, ToolOperations } from "../../protocol/tools.ts";
@@ -24,8 +25,11 @@ const ADAPTERS: { [O in ToolOperation]: Adapter<O> } = {
   "petcat.decode": (_params, attachments, context) => decode(attachments[0]!, context),
 };
 
-export function createToolDispatcher(options: { supervisor: ProcessSupervisor; env?: NodeJS.ProcessEnv; log?: (line: string) => void }): ToolDispatcher {
+/** `vice`: the version that the host read from the emulator at start, for host.status. */
+export function createToolDispatcher(options: { supervisor: ProcessSupervisor; env?: NodeJS.ProcessEnv; log?: (line: string) => void; vice?: ViceVersion }): ToolDispatcher {
   return (op, params, attachments, signal) => {
-    return ADAPTERS[op](params, attachments, { supervisor: options.supervisor, signal, env: options.env, log: options.log });
+    const context = { supervisor: options.supervisor, signal, env: options.env, log: options.log };
+    if (op === "host.status") return hostStatus(context, options.vice) as ReturnType<ToolDispatcher>;
+    return ADAPTERS[op](params, attachments, context);
   };
 }

package/src/host/tools/petcat.ts

@@ -16,14 +16,17 @@ import { runToolOrFail, type ToolContext } from "../../native/run.ts";
 
 const TIMEOUT_MS = 30_000;
 const LISTING = "listing.txt";
-/** petcat's listing lines ("   10 sys2061"), as number and text. */
+/**
+ * petcat's listing lines ("   10 sys2061"), as number and text. petcat
+ * prints π ($ff) as `~`, which is no PETSCII character: the text has π (F-13).
+ */
 export function parseListing(listing: string): Array<{ number: number; text: string }> {
   const lines: Array<{ number: number; text: string }> = [];
   for (const line of listing.split(/\r?\n/)) {
     if (line.trim() === "") continue;
     const match = /^\s*(\d+) ?(.*)$/.exec(line);
     if (match === null) throw new WireFailure("operation-failed", "petcat printed a listing line without a line number.");
-    lines.push({ number: Number(match[1]), text: match[2]! });
+    lines.push({ number: Number(match[1]), text: match[2]!.replaceAll("~", "π") });
   }
   return lines;
 }
@@ -36,9 +39,13 @@ export async function decode(
   if ("reason" in tokenized) return { result: { decoded: false, reason: tokenized.reason } };
   const executable = findTool(PETCAT, context.env);
   await requireMinimumVersion(PETCAT, executable, context);
+  // petcat gets the BASIC text only, closed with a real end marker: after a
+  // link that only ends BASIC (machine code right after the last line), petcat
+  // prints a comment line where a listing line belongs.
+  const text = Buffer.concat([program.subarray(0, tokenized.textBytes), Buffer.of(0, 0)]);
   const workspace = Workspace.create(context.supervisor);
   try {
-    workspace.materialize("input", [{ path: "program.prg", size: program.length }], [program]);
+    workspace.materialize("input", [{ path: "program.prg", size: text.length }], [text]);
     const listingPath = join(workspace.directory("out"), LISTING);
     const run = await runToolOrFail(
       "petcat",