@juzser/blacksmith 0.3.0 → 0.4.0

package/factory/orchestrator/dist/issueReporter.js

@@ -25,12 +25,15 @@
  * is a required parameter, supplied by the caller (task 5), never read off
  * the filesystem by this module.
  */
-import { FINGERPRINT_LINE_PREFIX, foldErrorEvents, renderBody, renderComment, renderTitle, toIssueBodyFields, toIssueCommentFields, } from './errorIssues.js';
+import { FINGERPRINT_LINE_PREFIX, foldErrorEvents, renderBody, renderComment, renderTitle, toIssueBodyFields, toIssueCommentFields, withSessionFallback, } from './errorIssues.js';
 import { appendEvent } from './events.js';
 import { buildCommentArgv, buildCreateIssueArgv, buildSearchIssuesArgv, classifyGh, resolveProjectRepo, } from './gh.js';
 /**
- * The closed, named outcome vocabulary. Exactly one of these eight words is
+ * The closed, named outcome vocabulary. Exactly one of these nine words is
  * recorded for every candidate error, always — functional clause 2.
+ * `skipped-unresolved-project` is settled before any of the others can be:
+ * a row this factory cannot identify the project of is never filed against
+ * this factory's own repository by default (the privacy-leak guard).
  */
 export const ISSUE_REPORT_OUTCOMES = [
     'opened',
@@ -40,6 +43,7 @@ export const ISSUE_REPORT_OUTCOMES = [
     'skipped-no-remote',
     'skipped-gh-missing',
     'skipped-unauthenticated',
+    'skipped-unresolved-project',
     'failed',
 ];
 const ISSUE_REPORTED_EVENT_TYPE = 'issue-reported';
@@ -60,8 +64,6 @@ export const ISSUE_REPORT_PAYLOAD_KEYS = [
     'source',
     'task_ref',
 ];
-/** Default project for an event stamped with none — matches events.ts's documented convention. */
-const DEFAULT_PROJECT = 'black-smith';
 function parseSearchResult(stdout) {
     let parsed;
     try {
@@ -94,14 +96,49 @@ function findExactMatch(issues, fingerprint) {
     const line = fingerprintLine(fingerprint);
     return issues.find((issue) => issue.body.split('\n').includes(line)) ?? null;
 }
+/**
+ * The task ref an unstamped row carries, if any -- the envelope's own
+ * `task_id` first, falling back to a hand-appended row's `payload.task_ref`.
+ * Mirrors errorIssues.ts's `candidateTaskRef`, which this module never
+ * imports so as to keep the two folds' internals independent.
+ */
+function candidateTaskRef(record) {
+    if (typeof record.task_id === 'string' && record.task_id.length > 0)
+        return record.task_id;
+    const payload = (record.payload ?? {});
+    return typeof payload.task_ref === 'string' && payload.task_ref.length > 0
+        ? payload.task_ref
+        : undefined;
+}
+/**
+ * A row's project, resolved the same way `errorIssues.ts`'s fold resolves
+ * one: an explicit stamp always wins; absent that, `resolveRow` (the row's
+ * own task ref widened with `withSessionFallback`'s session fallbacks) gets
+ * the answer. `null` when none of them can tell -- this factory's own
+ * project is never guessed. This is what keeps an unstamped row from a
+ * foreign (or unidentifiable) project's session from being folded into this
+ * factory's own prior-report history (and, through `decideOutcome`'s dedup
+ * key, its own repository) merely because nothing stamped it.
+ */
+function resolveRecordProject(record, resolveRow) {
+    if (typeof record.project === 'string')
+        return record.project;
+    return resolveRow(candidateTaskRef(record), record.session_id);
+}
 /**
  * Every already-appended `issue-reported` record still open, read off the
  * SNAPSHOT of events this call was handed — never off events this same call
  * itself appends. That is what lets the five duplicate candidates a single
  * broken gate produces in one round resolve through GitHub search (one
  * create, four comments) rather than short-circuiting on each other.
+ *
+ * A record whose project cannot be resolved at all is dropped rather than
+ * pushed: it can never match `priorReportFor`'s `h.project === report.project`
+ * comparison against a null-project report either (Step 0 below settles
+ * those before Step 4 runs), so keeping it around would only cost a lookup.
  */
-function priorOpenReports(events) {
+function priorOpenReports(events, resolveProject = () => null, selfFallback = () => null, scopeEvents = events) {
+    const resolveRow = withSessionFallback(scopeEvents, resolveProject, selfFallback);
     const out = [];
     for (const event of events) {
         const { record } = event;
@@ -116,8 +153,11 @@ function priorOpenReports(events) {
         if (typeof payload.fingerprint !== 'string' || typeof payload.latest_event_id !== 'string') {
             continue;
         }
+        const project = resolveRecordProject(record, resolveRow);
+        if (project === null)
+            continue;
         out.push({
-            project: record.project ?? DEFAULT_PROJECT,
+            project,
             fingerprint: payload.fingerprint,
             outcome: payload.outcome,
             latest_event_id: payload.latest_event_id,
@@ -155,7 +195,10 @@ async function appendIssueReported(report, record, opts) {
         plan_version: report.plan_version ?? 1,
         causal_parent: report.latest_event_id,
         payload: toPayload(record),
-        project: report.project,
+        // `EventInput.project` is `string | undefined` -- omitted, never
+        // `null`, when a row's project could not be resolved; the writer
+        // never stamps a guess (events.ts's documented convention).
+        ...(report.project !== null ? { project: report.project } : {}),
     }, opts);
 }
 /**
@@ -187,12 +230,21 @@ async function decideOutcome(report, isProjectEnabled, register, runner, history
         task_ref: report.task_ref,
         latest_event_id: report.latest_event_id,
     };
+    // Step 0: can this row's project be identified at all. A row still
+    // unresolved after the fold's own session fallbacks is never filed
+    // against this factory's own repository by default (the privacy-leak
+    // guard this whole module exists to close) -- settled before repo
+    // resolution or any `gh` interaction, ahead of every other step.
+    if (report.project === null) {
+        return { ...base, outcome: 'skipped-unresolved-project', reason: 'project-unresolved' };
+    }
+    const project = report.project;
     // Step 1: the switch.
-    if (!isProjectEnabled(report.project)) {
+    if (!isProjectEnabled(project)) {
         return { ...base, outcome: 'skipped-disabled', reason: 'switch-off' };
     }
     // Step 2: which repository.
-    const repo = resolveProjectRepo(report.project, register);
+    const repo = resolveProjectRepo(project, register);
     if (!('slug' in repo)) {
         return { ...base, outcome: 'skipped-no-remote', reason: repo.reason, detail: repo.detail };
     }
@@ -234,7 +286,11 @@ async function decideOutcome(report, isProjectEnabled, register, runner, history
     }
     const issues = parseSearchResult(searchResult.stdout);
     if (issues === null) {
-        return { ...base, outcome: 'failed', reason: 'search-failed', repo_slug: repoSlug };
+        // gh exited 0 but the output could not be read as an issue list (e.g.
+        // --json was dropped somewhere upstream and gh printed its human table,
+        // or the response was truncated). Distinct from a genuine nonzero exit
+        // above, which is a process failure rather than an unreadable payload.
+        return { ...base, outcome: 'failed', reason: 'search-unparseable', repo_slug: repoSlug };
     }
     // Step 6: an exact fingerprint-line match gets a comment.
     const match = findExactMatch(issues, report.fingerprint);
@@ -274,17 +330,26 @@ const DECISION_NOTE = 'create or comment: which of the two would run is decided
  * `0`, a placeholder known only after that search. `runner` is accepted for
  * signature parity with `reportErrors()`; nothing here reaches it.
  */
-export async function previewOutcomes(events, isProjectEnabled, register, runner, clock) {
+export async function previewOutcomes(events, isProjectEnabled, register, runner, clock, resolveProject = () => null, selfFallback = () => null, scopeEvents = events) {
     requireRegister(register, 'previewOutcomes');
     void runner;
-    const { reports } = foldErrorEvents(events, clock(), () => true);
-    const history = priorOpenReports(events);
+    const { reports } = foldErrorEvents(events, clock(), () => true, resolveProject, selfFallback, scopeEvents);
+    const history = priorOpenReports(events, resolveProject, selfFallback, scopeEvents);
     const out = [];
     for (const report of reports) {
         const { fingerprint, project, source, error_class, task_ref, latest_event_id } = report;
         const base = { fingerprint, project, source, error_class, task_ref, latest_event_id };
         const step3 = { step_3_gh_availability: STEP_3_NOT_PERFORMED };
         const settle = (rest) => out.push({ ...base, ...step3, ...rest });
+        // Step 0: can this row's project be identified at all.
+        if (project === null) {
+            settle({
+                settled_at_step: 0,
+                outcome: 'skipped-unresolved-project',
+                reason: 'project-unresolved',
+            });
+            continue;
+        }
         // Step 1: the switch.
         if (!isProjectEnabled(project)) {
             settle({ settled_at_step: 1, outcome: 'skipped-disabled', reason: 'switch-off' });
@@ -333,13 +398,13 @@ export async function previewOutcomes(events, isProjectEnabled, register, runner
  * calls `factoryProjects()` itself), `runner` is task 3's injected `gh`
  * command runner, and `clock` supplies `now` for the fold below.
  */
-export async function reportErrors(events, isProjectEnabled, register, runner, clock, opts = {}) {
+export async function reportErrors(events, isProjectEnabled, register, runner, clock, opts = {}, resolveProject = () => null, selfFallback = () => null, scopeEvents = events) {
     requireRegister(register, 'reportErrors');
     // Every project's switch is applied by this module's own step 1, not by
     // the fold: foldErrorEvents dropping a disabled project's candidates
     // silently would lose the `skipped-disabled` record clause 2 requires.
-    const { reports } = foldErrorEvents(events, clock(), () => true);
-    const history = priorOpenReports(events);
+    const { reports } = foldErrorEvents(events, clock(), () => true, resolveProject, selfFallback, scopeEvents);
+    const history = priorOpenReports(events, resolveProject, selfFallback, scopeEvents);
     const out = [];
     for (const report of reports) {
         const record = await decideOutcome(report, isProjectEnabled, register, runner, history);

package/factory/orchestrator/dist/judgeStopHook.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * `.claude/hooks/judge-stop.sh` — the SubagentStop decision for a judge-class
+ * agent (reviewer, verifier, grader, spec-reviewer, security-reviewer,
+ * auditor; `JUDGE_ROLES` in dispatchLint.ts is the authoritative set).
+ *
+ * A judge can end its turn without ever writing the artifact its dispatch
+ * declared, and today that gap is found only downstream, when `smith judge
+ * report` answers `judges.artifact-missing` — after the agent is gone. This
+ * hook closes the loop at the one moment it can still act: block the stop
+ * while the declared path does not exist, allow it once it does. A harness
+ * `maxTurns` cap is out of scope; this hook cannot override it.
+ *
+ * The declared-artifact line and its parser come from `dispatchLint.ts`,
+ * never redefined — `dispatch lint` already refuses, before dispatch, any
+ * judge prompt whose line is missing, relative, or mismatched, so this hook
+ * only asks "does the file exist yet", never "is the line well-formed".
+ *
+ * Fail open on anything this hook cannot read: a non-judge `agent_type`, a
+ * prompt with no declared-artifact line, a relative path, unparseable stdin,
+ * an unreadable transcript — blocking on those would trap the agent until
+ * `maxTurns` for an obligation the hook could never state. Every fail-open
+ * path prints a stderr note and is covered upstream by `dispatch lint` or
+ * downstream by `judge report`'s `judges.artifact-missing`.
+ *
+ * Fail closed ONLY on a readable absolute declared path that does not exist.
+ *
+ * SubagentStop stdin fields: https://code.claude.com/docs/en/hooks
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { JUDGE_ROLES, parseDeclaredArtifactLine } from './dispatchLint.js';
+const JUDGE_ROLE_SET = new Set(JUDGE_ROLES);
+/**
+ * The pure decision: given the hook's stdin and the subagent's prompt text
+ * (or `null` when it could not be read at all), decide whether the stop is
+ * allowed. Touches the filesystem only to check whether the declared path
+ * exists -- the one question this hook exists to ask.
+ */
+export function decideJudgeStop(input, promptText) {
+    const agentType = input.agent_type;
+    if (agentType === undefined || !JUDGE_ROLE_SET.has(agentType)) {
+        // Not one of the six judge roles -- a coder's turn carries no declared
+        // artifact at all, so there is nothing for this hook to check.
+        return { decision: 'allow' };
+    }
+    if (promptText === null) {
+        return {
+            decision: 'allow',
+            note: "judge-stop: could not read this agent's prompt (transcript missing or " +
+                "unreadable); allowing the stop. judge report's judges.artifact-missing " +
+                'remains the backstop.',
+        };
+    }
+    const declared = parseDeclaredArtifactLine(promptText);
+    if (declared === null) {
+        return {
+            decision: 'allow',
+            note: 'judge-stop: no "Declared artifact: <path>" line in this prompt; allowing ' +
+                "the stop. dispatch lint refuses this before dispatch, and judge report's " +
+                'judges.artifact-missing catches it downstream.',
+        };
+    }
+    if (!path.isAbsolute(declared)) {
+        return {
+            decision: 'allow',
+            note: `judge-stop: declared artifact "${declared}" is not an absolute path; ` +
+                'allowing the stop. dispatch lint refuses this before dispatch, and judge ' +
+                "report's judges.artifact-missing catches it downstream.",
+        };
+    }
+    if (!existsSync(declared)) {
+        return {
+            decision: 'block',
+            reason: `Declared artifact ${declared} does not exist yet. Write it before ending this turn.`,
+        };
+    }
+    // Existence is this hook's whole question -- an empty or unparseable file
+    // is `judge report`'s to refuse (`judges.artifact-unparseable`, `judges.
+    // artifact-not-a-list`), not this hook's to trap the agent over.
+    return { decision: 'allow' };
+}
+/**
+ * The last user-role message's text in a Claude Code JSONL transcript --
+ * where a dispatch prompt and its "Declared artifact:" line live. Walks
+ * backward from the end, since a subagent's transcript can carry many turns
+ * and the dispatch prompt need not be the only user turn. Returns `null` on
+ * any read or parse failure.
+ */
+export function extractLastUserPromptText(transcriptPath) {
+    let raw;
+    try {
+        raw = readFileSync(transcriptPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const lines = raw.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (line === undefined || line.trim() === '')
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const text = userTextOf(entry);
+        if (text !== null)
+            return text;
+    }
+    return null;
+}
+function userTextOf(entry) {
+    if (typeof entry !== 'object' || entry === null)
+        return null;
+    const rec = entry;
+    if (rec.type !== 'user')
+        return null;
+    const message = rec.message;
+    if (typeof message !== 'object' || message === null)
+        return null;
+    const content = message.content;
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        const parts = content
+            .filter((block) => typeof block === 'object' && block !== null)
+            .filter((block) => block.type === 'text' && typeof block.text === 'string')
+            .map((block) => block.text);
+        if (parts.length > 0)
+            return parts.join('\n');
+    }
+    return null;
+}
+/**
+ * The whole hook, minus process I/O: parse stdin, read the prompt, decide,
+ * and format the two output streams Claude Code and an operator each read.
+ * Exercised directly by tests without spawning a process; `main` below is
+ * the only piece that touches fd 0 and process.exit.
+ */
+export function runJudgeStopHook(rawStdin) {
+    let input;
+    try {
+        input = JSON.parse(rawStdin);
+    }
+    catch {
+        return {
+            stdout: '',
+            stderr: 'judge-stop: could not parse stdin as JSON; allowing the stop. ' +
+                "judge report's judges.artifact-missing remains the backstop.\n",
+        };
+    }
+    const promptText = input.transcript_path
+        ? extractLastUserPromptText(input.transcript_path)
+        : null;
+    const result = decideJudgeStop(input, promptText);
+    if (result.decision === 'block') {
+        return {
+            stdout: `${JSON.stringify({ decision: 'block', reason: result.reason })}\n`,
+            stderr: '',
+        };
+    }
+    return { stdout: '', stderr: result.note ? `${result.note}\n` : '' };
+}
+function main() {
+    const { stdout, stderr } = runJudgeStopHook(readFileSync(0, 'utf8'));
+    if (stdout)
+        process.stdout.write(stdout);
+    if (stderr)
+        process.stderr.write(stderr);
+}
+// Runs only when executed directly (judge-stop.sh execs `node
+// dist/judgeStopHook.js`) -- importing this module for its exports, as the
+// tests do, must never read stdin as a side effect.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main();
+}

package/factory/orchestrator/dist/logCache.js

@@ -0,0 +1,291 @@
+// The daemon's fix for finding 50acc356: `runTick` used to call `readEvents`
+// for every session on every tick, re-reading and re-parsing every byte ever
+// written to every log, forever. This module is the one place that reads a
+// session log more than once in a process's lifetime, and it reads each log
+// exactly once per byte that was ever appended to it.
+//
+// The fingerprint that decides "did this log change" is taken from an OPEN
+// file descriptor's fstat, never a path stat: `stat(path)` can race a
+// concurrent writer (open, then unlink-and-replace, then stat sees the new
+// inode while a reader mid-read still holds the old one) in a way an fstat on
+// a handle already open for THIS read cannot.
+//
+// Per log, the cache keeps an OFFSET (the byte offset just past the last
+// consumed newline) and an ANCHOR (the bytes of the last complete line,
+// terminating newline included, occupying exactly
+// `[offset - anchor.length, offset)`). A grown file is read once, from
+// `offset - anchor.length` to the new end; only when the leading
+// `anchor.length` bytes of that read still equal the cached anchor is the
+// growth treated as a genuine append, and only the bytes after `offset` are
+// parsed. Every other outcome — a different dev/ino, a shrink, an anchor
+// mismatch, or a cached offset of 0 with no anchor at all — is a full
+// re-read from byte 0.
+//
+// RESIDUAL CONTRACT: session logs are append-only by design (`appendEvent`
+// only ever appends). This cache DETECTS truncation, replacement, and any
+// rewrite that changes the anchor's bytes or offset. It does NOT detect an
+// in-place rewrite, on the same inode, that happens to keep the anchor's
+// bytes — terminating newline included — sitting in the same
+// `[offset - anchor.length, offset)` window, nor a same-size rewrite that
+// lands inside one mtime tick. Both are out of scope: nothing in this repo
+// writes a session log that way, so this is stated as a limit rather than
+// implied to be full change detection.
+import { open } from 'node:fs/promises';
+import path from 'node:path';
+import { EventError } from './events.js';
+import { STATE_EVENTS_DIR } from './paths.js';
+function fpEqual(a, b) {
+    return a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs;
+}
+/** Whatever a thrown value has to say for itself, without assuming it is an Error. */
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Same algorithm as `events.ts`'s private `readEventsAtPath` — trim trailing
+ * whitespace, split on `\n`, drop empty lines, parse each survivor as JSON —
+ * copied rather than imported so this module never calls `readEvents` (the
+ * `readEventsCalls` seam stays truthfully zero) while still throwing the
+ * identical `events.unreadable-session-log` error other readers throw.
+ *
+ * `startIndex` offsets the event id / line-number math for a delta parse:
+ * parsing only the newly appended tail of a log must still number its events
+ * (and report a malformed line's number) as if the whole file had been
+ * parsed at once.
+ */
+function parseCompleteLines(text, sessionId, filePath, startIndex) {
+    const lines = text
+        .trimEnd()
+        .split('\n')
+        .filter((line) => line.length > 0);
+    return lines.map((line, offset) => {
+        const index = startIndex + offset;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch (err) {
+            throw new EventError('events.unreadable-session-log', `Line ${index + 1} of ${filePath} is not JSON, so session "${sessionId}" cannot be read: ${errorText(err)}.`, { session_id: sessionId, path: filePath, line: index + 1 });
+        }
+        return { event_id: `${sessionId}#${index}`, record };
+    });
+}
+/**
+ * Parse a JSON pending tail — a well-formed JSON value with no terminating
+ * newline yet — into the one event it names. Throws the same
+ * `events.unreadable-session-log` error, with the same line number,
+ * `readEvents` would report for a malformed final line.
+ */
+function parsePendingTail(text, sessionId, filePath, index) {
+    let record;
+    try {
+        record = JSON.parse(text);
+    }
+    catch (err) {
+        throw new EventError('events.unreadable-session-log', `Line ${index + 1} of ${filePath} is not JSON, so session "${sessionId}" cannot be read: ${errorText(err)}.`, { session_id: sessionId, path: filePath, line: index + 1 });
+    }
+    return { event_id: `${sessionId}#${index}`, record };
+}
+const NEWLINE = 0x0a;
+/**
+ * Tail-detection and parse, applied to the RAW, untrimmed bytes of
+ * `tailBuf` — everything at and after `baseOffset` in the log.
+ *
+ * Locates the LAST `\n` in `tailBuf`: everything up to and including it is
+ * newline-terminated ("complete") lines, parsed and cached; everything after
+ * it is the candidate pending tail. A whitespace-only (or empty) candidate is
+ * no pending tail at all. `baseAnchor`/`baseOffset` are reused unchanged when
+ * `tailBuf` holds no newline — nothing newline-terminated was added, so
+ * nothing the entry remembers may advance.
+ */
+function parseTail(tailBuf, sessionId, filePath, baseOffset, baseIndex, baseAnchor, baseCachedEvents) {
+    const lastNL = tailBuf.lastIndexOf(NEWLINE);
+    let offset = baseOffset;
+    let anchor = baseAnchor;
+    let newComplete = [];
+    let pendingBuf;
+    if (lastNL === -1) {
+        pendingBuf = tailBuf;
+    }
+    else {
+        const completeBuf = tailBuf.subarray(0, lastNL + 1);
+        const prevNL = lastNL <= 0 ? -1 : tailBuf.lastIndexOf(NEWLINE, lastNL - 1);
+        const anchorStart = prevNL === -1 ? 0 : prevNL + 1;
+        anchor = Buffer.from(tailBuf.subarray(anchorStart, lastNL + 1));
+        offset = baseOffset + lastNL + 1;
+        newComplete = parseCompleteLines(completeBuf.toString('utf8'), sessionId, filePath, baseIndex);
+        pendingBuf = tailBuf.subarray(lastNL + 1);
+    }
+    const cachedEvents = newComplete.length === 0 ? [...baseCachedEvents] : [...baseCachedEvents, ...newComplete];
+    const pendingText = pendingBuf.toString('utf8');
+    if (pendingText.trim().length === 0) {
+        return { cachedEvents, events: cachedEvents, offset, anchor };
+    }
+    const pendingIndex = baseIndex + newComplete.length;
+    const pendingEvent = parsePendingTail(pendingText, sessionId, filePath, pendingIndex);
+    return { cachedEvents, events: [...cachedEvents, pendingEvent], offset, anchor };
+}
+const EMPTY_SEAM = {
+    opens: 0,
+    fstats: 0,
+    bytesRead: 0,
+    readEventsCalls: 0,
+    fullReparses: 0,
+};
+/**
+ * A reusable, package-internal cache of session event logs, keyed by a
+ * fingerprint taken from an open handle rather than a path stat.
+ *
+ * One instance is meant to live across many `runTick` calls (the daemon's
+ * long-running loop holds one for its whole run); a fresh instance is always
+ * cold, so `runTick` with no shared cache reads exactly what `readEvents`
+ * would have — this is an optimization for the repeat-tick case, not a
+ * change in what any single read returns.
+ */
+export class LogCache {
+    entries = new Map();
+    appliedSignatures = new Map();
+    counters;
+    /** `seam` lets a caller inject (and so share, or directly assert on) the counting object. */
+    constructor(seam) {
+        this.counters = seam ?? { ...EMPTY_SEAM };
+    }
+    logPath(sessionId, opts) {
+        return path.join(opts.stateDir ?? STATE_EVENTS_DIR, `${sessionId}.jsonl`);
+    }
+    /** This session's log, read through the cache. */
+    async read(sessionId, opts = {}) {
+        const filePath = this.logPath(sessionId, opts);
+        let handle;
+        try {
+            handle = await open(filePath, 'r');
+            this.counters.opens += 1;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                // The previous entry, if any, is left untouched — same rule as a
+                // read that throws below. A log that has vanished (and may come
+                // back) is not the same fact as a log this cache has never seen.
+                return [];
+            }
+            throw err;
+        }
+        try {
+            const stats = await handle.stat();
+            this.counters.fstats += 1;
+            const fp = {
+                dev: stats.dev,
+                ino: stats.ino,
+                size: stats.size,
+                mtimeMs: stats.mtimeMs,
+            };
+            const cached = this.entries.get(sessionId);
+            if (cached !== undefined && fpEqual(fp, cached.fp)) {
+                return cached.events;
+            }
+            // Append-only is verified, never inferred from size: the incremental
+            // path is only even attempted when the anchor byte-for-byte matches
+            // what the file now holds at the same window.
+            const canAttemptIncremental = cached !== undefined &&
+                fp.dev === cached.fp.dev &&
+                fp.ino === cached.fp.ino &&
+                cached.anchor.length > 0 &&
+                fp.size >= cached.offset;
+            if (canAttemptIncremental) {
+                // biome-ignore lint/style/noNonNullAssertion: canAttemptIncremental narrows `cached`.
+                const entry = cached;
+                const start = entry.offset - entry.anchor.length;
+                const readLen = fp.size - start;
+                const buf = Buffer.alloc(readLen);
+                const { bytesRead } = await handle.read(buf, 0, readLen, start);
+                this.counters.bytesRead += bytesRead;
+                const slice = buf.subarray(0, bytesRead);
+                if (slice.subarray(0, entry.anchor.length).equals(entry.anchor)) {
+                    const tailBuf = slice.subarray(entry.anchor.length);
+                    const parsed = parseTail(tailBuf, sessionId, filePath, entry.offset, entry.cachedEvents.length, entry.anchor, entry.cachedEvents);
+                    this.entries.set(sessionId, {
+                        fp,
+                        offset: parsed.offset,
+                        anchor: parsed.anchor,
+                        cachedEvents: parsed.cachedEvents,
+                        events: parsed.events,
+                    });
+                    return parsed.events;
+                }
+                // Anchor mismatch: a same-size-or-larger rewrite that is not a
+                // genuine append. Fall through to a full re-read.
+            }
+            this.counters.fullReparses += 1;
+            const whole = await handle.readFile();
+            this.counters.bytesRead += whole.length;
+            const parsed = parseTail(whole, sessionId, filePath, 0, 0, Buffer.alloc(0), []);
+            this.entries.set(sessionId, {
+                fp,
+                offset: parsed.offset,
+                anchor: parsed.anchor,
+                cachedEvents: parsed.cachedEvents,
+                events: parsed.events,
+            });
+            return parsed.events;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    /** The `event_id` of this session's last event, or `null` for empty/absent. */
+    async lastEventId(sessionId, opts = {}) {
+        const events = await this.read(sessionId, opts);
+        return events.length === 0 ? null : events[events.length - 1].event_id;
+    }
+    /**
+     * The fingerprint this cache last read for `sessionId`, or `undefined` if
+     * it has never been read through this cache. Lets a caller (the daemon's
+     * apply-skip below) build a cheap in-memory signature over a set of
+     * sessions without re-reading any of them.
+     */
+    fingerprintOf(sessionId) {
+        return this.entries.get(sessionId)?.fp;
+    }
+    /**
+     * The signature this cache last recorded a projector `apply()` against for
+     * `leaf` (`setAppliedSignature`'s argument), so the daemon can skip a
+     * redundant apply when nothing in the leaf's lineage changed since.
+     */
+    getAppliedSignature(leaf) {
+        return this.appliedSignatures.get(leaf);
+    }
+    setAppliedSignature(leaf, signature) {
+        this.appliedSignatures.set(leaf, signature);
+    }
+    /**
+     * Evicts every key not in `liveSessionIds` from both `entries` and
+     * `appliedSignatures`, so the cache's memory is bounded by live logs, not
+     * by history. `runTick` calls this once per tick with the session ids
+     * `listSessionIds` just returned -- the LISTED set, not the set of
+     * sessions whose read succeeded this tick -- so a session that is listed
+     * but unreadable keeps its entry (a read that throws leaves the entry
+     * untouched; eviction is the tick's decision, driven by the listing, not
+     * the read). A session that vanishes and later reappears loses both its
+     * fingerprint and its applied signature, so it is read cold and its leaf
+     * is re-applied. One pass over each map's own keys; no file I/O.
+     */
+    retainOnly(liveSessionIds) {
+        for (const sessionId of this.entries.keys()) {
+            if (!liveSessionIds.has(sessionId))
+                this.entries.delete(sessionId);
+        }
+        for (const leaf of this.appliedSignatures.keys()) {
+            if (!liveSessionIds.has(leaf))
+                this.appliedSignatures.delete(leaf);
+        }
+    }
+}
+/**
+ * The public factory. `dist/logCache.js` exports this, the `LogCache` type
+ * it returns, and the `LogCacheSeam` type its optional argument takes — the
+ * three names a consumer (task 3's dashboard wiring) imports to inject a
+ * counting cache elsewhere.
+ */
+export function createLogCache(seam) {
+    return new LogCache(seam);
+}