instar 1.3.645 → 1.3.647

package/dist/utils/jsonl-tail.js

@@ -0,0 +1,96 @@
+/**
+ * Bounded JSONL tail reader — read only the LAST window of an append-only log,
+ * never the whole file.
+ *
+ * Born from the 2026-06-22 event-loop-freeze batch: several timers and event
+ * handlers (CommitmentSentinel, CoherenceMonitor, PresenceProxy's
+ * checkLogForAgentResponse, TelegramAdapter.getMessageLog) each called
+ * `fs.readFileSync(messageLogPath, 'utf-8')` on the 12MB telegram-messages.jsonl
+ * just to look at the last ~50–200 lines. A 12MB synchronous read+split on a
+ * 5-minute timer froze the event loop for up to 20s per pass. These callers do
+ * not need the whole file — only its tail.
+ *
+ * Design (mirrors CoherenceJournal.readTailTolerant, generalized off the
+ * journal's typed entry shape):
+ *   - statSync the file (O(1)) — read at most `maxBytes` from the END.
+ *   - openSync + readSync the trailing window into a fixed buffer; never load
+ *     the whole file. O(maxBytes), not O(file).
+ *   - Discard the first (partial) line when the window started mid-file so a
+ *     truncated record is never mis-parsed.
+ *   - Return the raw trailing lines (newest LAST, file order preserved) — the
+ *     caller parses + filters exactly as it did over the full split before.
+ *
+ * Never throws — a read failure returns an empty result, matching the
+ * @silent-fallback-ok behavior of every former full-file caller. Observability
+ * / housekeeping reads must never endanger the observed operation.
+ */
+import fs from 'node:fs';
+/** Default trailing window: 512KB. At ~200 bytes/line that is ~2,600 recent
+ *  lines — far more than any caller's last-50/last-200 need, with headroom for
+ *  long messages, while staying a small bounded read regardless of file size. */
+export const DEFAULT_TAIL_BYTES = 512 * 1024;
+/**
+ * Read the last `maxBytes` of `filePath` and return its non-empty lines in file
+ * order. Reads at most `maxBytes` from disk regardless of total file size.
+ */
+export function readJsonlTailLines(filePath, maxBytes = DEFAULT_TAIL_BYTES) {
+    const empty = { lines: [], truncated: false };
+    try {
+        if (!fs.existsSync(filePath))
+            return empty;
+    }
+    catch {
+        return empty;
+    }
+    let size;
+    try {
+        size = fs.statSync(filePath).size;
+    }
+    catch {
+        return empty;
+    }
+    if (size === 0)
+        return empty;
+    const readBytes = Math.min(size, maxBytes);
+    const truncated = readBytes < size;
+    const start = size - readBytes;
+    let buf;
+    let fd = null;
+    try {
+        fd = fs.openSync(filePath, 'r');
+        buf = Buffer.alloc(readBytes);
+        fs.readSync(fd, buf, 0, readBytes, start);
+    }
+    catch {
+        return empty;
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+    let text = buf.toString('utf-8');
+    // If the window started mid-file, the first line is a partial record — drop it.
+    if (start > 0) {
+        const nl = text.indexOf('\n');
+        text = nl >= 0 ? text.slice(nl + 1) : '';
+    }
+    const lines = text.split('\n').filter((l) => l.length > 0);
+    return { lines, truncated };
+}
+/**
+ * Convenience: read the tail and return at most the last `limit` non-empty
+ * lines (file order). Equivalent to the common
+ * `readFileSync(...).split('\n').filter(Boolean).slice(-limit)` pattern, but
+ * bounded to a trailing `maxBytes` window instead of the whole file.
+ */
+export function readJsonlTailLastLines(filePath, limit, maxBytes = DEFAULT_TAIL_BYTES) {
+    const { lines } = readJsonlTailLines(filePath, maxBytes);
+    return limit >= lines.length ? lines : lines.slice(-limit);
+}
+//# sourceMappingURL=jsonl-tail.js.map

package/dist/utils/jsonl-tail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl-tail.js","sourceRoot":"","sources":["../../src/utils/jsonl-tail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB;;iFAEiF;AACjF,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,GAAG,IAAI,CAAC;AAU7C;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAgB,EAChB,WAAmB,kBAAkB;IAErC,MAAM,KAAK,GAAmB,EAAE,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAC9D,IAAI,CAAC;QACH,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAE7B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC3C,MAAM,SAAS,GAAG,SAAS,GAAG,IAAI,CAAC;IACnC,MAAM,KAAK,GAAG,IAAI,GAAG,SAAS,CAAC;IAE/B,IAAI,GAAW,CAAC;IAChB,IAAI,EAAE,GAAkB,IAAI,CAAC;IAC7B,IAAI,CAAC;QACH,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAChC,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC9B,EAAE,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;YAAS,CAAC;QACT,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YAChB,IAAI,CAAC;gBACH,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YACnB,CAAC;YAAC,MAAM,CAAC;gBACP,iBAAiB;YACnB,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjC,gFAAgF;IAChF,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3C,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3D,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAC9B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,QAAgB,EAChB,KAAa,EACb,WAAmB,kBAAkB;IAErC,MAAM,EAAE,KAAK,EAAE,GAAG,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACzD,OAAO,KAAK,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;AAC7D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.645",
+  "version": "1.3.647",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-22T18:50:01.119Z",
-  "instarVersion": "1.3.645",
+  "generatedAt": "2026-06-22T20:47:55.471Z",
+  "instarVersion": "1.3.647",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.646.md

@@ -0,0 +1,39 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`JobRunHistory.readLines()` did a synchronous `readFileSync` + per-line `JSON.parse` of the entire
+`.instar/ledger/job-runs.jsonl` (~13MB) on EVERY call — on the hot path of `findRun` /
+`recordCompletion` / `recordHandoff` / `query` / `stats` (every job completion/spawn, ~60s cadence).
+A live `/usr/bin/sample` caught the event loop frozen 13–16s in `ReadFileUtf8 → ParseJson →
+WriteFileUtf8`, misreported by SleepWakeDetector as a ~15s "wake". This is the THIRD distinct
+event-loop blocker behind the dashboard "disconnected" flapping (after sync tmux and sync keychain
+reads). The read path now uses an incremental in-memory cache keyed on `(size, mtimeMs)`: unchanged
+file → cache hit (zero IO); append → tail-read only (O(delta)); shrink/compaction → one full re-read.
+
+## What to Tell Your User
+
+If your dashboard kept dropping its connection even after the tmux and keychain fixes, this was the
+remaining cause: a 13MB job-history file re-read whole, every minute, on the server's main thread.
+After this update that freeze is gone. (A separate cleanup — capping that file's unbounded growth —
+is tracked separately.)
+
+## Summary of New Capabilities
+
+- Incremental `(size, mtimeMs)`-keyed in-memory cache in `JobRunHistory`; unchanged file = zero-IO
+  cache hit, append = tail-read only, compaction = one full re-read. Existing semantics (append-only,
+  dedup-last-wins, torn-line skip, corrupt-file recovery) preserved exactly.
+- Removes the third event-loop blocker behind the dashboard flapping + the associated SleepWakeDetector
+  false-wakes.
+
+## Evidence
+
+Root cause diagnosed by a live `/usr/bin/sample` (main thread in ReadFileUtf8 → ParseJson →
+WriteFileUtf8) + an mtime-watch catching the 13MB rewrite, correlated with 15–20s freezes every
+~20–60s. Fix covered by 4 new regression tests (cache-hit does zero full-file reads across 75 ops;
+external append via tail-read; torn-line skip; full re-read on shrink) on top of 30 existing; full
+scheduler suite green (346 tests total); tsc clean; no-silent-fallbacks + bounded-accumulation +
+no-wholefile-sync-read lints green.

package/upgrades/1.3.647.md

@@ -0,0 +1,56 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+FOUR callers each did a synchronous `fs.readFileSync` of the ~12MB `.instar/telegram-messages.jsonl`
+just to inspect its last 50–200 lines: `CommitmentSentinel.parseRecentMessages` (5-min timer),
+`CoherenceMonitor`'s output-sanity check (5-min timer), `checkLogForAgentResponse` (PresenceProxy ack
+path, event-driven), and `TelegramAdapter.getMessageLog` (analysis route). A 12MB sync read + split
+on a 5-minute timer froze the event loop up to ~20s per pass — the same ~0-CPU false-sleep signature
+the JobRunHistory fix removed. Separately, `JsonlFeedbackStore` re-read + re-`JSON.parse`d the entire
+~14MB `feedback.jsonl` at the start of every processing pass even when nothing had changed. This is
+the THIRD + FOURTH event-loop-blocker class behind the dashboard "disconnected" flapping (after sync
+tmux, sync keychain, and the JobRunHistory 13MB re-read).
+
+The fix is two behavior-preserving mechanisms: (A) a shared bounded tail-read utility
+(`src/utils/jsonl-tail.ts`) that reads only the last 512KB via `openSync`/`readSync` — mirroring
+`CoherenceJournal.readTailTolerant` — used by the four telegram-log readers; and (B) a
+`(size, mtimeMs)` load cache in `JsonlFeedbackStore` (mirroring the JobRunHistory cache) that serves a
+clone of the prior parse when the file is byte-for-byte unchanged.
+
+## What to Tell Your User
+
+If your dashboard kept dropping its connection even after the tmux, keychain, and job-history fixes,
+these two large files were the remaining cause: a 12MB message log re-read whole on a 5-minute timer,
+and a 14MB feedback log re-parsed from scratch every pass. After this update both freezes are gone —
+the message-log checks read only the last chunk of the file (instant regardless of size), and the
+feedback log is served from memory when nothing changed. (A separate cleanup — capping those files'
+unbounded growth — is tracked separately.)
+
+## Summary of New Capabilities
+
+- New `src/utils/jsonl-tail.ts` bounded tail-reader (`readJsonlTailLines` / `readJsonlTailLastLines`):
+  reads only the last `maxBytes` (default 512KB ≈ 2,600 lines) via `statSync`/`openSync`/`readSync`,
+  drops the partial first line, never loads the whole file, never throws.
+- The four telegram-log tail readers (CommitmentSentinel, CoherenceMonitor, PresenceProxy ack path,
+  TelegramAdapter.getMessageLog) converted from whole-12MB-file sync reads to bounded tail-reads;
+  parsed/filtered results are identical to the old full-split-then-slice.
+- `JsonlFeedbackStore` gains a `(size, mtimeMs)`-keyed in-memory load cache: unchanged file = zero-IO
+  clone-on-serve, any change = full re-read. Existing load semantics (dedup-last-wins, torn-line skip,
+  corrupt-file recovery) preserved exactly.
+- Removes the third + fourth event-loop-blocker class behind the dashboard flapping and the
+  associated SleepWakeDetector false-wakes.
+
+## Evidence
+
+Root cause diagnosed by a live profiler catching the event loop frozen in a whole-file
+ReadFileUtf8 → split on a 5-minute timer (the ~0-CPU false-sleep signature). Fix covered by 48 tests
+across four files: `jsonl-tail` (9 — tail correctness, partial-line drop, missing/empty file,
+truncation flag), `CoherenceMonitor-bounded-read` (2 — a `fs.readFileSync` spy FAILS if the whole
+12MB log is read, AND a bad pattern in a RECENT agent message at the END of a multi-MB log is still
+detected via the tail), `CommitmentSentinel` (26), `jsonl-feedback-store` (11 — including cache-hit
+serves zero-IO and any change re-reads). Cross-impact suites green; tsc exit 0; no-silent-fallbacks +
+bounded-accumulation lints green.

