amicus 4.8.1 → 4.9.0

package/src/utils/engine-log-parse.js

@@ -0,0 +1,289 @@
+/**
+ * @module utils/engine-log-parse
+ * Line-shape parsing for the engine log: level, session, message.
+ *
+ * Is this line an ERROR, is it about THIS session, and where does its human
+ * message begin.
+ *
+ * EXTRACTED from src/utils/engine-log.js (v4.9 W10 round 2). That module is the
+ * I/O half — candidate dirs, mtime order, the scan budget and its memo, with the
+ * bounded tail reads themselves in `./engine-log-tail.js` since PR #206;
+ * everything here is a pure function of ONE line, which is where every
+ * correlation and truncation finding has landed since. `engine-log.js`
+ * re-exports all of it, so a consumer still has one import site.
+ *
+ * TWO LINE FORMATS are in the wild and both are matched:
+ *   logfmt   (1.17.x): `… level=ERROR … session.id=ses_<id> error=<msg>`
+ *   columnar (1.2.x):  `ERROR <iso> +Nms service=… id=ses_<id> <msg>`
+ * A session-identity FIELD is the correlation key in both — never a bare
+ * mention (round-3 review A1; see lineIsAboutSession).
+ *
+ * WHAT IS NOT HERE: the excerpt sanitizer, which moved to `./text-sanitize.js`
+ * in round 3 when `engine-skew.js` became its second caller. The TOKENIZER
+ * stayed: logfmt/columnar token shapes are this module's domain, and all three
+ * of its consumers live in this file.
+ *
+ * PURE: no I/O, no throwing paths that a caller has to guard.
+ */
+
+'use strict';
+
+// The excerpt sanitizer MOVED to ./text-sanitize.js (round 3) once `engine-skew`
+// became its second caller — see that module's docblock. Re-exported below, as
+// the same function object, so every existing import site stays valid.
+const { collapseExcerpt, MAX_EXCERPT_CHARS } = require('./text-sanitize');
+
+/** A `key=value` token — the structural shape in both formats. */
+const PAIR_TOKEN = /^[\w.[\]-]+=/;
+/**
+ * The columnar header run before the message: `ERROR <iso> +Nms`. A LEVEL word,
+ * an ISO date, or a SIGNED duration — and nothing else.
+ *
+ * A bare number is deliberately NOT header-shaped (round-2 review B5): the
+ * header run ends the prefix on a pairless line, so anything it accepts is
+ * something it EATS — the older `[+-]?\d[\w.:+-]*` would have swallowed the `3`
+ * of `3 retries exhausted`.
+ */
+const HEADER_TOKEN = /^(?:[A-Z]+|\d{4}-\d\d-\d\d[\w:.+-]*|[+-]\d[\w.]*)$/;
+
+/**
+ * Which format is this line? A columnar line OPENS with a bare level token; a
+ * logfmt line opens with a `key=value`.
+ *
+ * Round-2 review A2: the shape decides, NOT the presence of the substring
+ * `error=` somewhere in the text. Running the logfmt extractor first on every
+ * line cut columnar messages that merely CONTAINED `error=` — measured before
+ * the fix, `… id=ses_… retry limit reached, error=true was set in config` came
+ * back as `true was set in config`.
+ */
+function isColumnarLine(line) {
+  return /^\s*[A-Z]+(\s|$)/.test(line);
+}
+
+/**
+ * The line's tokens: whitespace-separated, except that a QUOTED value
+ * (`key="…"`) holds together however much whitespace it contains, backslash
+ * escapes honoured so an embedded `\"` does not end it (round-2 review B5).
+ *
+ * ONE DIALECT, THREE CONSUMERS (round-3 reviews B2 and C5). "Where does a field
+ * end and prose begin" had three substring answers, each wrong somewhere: a
+ * whitespace split read `error="lost session.id=<them> mid-write"` as two
+ * fields, the second a session identity; the `error=` extractor matched that
+ * substring anywhere, so `msg="db error=timeout"` became the message. One
+ * tokenizer, and all three agree by construction.
+ *
+ * `at` is the token's offset in `line` — what lets a caller slice the ORIGINAL
+ * text rather than re-join tokens and lose its spacing.
+ * @param {string} line
+ * @returns {{text: string, at: number}[]}
+ */
+function tokenize(line) {
+  const text = String(line);
+  const tokens = [];
+  let i = 0;
+  while (i < text.length) {
+    if (/\s/.test(text[i])) { i += 1; continue; }
+    const at = i;
+    let quoted = false;
+    while (i < text.length && (quoted || !/\s/.test(text[i]))) {
+      if (quoted && text[i] === '\\') { i += 2; continue; }
+      if (text[i] === '"') { quoted = !quoted; }
+      i += 1;
+    }
+    tokens.push({ text: text.slice(at, i), at });
+  }
+  return tokens;
+}
+
+/**
+ * The index of the STRUCTURAL RUN's last token, or -1 when the line opens with
+ * prose. The run is `ERROR <iso> +Nms service=… id=ses_…` at a columnar line's
+ * start, and the whole `key=value` sequence of a logfmt line.
+ *
+ * Deliberately not "up to the LAST key=value on the line" (W10 round-1 review
+ * B2): an engine error naming a setting mid-sentence — `could not parse foo=bar
+ * in the config` — would lose everything before it. Once the run ends, the rest
+ * of the line is text, `=` and all.
+ *
+ * HEADER tokens count only until the first pair; after one, an all-caps or
+ * numeric word is message text (`… id=ses_x FATAL disk error`). But they do
+ * ADVANCE the run, letting a PAIRLESS columnar line shed its header (round-2 B5).
+ * @param {{text: string, at: number}[]} tokens
+ * @returns {number}
+ */
+function structuralRunEnd(tokens) {
+  let runEnd = -1;
+  let seenPair = false;
+  for (let i = 0; i < tokens.length; i++) {
+    if (PAIR_TOKEN.test(tokens[i].text)) { seenPair = true; runEnd = i; continue; }
+    if (!seenPair && HEADER_TOKEN.test(tokens[i].text)) { runEnd = i; continue; }
+    break;
+  }
+  return runEnd;
+}
+
+/** A leading QUOTED run's content, escapes decoded by `tokenize`'s own rule. */
+function unquote(raw) {
+  let out = '';
+  for (let i = 1; i < raw.length; i++) {
+    if (raw[i] === '\\' && i + 1 < raw.length) { out += raw[i + 1]; i += 1; continue; }
+    if (raw[i] === '"') { break; }
+    out += raw[i];
+  }
+  return out;
+}
+
+/**
+ * The logfmt `error=` value: quoted content when quoted, else the rest of the
+ * line, since an unquoted engine error is a sentence, not one token, and is
+ * conventionally last. Null when the line has no such key.
+ *
+ * A TOP-LEVEL key only (round-3 review C5). The old match was a substring sweep,
+ * so an `error=` inside another field's quoted value was taken as the message —
+ * MEASURED before the fix, `… msg="db error=timeout" error=connection refused`
+ * returned `timeout" error=connection refused`. Tokenizing first makes the
+ * boundary structural instead of textual.
+ */
+function errorFieldValue(line) {
+  const text = String(line);
+  for (const token of tokenize(text)) {
+    if (!token.text.startsWith('error=')) { continue; }
+    const value = token.text.slice('error='.length);
+    return value.startsWith('"') ? unquote(value) : text.slice(token.at + 'error='.length);
+  }
+  return null;
+}
+
+/**
+ * Everything after the structural run — exactly where a columnar message
+ * begins. With no structural token at all the whole line comes back, so an
+ * unrecognized future format degrades to "slightly noisy" rather than silence.
+ */
+function afterStructuralRun(line) {
+  const text = String(line);
+  const tokens = tokenize(text);
+  const runEnd = structuralRunEnd(tokens);
+  if (runEnd === -1) { return text.trim(); }
+  const next = tokens[runEnd + 1];
+  return next ? text.slice(next.at).trim() : '';
+}
+
+/** The human part of an ERROR line, chosen by the line's SHAPE. */
+function extractMessage(line) {
+  if (!isColumnarLine(line)) {
+    const value = errorFieldValue(line);
+    if (value !== null) { return value; }
+  }
+  return afterStructuralRun(line);
+}
+
+/** A token character. MEASURED (2026-08-25) over this machine's own engine logs:
+ *  369 distinct ids, each exactly `ses_` + 26 characters, every one drawn from
+ *  `[A-Za-z0-9]` — no `-`, `_`, or `.`. `_` counts here anyway: an id cannot
+ *  contain one, so a `_` beside a match means the token is longer than an id. */
+function isTokenCharCode(code) {
+  return (code >= 48 && code <= 57) || (code >= 65 && code <= 90)
+    || (code >= 97 && code <= 122) || code === 95;
+}
+
+/**
+ * Does `text` mention session `needle` as a WHOLE id?
+ *
+ * `String.includes` is wrong here: ids share prefixes, so `ses_abc` matches
+ * `ses_abc123`'s line and a leg would quote a stranger's failure as its own
+ * (W10 round-1 review A1). BOTH edges are anchored — round-1 anchored only the
+ * right one, so `Xses_abc` and `prev_ses_abc` still matched (round-2 review B6).
+ * A char-code boundary test rather than a regex: this runs per candidate field
+ * of every ERROR line in a tail read, once per dead seat in a wave.
+ */
+function mentionsSession(line, needle) {
+  let from = 0;
+  for (;;) {
+    const at = line.indexOf(needle, from);
+    if (at === -1) { return false; }
+    const after = at + needle.length;
+    if ((at === 0 || !isTokenCharCode(line.charCodeAt(at - 1)))
+      && (after >= line.length || !isTokenCharCode(line.charCodeAt(after)))) { return true; }
+    from = at + 1;
+  }
+}
+
+/** The field names that carry SESSION identity, in both formats. Exact
+ *  spellings: `parent.id` and `message.id` also end in `id` and name something
+ *  else entirely; treating them as identity hands us a foreign line. */
+const SESSION_FIELDS = new Set(['id', 'session', 'sessions', 'sessionid', 'session.id']);
+const FIELD_TOKEN = /^([\w.[\]-]+)=(.*)$/;
+
+/**
+ * ERROR level in either format: columnar's leading `ERROR` word, or logfmt's
+ * `level=ERROR` read as a TOP-LEVEL FIELD of the structural run.
+ *
+ * A FIELD, not a substring (#201 final-round tail C1). The old logfmt half was
+ * `/(^|\s)level=ERROR(\s|$)/` over the raw line — the last substring sweep left
+ * in this module, the shape rounds 2 and 3 replaced in the format test (A2),
+ * the `error=` extractor (C5) and the ownership scan (B2). A quoted value that
+ * merely CONTAINS the delimited text promoted the whole line, and an INFO line
+ * is ordinary prose about a retry: MEASURED before the fix, `… level=INFO …
+ * msg="upstream logged level=ERROR moments ago" fixture fell back to the cache`
+ * was reported as the leg's cause of death as `fixture fell back to the cache`.
+ * The same run bound applies as everywhere else: past the fields, `level=ERROR`
+ * is text a human wrote, `=` and all.
+ *
+ * The substring is still the FIRST test, just no longer the LAST word: it is a
+ * necessary condition, so a line without it rejects on one `indexOf` and never
+ * tokenizes — which is what keeps this the cheap half of the pair in
+ * `engine-log-tail.js :: newestExcerptInFile`.
+ */
+function isErrorLine(line) {
+  const text = String(line);
+  if (/^\s*ERROR\b/.test(text)) { return true; }
+  if (text.indexOf('level=ERROR') === -1) { return false; }
+  const tokens = tokenize(text);
+  const runEnd = structuralRunEnd(tokens);
+  for (let i = 0; i <= runEnd; i++) {
+    const field = FIELD_TOKEN.exec(tokens[i].text);
+    if (field && field[1].toLowerCase() === 'level' && field[2] === 'ERROR') { return true; }
+  }
+  return false;
+}
+
+/**
+ * Is this line ABOUT session `needle` — not merely one that mentions it?
+ *
+ * OWNERSHIP COMES ONLY FROM A SESSION-IDENTITY FIELD IN THE STRUCTURAL RUN. A
+ * line carrying no such field is NEVER attributed — no exception, no fallback.
+ *
+ * Round 2 established the first half (a whole-token MENTION is not ownership:
+ * `… session.id=ses_other parent.id=<us> error="…"` was returning another
+ * session's failure as this leg's own) but kept a bare-mention fallback for
+ * lines with no session field, and scanned fields by splitting on whitespace.
+ * Round-3 reviews A1+B2 measured both leaks: a foreign line's FREE TEXT still
+ * decided ownership whenever the line named no session in a field, and a
+ * `session.id=`-shaped token INSIDE free text — a storage path, an `error=`
+ * sentence, another field's quoted value — was read as a field and voted.
+ *
+ * PRECISION OVER RECALL is the lead's ruling, and the trade is cheap one way
+ * only: a missed attribution falls through to the byte-identical message this
+ * module's whole miss path is pinned on (and the skew clause is independent of
+ * it), while a wrong one states a stranger's failure as this leg's own.
+ */
+function lineIsAboutSession(line, needle) {
+  const tokens = tokenize(line);
+  const runEnd = structuralRunEnd(tokens);
+  let ours = false;
+  for (let i = 0; i <= runEnd; i++) {
+    const field = FIELD_TOKEN.exec(tokens[i].text);
+    if (!field || !SESSION_FIELDS.has(field[1].toLowerCase())) { continue; }
+    if (mentionsSession(field[2], needle)) { ours = true; }
+  }
+  return ours;
+}
+
+module.exports = {
+  isErrorLine,
+  extractMessage,
+  collapseExcerpt,
+  mentionsSession,
+  lineIsAboutSession,
+  MAX_EXCERPT_CHARS,
+};

