@juzser/blacksmith 0.3.0 → 0.5.0

package/factory/orchestrator/dist/lessons.js

@@ -30,11 +30,12 @@ import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import picomatch from 'picomatch';
 import { isOperatorActor } from './actors.js';
+import { templateFileFor } from './agentNames.js';
 import { foldLessons } from './db/projector.js';
 import { SmithError } from './errors.js';
 import { appendEvent, readLineageEvents } from './events.js';
 import { AGENTS_DIR, lessonsReadPath } from './paths.js';
-import { FILE_SCOPED_SCOPES, isFileScopedScope, LESSON_SCOPES, parseLessons, } from './severity.js';
+import { BULLET, CONTINUATION, ENTRY_HEADING, FILE_SCOPED_SCOPES, isFileScopedScope, LESSON_SCOPES, parseLessons, SECTION_HEADING, } from './severity.js';
 import { loadTaxonomy, validateTag } from './taxonomy.js';
 export class LessonsError extends SmithError {
 }
@@ -301,8 +302,8 @@ select on. Each names its own bullet, validated against \`taxonomy.yml\`:
 At dispatch, an \`agent-role\` entry reaches only the role its \`agent_role\`
 names, and a \`case-type\` entry only a task whose \`case\` its \`case_type\`
 names. An entry in one of those scopes with **no** selector reaches NOBODY —
-it is inert, not universal, and \`smith lessons for-dispatch\` reports it as
-such. \`smith lessons raise\` refuses to mint one; the entries that predate
+it is inert, not universal, and \`bs lessons for-dispatch\` reports it as
+such. \`bs lessons raise\` refuses to mint one; the entries that predate
 the selector (D-129) are the only ones that can still be in that state.
 
 Two kinds of entry are therefore injected at dispatch and still never
@@ -388,22 +389,186 @@ function renderEntry(lesson) {
     bullets.push(renderBulletLines('statement', lesson.statement));
     return `### ${headingFor(lesson)}\n\n${bullets.join('\n')}\n`;
 }