package/upgrades/eli16/eventloop-bounded-jsonl-reads.md

@@ -0,0 +1,47 @@
+# Bounded tail-reads for the 12MB telegram-log + 14MB feedback-store — ELI16
+
+## What this is
+
+Your agent's server runs everything on one main thread. If any single operation makes that thread
+wait, *everything* waits — the dashboard, your messages, every background check. When that wait is
+long enough, the dashboard's live connection drops (the "Disconnected" flapping you may have seen).
+
+This fixes the THIRD and FOURTH freezes behind that flapping. (The first was a slow shared terminal
+manager; the second was reading the macOS keychain the blocking way; the third was a 13MB job-history
+file re-read whole every minute — all already fixed.) This one is about two more big files.
+
+## What was wrong
+
+Your agent keeps a running log of every Telegram message it has ever sent or received, in a file
+called `telegram-messages.jsonl`. That file has grown to about **12 megabytes**. Several background
+checks only ever need to glance at the LAST few messages in that log — the last 50, or the last 100.
+But the way they were written, they read the **entire 12MB file** from disk and chopped it up, just
+to look at the tail. And some of these checks run on a **5-minute timer**, every few minutes, forever.
+Each one froze the server for up to **20 seconds**. (A second large file, a 14MB feedback log, had
+the same problem: it was re-read and re-parsed from scratch every processing pass even when nothing
+had changed.)
+
+A frozen main thread uses almost no CPU, so the freeze even looked to the agent like the laptop had
+briefly gone to sleep — a misleading signal on top of a real problem.
+
+## What's new
+
+Two simple changes, both behavior-preserving:
+
+- The background checks that only want the tail of the message log now read just the **last chunk**
+  of the file (a 512-kilobyte window — far more than enough to hold the last few hundred messages),
+  not the whole thing. So they're instant no matter how big the file gets.
+- The 14MB feedback log now remembers the file's size and last-modified time. If nothing changed
+  since it last read it, it returns the copy it already has, reading nothing from disk.
+
+So those per-call whole-file reads are gone from every one of these hot paths, and the freezes they
+caused are eliminated. Everything these checks actually do — what they look for, how they parse,
+how they recover from a corrupt file — is unchanged, and proven by tests. One of the new tests even
+plants a problem message at the very END of a multi-megabyte log to prove the tail-read still catches
+recent entries.
+
+## What you need to decide
+
+Nothing. It's self-contained and low-risk, fully covered by tests. One honest note: the log files
+themselves still grow large over time — putting a size cap on them is a separate cleanup I've flagged
+to track, not fixed here. Reading them is no longer a freeze; capping their growth comes next.

