mixdog 0.9.16 → 0.9.18

package/src/runtime/agent/orchestrator/session/manager/usage-metrics.mjs

@@ -6,12 +6,131 @@
 // _runtimeState map (owned by manager.mjs) to read the in-memory session and
 // flag usageMetricsTurnIncremental. manager.mjs wires it via configureUsageMetricsRuntime().
 import { providerInputExcludesCache } from '../../providers/registry.mjs';
-import { loadSession, saveSessionAsync } from '../store.mjs';
+import { loadSession, saveSessionAsync, _saveSessionSync } from '../store.mjs';
 
 // Per-session idempotency tracking: sessionId → Set of seen
 // turn:epoch:iteration:source keys.
 const _metricSeenIter = new Map();
 
+// ── Mid-turn save coalescing ──────────────────────────────────────────────
+// saveSessionAsync structured-clones the ENTIRE session on the main thread
+// per postMessage call (store.mjs saveSessionAsync). Calling it after EVERY
+// provider.send iteration is the cost this coalesces away: in-memory session
+// mutation above still happens every iteration (durability of the data is
+// unaffected — only how often it hits saveSessionAsync's postMessage clone).
+// sessionId → { inFlight, dirty, lastFlushAt, timer }
+const _metricSaveState = new Map();
+// sessionId → live session ref awaiting a still-deferred (timer-pending)
+// flush. Only populated for the window between "delta applied, save not yet
+// posted to the worker" and the actual saveSessionAsync call — once a save
+// is posted, store.mjs's own _saveWorkerPending covers process-exit drain.
+const _pendingMetricsFlush = new Map();
+const METRICS_SAVE_THROTTLE_MS = 500;
+
+function _metricsSaveState(sessionId) {
+    let state = _metricSaveState.get(sessionId);
+    if (!state) {
+        state = { inFlight: false, dirty: false, lastFlushAt: 0, timer: null, closed: false, failCount: 0 };
+        _metricSaveState.set(sessionId, state);
+    }
+    return state;
+}
+
+function _flushMetricsSave(session, sessionId) {
+    const state = _metricsSaveState(sessionId);
+    if (state.closed) return;
+    if (state.timer) { clearTimeout(state.timer); state.timer = null; }
+    _pendingMetricsFlush.delete(sessionId);
+    state.dirty = false;
+    state.inFlight = true;
+    state.lastFlushAt = Date.now();
+    saveSessionAsync(session, { expectedGeneration: session.generation })
+        .then(() => {
+            state.failCount = 0;
+        })
+        .catch((err) => {
+            process.stderr.write(`[usage-metrics] iteration save failed: ${err?.message ?? err}\n`);
+            // A rejected save must not silently drop the delta already
+            // applied in-memory — re-park it so the process-exit drain
+            // and/or the retry below still see it.
+            state.failCount += 1;
+            state.dirty = true;
+            _pendingMetricsFlush.set(sessionId, session);
+        })
+        .finally(() => {
+            state.inFlight = false;
+            if (state.closed) {
+                // dropMetricSeenState ran while this save was in flight —
+                // do not resurrect per-session state/timers post-close.
+                _metricSaveState.delete(sessionId);
+                _pendingMetricsFlush.delete(sessionId);
+                return;
+            }
+            // A newer delta (or the rejection re-park above) landed while
+            // this save was in flight — flush once more so it is never
+            // stranded. Always take the LATEST parked session, not the
+            // (possibly stale/pre-detach-resume) closure `session` — a
+            // newer delta may have parked a fresher session/generation.
+            // failCount cap: a persistently failing save (broken dir/disk)
+            // must not spin reject→re-park→retry forever with no backoff.
+            // The session stays parked in _pendingMetricsFlush, so a later
+            // _scheduleMetricsSave (next iteration) or the process-exit
+            // drain still gets a shot at persisting it.
+            if (state.dirty && state.failCount <= 3) {
+                const latest = _pendingMetricsFlush.get(sessionId) ?? session;
+                _flushMetricsSave(latest, sessionId);
+            }
+        });
+}
+
+/**
+ * Coalesce mid-turn metric saves: an in-flight guard collapses overlapping
+ * saves into one trailing flush, and a >=500ms per-session throttle caps
+ * how often a completed save re-triggers another. The idempotency Set above
+ * still updates per-iteration regardless of whether this call ends up
+ * actually posting to the worker this tick.
+ */
+function _scheduleMetricsSave(session, sessionId) {
+    const state = _metricsSaveState(sessionId);
+    if (state.closed) return;
+    if (state.inFlight) {
+        state.dirty = true;
+        _pendingMetricsFlush.set(sessionId, session);
+        return;
+    }
+    const elapsed = Date.now() - state.lastFlushAt;
+    if (elapsed >= METRICS_SAVE_THROTTLE_MS) {
+        _flushMetricsSave(session, sessionId);
+        return;
+    }
+    state.dirty = true;
+    _pendingMetricsFlush.set(sessionId, session);
+    if (!state.timer) {
+        const t = setTimeout(() => {
+            state.timer = null;
+            if (!state.inFlight && !state.closed) {
+                const latest = _pendingMetricsFlush.get(sessionId) ?? session;
+                _flushMetricsSave(latest, sessionId);
+            }
+        }, METRICS_SAVE_THROTTLE_MS - elapsed);
+        if (t.unref) t.unref();
+        state.timer = t;
+    }
+}
+
+// Process exit can land inside the throttle window, before the trailing
+// timer above ever calls saveSessionAsync (which would otherwise register
+// with store.mjs's own drainSessionStore-covered worker queue). Sync-flush
+// any such still-deferred session here so a normal-completion turn that
+// happens to exit mid-throttle never loses the latest iteration delta.
+process.on('exit', () => {
+    for (const [sessionId, session] of _pendingMetricsFlush) {
+        try { _saveSessionSync(session, { expectedGeneration: session.generation }); }
+        catch { /* best-effort: process is exiting */ }
+    }
+    _pendingMetricsFlush.clear();
+});
+
 // Injected accessor for manager's _runtimeState. Defaults to a no-op lookup so
 // the pure helpers remain usable (and unit-testable) before wiring.
 let _getRuntimeEntry = () => null;
