omp-conductor 0.2.0

package/src/escalate.ts

@@ -0,0 +1,265 @@
+/**
+ * Escalation: the one path by which a stuck run reaches someone who can unstick
+ * it. Tier 1 is the orchestrator session's problem, tier 2 is the human's, and
+ * an issue comment is what is left when neither transport is reachable.
+ *
+ * Two rules shape everything here:
+ *
+ *  1. An escalation is never silently dropped. Either a transport delivered it,
+ *     or `escalate()` throws so the dispatcher learns nobody is reachable. A
+ *     swallowed escalation looks exactly like a healthy fleet. Tier 1 is where
+ *     that is hardest: the orchestrator *accepts* an injection minutes before
+ *     its turn settles, so the dedup marker waits for the settlement and a
+ *     late failure falls back to an issue comment for that same escalation.
+ *  2. An escalation is never repeated. The dispatcher re-notices the same
+ *     unroutable issue on every poll, so the store's notification ledger — not
+ *     the loop — is what stops a human being paged every five minutes.
+ *
+ * The bot token is read at send time and never travels further than the request
+ * URL: it is redacted out of every error string this module can produce, since
+ * those strings end up in daemon logs and, on the fallback path, in a public
+ * issue comment.
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { OrchestratorHandle } from "./orchestrator.ts";
+import type { Escalation, ProjectConfig, Store, Tracker } from "./types.ts";
+
+/** Telegram rejects `sendMessage` over 4096 chars; leave room for the marker. */
+const TELEGRAM_TEXT_LIMIT = 4000;
+
+export interface Escalator {
+  escalate(e: Escalation): Promise<void>;
+}
+
+/**
+ * The human-facing text, shared by both transports so a Telegram ping and its
+ * issue-comment fallback are the same message — a human comparing the two
+ * should never have to wonder whether they describe the same event.
+ *
+ * Deliberately plain: Telegram is called without `parse_mode`, because an issue
+ * title containing `_` or `*` would otherwise make Telegram reject the whole
+ * send, turning a cosmetic problem into a lost escalation. Plain text is also
+ * valid Markdown, so the same string renders fine as an issue comment.
+ */
+export function formatEscalation(e: Escalation, project: string): string {
+  const lines = [
+    `omp-conductor · tier ${e.tier} escalation`,
+    `project: ${project}`,
+    `issue: #${e.issue}`,
+    `summary: ${e.summary}`,
+  ];
+  if (e.detail) lines.push(`detail: ${e.detail}`);
+  if (e.runId) lines.push(`run: ${e.runId}`);
+  return lines.join("\n");
+}
+
+/**
+ * `orchestrator` is the tier-1 transport when one is running: a tier-1
+ * escalation is the orchestrator's problem, not the human's, and an injected
+ * prompt is the only form of it that can actually change anything. It stays
+ * optional so a daemon whose orchestrator failed to start — and the unit suite —
+ * still escalate, just to an issue comment.
+ */
+export function createEscalator(
+  p: ProjectConfig,
+  tracker: Tracker,
+  store: Store,
+  orchestrator?: OrchestratorHandle,
+): Escalator {
+  return {
+    async escalate(e: Escalation): Promise<void> {
+      // Stable across daemon restarts: same project, issue, tier and summary is
+      // the same event, however many times the loop rediscovers it.
+      const key = `${p.name}:${e.issue}:${e.tier}:${e.summary}`;
+      if (store.wasNotified(key)) return;
+
+      const text = formatEscalation(e, p.name);
+      const chatId = p.escalation.telegramChatId;
+
+      if (e.tier === 1 && orchestrator) {
+        // Resolves on acceptance, not on an answer, so this does not park the
+        // tick behind a model. A rejection means the injection was never taken
+        // at all: `undefined` falls through to the human-facing path below
+        // rather than losing the escalation — a tier-1 event that reached
+        // nobody is indistinguishable from a healthy fleet.
+        const receipt = await orchestrator.deliver(e, p.name).catch(() => undefined);
+        if (receipt) {
+          /**
+           * This escalation's own late failure, routed to this escalation's own
+           * fallback. The key stays unmarked unless something actually lands:
+           * an unmarked key means the next tick re-escalates, which is the
+           * whole difference between a late escalation and a lost one. Marking
+           * on acceptance is what used to drop it — "notified" written over an
+           * event no human ever read, and nothing left to retry it.
+           */
+          const onTurnFailed = async (cause: unknown): Promise<void> => {
+            if (!p.escalation.fallbackToIssueComment) {
+              warn(
+                `tier 1 escalation on issue #${e.issue} was accepted by the orchestrator but its ` +
+                  `turn failed (${errText(cause)}), and no fallback is configured — left unmarked ` +
+                  `so the next tick retries`,
+              );
+              return;
+            }
+            try {
+              await tracker.comment(e.issue, text);
+              store.markNotified(key);
+            } catch (err) {
+              warn(
+                `tier 1 escalation on issue #${e.issue} failed after acceptance ` +
+                  `(${errText(cause)}) and its issue-comment fallback failed too ` +
+                  `(${errText(err)}) — left unmarked so the next tick retries`,
+              );
+            }
+          };
+
+          // Acceptance is not delivery: the orchestrator's turn for *this*
+          // injection can still fail minutes from now, so the marker waits for
+          // `settled`. Deliberately not awaited — `settled` resolves only when
+          // the model has finished answering, which is exactly the wait the
+          // dispatcher tick must not take.
+          void receipt.settled
+            .then(() => {
+              store.markNotified(key);
+            }, onTurnFailed)
+            .catch(() => {
+              // `markNotified` is the only thing above that can still throw,
+              // and a failing store write must not become an unhandled
+              // rejection in a daemon that has nobody left to throw at.
+            });
+          return;
+        }
+      }
+
+      if (e.tier === 2 && chatId) {
+        const token = readTelegramToken();
+        if (token) {
+          // A send failure throws: `markNotified` stays uncalled so the next
+          // poll retries instead of writing the event off as delivered.
+          // ponytail: no retry/backoff in here — the dispatcher tick is the
+          // retry. Upgrade path is a durable outbox table in the store.
+          await sendTelegram(token, chatId, text);
+          store.markNotified(key);
+          return;
+        }
+      }
+
+      // Tier 1 lands here with no orchestrator, or with one that would not take
+      // the injection; tier 2 lands here when omp-telegram is not installed or
+      // the project never configured a chat id.
+      if (!p.escalation.fallbackToIssueComment) {
+        throw new Error(
+          `no escalation transport configured for project "${p.name}": tier ${e.tier} ` +
+            `escalation on issue #${e.issue} (${e.summary}) could not be delivered — ` +
+            `set escalation.telegramChatId or escalation.fallbackToIssueComment`,
+        );
+      }
+      await tracker.comment(e.issue, text);
+      store.markNotified(key);
+    },
+  };
+}
+
+/**
+ * The tier-1 settlement tail runs after `escalate()` has already returned, so a
+ * failure there has no caller left to throw at. stderr is where it can still be
+ * seen: the daemon's log *is* its stderr, so these land in `daemon.log` beside
+ * every other conductor line.
+ *
+ * ponytail: duplicates daemon.ts's one-line format rather than sharing a
+ * logger. Upgrade path is a `log.ts` both modules import.
+ */
+function warn(msg: string): void {
+  process.stderr.write(`[conductor ${new Date().toISOString()}] ${msg}\n`);
+}
+
+function errText(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+/**
+ * omp-telegram owns `<state dir>/.env`; conductor only borrows the token, so a
+ * user already running that bot gets tier-2 pings with no extra configuration.
+ * Absence is not an error — it just means tier 2 degrades to the fallback.
+ */
+function readTelegramToken(): string | undefined {
+  const override = process.env.OMP_TELEGRAM_STATE_DIR?.trim();
+  const dir = override ? override : join(homedir(), ".omp", "agent", "telegram");
+  let raw: string;
+  try {
+    raw = readFileSync(join(dir, ".env"), "utf8");
+  } catch {
+    return undefined;
+  }
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const match = /^(?:export\s+)?TELEGRAM_BOT_TOKEN\s*=\s*(.*)$/.exec(trimmed);
+    if (!match) continue;
+    let value = (match[1] ?? "").trim();
+    const quote = value[0];
+    if (value.length >= 2 && (quote === '"' || quote === "'") && value.endsWith(quote)) {
+      value = value.slice(1, -1);
+    }
+    if (value) return value;
+  }
+  return undefined;
+}
+
+async function sendTelegram(token: string, chatId: string, text: string): Promise<void> {
+  const url = `https://api.telegram.org/bot${token}/sendMessage`;
+  const body = JSON.stringify({
+    chat_id: chatId,
+    // ponytail: hard truncation rather than splitting across messages — the
+    // tail of a stack trace is rarely the interesting part. Upgrade path is to
+    // attach the overflow as a file via sendDocument.
+    text:
+      text.length > TELEGRAM_TEXT_LIMIT ? `${text.slice(0, TELEGRAM_TEXT_LIMIT)}\n[truncated]` : text,
+    disable_web_page_preview: true,
+  });
+
+  let res: Response;
+  try {
+    res = await fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body });
+  } catch (cause) {
+    // The URL embeds the token, and runtimes love to quote the failing URL back
+    // at you — redact before this string reaches a log or an issue comment.
+    const nested = cause instanceof Error && cause.cause instanceof Error ? `: ${cause.cause.message}` : "";
+    const reason = cause instanceof Error ? `${cause.message}${nested}` : String(cause);
+    throw new Error(`telegram sendMessage failed: ${redact(reason, token)}`);
+  }
+
+  const payload = redact(await res.text().catch(() => ""), token).slice(0, 400);
+  if (!res.ok) {
+    throw new Error(`telegram sendMessage failed: HTTP ${res.status} ${payload}`);
+  }
+
+  // Telegram answers 200 with `{"ok":false}` for plenty of real failures
+  // (kicked from the chat, bad chat_id), so the status alone proves nothing.
+  let ok = false;
+  try {
+    const parsed: unknown = JSON.parse(payload);
+    ok = typeof parsed === "object" && parsed !== null && "ok" in parsed && parsed.ok === true;
+  } catch {
+    ok = false;
+  }
+  if (!ok) {
+    throw new Error(`telegram sendMessage rejected: ${payload}`);
+  }
+}
+
+/**
+ * Strips the bot token — and its secret half, which some proxies log on its
+ * own — out of any string that is about to be thrown, logged or commented.
+ */
+function redact(text: string, token: string): string {
+  let out = token ? text.split(token).join("<redacted>") : text;
+  const colon = token.indexOf(":");
+  const secret = colon >= 0 ? token.slice(colon + 1) : "";
+  if (secret.length >= 8) out = out.split(secret).join("<redacted>");
+  return out;
+}