+/**
+ * Walks a PRE-EXISTING lessons.md, salvaging every entry compileLessons()
+ * would otherwise have to overwrite from scratch. Deliberately stricter than
+ * severity.ts's parseLessons(): that parser is read-only, so silently
+ * skipping an entry it can't make sense of just leaves the same-mistake gate
+ * with one fewer rule. Here, skipping one means DELETING hand-authored
+ * content from the compiled file with no store row left to regenerate it
+ * from — so an entry under a real `## <scope>` section that doesn't parse is
+ * a hard error instead (never a silent drop), while content above the first
+ * `## <scope>` heading (this file's own header, including its illustrative
+ * fenced `### ` example) is ignored exactly as parseLessons ignores it: real
+ * entries only start once `scope` is one of severity.ts's `LESSON_SCOPES`.
+ *
+ * Line endings are normalized to `\n` before any of the above line-based
+ * regexes run: `SECTION_HEADING`/`BULLET`'s trailing `$` and `.` never match a
+ * `\r`, so on an unmodified `\r\n` file every line silently fails to match,
+ * `scope` never leaves `''`, and every entry in the file is dropped with no
+ * error at all — the exact silent-loss failure this function exists to
+ * prevent, just triggered by a different byte.
+ *
+ * A `### ` entry that carries a `lesson_id` bullet but sits under a `##`
+ * heading that is NOT one of `LESSON_SCOPES` — an unknown or misspelled
+ * section — is refused the same way an unparseable entry is, but only once a
+ * real scope section has already been seen once in the file: before that
+ * point the file is still in its own header/doc zone (the `## Schema`
+ * walkthrough, with its illustrative fenced example), which parseLessons has
+ * always ignored and must keep being ignored here too. After the first real
+ * scope section, though, a `## ` heading is no longer prose — it is a typo
+ * or a moved section, and an entry stranded under it would otherwise vanish
+ * exactly like the CRLF case above: no bucket matches, so it is never
+ * pushed, and flush()'s `heading === null` guard means it is never even
+ * counted as unparseable.
+ */
+function extractExistingLessonEntries(markdown) {
+    const lines = markdown.replace(/\r\n/g, '\n').split('\n');
+    const entries = [];
+    let scope = '';
+    let seenValidScope = false;
+    let heading = null;
+    let entryLines = [];
+    let bullets = {};
+    let lastKey = null;
+    /** Whether the entry currently being tracked sits under an unrecognized scope (see header comment). */
+    let orphan = false;
+    function flush() {
+        if (heading === null)
+            return;
+        while (entryLines.length > 0 && entryLines[entryLines.length - 1]?.trim() === '') {
+            entryLines.pop();
+        }
+        const lessonId = bullets.lesson_id;
+        const statement = bullets.statement;
+        if (orphan) {
+            if (lessonId) {
+                throw new LessonsError('lessons.entry-under-unknown-scope', `Existing lessons.md entry ${JSON.stringify(heading)} carries lesson_id ` +
+                    `${JSON.stringify(lessonId)} under "## ${scope}", which is not a recognized lesson ` +
+                    `scope (${VALID_SCOPES.join(', ')}) — refusing to compile, which would silently drop ` +
+                    'it. Fix the scope heading or remove the entry by hand, then recompile.', { scope, heading, lessonId });
+            }
+            // No lesson_id: treated like the header's own doc examples — ignored,
+            // not an error, so free-standing prose under a stray heading doesn't
+            // become a hard failure.
+            heading = null;
+            entryLines = [];
+            bullets = {};
+            lastKey = null;
+            orphan = false;
+            return;
+        }
+        if (!lessonId || !statement) {
+            throw new LessonsError('lessons.unparseable-existing-entry', `Existing lessons.md entry ${JSON.stringify(heading)} under "## ${scope}" is missing its ` +
+                `${!lessonId ? 'lesson_id' : 'statement'} bullet — refusing to compile, which would ` +
+                'silently drop it. Fix or remove the entry by hand, then recompile.', { scope, heading });
+        }
+        entries.push({ lessonId, scope, raw: `${entryLines.join('\n')}\n` });
+        heading = null;
+        entryLines = [];
+        bullets = {};
+        lastKey = null;
+        orphan = false;
+    }
+    for (const line of lines) {
+        const sectionMatch = line.match(SECTION_HEADING);
+        if (sectionMatch) {
+            flush();
+            scope = sectionMatch[1].trim();
+            if (VALID_SCOPES.includes(scope))
+                seenValidScope = true;
+            continue;
+        }
+        if (ENTRY_HEADING.test(line)) {
+            flush();
+            if (VALID_SCOPES.includes(scope)) {
+                heading = line;
+                entryLines = [line];
+                bullets = {};
+                lastKey = null;
+                orphan = false;
+            }
+            else if (seenValidScope) {
+                heading = line;
+                entryLines = [line];
+                bullets = {};
+                lastKey = null;
+                orphan = true;
+            }
+            continue;
+        }
+        if (heading === null)
+            continue;
+        entryLines.push(line);
+        const bulletMatch = line.match(BULLET);
+        if (bulletMatch) {
+            const key = bulletMatch[1];
+            bullets[key] = bulletMatch[2].trim();
+            lastKey = key;
+            continue;
+        }
+        if (line.trim() === '') {
+            lastKey = null;
+            continue;
+        }
+        const continuationMatch = line.match(CONTINUATION);
+        if (continuationMatch && lastKey) {
+            const existingValue = bullets[lastKey] ?? '';
+            bullets[lastKey] = `${existingValue} ${continuationMatch[1].trim()}`.trim();
+        }
+    }
+    flush();
+    return entries;
+}
+/**
+ * Which pre-existing entries a compile of `lessons` against `existingMarkdown`
+ * would preserve — the same set compileLessons() itself splices in, exposed
+ * so a caller (the CLI's `lessons compile` handler) can report how many
+ * survived without re-deriving the "now store-tracked, so the fresh render
+ * wins" filter a second time and risking the two counts drifting apart.
+ */
+export function lessonsToPreserve(lessons, existingMarkdown) {
+    if (existingMarkdown === undefined)
+        return [];
+    const knownIds = new Set(lessons.map((l) => l.lessonId));
+    return extractExistingLessonEntries(existingMarkdown).filter((entry) => !knownIds.has(entry.lessonId));
+}
 /**
  * Regenerates the full factory/policies/lessons.md content from a list of
  * APPROVED lessons. Round-trips through severity.ts's parseLessons(): every
  * entry here that carries a `finding_category` + `statement` (claim-path or
  * stack-wide scoped) survives the parse back into a `LessonRule`.
+ *
+ * `existingMarkdown`, when given, is the compiled file's own PRIOR content
+ * (e.g. read from `--out` before overwriting it). Compiling `lessons` alone
+ * loses every entry lessons.md carries that has no row in the store — a hand
+ * lesson raised before the store existed, or one `smith lessons raise` never
+ * touched — because this function only ever knew how to build the file from
+ * scratch. With `existingMarkdown`, any such entry (its `lesson_id` absent
+ * from `lessons`) is preserved verbatim instead of dropped; an entry whose id
+ * DOES appear in `lessons` is regenerated fresh from the store, same as
+ * before — the store stays the one source of truth for anything it tracks.
+ * Compiling the real repo file against the current store this way is
+ * insertions-only: nothing already there disappears.
  */