@@ -23,7 +142,20 @@ export function configureUsageMetricsRuntime({ getRuntimeEntry } = {}) {
 
 /** Drop the per-session metric-idempotency Set (called on session close). */
 export function dropMetricSeenState(sessionId) {
-    if (sessionId) _metricSeenIter.delete(sessionId);
+    if (!sessionId) return;
+    _metricSeenIter.delete(sessionId);
+    const state = _metricSaveState.get(sessionId);
+    if (state) {
+        state.closed = true;
+        if (state.timer) { clearTimeout(state.timer); state.timer = null; }
+        // Only delete the map entry when nothing is in flight — an in-flight
+        // save's own .finally (guarded by state.closed above) performs the
+        // cleanup itself once it settles, so a stray concurrent call cannot
+        // recreate a fresh (non-closed) entry via _metricsSaveState() while
+        // that write is still outstanding.
+        if (!state.inFlight) _metricSaveState.delete(sessionId);
+    }
+    _pendingMetricsFlush.delete(sessionId);
 }
 
 /** Monotonic per-session ask/turn id for incremental usage idempotency. */
@@ -206,5 +338,12 @@ export async function persistIterationMetrics(delta) {
     }
     session.lastIterationIndex = iterationIndex;
     session.updatedAt = ts || Date.now();
-    await saveSessionAsync(session, { expectedGeneration: session.generation });
+    // Coalesced mid-turn persistence (see _scheduleMetricsSave above): an
+    // in-flight guard + >=500ms per-session throttle collapse the per-
+    // iteration saveSessionAsync postMessage/clone cost. The idempotency Set
+    // update above already happened unconditionally this call, so a
+    // throttled/skipped flush here never loses delta accounting — only the
+    // disk-write cadence changes. Terminal save at turn end (askSession) and
+    // the exit drain above both still cover the last pending delta.
+    _scheduleMetricsSave(session, sessionId);
 }

