@henols/c64-re-tools 1.1.0 → 2.0.0-rc.11

package/src/host/server.ts

@@ -0,0 +1,392 @@
+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, 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); bytes the operation sends back go
+   * into `reply`.
+   */
+  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; log?: (line: string) => void }) => Promise<ViceSessionHandle>;
+
+/**
+ * Runs one native-tool request. `signal` aborts when the client goes away; the
+ * tool must then stop its children and remove its workspace. Throws WireFailure.
+ */
+export type ToolDispatcher = <O extends ToolOperation>(
+  op: O,
+  params: ToolOperations[O]["params"],
+  attachments: Buffer[],
+  signal: AbortSignal,
+) => Promise<{ result: ToolOperations[O]["result"]; attachments?: Buffer[] }>;
+
+export interface HostServerOptions {
+  createViceSession: ViceSessionFactory;
+  /** Native-tool requests on "tool" connections; without it they are refused. */
+  tools?: ToolDispatcher;
+  /** Defaults to 127.0.0.1; 0.0.0.0 listens on every address, so a container reaches it too. */
+  host?: string;
+  /** 0 picks a free port. */
+  port: number;
+  /** How long a new connection may stay silent before it must send hello. */
+  handshakeTimeoutMs?: number;
+  /** How long a ready connection may send nothing (no request, no ping) before it is closed with its session. */
+  heartbeatTimeoutMs?: number;
+  log?: (line: string) => void;
+}
+
+export interface HostServer {
+  readonly host: string;
+  readonly port: number;
+  /** Stops listening, closes every connection and stops every session. */
+  close(): Promise<void>;
+}
+
+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;
+
+/** 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);
+}
+
+function toWireError(error: unknown, fallback: WireError): WireError {
+  return error instanceof WireFailure ? error.toWire() : fallback;
+}
+
+/** Numbers the connections of this process, for the trace. */
+let connectionCount = 0;
+
+/** Owns one client connection: handshake, then requests against at most one VICE session. */
+class Connection {
+  readonly closed: Promise<void>;
+  readonly #id = ++connectionCount;
+  #state: "handshake" | "starting" | "open" | "closed" = "handshake";
+  #session: ViceSessionHandle | undefined;
+  #starting: Promise<ViceSessionHandle | undefined> | undefined;
+  #shuttingDown = false;
+  readonly #toolAbort = new AbortController();
+  #isTool = false;
+  readonly #reader = new MessageReader();
+
+  readonly #socket: Socket;
+  readonly #options: HostServerOptions;
+  readonly #log: (line: string) => void;
+  readonly #handshakeTimer: NodeJS.Timeout;
+  /** Runs from ready on; every received frame restarts it. */
+  #heartbeatTimer: NodeJS.Timeout | undefined;
+  #refusedTimer: NodeJS.Timeout | undefined;
+  #resolveClosed!: () => void;
+
+  constructor(socket: Socket, options: HostServerOptions, log: (line: string) => void) {
+    this.#socket = socket;
+    this.#options = options;
+    // 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));
+    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,
+    );
+    socket.setNoDelay(true);
+    // The kernel also probes an idle connection, for a peer that vanished without a close.
+    socket.setKeepAlive(true, 10_000);
+    socket.on("data", (chunk) => this.#receive(chunk));
+    socket.on("error", (error) => this.#log(`connection error: ${error.message}`));
+    socket.on("close", () => void this.#shutdown());
+  }
+
+  /** Closes the connection and its session. */
+  close(): Promise<void> {
+    this.#socket.destroy();
+    return this.closed;
+  }
+
+  /**
+   * A client that sends nothing for the heartbeat timeout is gone or hung (a
+   * half-open connection never closes by itself): close it, and with it its
+   * session and emulator.
+   */
+  #restartHeartbeat(): void {
+    if (this.#state !== "open") return;
+    clearTimeout(this.#heartbeatTimer);
+    const timeout = this.#options.heartbeatTimeoutMs ?? HEARTBEAT_TIMEOUT_MS;
+    this.#heartbeatTimer = setTimeout(() => this.#abort(`no message or ping for ${timeout} ms; the client is gone`), timeout);
+  }
+
+  #send(message: HostMessage, attachments: readonly Uint8Array[] = []): void {
+    if (this.#state !== "closed" && !this.#socket.destroyed) this.#socket.write(encodeFrame(message, attachments));
+  }
+
+  /** Ends the host's side after a refusal; a client that does not close its side in time is cut off. */
+  #endRefused(): void {
+    this.#socket.end();
+    this.#refusedTimer = setTimeout(() => this.#abort("the refused client did not close the connection"), REFUSED_CLOSE_MS);
+  }
+
+  #abort(reason: string): void {
+    this.#log(`closing connection: ${reason}`);
+    this.#socket.destroy();
+  }
+
+  #receive(chunk: Buffer): void {
+    this.#restartHeartbeat();
+    try {
+      for (const { message, attachments } of this.#reader.push(chunk)) {
+        if (this.#state === "closed") return;
+        this.#dispatch(message, attachments);
+      }
+    } catch (error) {
+      // Any failure closes only this connection; the listener and the other connections go on.
+      if (error instanceof ProtocolError) this.#abort(`protocol error: ${error.message}`);
+      else this.#abort(`internal error: ${describe(error)}`);
+    }
+  }
+
+  /** Closes this connection when work that runs after its message fails in an unexpected way. */
+  #contain(work: Promise<void>): void {
+    work.catch((error: unknown) => this.#abort(`internal error: ${describe(error)}`));
+  }
+
+  #dispatch(raw: unknown, attachments: Buffer[]): void {
+    const message = parseClientMessage(raw);
+    if (this.#state === "handshake") {
+      if (message.type !== "hello") throw new ProtocolError("first message is not hello");
+      clearTimeout(this.#handshakeTimer);
+      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 });
+        this.#send({ type: "error", error: mismatch });
+        this.#endRefused();
+        this.#state = "closed";
+        return;
+      }
+      if (message.role === "tool") {
+        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;
+    }
+    if (message.type === "hello") throw new ProtocolError("hello sent twice");
+    if (this.#state !== "open") throw new ProtocolError(`${message.type} sent before ready`);
+    if (message.type === "ping") {
+      this.#send({ type: "pong" });
+      return;
+    }
+    this.#contain(this.#answer(message, attachments));
+  }
+
+  async #startSession(videoStandard: VideoStandard): Promise<void> {
+    const started = performance.now();
+    this.#starting = this.#createSession(videoStandard);
+    const session = await this.#starting;
+    // A connection closed while starting is shut down by #shutdown, which awaits #starting.
+    if (session === undefined || this.#state === "closed") return;
+    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();
+  }
+
+  /** 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, 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 });
+      this.#send({
+        type: "error",
+        error: toWireError(error, { code: "machine-unavailable", message: "The emulator could not be started." }),
+      });
+      this.#endRefused();
+      return undefined;
+    }
+  }
+
+  async #answer(request: ReceivedRequest, attachments: Buffer[]): Promise<void> {
+    const started = performance.now();
+    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[] = [];
+      if (this.#isTool) {
+        const { op } = request;
+        const tools = this.#options.tools;
+        if (!isOneOf(TOOL_OPERATIONS, op) || tools === undefined) throw new WireFailure("invalid-input", `unknown operation: ${op}`);
+        const params = validateToolParams(op, request.params, attachments);
+        const answer = await tools(op, params, attachments, this.#toolAbort.signal);
+        result = answer.result;
+        replyAttachments = answer.attachments ?? [];
+      } else {
+        const { op } = request;
+        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, params)) {
+          throw new WireFailure("invalid-input", `${op} takes ${attachmentCount(op, params)} file attachment(s)`);
+        }
+        result = await session.handle(op, params, attachments, replyAttachments);
+      }
+      this.#send({ type: "reply", id: request.id, result }, replyAttachments);
+      record({ ok: true, result });
+    } catch (error) {
+      if (!(error instanceof WireFailure)) {
+        this.#log(`operation ${request.op} failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+      }
+      const wire = toWireError(error, { code: "operation-failed", message: "The operation failed inside the host runtime." });
+      this.#send({ type: "reply", id: request.id, error: wire });
+      record({ ok: false, ...wire });
+    }
+  }
+
+  async #shutdown(): Promise<void> {
+    if (this.#shuttingDown) return;
+    this.#shuttingDown = true;
+    this.#state = "closed";
+    trace().event("connection.close", { connection: this.#id });
+    clearTimeout(this.#handshakeTimer);
+    clearTimeout(this.#heartbeatTimer);
+    clearTimeout(this.#refusedTimer);
+    // Tool work for a client that is gone stops: its children and workspaces go too.
+    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();
+  }
+}
+
+/** 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;
+  const port = Number(text);
+  return port <= 0xffff ? port : undefined;
+}
+
+/**
+ * Resolves with the first SIGINT or SIGTERM. The handlers stay: a later
+ * signal is logged and ignored, so a second Ctrl+C cannot cut the shutdown
+ * short before every emulator and tool is stopped.
+ */
+export function stopSignal(log: (line: string) => void): Promise<NodeJS.Signals> {
+  return new Promise((resolve) => {
+    let stopping = false;
+    const stop = (signal: NodeJS.Signals) => {
+      if (stopping) {
+        log(`received ${signal} again; the host is already stopping`);
+        return;
+      }
+      stopping = true;
+      log(`received ${signal}, stopping`);
+      resolve(signal);
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+  });
+}
+
+/** A listener that could not start, with the address and the port it tried and the system error code. */
+export class ListenError extends Error {
+  readonly code: string | undefined;
+  readonly address: string;
+  readonly port: number;
+
+  constructor(cause: unknown, address: string, port: number) {
+    super(`cannot listen on ${address} port ${port}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    this.name = "ListenError";
+    this.code = (cause as NodeJS.ErrnoException | undefined)?.code;
+    this.address = address;
+    this.port = port;
+  }
+}
+
+/** Starts the Host Runtime listener. Each connection owns at most one VICE session. */
+export async function startHostServer(options: HostServerOptions): Promise<HostServer> {
+  const log = options.log ?? (() => {});
+  const host = options.host ?? "127.0.0.1";
+  const connections = new Set<Connection>();
+  const servers: Server[] = [];
+  const listen = (address: string, port: number) => {
+    const server: Server = createServer((socket) => {
+      const connection = new Connection(socket, options, log);
+      connections.add(connection);
+      void connection.closed.then(() => connections.delete(connection));
+    });
+    servers.push(server);
+    return new Promise<number>((resolve, reject) => {
+      const failed = (error: Error) => reject(new ListenError(error, address, port));
+      server.once("error", failed);
+      server.listen({ host: address, port, exclusive: true }, () => {
+        server.off("error", failed);
+        const bound = server.address();
+        if (bound === null || typeof bound === "string") reject(new Error("listener has no TCP address"));
+        else resolve(bound.port);
+      });
+    });
+  };
+
+  let port: number;
+  try {
+    port = await listen(host, options.port);
+  } catch (error) {
+    await Promise.all(servers.map((server) => new Promise<void>((resolve) => server.close(() => resolve()))));
+    throw error;
+  }
+
+  let closing: Promise<void> | undefined;
+  return {
+    host,
+    port,
+    close() {
+      closing ??= (async () => {
+        const stopped = Promise.all(servers.map((server) => new Promise<void>((resolve) => server.close(() => resolve()))));
+        await Promise.all([...connections].map((connection) => connection.close()));
+        await stopped;
+      })();
+      return closing;
+    },
+  };
+}

package/src/host/tools/c1541.ts

@@ -0,0 +1,284 @@
+// The c1541 adapter. c1541 does all image access: it recognises the
+// image, reports free blocks and the BAM, follows sector chains and writes raw
+// blocks. File names never go to c1541: its name arguments and its directory
+// listing change letter case, so the adapter reads the raw header and
+// directory blocks and matches names by their exact PETSCII bytes.
+//
+// c1541 exits 0 after most errors, so success is decided from its output and
+// from the output files it was asked to write.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { petsciiNameToText, textToPetsciiName } from "../../c64.ts";
+import { WireFailure } from "../../protocol/messages.ts";
+import { CBM_FILE_TYPES, type C1541Params, type C1541Result, type CbmFileType, type DiskFile, type DiskSector } from "../../protocol/tools.ts";
+import { Workspace } from "../../native/staging.ts";
+import { C1541, findTool } from "../../native/discover.ts";
+import { requireMinimumVersion } from "./version.ts";
+import { runToolOrFail, type ToolContext } from "../../native/run.ts";
+
+const TIMEOUT_MS = 30_000;
+const BLOCK_BYTES = 256;
+/** Block reads in one c1541 call, so that its command line stays far below the Windows limit of 32767 characters. */
+export const READS_PER_CALL = 256;
+
+/** Where a drive format keeps its header block and the header's fields. */
+interface Layout {
+  header: DiskSector;
+  name: number;
+  id: number;
+  dos: number;
+}
+
+const LAYOUTS: Record<string, Layout> = {
+  "1541": { header: { track: 18, sector: 0 }, name: 0x90, id: 0xa2, dos: 0xa5 },
+  "1571": { header: { track: 18, sector: 0 }, name: 0x90, id: 0xa2, dos: 0xa5 },
+  "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}`);
+
+/** The drive format and track count from c1541's info command. */
+export function parseInfo(output: string): { format: string; tracks: number } {
+  const format = /^disk format\s*:\s*(\S+)/m.exec(output);
+  const tracks = /^track count\s*:\s*(\d+)/m.exec(output);
+  if (format === null || tracks === null) {
+    throw new WireFailure("media-error", "c1541 does not recognise the disk image. Check that the file is a complete disk image of the given type.");
+  }
+  return { format: format[1]!, tracks: Number(tracks[1]) };
+}
+
+export function parseFreeBlocks(output: string): number {
+  const match = /^(\d+) blocks free\.$/m.exec(output);
+  if (match === null) throw new WireFailure("operation-failed", "c1541 did not report the free blocks of the disk.");
+  return Number(match[1]);
+}
+
+/** A sector chain as c1541's chain command prints it: "(17, 1) -> (17,11) -> 207". */
+export function parseChain(output: string, start: DiskSector): DiskSector[] {
+  const where = `the sector chain from track ${start.track} sector ${start.sector}`;
+  if (/cyclic reference found/.test(output)) throw damaged(`${where} loops.`);
+  const line = /^\(\s*\d+,\s*\d+\).*$/m.exec(output)?.[0];
+  if (line === undefined) throw damaged(`${where} cannot be read.`);
+  const parts = line.split(" -> ");
+  const end = parts.pop()!;
+  if (!/^\d+$/.test(end.trim())) throw damaged(`${where} leaves the disk.`);
+  return parts.map((part) => {
+    const match = /^\(\s*(\d+),\s*(\d+)\)$/.exec(part.trim());
+    if (match === null) throw new WireFailure("operation-failed", "c1541 printed a sector chain in an unknown form.");
+    return { track: Number(match[1]), sector: Number(match[2]) };
+  });
+}
+
+/** The BAM grid c1541 prints: one row per track, "*" for a used sector, "." for a free one. */
+export function parseBam(output: string, tracks: number): Array<{ track: number; freeSectors: number[]; usedSectors: number[] }> {
+  const rows: Array<{ track: number; freeSectors: number[]; usedSectors: number[] }> = [];
+  for (const line of output.split(/\r?\n/)) {
+    const match = /^\s*(\d+)\s+([.*]{1,8}(?: [.*]{1,8})*)\s*$/.exec(line);
+    if (match === null) continue;
+    const row = { track: Number(match[1]), freeSectors: [] as number[], usedSectors: [] as number[] };
+    [...match[2]!.replace(/ /g, "")].forEach((mark, sector) => (mark === "*" ? row.usedSectors : row.freeSectors).push(sector));
+    rows.push(row);
+  }
+  const complete = rows.length === tracks && rows.every((row, index) => row.track === index + 1);
+  if (!complete) throw new WireFailure("operation-failed", `c1541 printed a BAM that does not cover the ${tracks} tracks of the disk.`);
+  return rows;
+}
+
+/** The bytes of a name field up to the first shifted space ($a0). */
+function nameField(block: Buffer, offset: number, length: number): Uint8Array {
+  const field = block.subarray(offset, offset + length);
+  const end = field.indexOf(0xa0);
+  return Uint8Array.from(end < 0 ? field : field.subarray(0, end));
+}
+
+function fileType(typeByte: number): CbmFileType {
+  return CBM_FILE_TYPES[typeByte & 0x07] ?? "unknown";
+}
+
+/** The disk header and the directory entries, from the raw header block and the directory blocks after it. */
+export function parseDirectory(blocks: Buffer[], layout: Layout): { diskName: string; diskId: string; dosType: string; entries: DiskEntry[] } {
+  const [header, ...directory] = blocks;
+  if (header === undefined) throw new WireFailure("operation-failed", "c1541 returned no header block.");
+  const entries: DiskEntry[] = [];
+  for (const block of directory) {
+    for (let offset = 0; offset < BLOCK_BYTES; offset += 32) {
+      const typeByte = block.readUInt8(offset + 2);
+      // 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);
+      const entry: DiskEntry = {
+        name: petsciiNameToText(nameBytes),
+        nameBytes,
+        type: fileType(typeByte),
+        blocks: block.readUInt16LE(offset + 30),
+        closed: (typeByte & 0x80) !== 0,
+        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 {
+    diskName: petsciiNameToText(nameField(header, layout.name, 16)),
+    diskId: petsciiNameToText(header.subarray(layout.id, layout.id + 2)),
+    dosType: petsciiNameToText(header.subarray(layout.dos, layout.dos + 2)),
+    entries,
+  };
+}
+
+/** A file's data from its blocks in chain order: 254 bytes per block, the last block up to its end index. */
+export function fileData(blocks: Buffer[], chain: DiskSector[]): Buffer {
+  const parts: Buffer[] = [];
+  blocks.forEach((block, index) => {
+    const next = chain[index + 1];
+    if (next === undefined) {
+      if (block[0] !== 0) throw new WireFailure("operation-failed", "c1541 returned a last file block that links further.");
+      parts.push(block.subarray(2, Math.max(2, block.readUInt8(1) + 1)));
+    } else {
+      if (block[0] !== next.track || block[1] !== next.sector) throw new WireFailure("operation-failed", "c1541 returned file blocks that do not match the sector chain.");
+      parts.push(block.subarray(2));
+    }
+  });
+  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]);
+
+/** Runs c1541 commands on the staged image and returns all its output. */
+export class C1541Session {
+  readonly #executable: string;
+  readonly #workspace: Workspace;
+  readonly #image: string;
+  readonly #context: ToolContext;
+  #reads = 0;
+
+  constructor(executable: string, workspace: Workspace, image: string, context: ToolContext) {
+    this.#executable = executable;
+    this.#workspace = workspace;
+    this.#image = image;
+    this.#context = context;
+  }
+
+  async run(commands: string[]): Promise<string> {
+    const run = await runToolOrFail(
+      "c1541",
+      "The disk inspection",
+      {
+        argv: [this.#executable, "-attach", this.#image, ...commands],
+        cwd: this.#workspace.root,
+        timeoutMs: TIMEOUT_MS,
+        truncated: "c1541 printed more output than the host accepts.",
+      },
+      this.#context,
+    );
+    return `${run.stdout}\n${run.stderr}`;
+  }
+
+  async chain(start: DiskSector): Promise<DiskSector[]> {
+    return parseChain(await this.run(["-chain", String(start.track), String(start.sector)]), start);
+  }
+
+  /** Raw blocks, in the given order, through c1541's block read: at most READS_PER_CALL blocks in each c1541 call. */
+  async blocks(sectors: DiskSector[]): Promise<Buffer[]> {
+    const blocks: Buffer[] = [];
+    for (let first = 0; first < sectors.length; first += READS_PER_CALL) {
+      blocks.push(...(await this.#readBlocks(sectors.slice(first, first + READS_PER_CALL))));
+    }
+    return blocks;
+  }
+
+  async #readBlocks(sectors: DiskSector[]): Promise<Buffer[]> {
+    const directory = `blocks-${this.#reads++}`;
+    const full = this.#workspace.directory(directory);
+    const reads = sectors.map((at, index) => ({ at, file: `${index}.bin` }));
+    const output = await this.run(reads.flatMap(({ at, file }) => ["-bread", join(directory, file), String(at.track), String(at.sector)]));
+    return reads.map(({ at, file }) => {
+      const path = join(full, file);
+      const block = existsSync(path) ? readFileSync(path) : undefined;
+      if (block?.length === BLOCK_BYTES) return block;
+      if (/cannot read track|out of bounds/.test(output)) throw damaged(`track ${at.track} sector ${at.sector} cannot be read.`);
+      throw new WireFailure("operation-failed", `c1541 did not write track ${at.track} sector ${at.sector}.`);
+    });
+  }
+}
+
+export async function inspect(params: C1541Params, image: Buffer, context: ToolContext): Promise<{ result: C1541Result; attachments?: Buffer[] }> {
+  const executable = findTool(C1541, context.env);
+  await requireMinimumVersion(C1541, executable, context);
+  const workspace = Workspace.create(context.supervisor);
+  try {
+    const file = `image.${params.imageType}`;
+    workspace.materialize("input", [{ path: file, size: image.length }], [image]);
+    const c1541 = new C1541Session(executable, workspace, `input/${file}`, context);
+    const overview = await c1541.run(["-info", "-dir"]);
+    const info = parseInfo(overview);
+    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.`);
+
+    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) } };
+    }
+
+    if (params.name === undefined) throw new WireFailure("invalid-input", `action ${params.action} needs a file name`);
+    const wanted = textToPetsciiName(params.name);
+    const entry = directory.entries.find((candidate) => sameBytes(candidate.nameBytes, wanted));
+    if (entry === undefined) return { result: { action: params.action, found: false } };
+    if (params.action === "entry") {
+      return { result: { action: "entry", found: true, entry: { ...toFile(entry), startTrack: entry.startTrack, startSector: entry.startSector } } };
+    }
+    // A file without blocks (a DEL entry, for example) has no chain.
+    const start = { track: entry.startTrack, sector: entry.startSector };
+    const chain = start.track === 0 ? [] : await c1541.chain(start);
+    if (params.action === "chain") return { result: { action: "chain", found: true, sectors: chain } };
+    const data = fileData(await c1541.blocks(chain), chain);
+    return { result: { action: "read", found: true, name: entry.name, bytes: data.length }, attachments: [data] };
+  } finally {
+    workspace.remove();
+  }
+}