-export function compileLessons(lessons) {
+export function compileLessons(lessons, existingMarkdown) {
     const bySection = new Map(VALID_SCOPES.map((s) => [s, []]));
     for (const lesson of lessons) {
         const bucket = bySection.get(lesson.lessonScope);
         if (bucket)
             bucket.push(lesson);
     }
+    const preservedBySection = new Map(VALID_SCOPES.map((s) => [s, []]));
+    for (const entry of lessonsToPreserve(lessons, existingMarkdown)) {
+        const bucket = preservedBySection.get(entry.scope);
+        if (bucket)
+            bucket.push(entry.raw);
+    }
     const sections = VALID_SCOPES.map((scope) => {
-        const entries = bySection.get(scope) ?? [];
-        const body = entries.length === 0 ? '_(none yet)_\n' : entries.map(renderEntry).join('\n');
+        const freshBlocks = (bySection.get(scope) ?? []).map(renderEntry);
+        const keptBlocks = preservedBySection.get(scope) ?? [];
+        const blocks = [...keptBlocks, ...freshBlocks];
+        const body = blocks.length === 0 ? '_(none yet)_\n' : blocks.join('\n');
         return `## ${scope}\n\n${body}`;
     });
     return `${LESSONS_MD_HEADER}\n${sections.join('\n')}`;
@@ -494,7 +659,7 @@ export function scopesForRole(role, opts = {}) {
     if (!ROLE_NAME.test(role)) {
         throw new LessonsError('lessons.invalid-role-name', `Not a role name: ${JSON.stringify(role)} (expected e.g. "coder", "security-reviewer").`, { role });
     }
-    const templatePath = path.join(opts.agentsDir ?? AGENTS_DIR, `${role}.md`);
+    const templatePath = path.join(opts.agentsDir ?? AGENTS_DIR, templateFileFor(role));
     let template;
     try {
         template = readFileSync(templatePath, 'utf8');
@@ -506,13 +671,13 @@ export function scopesForRole(role, opts = {}) {
     for (const match of template.matchAll(SCOPE_MARKER)) {
         const scope = match[1];
         if (!VALID_SCOPES.includes(scope)) {
-            throw new LessonsError('lessons.unknown-lesson-scope', `${role}.md declares lesson scope "${scope}", which is not one of: ${VALID_SCOPES.join(', ')}.`, { role, scope, templatePath });
+            throw new LessonsError('lessons.unknown-lesson-scope', `${templateFileFor(role)} declares lesson scope "${scope}", which is not one of: ${VALID_SCOPES.join(', ')}.`, { role, scope, templatePath });
         }
         if (!scopes.includes(scope))
             scopes.push(scope);
     }
     if (scopes.length === 0) {
-        throw new LessonsError('lessons.role-template-has-no-scope-marker', `${role}.md carries no <!-- LESSONS:<scope> --> marker, so no lesson can reach it.`, { role, templatePath });
+        throw new LessonsError('lessons.role-template-has-no-scope-marker', `${templateFileFor(role)} carries no <!-- LESSONS:<scope> --> marker, so no lesson can reach it.`, { role, templatePath });
     }
     return scopes;
 }
@@ -594,7 +759,7 @@ export function lessonsForDispatch(role, claimPaths, opts = {}) {
         markdown = readFileSync(lessonsPath, 'utf8');
     }
     catch {
-        throw new LessonsError('lessons.compiled-file-not-found', `No compiled lessons at ${lessonsPath} — run \`smith lessons compile\`.`, { role, lessonsPath });
+        throw new LessonsError('lessons.compiled-file-not-found', `No compiled lessons at ${lessonsPath} — run \`bs lessons compile\`.`, { role, lessonsPath });
     }
     // A mistyped case would otherwise match no entry and emit no warning — a
     // silent empty injection, the exact failure D-129 is about. The role needs
@@ -877,6 +1042,17 @@ export async function dream(events, ctx, opts = {}, options = {}) {
             noveltyRejected.push(lessonId);
         }
     }
+    // DS8 plan §2.3 -- a durable mark that a pass happened, even one that
+    // raised nothing, so the Lessons page can show when lessons were last
+    // checked rather than only when one was last raised.
+    await appendEvent({
+        session_id: ctx.sessionId,
+        actor: ctx.actor ?? 'system',
+        event_type: 'lessons-pass-completed',
+        plan_version: ctx.planVersion,
+        causal_parent: parent,
+        payload: { raised: raised.length },
+    }, opts);
     return {
         checkpointsExtracted: checkpoints.length,
         raised,
@@ -1111,8 +1287,9 @@ export async function raiseLessonCandidate(input, ctx, opts = {}, options = {})
             ...(contradictionOf ? { possible_contradiction_of: contradictionOf } : {}),
         },
     }, opts);
+    let lastEventId = raisedEvent.event_id;
     if (!novelty.novel) {
-        await appendEvent({
+        const rejectedEvent = await appendEvent({
             session_id: ctx.sessionId,
             actor: 'system',
             event_type: 'lesson-status-changed',
@@ -1120,6 +1297,7 @@ export async function raiseLessonCandidate(input, ctx, opts = {}, options = {})
             causal_parent: raisedEvent.event_id,
             payload: { lesson_id: lessonId, from_status: 'candidate', to_status: 'novelty-rejected' },
         }, opts);
+        lastEventId = rejectedEvent.event_id;
     }
     return {
         lessonId,
@@ -1128,6 +1306,7 @@ export async function raiseLessonCandidate(input, ctx, opts = {}, options = {})
         mostSimilar: novelty.mostSimilar,
         possibleContradictionOf: contradictionOf,
         warnings,
+        event_id: lastEventId,
     };
 }
 // ---------------------------------------------------------------------------

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);
+}