package/src/runtime/agent/orchestrator/session/store-summary-index.mjs

@@ -8,7 +8,7 @@
 import { mkdirSync } from 'fs';
 import { join } from 'path';
 import { getPluginData } from '../config.mjs';
-import { updateJsonAtomicSync, writeJsonAtomicSync } from '../../../shared/atomic-file.mjs';
+import { updateJsonAtomicSync, updateJsonAtomic, writeJsonAtomicSync } from '../../../shared/atomic-file.mjs';
 
 export const SESSION_SUMMARY_INDEX_VERSION = 1;
 
@@ -158,34 +158,115 @@ export function _writeSummaryIndex(rows) {
     return cleanRows;
 }
 
-export function _upsertSessionSummary(session) {
-    const row = _sessionSummary(session);
-    if (!row) return;
-    try {
-        updateJsonAtomicSync(summaryIndexPath(), (cur) => {
+// ── Non-blocking upsert/remove ──────────────────────────────────────────────
+// The summary index is a best-effort sidecar, but its writers used to take
+// the cross-process file lock with the DEFAULT 8s timeout — and
+// withFileLockSync waits with Atomics.wait, which BLOCKS the main thread.
+// Every session save calls _upsertSessionSummary, so with several mixdog
+// processes (TUI + agent workers + memory service) contending on a multi-MB
+// index, a busy lock froze typing/rendering for seconds at a time.
+// Now: callers only QUEUE the mutation (O(1), no I/O) and the flush runs on
+// a deferred tick with a ZERO-WAIT try-lock — if another process holds the
+// lock we never sleep on it, we re-queue and retry on an unref'd timer. The
+// caller's thread never blocks on this lock at all.
+const SUMMARY_LOCK_TIMEOUT_MS = 0; // try-lock: acquire-or-fail, never wait
+const SUMMARY_RETRY_DELAY_MS = 1000;
+const _pendingUpserts = new Map(); // id → summary row (latest wins)
+const _pendingRemovals = new Set(); // ids to drop (upsert/removal are mutually exclusive per id)
+let _summaryRetryTimer = null;
+let _summaryFlushScheduled = false;
+
+function _scheduleSummaryRetry() {
+    if (_summaryRetryTimer) return;
+    _summaryRetryTimer = setTimeout(() => {
+        _summaryRetryTimer = null;
+        _flushPendingSummaryOps();
+    }, SUMMARY_RETRY_DELAY_MS);
+    _summaryRetryTimer.unref?.();
+}
+
+// Defer the flush off the caller's stack: the 1MB+ parse/stringify inside
+// updateJsonAtomicSync (~10ms on a warm cache) has no business on the
+// keystroke/session-save path.
+function _scheduleSummaryFlush() {
+    if (_summaryFlushScheduled) return;
+    _summaryFlushScheduled = true;
+    setImmediate(() => {
+        _summaryFlushScheduled = false;
+        _flushPendingSummaryOps();
+    });
+}
+
+export function _flushPendingSummaryOps({ sync = false } = {}) {
+    if (_pendingUpserts.size === 0 && _pendingRemovals.size === 0) return;
+    // Snapshot + clear first: ops queued by other callers DURING the flush
+    // must not be lost, and a failed flush re-queues only what it took
+    // (without clobbering anything newer queued meanwhile).
+    const upserts = new Map(_pendingUpserts);
+    const removals = new Set(_pendingRemovals);
+    _pendingUpserts.clear();
+    _pendingRemovals.clear();
+    const mutate = (cur) => {
             const index = _normalizeSummaryIndex(cur);
-            const rows = index.rows.filter((r) => r.id !== row.id);
-            const cleanRow = _normalizeSummaryRow(row);
-            if (!cleanRow) return undefined;
-            const existing = index.rows.find((r) => r.id === row.id) || null;
-            if (existing && JSON.stringify(existing) === JSON.stringify(cleanRow)) return undefined;
-            rows.push(cleanRow);
+            let changed = false;
+            const rows = index.rows.filter((r) => {
+                if (removals.has(r.id) || upserts.has(r.id)) { changed = true; return false; }
+                return true;
+            });
+            for (const row of upserts.values()) {
+                const cleanRow = _normalizeSummaryRow(row);
+                if (!cleanRow) continue;
+                const existing = index.rows.find((r) => r.id === cleanRow.id) || null;
+                if (existing && JSON.stringify(existing) === JSON.stringify(cleanRow)) {
+                    rows.push(existing);
+                    continue;
+                }
+                rows.push(cleanRow);
+                changed = true;
+            }
+            if (!changed) return undefined;
             rows.sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
             return { version: SESSION_SUMMARY_INDEX_VERSION, updatedAt: Date.now(), rows };
-        }, { compact: true, lock: true });
-    } catch { /* summary index is best-effort */ }
+    };
+    const requeue = () => {
+        // Lock busy (or transient I/O failure) — re-queue what we took unless
+        // a newer op for the same id arrived during the flush, then retry
+        // asynchronously.
+        for (const [id, row] of upserts) {
+            if (!_pendingUpserts.has(id) && !_pendingRemovals.has(id)) _pendingUpserts.set(id, row);
+        }
+        for (const id of removals) {
+            if (!_pendingUpserts.has(id)) _pendingRemovals.add(id);
+        }
+        _scheduleSummaryRetry();
+    };
+    // Exit-drain path needs the synchronous write (the loop may not pump
+    // after 'exit'). Normal scheduled flushes on the lead/TUI main process
+    // use the async try-lock: the lock WAIT is off the event loop, so a
+    // busy multi-MB index never freezes typing/rendering.
+    if (sync) {
+        try {
+            updateJsonAtomicSync(summaryIndexPath(), mutate, { compact: true, lock: true, timeoutMs: SUMMARY_LOCK_TIMEOUT_MS });
+        } catch { requeue(); }
+        return;
+    }
+    updateJsonAtomic(summaryIndexPath(), mutate, { compact: true, lock: true, timeoutMs: SUMMARY_LOCK_TIMEOUT_MS })
+        .catch(() => { requeue(); });
+}
+
+export function _upsertSessionSummary(session) {
+    const row = _sessionSummary(session);
+    if (!row) return;
+    _pendingRemovals.delete(row.id);
+    _pendingUpserts.set(row.id, row);
+    _scheduleSummaryFlush();
 }
 
 export function _removeSessionSummary(id) {
     if (!id) return;
-    try {
-        updateJsonAtomicSync(summaryIndexPath(), (cur) => {
-            const index = _normalizeSummaryIndex(cur);
-            const rows = index.rows.filter((r) => r.id !== id);
-            if (rows.length === index.rows.length) return undefined;
-            return { version: SESSION_SUMMARY_INDEX_VERSION, updatedAt: Date.now(), rows };
-        }, { compact: true, lock: true });
-    } catch { /* summary index is best-effort */ }
+    _pendingUpserts.delete(id);
+    _pendingRemovals.add(id);
+    _scheduleSummaryFlush();
 }
 
 /**
@@ -196,12 +277,9 @@ export function _removeSessionSummary(id) {
  */
 export function _pruneSummaryIndexIds(ids) {
     if (!(ids instanceof Set) || ids.size === 0) return;
-    try {
-        updateJsonAtomicSync(summaryIndexPath(), (cur) => {
-            const index = _normalizeSummaryIndex(cur);
-            const rows = index.rows.filter((r) => !ids.has(r.id));
-            if (rows.length === index.rows.length) return undefined;
-            return { version: SESSION_SUMMARY_INDEX_VERSION, updatedAt: Date.now(), rows };
-        }, { compact: true, lock: true });
-    } catch { /* summary index is best-effort */ }
+    for (const id of ids) {
+        _pendingUpserts.delete(id);
+        _pendingRemovals.add(id);
+    }
+    _scheduleSummaryFlush();
 }

package/src/runtime/agent/orchestrator/session/store.mjs

@@ -21,6 +21,7 @@ import {
     _upsertSessionSummary,
     _removeSessionSummary,
     _pruneSummaryIndexIds,
+    _flushPendingSummaryOps,
 } from './store-summary-index.mjs';
 // Facade re-export: summary-index API moved to store-summary-index.mjs; keep
 // prior importers of store.mjs unchanged.
@@ -404,6 +405,10 @@ export function drainSessionStore() {
         }
     }
     _savePending.clear();