package/upgrades/eli16/jobrunhistory-incremental-cache.md

@@ -0,0 +1,43 @@
+# JobRunHistory incremental cache — event-loop freeze fix — ELI16
+
+## What this is
+
+Your agent's server runs everything on one main thread. If any single operation makes that thread
+wait, *everything* waits — the dashboard, your messages, every background check. That's a "freeze,"
+and a long-enough freeze drops the dashboard's live connection (the "Disconnected" flapping).
+
+This fixes the THIRD distinct freeze behind that flapping. (The first was a slow shared terminal
+manager; the second was reading the macOS keychain the blocking way — both already fixed.) This one:
+the agent keeps a log of every background job it has ever run, in a file called `job-runs.jsonl`. That
+file has grown to about **13 megabytes**. And every time a job finished or started — which happens
+about every minute — the server read the WHOLE 13MB file from disk and re-parsed all of it, on the
+main thread. That single operation froze the server for **13 to 16 seconds**, every minute or so. It
+even looked to the agent like the laptop had gone to sleep (a blocked main thread uses almost no CPU,
+so the sleep-detector misreads it).
+
+## What already exists
+
+The agent already uses this "keep a cached copy instead of re-reading from scratch" pattern elsewhere
+(the cartographer code map serves a cached snapshot instead of recomputing live). This job-history
+file just never got that treatment — it re-read the whole thing every single time.
+
+## What's new
+
+The job-run history now keeps a **smart in-memory cache**. It remembers the file's size and
+last-modified time:
+- If nothing changed since last time → it returns the cached copy instantly, reading nothing from
+  disk.
+- If a new line was appended (the normal case) → it reads ONLY the new bit at the end, not the whole
+  13MB.
+- If the file was compacted (shrunk) → it does one full re-read to stay correct.
+
+So the per-call full-file read+parse is gone from every hot path. The freeze it caused is eliminated.
+All the existing behavior (how it dedupes, recovers from a corrupt file, etc.) is preserved exactly,
+proven by the test suite.
+
+## What you need to decide
+
+Nothing. It's a self-contained, low-risk read-path cache, fully covered by tests. One honest note:
+the `job-runs.jsonl` file (and a separate 91MB cartographer file) keep growing without a size limit —
+the cache makes reading them cheap regardless, but capping their growth is a separate cleanup item
+I've flagged to track, not fixed here.