package/src/utils/engine-log-tail.js

@@ -0,0 +1,114 @@
+/**
+ * @module utils/engine-log-tail
+ * One engine-log FILE: read its tail, find the newest usable excerpt in it.
+ *
+ * Extracted from `./engine-log.js` in PR #206's fix round, for the reason that
+ * file's two earlier extractions happened (`./engine-log-parse.js` in W10 round
+ * 2, `./text-sanitize.js` in round 3): it sat at exactly 300/300 lines, and the
+ * A1+B2 fix — a MISS may not be served from the warm scan memo — needs both new
+ * code and the disclosure of its residual. A same-line-count swap would have
+ * had to pay for those by deleting prose three review rounds argued for, so the
+ * stable neighbour moved instead and moved UNCHANGED.
+ *
+ * THE SPLIT. `./engine-log.js` decides WHICH files to open and in what order,
+ * and holds the total byte budget one lookup may spend. This file spends it,
+ * one file at a time: how much of a file to read, how to decode it safely, and
+ * which line in it answers. The line SHAPE rules — what an ERROR line is, which
+ * line is about a session, where its message begins — are `./engine-log-parse.js`.
+ *
+ * BEST-EFFORT, like its caller: an unreadable file yields null and no bytes
+ * charged, never a throw. A log read must not become the failure it reports on.
+ */
+
+'use strict';
+
+const {
+  isErrorLine, extractMessage, collapseExcerpt, lineIsAboutSession,
+} = require('./engine-log-parse');
+
+/** Read at most the last 256 KiB of any candidate. The legacy single file is
+ *  2.4 MB on the reference machine, and this runs on a leg's death path (often
+ *  once per dead seat in a wave) — whole-file reads are not an acceptable cost
+ *  for a diagnostic nicety. */
+const MAX_TAIL_BYTES = 256 * 1024;
+
+/** Read the last MAX_TAIL_BYTES of a file, or `budget` bytes if that is less.
+ *  When the read started mid-file the first line is dropped: it is a fragment,
+ *  and slicing at a byte offset can also land inside a multi-byte UTF-8
+ *  sequence. `bytes` is what the read actually spent, so the caller can charge
+ *  it against its own scan budget (`engine-log.js :: MAX_SCAN_BYTES`).
+ *  @returns {{text: string, bytes: number}} */
+function readTail(file, fsImpl, budget) {
+  const size = fsImpl.statSync(file).size;
+  const cap = Math.min(MAX_TAIL_BYTES, Math.max(0, budget));
+  const start = Math.max(0, size - cap);
+  const length = Math.min(size, cap);
+  if (!(length > 0)) { return { text: '', bytes: 0 }; }
+  const fd = fsImpl.openSync(file, 'r');
+  let text;
+  try {
+    const buf = Buffer.alloc(length);
+    // Decode only what was actually read: a short read would otherwise decode
+    // the allocation's zero-fill as NUL characters, which no whitespace
+    // collapse strips and which would ride into the excerpt.
+    const bytesRead = fsImpl.readSync(fd, buf, 0, length, start);
+    text = buf.toString('utf-8', 0, Number.isFinite(bytesRead) ? bytesRead : length);
+  } finally {
+    try { fsImpl.closeSync(fd); } catch (_e) { /* best effort */ }
+  }
+  if (start > 0) {
+    const firstBreak = text.indexOf('\n');
+    text = firstBreak === -1 ? '' : text.slice(firstBreak + 1);
+  }
+  return { text, bytes: length };
+}
+
+/**
+ * The NEWEST usable excerpt in this file for `needle`. Logs are append-ordered,
+ * so scanning backwards reaches the newest match first — and the newest is the
+ * one that killed the leg (a session can log several errors while it degrades).
+ *
+ * ABOUT, not merely mentioning (round-2 review A1, tightened in round 3): a line
+ * whose structural session field names someone else is skipped even when our id
+ * appears elsewhere on it, and the walk continues to an older line that is
+ * really ours.
+ *
+ * USABLE, not merely matching (round-3 review C4). A matching line whose message
+ * part is empty used to end the file's scan, so the fallthrough skipped to the
+ * next FILE and never reached the older line in THIS one that actually says what
+ * happened — and those two are typically neighbours, the real failure followed by
+ * a terse message-less line as the session tears down. The excerpt is therefore
+ * built here, inside the walk, and an empty one just keeps walking. It costs no
+ * extra I/O: the tail is already in memory, so the byte budget is unchanged.
+ *
+ * `isErrorLine` runs FIRST because it is the cheaper test — it rejects a
+ * non-ERROR line on one `indexOf` and tokenizes only when the level substring
+ * is actually present (#201 tail C1), while ownership tokenizes every line it
+ * is handed. Only ERROR lines can ever answer.
+ *
+ * `tails` is the caller's memo (#201 tail C2); a cached entry carries the bytes
+ * its ORIGINAL read spent, charged again here, so the budget accounts
+ * identically warm or cold and both walk the same files to the same stop. A
+ * FAILED read is deliberately not cached — an unreadable file is a transient.
+ * @returns {{excerpt: string|null, bytes: number}} `bytes` is the budget spent.
+ */
+function newestExcerptInFile(file, needle, fsImpl, budget, tails) {
+  let read = tails && tails.get(file);
+  if (!read) {
+    try { read = readTail(file, fsImpl, budget); } catch (_e) { return { excerpt: null, bytes: 0 }; }
+    if (tails) { tails.set(file, read); }
+  }
+  const lines = read.text.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (!isErrorLine(line) || !lineIsAboutSession(line, needle)) { continue; }
+    const excerpt = collapseExcerpt(extractMessage(line));
+    if (excerpt) { return { excerpt, bytes: read.bytes }; }
+  }
+  return { excerpt: null, bytes: read.bytes };
+}
+
+// `MAX_TAIL_BYTES` and `readTail` stay internal: nothing outside this file
+// consumes either, and a constant in a `Key Exports` cell reads as a function
+// it is not (engine-log.js's rule).
+module.exports = { newestExcerptInFile };