package/factory/orchestrator/dist/mcp.js

@@ -260,7 +260,7 @@ export function addMcpSurface(opts) {
     const targetDir = opts.targetDir ?? path.join(opts.projectsDir ?? PROJECTS_DIR, opts.projectName);
     const manifestPath = path.join(targetDir, 'mcp.manifest.json');
     if (!existsSync(path.join(targetDir, 'package.json'))) {
-        throw new McpError('mcp.unknown-project', `${targetDir} is not a scaffolded project (no package.json). Run \`smith new ${opts.projectName}\` first.`, { targetDir, projectName: opts.projectName });
+        throw new McpError('mcp.unknown-project', `${targetDir} is not a scaffolded project (no package.json). Run \`bs new ${opts.projectName}\` first.`, { targetDir, projectName: opts.projectName });
     }
     if (existsSync(manifestPath)) {
         throw new McpError('mcp.surface-exists', `${manifestPath} already exists. Edit the manifest in place; re-scaffolding would discard declared tools and their operator sign-off.`, { manifestPath, projectName: opts.projectName });
@@ -314,7 +314,7 @@ export function registerMcpMilestone(projectName, roadmapPath = ensureWritableRo
         // in the roadmap itself which epic closes the milestone, the way
         // envkit-config-loader already does, instead of leaving it to convention.
         `- epics: [${id}]\n` +
-        '- goal: Declare and harden the MCP surface — `smith mcp check` green against ' +
+        '- goal: Declare and harden the MCP surface — `bs mcp check` green against ' +
         'docs/standards/mcp.md. Required before the final milestone can close.\n';
     writeFileSync(roadmapPath, `${text.trimEnd()}\n${block}`, 'utf8');
     return id;
@@ -339,7 +339,7 @@ export function checkRoadmapMcpMilestone(project, milestones) {
             {
                 rule: 'MCP-M1',
                 path: `/milestones/${project}`,
-                message: `Project "${project}" has no \`${project}-${MCP_MILESTONE_SUFFIX}\` milestone. Run \`smith mcp init ${project}\` to register it.`,
+                message: `Project "${project}" has no \`${project}-${MCP_MILESTONE_SUFFIX}\` milestone. Run \`bs mcp init ${project}\` to register it.`,
             },
         ];
     }
@@ -453,7 +453,7 @@ export function runMcpCheck(opts) {
     const manifestPath = path.join(targetDir, MANIFEST_NAME);
     const roadmapPath = opts.roadmapPath ?? roadmapReadPath();
     if (!existsSync(manifestPath)) {
-        throw new McpError('mcp.no-surface', `${manifestPath} does not exist. Run \`smith mcp init ${opts.projectName}\` before checking the surface.`, { manifestPath, projectName: opts.projectName });
+        throw new McpError('mcp.no-surface', `${manifestPath} does not exist. Run \`bs mcp init ${opts.projectName}\` before checking the surface.`, { manifestPath, projectName: opts.projectName });
     }
     let manifest;
     try {
@@ -548,8 +548,8 @@ export function mcpBlockers(epicId, status) {
     if (!status.check) {
         return [
             status.problem === 'unreadable'
-                ? `epic ${epicId} is under milestone ${milestone} but its MCP surface at ${manifest} exists and could not be read, so no verdict could be rendered — fix the manifest in place and run \`smith mcp check\` for the parser's own message. Do not re-run \`smith mcp init\`: it refuses over an existing manifest, because re-scaffolding would discard the declared tools and their operator sign-off.`
-                : `epic ${epicId} is under milestone ${milestone} but has no MCP surface at ${manifest} — run \`smith mcp init\` and declare it.`,
+                ? `epic ${epicId} is under milestone ${milestone} but its MCP surface at ${manifest} exists and could not be read, so no verdict could be rendered — fix the manifest in place and run \`bs mcp check\` for the parser's own message. Do not re-run \`bs mcp init\`: it refuses over an existing manifest, because re-scaffolding would discard the declared tools and their operator sign-off.`
+                : `epic ${epicId} is under milestone ${milestone} but has no MCP surface at ${manifest} — run \`bs mcp init\` and declare it.`,
         ];
     }
     return status.check.violations.map((v) => `mcp surface ${milestone}: ${v.rule} at ${v.path} — ${v.message}`);