package/src/lifecycle.ts

@@ -0,0 +1,367 @@
+/**
+ * Lifecycle for the standalone daemon: start it in the background, prove it
+ * came up, stop it, and answer "is it running?" honestly.
+ *
+ * The record under the runtime directory is a hint, never a fact. A pidfile
+ * outlives the process that wrote it — a crash, a reboot, an OOM kill all
+ * leave one behind — and pids are recycled, so the file's *existence* says
+ * nothing. Every read probes the pid before believing the record; a stale
+ * entry is cleared rather than honoured, because the two failures that cost an
+ * operator real time are `start` refusing against a ghost and `status`
+ * reporting a daemon that died hours ago.
+ *
+ * Deliberately free of every other module in this package: nothing here opens
+ * the store, loads the config or talks to `gh`, so `stop` and `status` keep
+ * working when the config is the very thing that is broken.
+ */
+
+import { spawn } from "node:child_process";
+import { chmodSync, closeSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Mirrors `DEFAULT_PORT` in ./daemon.ts. Duplicated rather than imported so
+ * this module stays free of the dispatcher's dependency tree.
+ * // ponytail: two constants that must agree. If a third caller ever needs it,
+ * // move it into ./types.ts and import it in both places.
+ */
+const DEFAULT_PORT = 8787;
+
+/** How long `startDaemon` waits for the first successful `/healthz`. */
+const READY_TIMEOUT_MS = 15_000;
+const READY_POLL_MS = 250;
+
+/** `/healthz` is a local, in-memory answer; a slow one means something is wrong. */
+const HEALTH_TIMEOUT_MS = 1_500;
+
+/** Default grace period between `SIGTERM` and `SIGKILL`. */
+const STOP_TIMEOUT_MS = 10_000;
+
+/** Bytes of `daemon.log` quoted back when the daemon dies during boot. */
+const LOG_TAIL_BYTES = 4_096;
+
+/**
+ * Where the pidfile and the log live. Sits under `~/.omp/run/daemons/` with
+ * the other omp daemons rather than beside the config, because this is
+ * runtime state that is meaningless after a reboot — the config directory is
+ * for things worth keeping.
+ */
+export function runtimeDir(): string {
+  const override = process.env["OMP_CONDUCTOR_RUNTIME_DIR"];
+  if (override !== undefined && override.length > 0) return override;
+  return join(homedir(), ".omp", "run", "daemons", "omp-conductor");
+}
+
+/** What a running daemon was started with, as far as the pidfile knows. */
+export interface DaemonRecord {
+  pid: number;
+  port: number;
+  project?: string;
+  startedAt: number;
+  logFile: string;
+}
+
+function recordPath(): string {
+  return join(runtimeDir(), "daemon.json");
+}
+
+/** Creates the runtime directory 0700; only chmods what this call created. */
+function ensureRuntimeDir(): string {
+  const dir = runtimeDir();
+  const created = mkdirSync(dir, { recursive: true, mode: 0o700 });
+  // mkdir's mode is masked by umask, so fix up what we made; an existing
+  // directory keeps whatever the operator chose for it.
+  if (created !== undefined) chmodSync(dir, 0o700);
+  return dir;
+}
+
+/**
+ * Reads the pidfile. Every failure — absent, unreadable, truncated mid-write,
+ * hand-edited into nonsense — is the same answer: `undefined`. A lifecycle
+ * command that throws because a runtime file is garbage is a lifecycle command
+ * that cannot clean up after itself.
+ */
+export function readRecord(): DaemonRecord | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(recordPath(), "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object") return undefined;
+  const r = parsed as Record<string, unknown>;
+
+  const pid = r["pid"];
+  const port = r["port"];
+  const startedAt = r["startedAt"];
+  const logFile = r["logFile"];
+  const project = r["project"];
+
+  // pid 0 and 1 are never ours: 0 means "this process group" to `kill`, which
+  // would make a corrupt file signal the whole group.
+  if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 1) return undefined;
+  if (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535) return undefined;
+  if (typeof startedAt !== "number" || !Number.isFinite(startedAt)) return undefined;
+  if (typeof logFile !== "string" || logFile.length === 0) return undefined;
+  if (project !== undefined && typeof project !== "string") return undefined;
+
+  return { pid, port, startedAt, logFile, ...(project === undefined ? {} : { project }) };
+}
+
+/**
+ * Writes the pidfile atomically — temp file, then rename — so a reader never
+ * catches a half-written record and concludes the daemon is gone. Mode 0600:
+ * it names a process another user has no business signalling.
+ */
+export function writeRecord(r: DaemonRecord): void {
+  const dir = ensureRuntimeDir();
+  const target = recordPath();
+  const tmp = join(dir, `.daemon.json.${process.pid.toString(36)}.${Date.now().toString(36)}.tmp`);
+  try {
+    writeFileSync(tmp, `${JSON.stringify(r, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, target);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+  chmodSync(target, 0o600);
+}
+
+/** Removes the pidfile. Absent is success — this is how staleness is repaired. */
+export function clearRecord(): void {
+  rmSync(recordPath(), { force: true });
+}
+
+/**
+ * Whether a pid names a live process. Signal 0 performs the permission and
+ * existence checks without delivering anything: `ESRCH` is dead, `EPERM` is
+ * alive but owned by somebody else — still alive, so still a reason not to
+ * start a second daemon.
+ */
+export function isAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * The record, but only when the process it names is actually running. A dead
+ * pid clears the file on the way out, so the next `start` is not blocked by a
+ * daemon that stopped existing three reboots ago.
+ */
+export function livingDaemon(): DaemonRecord | undefined {
+  const rec = readRecord();
+  if (rec === undefined) return undefined;
+  if (isAlive(rec.pid)) return rec;
+  clearRecord();
+  return undefined;
+}
+
+/**
+ * Probes the daemon's own health endpoint. Never throws: a refused connection,
+ * a DNS-less host, a hung socket and a 500 are all just "not healthy", and the
+ * callers of this are the ones responsible for saying so nicely.
+ */
+export async function healthCheck(port: number): Promise<{ ok: boolean; body?: string }> {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/healthz`, {
+      signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS),
+    });
+    const body = (await res.text()).trim();
+    return { ok: res.ok, ...(body.length > 0 ? { body } : {}) };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/**
+ * Starts the daemon in the background and does not return until it answers
+ * `/healthz`.
+ *
+ * Spawning is not starting. A daemon whose config is broken, whose port is
+ * taken or whose database is locked exits within a second of being spawned,
+ * and a `start` that printed "started" for it hands the operator a lie they
+ * only discover when work silently fails to be picked up. So: spawn, watch
+ * both the pid and the endpoint, and fail loudly with the log if either says
+ * no.
+ */
+export async function startDaemon(o: { port?: number; project?: string } = {}): Promise<DaemonRecord> {
+  const running = livingDaemon();
+  if (running !== undefined) {
+    throw new Error(
+      `daemon already running (pid ${running.pid}, port ${running.port}) — ` +
+        `use "omp-conductor restart" to replace it, or "omp-conductor stop" first`,
+    );
+  }
+
+  const port = o.port ?? DEFAULT_PORT;
+  const logFile = join(ensureRuntimeDir(), "daemon.log");
+
+  // Append, never truncate: the previous boot's failure is usually the reason
+  // somebody is running `start` again.
+  const logFd = openSync(logFile, "a", 0o600);
+  let pid: number | undefined;
+  try {
+    const child = spawn(
+      process.execPath,
+      [join(import.meta.dir, "cli.ts"), "daemon", "--port", String(port), ...(o.project === undefined ? [] : ["--project", o.project])],
+      {
+        // The runtime directory is one we know exists and will not be deleted
+        // out from under a long-running process; the daemon itself resolves
+        // every path from the config, so cwd is only about not holding a
+        // stale directory open.
+        cwd: runtimeDir(),
+        detached: true,
+        stdio: ["ignore", logFd, logFd],
+      },
+    );
+    child.once("error", (err) => {
+      process.stderr.write(`omp-conductor: daemon process failed: ${err.message}\n`);
+    });
+    // Detach from the parent's event loop and process group so the daemon
+    // outlives the shell that started it.
+    child.unref();
+    pid = child.pid;
+  } finally {
+    closeSync(logFd);
+  }
+
+  if (pid === undefined) throw new Error(`could not spawn the daemon; see ${logFile}`);
+
+  const record: DaemonRecord = {
+    pid,
+    port,
+    startedAt: Date.now(),
+    logFile,
+    ...(o.project === undefined ? {} : { project: o.project }),
+  };
+  // Written before the wait so a concurrent `status` sees a booting daemon
+  // rather than nothing at all.
+  writeRecord(record);
+
+  const deadline = Date.now() + READY_TIMEOUT_MS;
+  for (;;) {
+    // Liveness first. If the child is gone, a healthy answer on that port came
+    // from somebody else's server, and reporting it as ours would be worse
+    // than reporting nothing.
+    if (!isAlive(pid)) {
+      clearRecord();
+      throw new Error(`daemon exited during startup${tailLog(logFile)}`);
+    }
+    const health = await healthCheck(port);
+    if (health.ok) return record;
+    if (Date.now() >= deadline) break;
+    await sleep(READY_POLL_MS);
+  }
+
+  // Alive but never healthy: a wedged process is not a running daemon, and
+  // leaving it behind would block the next `start` for no benefit.
+  await terminate(pid, STOP_TIMEOUT_MS);
+  clearRecord();
+  throw new Error(
+    `daemon did not answer http://127.0.0.1:${port}/healthz within ${Math.round(READY_TIMEOUT_MS / 1000)}s${tailLog(logFile)}`,
+  );
+}
+
+/**
+ * Stops the daemon: `SIGTERM`, wait, then `SIGKILL`.
+ *
+ * `SIGTERM` asks the loop to finish the tick it is on, and a tick that has a
+ * worker in flight can run for the worker's whole wall clock. The grace period
+ * is therefore a deadline, not a promise of a clean drain.
+ * // ponytail: no way to say "stop when the current worker lands". If that
+ * // matters, take a `--timeout` on the CLI verb, or poll `activeRuns` before
+ * // escalating.
+ */
+export async function stopDaemon(o: { timeoutMs?: number } = {}): Promise<"stopped" | "not-running"> {
+  const rec = livingDaemon();
+  if (rec === undefined) {
+    // `livingDaemon` already cleared a stale file; this covers the unparseable
+    // one it refused to read.
+    clearRecord();
+    return "not-running";
+  }
+  const gone = await terminate(rec.pid, o.timeoutMs ?? STOP_TIMEOUT_MS);
+  if (!gone) {
+    // The record stays: something is still holding that pid, and forgetting
+    // about it would let the next `start` bind a port that is already taken.
+    throw new Error(`daemon pid ${rec.pid} survived SIGTERM and SIGKILL — it may belong to another user`);
+  }
+  clearRecord();
+  return "stopped";
+}
+
+// ---------------------------------------------------------------------------
+// internals
+// ---------------------------------------------------------------------------
+
+function sleep(ms: number): Promise<void> {
+  return new Promise<void>((resolve) => {
+    const t = setTimeout(resolve, ms);
+    t.unref?.();
+  });
+}
+
+/** `SIGTERM`, poll until dead, then `SIGKILL`. Returns whether the pid is gone. */
+async function terminate(pid: number, timeoutMs: number): Promise<boolean> {
+  if (!isAlive(pid)) return true;
+  if (!signal(pid, "SIGTERM")) return !isAlive(pid);
+
+  const deadline = Date.now() + timeoutMs;
+  while (isAlive(pid) && Date.now() < deadline) await sleep(100);
+  if (!isAlive(pid)) return true;
+
+  signal(pid, "SIGKILL");
+  // SIGKILL is not instant — the kernel still has to reap it — so give the
+  // pid a moment to disappear before anyone reads liveness again.
+  const hardDeadline = Date.now() + 2_000;
+  while (isAlive(pid) && Date.now() < hardDeadline) await sleep(50);
+  return !isAlive(pid);
+}
+
+/** Sends a signal, treating "already gone" as success. Returns false if the send failed. */
+function signal(pid: number, sig: NodeJS.Signals): boolean {
+  try {
+    process.kill(pid, sig);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === "ESRCH";
+  }
+}
+
+/**
+ * The tail of the daemon log, formatted for an error message. Reads the last
+ * few KB by offset rather than the whole file, because the log is append-only
+ * across every boot and can be arbitrarily long.
+ */
+function tailLog(path: string): string {
+  let text: string;
+  let truncated = false;
+  try {
+    const size = statSync(path).size;
+    const want = Math.min(size, LOG_TAIL_BYTES);
+    if (want === 0) return ` — nothing was written to ${path}`;
+    truncated = want < size;
+    const fd = openSync(path, "r");
+    try {
+      const buf = Buffer.allocUnsafe(want);
+      const read = readSync(fd, buf, 0, want, size - want);
+      text = buf.subarray(0, read).toString("utf8");
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    return ` — see ${path}`;
+  }
+  // Reading from an offset lands mid-line; that fragment is an artefact, not
+  // output. Reading the whole file does not, so keep line one in that case.
+  const all = text.split("\n");
+  const lines = (truncated ? all.slice(1) : all).filter((l) => l.trim().length > 0);
+  if (lines.length === 0) return ` — see ${path}`;
+  return `:\n${lines.slice(-10).join("\n")}\n(full log: ${path})`;
+}