package/src/utils/engine-log.js

@@ -0,0 +1,250 @@
+/**
+ * @module utils/engine-log
+ * Resolve the OpenCode engine's own error line for one session.
+ *
+ * A leg that dies silent can then quote the truth instead of a guess.
+ *
+ * WHY (#133). The NO_OUTPUT_BACKSTOP message reports only what the deadline
+ * observed — deliberately, since the guess it replaced ("likely a listed-but-
+ * not-serving model or a dead endpoint") sent 30 minutes of a real outage's
+ * debugging at model ids and API keys. But the engine had written its real
+ * failure to its own log at the exact timestamp of every dead session the
+ * whole time. Reporting silence while the cause sits on disk unread is the
+ * "correct but SILENT degrade" the product principle forbids as hard as a
+ * crash. This module reads it; src/headless.js appends it to the reason.
+ *
+ * MEASURED (2026-08-25). The long-quoted single-file premise —
+ * `~/.local/share/opencode/log/opencode.log` — is STALE. The current engine
+ * writes ONE timestamped file PER PROCESS (`2026-08-25T185532.log`), and the
+ * two schemes coexist across machines: the reference machine still carries a
+ * 2.4 MB legacy `opencode.log`, while this one holds 12 timestamped files and
+ * NO `opencode.log` at all. A resolver that opened only the legacy name would
+ * therefore return nothing on a current install — silently, forever.
+ *
+ * THE TWO LINE FORMATS (logfmt at 1.17.x, columnar at 1.2.x), which line is an
+ * ERROR, which line is about this session, and where its message begins all
+ * live in `./engine-log-parse.js` — extracted in W10 round 2 and re-exported
+ * below. Reading ONE file's tail and finding the newest usable line in it is
+ * `./engine-log-tail.js`, extracted in PR #206's fix round. This file is what
+ * is left of the I/O half: which files to open, in what order, the total bytes
+ * one lookup may spend — and how long one scan is reused (#201 tail C2).
+ *
+ * THAT REUSE SERVES HITS ONLY (PR #206 round-1 A1+B2). A MISS re-lists and
+ * re-reads before it is believed, because the engine writes a leg's error WHEN
+ * that leg dies — possibly after the cached scan, possibly into a file it has
+ * only just rolled over to — so an absence in a previous call's listing and
+ * tails is not an absence on disk. The accepted residual runs the other way,
+ * and round 3 states its REAL bound. What a warm HIT serves is the
+ * newest-for-THIS-SESSION line as of the moment the slot was built, so the
+ * TTL bounds the MISSED WINDOW — lines written in the last ≤10 seconds — and
+ * bounds nothing about the AGE of what is served: the GAP between the quoted
+ * line and the line it misses is unbounded, because the cached answer can be
+ * arbitrarily old and still have been newest when it was read. A minutes-old
+ * error can therefore be quoted while a fatal line written two seconds ago
+ * sits unread. What it quotes is still a genuine ERROR line for THIS leg,
+ * which is a true diagnostic; suppression — reporting silence while the cause
+ * sits on disk unread — is the failure this module exists to end.
+ *
+ * EVERYTHING HERE IS BEST-EFFORT: every path returns null rather than
+ * throwing. A log read must never break a leg's death report — the report is
+ * the product; the excerpt is a bonus on top of it.
+ */
+
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const {
+  isErrorLine, extractMessage, collapseExcerpt, mentionsSession, lineIsAboutSession,
+} = require('./engine-log-parse');
+const { newestExcerptInFile } = require('./engine-log-tail');
+
+/**
+ * The TOTAL tail bytes one lookup may read across all candidates — 8 full tail
+ * reads' worth (`engine-log-tail.js :: MAX_TAIL_BYTES`, 256 KiB). The bound that
+ * used to sit here was "the 3 newest files by mtime", and it broke exactly where
+ * this module matters most (round-2 review
+ * B1): the engine writes one log PER PROCESS, so in a mass-death wave every
+ * seat has its own file and the SURVIVORS keep writing — the dead leg's own log
+ * gets pushed out of the top 3 by the legs that did NOT die. A byte budget
+ * bounds the same cost (I/O, not file handles) without letting the answer's
+ * position in the mtime order decide whether it is ever read.
+ */
+const MAX_SCAN_BYTES = 2 * 1024 * 1024;
+/**
+ * How long ONE scan (the listing plus the tails it read) is reused (#201 tail
+ * C2). MEASURED, not guessed: this runs on a leg's DEATH PATH and legs die in
+ * WAVES — a wave's seats launch together, so their backstop deadlines land
+ * together, each observed on a 2-second poll tick (`POLL_INTERVAL_MS`,
+ * src/headless.js:80). Ten seconds is five of those ticks: wide enough for a
+ * whole wave to share one scan, short enough that a LATER failure gets a
+ * genuinely fresh read instead of a stale answer about an older death. Not a
+ * knob — any second-granularity value trades the same way.
+ */
+const SCAN_CACHE_TTL_MS = 10 * 1000;
+const scanCaches = new WeakMap();
+
+/**
+ * The live scan slot — `{key, at, files, tails}` — freshly reset when absent,
+ * stale, or built for other dirs. Bounded BY CONSTRUCTION: ONE slot per fs
+ * impl, holding one listing and one scan's worth of tails (MAX_SCAN_BYTES);
+ * another dir set evicts rather than accumulating. Keyed by the fs IMPL:
+ * production always passes the same `require('fs')` object, so a wave of seats
+ * shares one slot, while a test seam (or a hostile one) is a fresh object with
+ * a slot of its own — the fs seam is this module's whole testability and a
+ * shared cache would quietly break it. `engineErrorForSession` also DROPS the
+ * live slot behind a MISS, so the pass after one builds a new one.
+ */
+function scanSlot(fsImpl, key) {
+  const now = Date.now();
+  let slot = scanCaches.get(fsImpl);
+  if (!slot || slot.key !== key || now - slot.at >= SCAN_CACHE_TTL_MS) {
+    slot = { key, at: now, files: null, tails: new Map() };
+    scanCaches.set(fsImpl, slot);
+  }
+  return slot;
+}
+
+/**
+ * Ordered, de-duplicated candidate engine-log DIRECTORIES, most specific first
+ * — the same order as `src/utils/auth-json.js :: authJsonCandidates` (same
+ * engine, same data root), whose comment records the measurement that on
+ * Windows OpenCode still writes to `~/.local/share/opencode`, which is why the
+ * `.local/share` path stays FIRST after XDG rather than APPDATA. Order is a
+ * listing order, not a precedence: all of them are searched (see
+ * existingEngineLogDirs), and mtime decides which file answers.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string[]}
+ */
+function engineLogDirCandidates(env = process.env) {
+  const home = os.homedir();
+  const candidates = [];
+  if (env.XDG_DATA_HOME) { candidates.push(path.join(env.XDG_DATA_HOME, 'opencode', 'log')); }
+  candidates.push(path.join(home, '.local', 'share', 'opencode', 'log'));
+  if (process.platform === 'win32') {
+    const appData = env.APPDATA || path.join(home, 'AppData', 'Roaming');
+    candidates.push(path.join(appData, 'opencode', 'log'));
+  }
+  return [...new Set(candidates)];
+}
+
+/**
+ * EVERY candidate directory that exists, in candidate order — NOT "the first
+ * one that exists" (W10 round-1 review A2). The dirs are alternative homes for
+ * the SAME engine's logs, and existence says nothing about which one the live
+ * engine writes to: a stale `$XDG_DATA_HOME`, or an empty dir left by a
+ * previous install, would otherwise shadow the dir holding the answer — this
+ * module's own silent-forever miss, one layer up from where it was fixed.
+ * @returns {string[]}
+ */
+function existingEngineLogDirs(env, fsImpl) {
+  const dirs = [];
+  for (const dir of engineLogDirCandidates(env)) {
+    try { if (fsImpl.existsSync(dir)) { dirs.push(dir); } } catch (_e) { /* try the next */ }
+  }
+  return dirs;
+}
+
+/**
+ * EVERY `*.log` across all candidate dirs, newest first by mtime. The order is
+ * taken over the UNION, not per directory, so which dir a file sits in never
+ * outranks how recently the engine wrote to it.
+ *
+ * Not truncated here: the scan reads down this list until it finds a match or
+ * spends MAX_SCAN_BYTES (see engineErrorForSession). Listing is a stat per
+ * file; only the READS are the cost worth bounding. This also retires the
+ * legacy `opencode.log`'s reserved slot — on a single-file machine it is the
+ * newest file anyway (it is written continuously), and on a migrated machine it
+ * is stale and simply sorts last, which is the same answer the reserved slot
+ * was there to produce.
+ * @param {string[]} dirs
+ * @returns {string[]} absolute paths, newest first
+ */
+function candidateLogFiles(dirs, fsImpl) {
+  const found = [];
+  for (const dir of dirs) {
+    let names;
+    try { names = fsImpl.readdirSync(dir); } catch (_e) { continue; }
+    for (const name of names) {
+      if (!String(name).endsWith('.log')) { continue; }
+      const full = path.join(dir, name);
+      try {
+        found.push({ full, mtimeMs: fsImpl.statSync(full).mtimeMs || 0 });
+      } catch (_e) { /* vanished or unreadable — skip it */ }
+    }
+  }
+  found.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return found.map((f) => f.full);
+}
+
+/**
+ * The engine's own error line for a session, as a one-line excerpt.
+ *
+ * @param {string} sessionId - `ses_…` (createSession's return) or the bare id.
+ * @param {object} [options]
+ * @param {string} [options.dataDir] - XDG-style DATA dir override; the module
+ *   appends `opencode/log` itself, exactly as `$XDG_DATA_HOME` behaves in
+ *   src/utils/auth-json.js. Tests point this at a synthetic fixture tree. When
+ *   given it is the ONLY dir searched — an explicit override is a statement,
+ *   not one more candidate.
+ * @param {NodeJS.ProcessEnv} [options.env] - environment for dir resolution.
+ * @param {object} [options.fs] - fs seam (needs existsSync/readdirSync/
+ *   statSync/openSync/readSync/closeSync); defaults to the real module.
+ * @returns {string|null} excerpt, or null on EVERY miss path (no dir, no file,
+ *   no line whose own session field names us, no ERROR line, every match empty,
+ *   unreadable file, hostile fs, budget spent).
+ */
+function engineErrorForSession(sessionId, options = {}) {
+  try {
+    if (!sessionId || typeof sessionId !== 'string') { return null; }
+    const fsImpl = options.fs || require('fs');
+    const dirs = options.dataDir
+      ? [path.join(options.dataDir, 'opencode', 'log')]
+      : existingEngineLogDirs(options.env || process.env, fsImpl);
+    if (!dirs.length) { return null; }
+    const needle = sessionId.startsWith('ses_') ? sessionId : `ses_${sessionId}`;
+    const key = dirs.join('\0');
+    // TWO passes at most. Pass 1 may run on a WARM slot — the listing and tails
+    // another seat that died in the same window already read (#201 tail C2, see
+    // SCAN_CACHE_TTL_MS): the SCAN is memoized, never the ANSWER, so each seat
+    // still walks the lines for its OWN id. A HIT off that slot is served; a
+    // MISS is not (PR #206 round-1 A1+B2, see the module header) — pass 2 drops
+    // the slot and re-lists and re-reads before believing the absence.
+    for (let pass = 0; pass < 2; pass++) {
+      const slot = scanSlot(fsImpl, key);
+      const cold = !slot.files; // a slot built just now carries no listing yet
+      if (cold) { slot.files = candidateLogFiles(dirs, fsImpl); }
+      // Newest first, reading until the answer turns up or the byte budget is
+      // spent — NOT "the N newest files" (round-2 review B1, see MAX_SCAN_BYTES).
+      let budget = MAX_SCAN_BYTES;
+      for (const file of slot.files) {
+        if (budget <= 0) { break; }
+        const found = newestExcerptInFile(file, needle, fsImpl, budget, slot.tails);
+        budget -= found.bytes;
+        if (found.excerpt) { return found.excerpt; }
+      }
+      if (cold) { break; } // this pass read the disk itself: nothing to distrust
+      scanCaches.delete(fsImpl);
+    }
+    return null;
+  } catch (_e) {
+    return null; // a diagnostic read must never become the failure it reports on
+  }
+}
+
+// The line-shape helpers are RE-EXPORTED from their new home in
+// `engine-log-parse.js` so this module stays the single import site a consumer
+// needs (tests/engine-log.test.js pins that they are the same function objects,
+// not copies). The scan budget and the TTL beside it — like the tail bound now
+// in `engine-log-tail.js` — are deliberately NOT exported: nothing outside
+// consumes them, and a constant in a `Key Exports` cell reads as a function it
+// is not.
+module.exports = {
+  engineErrorForSession,
+  engineLogDirCandidates,
+  isErrorLine,
+  extractMessage,
+  collapseExcerpt,
+  mentionsSession,
+  lineIsAboutSession,
+};