package/upgrades/side-effects/eventloop-bounded-jsonl-reads.md

@@ -0,0 +1,96 @@
+# Side-Effects Review — bounded tail-reads for the 12MB telegram-log + 14MB feedback-store (event-loop freeze fix)
+
+**Slug:** `eventloop-bounded-jsonl-reads` · **Tier:** 1 (focused low-risk bounded-read class fix, no
+spec; live-profiler root-cause). Parent principles: **Structure beats Willpower** — never block the
+event loop (the THIRD + FOURTH distinct event-loop-blocker class behind the dashboard "disconnected"
+flapping, after sync tmux + sync keychain + the JobRunHistory 13MB re-read); and **Bounded
+Accumulation** (the size of an append-only log must never determine the cost of reading it).
+
+## Summary of the change
+
+FOUR callers each did `fs.readFileSync(messageLogPath, 'utf-8')` on the ~12MB
+`.instar/telegram-messages.jsonl` just to inspect the last 50–200 lines:
+- `CommitmentSentinel.parseRecentMessages` (`src/monitoring/CommitmentSentinel.ts`) — 5-minute timer,
+  only ever looks at the last `maxMessagesPerScan*10` lines.
+- `CoherenceMonitor` output-sanity check (`src/monitoring/CoherenceMonitor.ts`) — 5-minute timer,
+  only ever looks at the last 50 agent messages.
+- `checkLogForAgentResponse` (PresenceProxy ack path, `src/commands/server.ts`) — event-driven on
+  every PresenceProxy tier verdict, only ever looks at the last 50 lines.
+- `TelegramAdapter.getMessageLog` (`src/messaging/TelegramAdapter.ts`) — analysis route, only ever
+  returns the last `limit` (default 100) entries.
+
+A 12MB synchronous read + `.split('\n')` on a 5-minute timer froze the event loop for up to ~20s per
+pass — the same ~0-CPU false-sleep signature the JobRunHistory fix removed. PLUS `JsonlFeedbackStore`
+(`src/feedback-factory/store/JsonlFeedbackStore.ts`) re-read + re-`JSON.parse`d the entire ~14MB
+`feedback.jsonl` at the start of every processing pass even when nothing had changed.
+
+The fix is two behavior-preserving mechanisms:
+
+**(A) A shared bounded tail-read utility** — `src/utils/jsonl-tail.ts` (`readJsonlTailLines` /
+`readJsonlTailLastLines`). It `statSync`s the file (O(1)), `openSync` + `readSync`s only the trailing
+`maxBytes` (default 512KB ≈ ~2,600 recent lines, far more than any caller needs) into a fixed buffer,
+drops the first partial line when the window started mid-file, and returns the trailing lines in file
+order. It NEVER loads the whole file and NEVER throws (a read failure returns an empty result,
+matching the `@silent-fallback-ok` behavior of every former full-file caller). It mirrors
+`CoherenceJournal.readTailTolerant`, generalized off that journal's typed-entry shape. The four
+telegram-log readers above now call it instead of `readFileSync`.
+
+**(B) A `(size, mtimeMs)` load cache in `JsonlFeedbackStore.loadJsonl`** — when the on-disk file is
+byte-for-byte the one last folded, it serves a clone of the prior parse with ZERO IO/parse; any
+change (append, shrink, delete) re-reads from disk. Mirrors the JobRunHistory cache pattern. The
+clone-on-serve guarantees a caller mutating the returned Map can never poison the cache.
+
+## 1. Correctness / behavioral equivalence
+
+The telegram-log readers each consumed only a fixed tail (last 50 / last 200 / last `limit`) of the
+log, so the 512KB window (≈ 2,600 lines) is strictly a superset of every caller's need — the parsed +
+filtered result is identical to the old full-split-then-slice. The partial-first-line drop guarantees
+a truncated record at the window boundary is never mis-parsed. The feedback store's load semantics
+(per-line parse, dedup-last-wins-by-id, torn-line skip, corrupt-file recovery) are preserved exactly;
+the cache is only consulted when the fingerprint matches and is invalidated on any change. Verified:
+48/48 across the four touched test files (`jsonl-tail` 9, `CoherenceMonitor-bounded-read` 2,
+`CommitmentSentinel` 26, `jsonl-feedback-store` 11) plus the cross-impact suites; tsc exit 0; lints
+green. The two new regression tests spy on `fs.readFileSync` to FAIL if the whole telegram log is
+read, AND prove a bad pattern in a RECENT agent message at the END of a multi-MB log is still
+detected via the tail.
+
+## 2. Cache-coherence / multi-writer safety
+
+The telegram-log tail-read holds no state — every call re-reads the live tail, so a concurrent
+appender is always reflected. The feedback-store `(size, mtimeMs)` key invalidates on any byte/mtime
+change (append, compaction rewrite, delete-then-recreate), so an unchanged file is the only cache-hit
+case and a stale fold can never be served. The cache is per-process in-memory (not shared) — no
+cross-process coherence concern (each process reads its own view, same as before). `loadCache` is
+keyed per absolute path and dropped on `existsSync` failure.
+
+## 3. Fail-safe
+
+`jsonl-tail.ts` never throws: missing file, stat failure, open/read failure each return an empty
+result — exactly the prior `@silent-fallback-ok` degradation of the full-file callers (an
+observability/housekeeping read must never endanger the observed operation). The feedback store's
+stat-failure path falls through to a full read (`/* fall through to a full read — never let stat
+failure skip the load */`), so a stat error degrades to the correct (slow) result, never wrong data.
+
+## 4. Blast radius
+
+One new utility module + its test; four read-site one-liner swaps (CommitmentSentinel, CoherenceMonitor,
+server.ts PresenceProxy ack, TelegramAdapter.getMessageLog); one read-path cache in JsonlFeedbackStore
++ a test-only cache-clear export. No API/route change, no schema change, no write-path semantics
+change, no new external surface.
+
+## 5. Residual (tracked, NOT fixed here — out of scope)
+
+The existing `lint-no-wholefile-sync-read` ratchet only catches LITERAL path basenames in the read
+call, but these four sites read VARIABLE paths (`this.messageLogPath`, a `logPath` param), so the
+lint could never have flagged them — which is why they survived the earlier sweeps. The durable
+structural prevention is an **accessor funnel** (route all append-log reads through a single bounded
+accessor that the lint can enforce), which is **Bounded Accumulation Increment 2** — a tracked
+follow-up named here so it is not silently dropped. Separately, the telegram-messages.jsonl and
+feedback.jsonl files themselves still grow UNBOUNDED — a size/retention cap is the same Bounded
+Accumulation track. This change makes READS cheap regardless of size; it does not cap the files.
+
+## 6. Rollback
+
+Revert the source files. The change is purely read-path (a bounded tail-read + a fingerprint cache);
+reverting restores the (slow but correct) full-read behavior. No data migration, no on-disk format
+change to undo.