+    // Summary-index ops queued by the deferred/no-wait flush path: give them
+    // one last best-effort flush before exit (still zero-wait; losing them is
+    // acceptable — the index self-heals on next rebuild).
+    try { _flushPendingSummaryOps({ sync: true }); } catch { /* best-effort */ }
     // Outstanding worker-queue writes: process exit may interrupt the worker
     // thread before it processes its message queue, so each pending payload
     // is sync-flushed directly here. The Promise is then rejected so the

package/src/runtime/agent/orchestrator/stall-policy.mjs

@@ -68,13 +68,17 @@ export const DEFAULT_ACTIVITY_HEARTBEAT_MS = resolveTimeoutMs(
 
 export const PROVIDER_FIRST_BYTE_TIMEOUT_MS = resolveTimeoutMs(
     'MIXDOG_PROVIDER_FIRST_BYTE_TIMEOUT_MS',
-    // 2026-07 trace audit: heavy-worker claude-sonnet-5 xhigh TTFT distribution
-    // showed avg ~25s, max ~120s (15/75 requests over 60s) — the old 120s
-    // window sat exactly on the observed tail and killed/retried healthy slow
-    // first bytes (9 first-byte retries in one 75-iteration session, plus one
-    // full turn lost). 180s clears the tail while the mid-stream retry ladder
-    // and the agent stall watchdog still bound a truly dead socket.
-    Math.min(180_000, PROVIDER_MAX_BEFORE_WARN_MS),
+    // 2026-07-05 trace audit (24h): worker claude-sonnet-5 successful TTFT
+    // p90 43s / p99 164s / max 171s — the distribution hugs the previous 180s
+    // window, and 16/178 fetches "died" in repeated back-to-back 183s
+    // fetch→fetch cycles (3+ consecutive in the worst session). That pattern
+    // is queued-but-alive first bytes being axed AT the window and re-queued
+    // from scratch, not dead sockets: each trip doubled the wait (one worker
+    // session burned ~40min purely on 180s-abort→retry loops). Raise to the
+    // policy ceiling (STALL_WARN - tick, ~285s): models with fast first bytes
+    // never reach the timer, and a truly wedged socket is still bounded by
+    // the agent stall first-byte abort (300s, DEFAULT_STALL_FIRST_BYTE_ABORT_S).
+    PROVIDER_MAX_BEFORE_WARN_MS,
     { minMs: MIN_PROVIDER_TIMEOUT_MS, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
 );
 
@@ -140,11 +144,17 @@ export const PROVIDER_SSE_IDLE_TIMEOUT_MS = resolveTimeoutMs(
 // env-overridable and disablable via MIXDOG_ENABLE_STREAM_WATCHDOG=0.
 export const PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS = resolveTimeoutMs(
     ['MIXDOG_PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS', 'MIXDOG_PROVIDER_SSE_IDLE_TIMEOUT_MS'],
-    // Raised 120s→180s alongside PROVIDER_FIRST_BYTE_TIMEOUT_MS (see comment
-    // there): observed healthy inter-event gaps on xhigh reasoning streams
-    // brushed the old 120s window; stalls after a tool emit are unretryable,
-    // so a false trip there costs the whole turn.
-    180_000,
+    // 2026-07-05 trace audit: effort-mode (output_config.effort) sonnet-5
+    // streams deliver NO deltas during the thinking phase — the whole
+    // thinking+text body flushes at the end (44/47 slow turns had
+    // stream_total-ttft < 2s; silent-window token rate a steady ~92 tok/s,
+    // i.e. live generation, not a wedge). Successful turns topped out at
+    // ttft 171s while 13 kills sat at exactly ~183s fetch→fetch — the old
+    // 180s window was beheading every turn whose silent thinking ran past
+    // it, then retrying the whole thinking run from zero. Raised to the
+    // policy ceiling (STALL_WARN - tick ≈ 285s); the agent stall watchdog
+    // (worker 300s) remains the true-wedge backstop just above it.
+    PROVIDER_MAX_BEFORE_WARN_MS,
     { minMs: 10_000, maxMs: STALL_WARN_MS },
 );
 

package/src/runtime/agent/orchestrator/tools/builtin/builtin-tools.mjs

@@ -117,7 +117,9 @@ export const BUILTIN_TOOLS = [
                 offset: { type: 'number', minimum: 0, description: 'Skip output lines for paging.' },
                 '-A': { type: 'number', minimum: 0, description: 'Lines after each match.' },
                 '-B': { type: 'number', minimum: 0, description: 'Lines before each match.' },
-                '-C': { type: 'number', minimum: 0, description: 'Lines before/after each match.' },
+                // Description nudges -C 5 on content modes — measured fix for
+                // grep→read same-file re-open round-trips (2026-07 diag).
+                '-C': { type: 'number', minimum: 0, description: 'Lines before/after each match. Content modes: pass -C 5+ so the hit is edit-ready; skipping it forces a follow-up read.' },
             },
             required: [],
         },

package/src/runtime/agent/orchestrator/tools/builtin/read-single-tool.mjs

@@ -1,4 +1,4 @@
-import { closeSync, lstatSync, openSync, readFileSync, readSync, realpathSync, readdirSync, statSync } from 'fs';
+import { lstatSync, realpathSync, readdirSync, statSync } from 'fs';
 import * as fsPromises from 'fs/promises';
 import { readFile } from 'fs/promises';
 import { extname } from 'path';
@@ -26,12 +26,12 @@ function withSymbolReadNote(text, args) {
 // decoding. utf8-with-BOM (EF BB BF) keeps the utf-8 decoder; its leading
 // U+FEFF is stripped for display downstream, so bomLen is reported but not
 // applied for utf8.
-function detectReadEncoding(fullPath) {
-    let fd;
+async function detectReadEncoding(fullPath) {
+    let fh;
     try {
-        fd = openSync(fullPath, 'r');
+        fh = await fsPromises.open(fullPath, 'r');
         const head = Buffer.alloc(3);
-        const n = readSync(fd, head, 0, 3, 0);
+        const { bytesRead: n } = await fh.read(head, 0, 3, 0);
         if (n >= 2 && head[0] === 0xff && head[1] === 0xfe) {
             return { encoding: 'utf16le', bomLen: 2 };
         }
@@ -45,7 +45,7 @@ function detectReadEncoding(fullPath) {
     } catch {
         return { encoding: 'utf8', bomLen: 0 };
     } finally {
-        if (fd !== undefined) { try { closeSync(fd); } catch {} }
+        if (fh !== undefined) { try { await fh.close(); } catch {} }
     }
 }
 
@@ -260,17 +260,17 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
     // entry stores a contentPrefixHash, recompute the current prefix and bail
     // to a fresh read on mismatch. Helper kept local (not hoisted) so it can
     // close over fullPath and st without an extra arg.
-    const _readPrefixHashForCacheGuard = () => {
+    const _readPrefixHashForCacheGuard = async () => {
         try {
             if (st.size <= 65536) {
-                return _hashText(readFileSync(fullPath, 'utf-8'));
+                return _hashText(await readFile(fullPath, 'utf-8'));
             }
-            const _fd = openSync(fullPath, 'r');
+            const _fh = await fsPromises.open(fullPath, 'r');
             try {
                 const _buf = Buffer.allocUnsafe(65536);
-                const _n = readSync(_fd, _buf, 0, 65536, 0);
+                const { bytesRead: _n } = await _fh.read(_buf, 0, 65536, 0);
                 return _hashText(_buf.subarray(0, _n));
-            } finally { try { closeSync(_fd); } catch {} }
+            } finally { try { await _fh.close(); } catch {} }
         } catch { return ''; }
     };
     const cachedEntry = _cacheGetEntry(cacheKey);
@@ -295,7 +295,7 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
                 // exact full contentHash when present, else the prefix hash
                 // (also full-body here). A read failure drops to fresh read.
                 try {
-                    const _freshHash = _hashText(readFileSync(fullPath, 'utf-8'));
+                    const _freshHash = _hashText(await readFile(fullPath, 'utf-8'));
                     const _expect = _snapHash || _prefixHash;
                     if (!_freshHash || _freshHash !== _expect) _entryStillValid = false;
                 } catch { _entryStillValid = false; }
@@ -310,7 +310,7 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
                 // writes through edit/apply_patch/write invalidate by path,
                 // and shell mutationMode='global' wipes both builtin +
                 // code-graph caches, bounding stale risk past the head.
-                const _curHash = _readPrefixHashForCacheGuard();
+                const _curHash = await _readPrefixHashForCacheGuard();
                 if (!_curHash || _curHash !== _prefixHash) _entryStillValid = false;
             }
         }
@@ -377,7 +377,7 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
             && typeof _snap.contentHash === 'string'
             && _snap.contentHash) {
             let _diskHash = '';
-            try { _diskHash = _hashText(readFileSync(fullPath, 'utf-8')); } catch {}
+            try { _diskHash = _hashText(await readFile(fullPath, 'utf-8')); } catch {}
             if (_diskHash && _diskHash === _snap.contentHash) {
                 if (options?.suppressReadUnchangedStub !== true) {
                     return withSymbolReadNote(`[file unchanged: ${normalizeOutputPath(filePath)}]`, args);
@@ -389,7 +389,7 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
     // large UTF-16LE+BOM file is recognized as text up front and routed to
     // the bounded in-memory utf16le path below, never mis-decoded as utf-8
     // or rejected by the utf-8 streaming/binary branch (Bug 1).
-    const _readEnc = detectReadEncoding(fullPath);
+    const _readEnc = await detectReadEncoding(fullPath);
     // UTF-16 (LE or BE) reads share one constraint: the streaming/binary
     // paths decode chunks as utf-8, so a BOM-flagged UTF-16 file must route
     // to the bounded in-memory decode below regardless of byte order.

package/src/runtime/agent/orchestrator/tools/builtin/snapshot-store.mjs

@@ -126,7 +126,7 @@ function _reviveInfinitySentinels(value) {
     return value;
 }
 
-function persistScopeSync(scopeKey) {
+function persistScopeSync(scopeKey, { exitDrain = false } = {}) {
     const path = snapshotScopeFilePath(scopeKey);
     if (!path) return;
     const readFiles = readFilesByScope.get(scopeKey);
@@ -141,6 +141,14 @@ function persistScopeSync(scopeKey) {
         writeJsonAtomicSync(path, _withInfinitySentinels(obj), {
             compact: true,
             lock: true,
+            // Try-once (timeoutMs:0): scheduleScopePersist fires this from the
+            // debounced timer on the lead/TUI main process after every read/grep
+            // tool. withFileLockSync's Atomics.wait would block the loop on
+            // cross-process contention; best-effort — a busy lock just drops
+            // this flush (the next read re-schedules, exit-drain still writes).
+            // Exit drain uses a short blocking wait instead so the final flush
+            // is not silently dropped under contention (loop no longer matters).
+            timeoutMs: exitDrain ? 1000 : 0,
             mode: 0o600,
             fsync: false,
             fsyncDir: false,
@@ -191,7 +199,7 @@ export function scheduleScopePersist(scopeKey) {
 function flushAllScopesSync() {
     for (const [key, timer] of persistPending) {
         try { clearTimeout(timer); } catch {}
-        try { persistScopeSync(key); } catch {}
+        try { persistScopeSync(key, { exitDrain: true }); } catch {}
     }
     persistPending.clear();
 }

package/src/runtime/agent/orchestrator/tools/code-graph/disk-cache.mjs

@@ -301,7 +301,13 @@ function _persistDiskCodeGraphCacheNow() {
     for (const [cwd, entry] of _diskCodeGraphCache) {
       const hash = _hashCwd(cwd);
       const file = join(dir, `${hash}.json`);
-      writeJsonAtomicSync(file, entry, { compact: true, lock: true });
+      // Try-once (timeoutMs:0): the debounced flush runs on the lead/TUI main
+      // process (codeGraph tool + prewarm). withFileLockSync's Atomics.wait
+      // would freeze the renderer on cross-process cache contention. Cache is
+      // rebuildable — a busy lock just skips this flush; _scheduleDiskCodeGraphCacheFlush
+      // re-schedules on the next build. Exit drain still runs (unref'd timer
+      // cancelled + direct call).
+      writeJsonAtomicSync(file, entry, { compact: true, lock: true, timeoutMs: 0 });
       manifest[cwd] = { hash, builtAt: entry.builtAt || Date.now() };
     }
     const pruned = _pruneCodeGraphManifestForBudget(manifest, dir);
@@ -314,7 +320,7 @@ function _persistDiskCodeGraphCacheNow() {
     }
 
     const manifestFile = join(dir, 'manifest.json');
-    writeJsonAtomicSync(manifestFile, manifest, { compact: true, lock: true });
+    writeJsonAtomicSync(manifestFile, manifest, { compact: true, lock: true, timeoutMs: 0 });
     _diskManifest = manifest;
 
     // Sweep orphan per-cwd files. validHashes now includes every hash in

package/src/runtime/channels/backends/discord-attachments.mjs

@@ -5,13 +5,13 @@ import { join, sep } from "path";
 
 const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
 
-async function downloadSingleAttachment(att, inboxDir) {
+async function downloadSingleAttachment(att, inboxDir, { timeoutMs = 180_000 } = {}) {
   if (att.size > MAX_ATTACHMENT_BYTES) {
     throw new Error(
       `attachment too large: ${(att.size / 1024 / 1024).toFixed(1)}MB, max ${MAX_ATTACHMENT_BYTES / 1024 / 1024}MB`
     );
   }
-  const res = await fetch(att.url, { signal: AbortSignal.timeout(180_000) });
+  const res = await fetch(att.url, { signal: AbortSignal.timeout(timeoutMs) });
   if (!res.ok) {
     throw new Error(`attachment download failed: HTTP ${res.status}`);
   }

package/src/runtime/channels/backends/discord-gateway.mjs

@@ -212,13 +212,23 @@ async function awaitLogin(self) {
       resolve();
     });
   });
+  // Observe the ready timer from the start: login() can hang past the 30s
+  // timer (gateway reconnect), and a rejection on an un-awaited readyPromise
+  // becomes a process-global unhandledRejection → fatal crash path
+  // (channels/index.mjs unhandledRejection → _fatalCrash → exit(1)). Racing
+  // login with readyPromise keeps the rejection inside this connect() chain,
+  // which every caller already catches non-fatally.
+  const loginPromise = self.client.login(self.token);
+  // A late login settlement after the timeout raced ahead must not itself
+  // become a second unhandled rejection.
+  loginPromise.catch(() => {});
   try {
-    await self.client.login(self.token);
+    await Promise.race([loginPromise, readyPromise]);
+    await readyPromise;
   } catch (err) {
     clearTimeout(readyTimeout);
     throw err;
   }
-  await readyPromise;
 }
 
 export {