pi-tmux-session-map 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Wozniak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# pi-tmux-session-map
+
+A [pi](https://pi.dev) extension that records which Pi session runs in which tmux pane, so tmux-resurrect can restore the **exact** session after a tmux server restart — instead of blindly continuing the newest session for the pane's working directory.
+
+It also writes [tws](https://github.com/ytaskiran/tws)-compatible Pi work-status sidecar files for both tmux and Zellij, so each TWS edition can distinguish working, retrying, successful, cancelled, incomplete, and failed Pi runs.
+
+## Problem
+
+`pi --continue` resumes the most recent session for the current directory. When tmux-resurrect restores panes with a blanket `pi --continue`, every pane in the same directory gets the same (newest) session — the wrong one for all but one pane.
+
+## How it works
+
+The extension resolves a stable tmux pane key:
+
+```
+#{session_name}:#{window_index}.#{pane_index}
+```
+
+That key is stable across tmux server restarts (unlike pane ids like `%42`), which is exactly what tmux-resurrect restores. File names use a readable sanitized prefix plus a 12-character SHA-256 suffix so different pane keys cannot collide and very long tmux session names stay below filesystem filename limits.
+
+For tmux it writes the exact-resume mapping and status sidecar. For Zellij it writes only the status sidecar because Zellij owns session resurrection itself:
+
+```text
+~/.local/state/pi/tmux-sessions/<sanitized-pane-key>-<sha256-12>.session
+~/.config/tws/pi-status/<sanitized-pane-key>-<sha256-12>.json
+~/.config/tws-zellij/pi-status/<sanitized-pane-key>-<sha256-12>.json
+```
+
+The `.session` file contains the active Pi session file path. It is written on `session_start`, `session_info_changed`, `agent_start`, and `agent_end` when the current Pi session has a backing session file.
+
+The `.json` file contains the multiplexer backend, tws work state (`idle`, `working`, `retrying`, `done`, `cancelled`, `incomplete`, `failed`, `shutdown`), and pane/session metadata. A technical-error `agent_end` is provisional `retrying`; aborts and token-limit responses become `cancelled`/`incomplete` immediately. `agent_settled` confirms the final outcome (`failed` if recovery did not succeed). The extension touches the matching `agent.trigger` file after status writes so that edition refreshes within one poll tick.
+
+Mappings are intentionally **not** removed on shutdown — they must survive `tmux kill-server` so resurrect can use them. Every Pi start in a pane overwrites that pane's mapping, so stale entries self-heal. Very old mapping files and interrupted atomic-write temp files are cleaned up opportunistically on session start.
+
+## Install
+
+Requires Pi `0.80.5` or newer (`agent_settled` lifecycle event).
+
+```sh
+pi install npm:pi-tmux-session-map
+```
+
+Then reload pi:
+
+```txt
+/reload
+```
+
+## Pairing with tmux-resurrect
+
+Add a `pi-tmux-resume` wrapper on your `PATH`:
+
+```sh
+#!/usr/bin/env bash
+set -euo pipefail
+
+state_dir="$HOME/.local/state/pi/tmux-sessions"
+
+fallback() {
+  exec pi --continue
+}
+
+if [ -z "${TMUX:-}" ] || [ -z "${TMUX_PANE:-}" ]; then
+  fallback
+fi
+
+key="$(tmux display-message -p -t "$TMUX_PANE" '#{session_name}:#{window_index}.#{pane_index}' 2>/dev/null || true)"
+if [ -z "$key" ]; then
+  fallback
+fi
+
+# Keep in sync with src/domain/pane-key.ts.
+sanitized="$(printf '%s' "$key" | LC_ALL=C tr -c 'A-Za-z0-9._-' '_' | cut -c 1-120)"
+if [ -z "$sanitized" ] || printf '%s' "$sanitized" | grep -Eq '^\.+$'; then
+  sanitized="pane"
+fi
+hash="$(printf '%s' "$key" | shasum -a 256 | awk '{print substr($1, 1, 12)}')"
+map="$state_dir/$sanitized-$hash.session"
+
+if [ -f "$map" ]; then
+  session_file="$(head -n 1 "$map" 2>/dev/null || true)"
+  if [ -n "$session_file" ] && [ -f "$session_file" ]; then
+    exec pi --session "$session_file"
+  fi
+fi
+
+fallback
+```
+
+Then tell tmux-resurrect to restore Pi panes with it:
+
+```tmux
+set -g @resurrect-processes '"~pi-coding-agent/dist/cli.js->pi-tmux-resume"'
+```
+
+## Behavior
+
+The exact session mapping is written only when Pi runs inside tmux (`$TMUX` and `$TMUX_PANE` set) and the current session has a backing session file. The tws status file is written inside either tmux or Zellij (`$ZELLIJ`, `$ZELLIJ_SESSION_NAME`, and `$ZELLIJ_PANE_ID`), even when the Pi session file is not available yet; `session_file` is `null` until Pi creates one. Final failure-like outcomes are delayed until `agent_settled`, so automatic retries or compaction recovery do not appear as permanent failures.
+
+If the recorded session file no longer exists, the wrapper falls back to `pi --continue` for the pane's working directory.
+
+## Caveats
+
+- Pane keys use window/pane *indexes*: if you reorder windows or panes between save and restore, a mapping can point at a sibling pane's session. It self-heals on the next Pi start.
+
+## License
+
+MIT
+
+## Configuration
+
+Optional environment variables for hardening or local integration:
+
+- `PI_TMUX_SESSION_MAP_STATE_DIR` — override the mapping directory.
+- `PI_TMUX_SESSION_MAP_TWS_CONFIG_DIR` — override the tws config directory.
+- `PI_TMUX_SESSION_MAP_TWS_STATUS_DIR` — override only the tws status directory.
+- `PI_TMUX_SESSION_MAP_TWS_TRIGGER_FILE` — override the tws trigger file.
+- `PI_TMUX_SESSION_MAP_TMUX_BIN` — override the `tmux` binary path.
+- `PI_TMUX_SESSION_MAP_ZELLIJ_BIN` — override the `zellij` binary path.
+- `PI_TMUX_SESSION_MAP_ZELLIJ_STATUS_DIR` — override the Zellij TWS status directory.
+- `PI_TMUX_SESSION_MAP_ZELLIJ_TRIGGER_FILE` — override the Zellij TWS trigger file.
+
+Lifecycle sidecar updates are serialized in-process, mapping and status files are written atomically, and `tmux display-message` is bounded by a short timeout so Pi lifecycle hooks do not hang indefinitely.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "pi-tmux-session-map",
+  "version": "0.3.0",
+  "description": "Map Pi sessions to tmux panes and publish TWS work status for tmux and Zellij.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "tmux",
+    "zellij",
+    "tws",
+    "tmux-resurrect"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/patlux/pi-tmux-session-map.git"
+  },
+  "homepage": "https://github.com/patlux/pi-tmux-session-map#readme",
+  "bugs": {
+    "url": "https://github.com/patlux/pi-tmux-session-map/issues"
+  },
+  "files": [
+    "src",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --experimental-strip-types --test \"test/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit",
+    "benchmark": "node --experimental-strip-types scripts/benchmark-overhead.mjs",
+    "check:installed": "npm run check && node scripts/check-installed-cache.mjs",
+    "check": "npm run typecheck && npm test && npm pack --dry-run"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.80.5"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.5",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/scripts/benchmark-overhead.mjs

@@ -0,0 +1,165 @@
+import { chmod, mkdtemp, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const root = await mkdtemp(join(tmpdir(), "pi-tmux-session-map-bench-"));
+const stateDir = join(root, "state");
+const twsDir = join(root, "tws");
+const statusDir = join(twsDir, "pi-status");
+const ackDir = join(root, "ack");
+const backend = process.env.BENCH_BACKEND === "zellij" ? "zellij" : "tmux";
+const callsFile = join(root, "mux-calls.jsonl");
+const fakeMux = join(root, backend);
+const sessionFile = join(root, "session.jsonl");
+
+await writeFile(sessionFile, "{}\n");
+await writeFile(
+  fakeMux,
+  backend === "tmux"
+    ? `#!/bin/sh\nprintf '%s\\n' "$*" >> "$PI_TMUX_SESSION_MAP_BENCH_CALLS"\nprintf 'bench:1.0\\tbench\\t1\\t0\\n'\n`
+    : `#!/bin/sh\nprintf '%s\\n' "$*" >> "$PI_TMUX_SESSION_MAP_BENCH_CALLS"\nprintf '[{"id":1,"is_plugin":false,"tab_position":1}]\\n'\n`,
+);
+await chmod(fakeMux, 0o755);
+
+Object.assign(process.env, {
+  PI_TMUX_SESSION_MAP_TMUX_BIN: fakeMux,
+  PI_TMUX_SESSION_MAP_ZELLIJ_BIN: fakeMux,
+  PI_TMUX_SESSION_MAP_STATE_DIR: stateDir,
+  PI_TMUX_SESSION_MAP_TWS_CONFIG_DIR: twsDir,
+  PI_TMUX_SESSION_MAP_TWS_STATUS_DIR: statusDir,
+  PI_TMUX_SESSION_MAP_TWS_TRIGGER_FILE: join(twsDir, "agent.trigger"),
+  PI_TMUX_SESSION_MAP_ZELLIJ_STATUS_DIR: statusDir,
+  PI_TMUX_SESSION_MAP_ZELLIJ_TRIGGER_FILE: join(twsDir, "agent.trigger"),
+  PI_TMUX_SESSION_MAP_BENCH_CALLS: callsFile,
+  PI_TMUX_RESTORE_TOKEN: "restore-token",
+  PI_TMUX_EXPECTED_PANE: "bench:1.0",
+  PI_TMUX_EXPECTED_SESSION_ID: "session-id",
+  PI_TMUX_EXPECTED_SESSION_FILE: sessionFile,
+  PI_TMUX_RESTORE_ACK_DIR: ackDir,
+});
+if (backend === "tmux") {
+  process.env.TMUX = join(root, "tmux.sock");
+  process.env.TMUX_PANE = "%1";
+  delete process.env.ZELLIJ;
+  delete process.env.ZELLIJ_SESSION_NAME;
+  delete process.env.ZELLIJ_PANE_ID;
+} else {
+  delete process.env.TMUX;
+  delete process.env.TMUX_PANE;
+  process.env.ZELLIJ = "1";
+  process.env.ZELLIJ_SESSION_NAME = "bench";
+  process.env.ZELLIJ_PANE_ID = "1";
+}
+
+const beforeImport = process.memoryUsage();
+const importStarted = process.hrtime.bigint();
+const { default: extension } = await import("../src/index.ts");
+const importElapsedMs = Number(process.hrtime.bigint() - importStarted) / 1e6;
+const afterImport = process.memoryUsage();
+
+const handlers = new Map();
+extension({
+  on(event, handler) {
+    handlers.set(event, handler);
+  },
+});
+
+const context = {
+  cwd: root,
+  sessionManager: {
+    getSessionFile: () => sessionFile,
+    getSessionName: () => "Optimize overhead",
+    getSessionId: () => "session-id",
+  },
+};
+
+async function snapshot() {
+  const result = new Map();
+  for (const dir of [stateDir, statusDir, twsDir, ackDir]) {
+    let entries;
+    try {
+      entries = await readdir(dir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const path = join(dir, entry);
+      const info = await stat(path, { bigint: true });
+      if (!info.isFile()) {
+        continue;
+      }
+      result.set(path, `${info.ino}:${info.mtimeNs}:${info.size}:${await readFile(path, "utf8")}`);
+    }
+  }
+  return result;
+}
+
+function mutations(before, after) {
+  let count = 0;
+  for (const [path, value] of after) {
+    if (before.get(path) !== value) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+async function invoke(event, payload) {
+  const handler = handlers.get(event);
+  if (!handler) {
+    throw new Error(`missing ${event} handler`);
+  }
+  const before = await snapshot();
+  await handler(payload, context);
+  const after = await snapshot();
+  return mutations(before, after);
+}
+
+const phases = {};
+phases.startup = await invoke("session_start", { reason: "resume" });
+phases.namingUnchanged = await invoke("session_info_changed", { name: "Optimize overhead" });
+phases.agentStart = await invoke("agent_start", {});
+phases.agentEnd = await invoke("agent_end", {
+  messages: [{ role: "assistant", stopReason: "stop" }],
+});
+phases.settlement = await invoke("agent_settled", {});
+phases.shutdown = await invoke("session_shutdown", {});
+
+const muxCalls = (await readFile(callsFile, "utf8")).trim().split("\n").filter(Boolean);
+const baseline = backend === "tmux"
+  ? {
+      muxSubprocesses: 7,
+      filesystemArtifactMutations: {
+        startup: 4,
+        namingUnchanged: 3,
+        agentStart: 3,
+        agentEnd: 3,
+        settlement: 3,
+        shutdown: 0,
+      },
+    }
+  : {
+      muxSubprocesses: 6,
+      filesystemArtifactMutations: {
+        startup: 2,
+        namingUnchanged: 2,
+        agentStart: 2,
+        agentEnd: 2,
+        settlement: 2,
+        shutdown: 0,
+      },
+    };
+
+console.log(JSON.stringify({
+  backend,
+  baselineWithoutCaching: baseline,
+  import: {
+    elapsedMs: importElapsedMs,
+    rssDelta: afterImport.rss - beforeImport.rss,
+    heapUsedDelta: afterImport.heapUsed - beforeImport.heapUsed,
+    moduleLoadList: process.moduleLoadList.length,
+  },
+  muxSubprocesses: muxCalls.length,
+  filesystemArtifactMutations: phases,
+  totalFilesystemArtifactMutations: Object.values(phases).reduce((sum, value) => sum + value, 0),
+}, null, 2));

package/scripts/check-installed-cache.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const files = [
+  "package.json",
+  "README.md",
+  "scripts/check-installed-cache.mjs",
+  "src/index.ts",
+  "src/domain/async-queue.ts",
+  "src/domain/atomic-write.ts",
+  "src/domain/error-reporter.ts",
+  "src/domain/pane-info.ts",
+  "src/domain/pane-key.ts",
+  "src/domain/state.ts",
+  "src/domain/status.ts",
+];
+
+const installedRoot = join(homedir(), ".pi", "agent", "git", "github.com", "patlux", "pi-tmux-session-map");
+
+function hash(path) {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+if (!existsSync(installedRoot)) {
+  console.log(`installed cache not present: ${installedRoot}`);
+  process.exit(0);
+}
+
+const mismatches = [];
+for (const file of files) {
+  const source = join(process.cwd(), file);
+  const installed = join(installedRoot, file);
+  if (!existsSync(installed)) {
+    mismatches.push(`${file}: missing from installed cache`);
+    continue;
+  }
+  if (hash(source) !== hash(installed)) {
+    mismatches.push(`${file}: differs from installed cache`);
+  }
+}
+
+if (mismatches.length > 0) {
+  console.error(`installed cache is stale at ${installedRoot}`);
+  for (const mismatch of mismatches) {
+    console.error(`- ${mismatch}`);
+  }
+  process.exit(1);
+}
+
+console.log(`installed cache matches source: ${installedRoot}`);

package/src/domain/async-queue.ts

@@ -0,0 +1,18 @@
+export type AsyncQueue = {
+  enqueue<T>(operation: () => Promise<T>): Promise<T>;
+};
+
+export function createAsyncQueue(): AsyncQueue {
+  let tail = Promise.resolve();
+
+  return {
+    enqueue<T>(operation: () => Promise<T>): Promise<T> {
+      const run = tail.then(operation, operation);
+      tail = run.then(
+        () => undefined,
+        () => undefined,
+      );
+      return run;
+    },
+  };
+}

package/src/domain/atomic-write.ts

@@ -0,0 +1,193 @@
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
+import { mappedSessionFile } from "./session-mapping.ts";
+
+let atomicWriteCounter = 0;
+
+export type CleanupResult = {
+  scanned: number;
+  removed: number;
+};
+
+export async function ensureDirectory(dir: string, mode = 0o700): Promise<void> {
+  await mkdir(dir, { recursive: true, mode });
+}
+
+function nextTempPath(file: string): string {
+  atomicWriteCounter += 1;
+  return join(dirname(file), `${basename(file)}.tmp-${process.pid}-${atomicWriteCounter}`);
+}
+
+export async function writeAtomic(file: string, data: string, mode: number): Promise<void> {
+  const tmp = nextTempPath(file);
+  let renamed = false;
+  try {
+    await writeFile(tmp, data, { mode });
+    await rename(tmp, file);
+    renamed = true;
+  } finally {
+    if (!renamed) {
+      await rm(tmp, { force: true });
+    }
+  }
+}
+
+export async function cleanupStaleTempFiles(
+  dir: string,
+  maxAgeMs: number,
+  nowMs = Date.now(),
+): Promise<CleanupResult> {
+  if (maxAgeMs <= 0) {
+    return { scanned: 0, removed: 0 };
+  }
+
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return { scanned: 0, removed: 0 };
+  }
+
+  let scanned = 0;
+  let removed = 0;
+  for (const entry of entries) {
+    if (!entry.includes(".tmp-")) {
+      continue;
+    }
+    scanned += 1;
+    const path = join(dir, entry);
+    try {
+      const info = await stat(path);
+      if (nowMs - info.mtimeMs <= maxAgeMs) {
+        continue;
+      }
+      await rm(path, { force: true });
+      removed += 1;
+    } catch {
+      // Best-effort cleanup only.
+    }
+  }
+  return { scanned, removed };
+}
+
+export async function cleanupSupersededStatusFiles(
+  dir: string,
+  currentFileName: string,
+  paneId: string,
+): Promise<CleanupResult> {
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return { scanned: 0, removed: 0 };
+  }
+
+  let scanned = 0;
+  let removed = 0;
+  for (const entry of entries) {
+    if (!entry.endsWith(".json") || entry === currentFileName) {
+      continue;
+    }
+    scanned += 1;
+    const path = join(dir, entry);
+    try {
+      const payload = JSON.parse(await readFile(path, "utf8"));
+      if (payload?.pane_id !== paneId) {
+        continue;
+      }
+      await rm(path, { force: true });
+      removed += 1;
+    } catch {
+      // Best-effort cleanup only; malformed files are ignored here and skipped
+      // by tws when read.
+    }
+  }
+  return { scanned, removed };
+}
+
+export async function cleanupSupersededSessionMappings(
+  dir: string,
+  currentFileName: string,
+  sessionFile: string,
+): Promise<CleanupResult> {
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return { scanned: 0, removed: 0 };
+  }
+
+  let scanned = 0;
+  let removed = 0;
+  for (const entry of entries) {
+    if (!entry.endsWith(".session") || entry === currentFileName) {
+      continue;
+    }
+    scanned += 1;
+    const path = join(dir, entry);
+    try {
+      // A Pi session file is owned by exactly one live pane, so any other
+      // mapping pointing at it is a stale key (window renamed / pane moved) or
+      // a legacy-named duplicate of the current key.
+      const target = mappedSessionFile(await readFile(path, "utf8")) ?? "";
+      if (target !== sessionFile) {
+        continue;
+      }
+      await rm(path, { force: true });
+      removed += 1;
+    } catch {
+      // Best-effort cleanup only.
+    }
+  }
+  return { scanned, removed };
+}
+
+export async function cleanupStaleSessionMappings(
+  dir: string,
+  maxAgeMs: number,
+  nowMs = Date.now(),
+): Promise<CleanupResult> {
+  if (maxAgeMs <= 0) {
+    return { scanned: 0, removed: 0 };
+  }
+
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return { scanned: 0, removed: 0 };
+  }
+
+  let scanned = 0;
+  let removed = 0;
+  for (const entry of entries) {
+    if (!entry.endsWith(".session")) {
+      continue;
+    }
+    scanned += 1;
+    const path = join(dir, entry);
+    try {
+      const info = await stat(path);
+      if (nowMs - info.mtimeMs <= maxAgeMs) {
+        continue;
+      }
+
+      const sessionFile = mappedSessionFile(await readFile(path, "utf8")) ?? "";
+      if (sessionFile !== "") {
+        try {
+          await stat(sessionFile);
+          continue;
+        } catch {
+          // Missing target session file means the mapping is stale.
+        }
+      }
+
+      await rm(path, { force: true });
+      removed += 1;
+    } catch {
+      // Best-effort cleanup only.
+    }
+  }
+  return { scanned, removed };
+}

package/src/domain/error-reporter.ts

@@ -0,0 +1,39 @@
+export type LogError = (message: string) => void;
+
+export type ErrorReporter = {
+  report(prefix: string, error: unknown, nowMs?: number): void;
+};
+
+type ErrorBucket = {
+  lastLoggedAtMs: number;
+  suppressed: number;
+};
+
+export function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function createThrottledErrorReporter(
+  windowMs = 60_000,
+  log: LogError = console.error,
+): ErrorReporter {
+  const buckets = new Map<string, ErrorBucket>();
+
+  return {
+    report(prefix: string, error: unknown, nowMs = Date.now()): void {
+      const message = formatError(error);
+      const key = `${prefix}\n${message}`;
+      const bucket = buckets.get(key);
+
+      if (bucket && nowMs - bucket.lastLoggedAtMs < windowMs) {
+        bucket.suppressed += 1;
+        return;
+      }
+
+      const suppressed = bucket?.suppressed ?? 0;
+      buckets.set(key, { lastLoggedAtMs: nowMs, suppressed: 0 });
+      const suffix = suppressed > 0 ? ` (suppressed ${suppressed} similar error${suppressed === 1 ? "" : "s"})` : "";
+      log(`${prefix}: ${message}${suffix}`);
+    },
+  };
+}