package/upgrades/side-effects/jobrunhistory-incremental-cache.md

@@ -0,0 +1,61 @@
+# Side-Effects Review — JobRunHistory incremental cache (event-loop freeze fix)
+
+**Slug:** `jobrunhistory-incremental-cache` · **Tier:** 1 (focused bug fix, no spec; live-profiler
+root-cause). Parent principle: **Structure beats Willpower** — never block the event loop (the third
+distinct event-loop blocker behind the dashboard "disconnected" flapping, after sync tmux + sync
+keychain reads).
+
+## Summary of the change
+
+`JobRunHistory.readLines()` (`src/scheduler/JobRunHistory.ts`) did `fs.readFileSync` + per-line
+`JSON.parse` of the ENTIRE `.instar/ledger/job-runs.jsonl` (~13MB) on EVERY call — and it is on the
+hot path of `findRun` / `recordCompletion` / `recordReflection` / `recordHandoff` / `query` / `stats`
+/ `allStats` / `getLastHandoff`, all driven by the scheduler every job completion/spawn (~60s
+cadence: health-check, commitment-detection, mentor jobs). A live `/usr/bin/sample` caught the main
+thread in `ReadFileUtf8 → ParseJson → WriteFileUtf8` — a 13–16s event-loop freeze misreported by
+SleepWakeDetector as a ~15s "wake" (the ~0-CPU false-sleep signature). This adds an **incremental
+in-memory cache** of parsed runs keyed on the file's `(size, mtimeMs)`: an unchanged file returns the
+cache with ZERO IO/parse; an append-only growth reads ONLY the appended tail via `fs.readSync` from
+the last offset (O(delta), not O(13MB)); a shrink/rewrite (compaction) triggers one full re-read.
+
+## 1. Correctness / behavioral equivalence
+
+Existing semantics preserved exactly: append-only, dedup-last-wins, torn-line skip, corrupt-file
+recovery. `appendLine` keeps the cache coherent so the read after a completion is also free;
+`compact()` re-seeds the cache after its rewrite. Verified: 30 original `JobRunHistory` tests + 4 new
+regression tests (cache-hit does zero full-file reads across 75 ops; external append picked up via
+tail-read; torn-line skipped; full re-read on shrink); the full scheduler suite (incl. MigrationLedger,
+reaper, run-record) = 325; 346 total green.
+
+## 2. Cache-coherence / multi-writer safety
+
+The file has two in-process append writers (this instance + `MigrationLedger.appendMigrationEvent`),
+both append-only. The `(size, mtimeMs)` key + intact-prefix tail-read handles an external append
+correctly (picks up appended rows via tail-read). A shrink (only `compact()` rewrites) forces a full
+re-read, so a compaction can never serve a stale cache. The cache is per-process in-memory (not
+shared) — no cross-process coherence concern (each process reads its own view, same as before).
+
+## 3. Fail-safe
+
+The new fail paths (cache read, tail-read, stat) fall back to a full re-read or to the prior
+behavior; each genuinely fail-safe catch is tagged `@silent-fallback-ok`. A stat/read error degrades
+to a full re-read (correct result, just not the fast path) — never wrong data, never a crash.
+
+## 4. Blast radius
+
+One module (`JobRunHistory.ts`) + its test. No API/route change, no schema change, no write-path
+semantics change (`compact()` still rewrites on its existing cadence — see the residual note). No
+new external surface.
+
+## 5. Residual (tracked, NOT fixed here — out of scope)
+
+`job-runs.jsonl` grows UNBOUNDED to 13MB (and the cartographer `index.json` is 91MB) — a genuine
+Bounded-Accumulation issue. The cache makes READS cheap regardless of size, but `compact()` still
+does a full synchronous ~13MB WRITE on startup, and the file keeps growing. A retention/rotation cap
+on `job-runs.jsonl` (and the cartographer index) is a separate Bounded-Accumulation follow-up worth
+filing — named here so it is not silently dropped.
+
+## 6. Rollback
+
+Revert the one source file. The change is purely a read-path cache; reverting restores the (slow but
+correct) full-read behavior.