mixdog 0.9.95 → 0.9.96

package/src/runtime/memory/lib/http-router.mjs

@@ -171,6 +171,7 @@ export function createHttpRouter({
       try {
         const db = getDb()
         const stats = await entryStats()
+        const memory = process.memoryUsage()
         sendJson(res, {
           status: 'ok',
           worker_pid: process.pid,
@@ -192,6 +193,13 @@ export function createHttpRouter({
           cycle_running: cycleScheduler.getCycleRunning(),
           cycle_health: cycleScheduler.getCycleHealth(),
           cycle_backlog: cycleScheduler.getCycleBacklogSnapshot(),
+          memory: {
+            rssBytes: memory.rss,
+            heapTotalBytes: memory.heapTotal,
+            heapUsedBytes: memory.heapUsed,
+            externalBytes: memory.external,
+            arrayBufferBytes: memory.arrayBuffers,
+          },
         })
       } catch (e) { sendError(res, e.message) }
       return

package/src/runtime/memory/lib/ko-morph.mjs

@@ -15,7 +15,6 @@
 //   analyze(text)  — sync; returns TokenInfo[] or null when not ready.
 //   stems(text)    — sync; content-morpheme stems (NNG/NNP/VV/VA/XR/SL) or null.
 import fs from 'node:fs'
-import os from 'node:os'
 import path from 'node:path'
 import zlib from 'node:zlib'
 
@@ -54,11 +53,7 @@ let _idleTimer = null
 const _envIdleMs = Number(process.env.MIXDOG_KO_MORPH_IDLE_TIMEOUT_MS)
 const IDLE_TIMEOUT_MS = Number.isFinite(_envIdleMs) && _envIdleMs >= 0
   ? _envIdleMs
-  : 2 * 60_000
-const _envPressureMb = Number(process.env.MIXDOG_KO_MORPH_PRESSURE_MIN_FREE_MB)
-const PRESSURE_MIN_FREE_BYTES = (
-  Number.isFinite(_envPressureMb) && _envPressureMb >= 0 ? _envPressureMb : 1536
-) * 1024 * 1024
+  : 60_000
 
 export function isReady() { return _state === 'ready' && _kiwi != null }
 export function state() { return _state }
@@ -78,14 +73,8 @@ function releaseLoaded(reason = '') {
 
 function touchIdleTimer() {
   if (_idleTimer) clearTimeout(_idleTimer)
-  let delay = IDLE_TIMEOUT_MS
-  try {
-    if (PRESSURE_MIN_FREE_BYTES > 0 && os.freemem() < PRESSURE_MIN_FREE_BYTES) delay = 1
-  } catch {}
-  if (delay <= 0) return
-  _idleTimer = setTimeout(() => releaseLoaded(
-    delay <= 1 ? 'host memory pressure' : 'idle timeout',
-  ), delay)
+  if (IDLE_TIMEOUT_MS <= 0) return
+  _idleTimer = setTimeout(() => releaseLoaded('idle timeout'), IDLE_TIMEOUT_MS)
   _idleTimer.unref?.()
 }
 
@@ -166,12 +155,6 @@ export async function init(dataDir, log = () => {}) {
     return true
   }
   if (_initPromise) return _initPromise
-  try {
-    if (PRESSURE_MIN_FREE_BYTES > 0 && os.freemem() < PRESSURE_MIN_FREE_BYTES) {
-      _log('[memory-service] kiwi morph load deferred under host memory pressure\n')
-      return false
-    }
-  } catch {}
   _state = 'loading'
   const t0 = Date.now()
   _log(`[memory-service] kiwi morph init start (model ${KIWI_MODEL_VERSION})\n`)

package/src/runtime/memory/lib/memory-action-handlers.mjs

@@ -33,6 +33,7 @@ import {
   promoteCoreCandidate,
   dismissCoreCandidate,
   normalizeCoreInput,
+  normalizeCoreOp,
 } from './core-memory-store.mjs'
 import { resolveProjectId, resolveProjectScope } from './project-id-resolver.mjs'
 import { resolvePluginData } from '../../shared/plugin-paths.mjs'
@@ -602,7 +603,7 @@ export function createMemoryActionHandlers({
     }
 
     if (action === 'core') {
-      const op = String(args.op ?? '').trim().toLowerCase()
+      const op = normalizeCoreOp(args.op)
       if (!['add', 'edit', 'delete', 'list', 'candidates', 'promote', 'dismiss'].includes(op)) {
         return { text: 'core requires op: "add" | "edit" | "delete" | "list" | "candidates" | "promote" | "dismiss"', isError: true }
       }

package/src/runtime/memory/lib/memory-cycle1.mjs

@@ -634,6 +634,7 @@ async function _runCycle1Impl(db, config = {}, options = {}, _dataDir = null) {
         timeout,
         // Pin cwd to null so every memory cycle call hits the same agent cache shard.
         cwd: null,
+        signal,
       }, userMessage)
       throwIfAborted(signal)
       __mixdogMemoryLog(`[cycle1-time] window=${windowIdx} llmMs=${Date.now() - _tLlm}\n`)

package/src/runtime/memory/lib/memory-cycle2-gate.mjs

@@ -32,7 +32,7 @@ const isShiftFollowToken = (tok) => {
   return ALL_PRIMARY_VERBS.has(v) || v === 'why' || v === 'core'
 }
 
-async function invokeLlm(prompt, mode, preset, timeout, llmCall = callAgentDispatch) {
+async function invokeLlm(prompt, mode, preset, timeout, llmCall = callAgentDispatch, signal = null) {
   return await llmCall({
     agent: 'cycle2-agent',
     taskType: 'maintenance',
@@ -40,6 +40,7 @@ async function invokeLlm(prompt, mode, preset, timeout, llmCall = callAgentDispa
     preset,
     timeout,
     cwd: null,
+    signal,
   }, prompt)
 }
 
@@ -357,7 +358,7 @@ export async function runUnifiedGate(db, rows, activeContext, config = {}, optio
   const callOnce = async (extraTag) => {
     throwIfAborted(signal)
     const p = extraTag ? `${prompt}\n\n[retry:${extraTag}]` : prompt
-    const raw = await invokeLlm(p, mode, preset, timeout, options.callLlm)
+    const raw = await invokeLlm(p, mode, preset, timeout, options.callLlm, signal)
     throwIfAborted(signal)
     return raw
   }
@@ -518,6 +519,7 @@ export async function sonnetCascade(candidates, rulesDigest, options = {}) {
       preset,
       timeout: 600000,
       cwd: null,
+      signal,
     }, prompt)
   } catch (err) {
     if (signal?.aborted) throw signal.reason ?? err

package/src/runtime/memory/lib/memory-cycle2-mutations.mjs

@@ -322,6 +322,7 @@ async function _llmJudgePair(summaryA, summaryB, siblingContext = [], options =
       preset: options.preset || resolveMaintenancePreset('memory'),
       timeout: 30000,
       cwd: null,
+      signal,
     }, prompt)
     throwIfAborted(signal)
     return String(raw ?? '').trim().toLowerCase().startsWith('merge')

package/src/runtime/memory/lib/memory-cycle3.mjs

@@ -36,7 +36,7 @@ function resourceDir() {
   return process.env.MIXDOG_ROOT || fileURLToPath(new URL('../../../..', import.meta.url))
 }
 
-async function invokeLlm(prompt, mode, preset, timeout, llmCall = callAgentDispatch) {
+async function invokeLlm(prompt, mode, preset, timeout, llmCall = callAgentDispatch, signal = null) {
   return await llmCall({
     agent: 'cycle3-agent',
     taskType: 'maintenance',
@@ -44,6 +44,7 @@ async function invokeLlm(prompt, mode, preset, timeout, llmCall = callAgentDispa
     preset,
     timeout,
     cwd: null,
+    signal,
   }, prompt)
 }
 
@@ -55,6 +56,7 @@ export async function invokeCycle3Maintenance(prompt, options = {}) {
     preset,
     Number(options.timeout ?? 600000),
     options.callLlm,
+    options.signal,
   )
 }
 

package/src/runtime/memory/lib/pg/process.mjs

@@ -107,6 +107,7 @@ async function findFreePort(preferred) {
 // ---------------------------------------------------------------------------
 
 const MIXDOG_CONF_V2_MARKER = '# mixdog overrides v2 — bgwriter / checkpoint distribution'
+const MIXDOG_CONF_V3_MARKER = '# mixdog overrides v3 — bounded local-app resources'
 
 // Lines emitted into postgresql.conf for v2. effective_io_concurrency requires
 // posix_fadvise; PostgreSQL rejects non-zero values on Windows and macOS.
@@ -124,6 +125,21 @@ function buildV2Block() {
   return lines.join('\n') + '\n'
 }
 
+function buildV3Block() {
+  return [
+    '',
+    MIXDOG_CONF_V3_MARKER,
+    // The only long-lived pools are memory(max 5) + trace(max 5). Keep ample
+    // recovery/bootstrap headroom without reserving backend slots for 100
+    // connections this single-user local store can never use.
+    'max_connections = 32',
+    // Mixdog queries are short indexed lookups / bounded batches. LLVM compile
+    // setup adds latency and transient memory; parallel query workers remain
+    // untouched for genuinely large scans.
+    'jit = off',
+  ].join('\n') + '\n'
+}
+
 // Migration: an earlier v2 emitted effective_io_concurrency on every POSIX
 // platform. Strip it anywhere except Linux so old macOS clusters can start.
 function stripPlatformInvalidLines(conf) {
@@ -136,18 +152,25 @@ function ensureConfV2(pgdataDir) {
   if (!existsSync(confPath)) return false
   const original = readFileSync(confPath, 'utf8')
   let conf = stripPlatformInvalidLines(original)
-  const stripped = conf !== original
-  const hasMarker = conf.includes(MIXDOG_CONF_V2_MARKER)
-  if (hasMarker && !stripped) return false
-  if (!hasMarker) conf = conf + buildV2Block()
+  let changed = conf !== original
+  if (!conf.includes(MIXDOG_CONF_V2_MARKER)) {
+    conf += buildV2Block()
+    changed = true
+  }
+  if (!conf.includes(MIXDOG_CONF_V3_MARKER)) {
+    conf += buildV3Block()
+    changed = true
+  }
+  if (!changed) return false
   writeFileSync(confPath, conf)
   return true
 }
 
-// Public reconcile: idempotent conf v2 append + pg_ctl reload on a running
-// instance. Single source of truth for v2 application — supervisor and other
+// Public reconcile: idempotent current override append + pg_ctl reload on a
+// running instance. Single source of truth — supervisor and other
 // callers route through this rather than re-implementing the conf/reload pair.
-// All v2 settings are reload-applicable (no restart required).
+// Reload-compatible settings apply immediately; postmaster settings such as
+// max_connections apply on the next normal PG start (never restart live work).
 export function reconcileConfV2(runtimeDir, pgdataDir) {
   const applied = ensureConfV2(pgdataDir)
   if (!applied) return { applied: false, reloaded: false }
@@ -156,7 +179,7 @@ export function reconcileConfV2(runtimeDir, pgdataDir) {
   })
   const reloaded = reload.status === 0
   if (reloaded) {
-    __mixdogMemoryLog('[pg-process] postgresql.conf v2 overrides applied via pg_ctl reload\n')
+    __mixdogMemoryLog('[pg-process] postgresql.conf overrides reconciled via pg_ctl reload\n')
   } else {
     __mixdogMemoryLog(`[pg-process] pg_ctl reload after v2 append failed (non-fatal): ${reload.stderr?.toString() || ''}\n`)
   }
@@ -252,7 +275,7 @@ export async function startPg({
       'wal_compression = on',              // smaller WAL segments; fewer bytes for Defender to scan per segment
       'wal_init_zero = off',               // skips zero-fill on new WAL segment; cuts Defender contact at segment creation
       'wal_recycle = off',                 // disables WAL rename/recycle loop; eliminates rename-storm EPERM pattern in pgdata
-    ].join('\n') + '\n' + buildV2Block()
+    ].join('\n') + '\n' + buildV2Block() + buildV3Block()
 
     try {
       const existing = readFileSync(confPath, 'utf8')

package/src/runtime/memory/tool-defs.mjs

@@ -10,11 +10,7 @@ export const TOOL_DEFS = [
     name: 'memory',
     title: 'Memory Cycle',
     annotations: { title: 'Memory Cycle', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
-    description: [
-      'Core-memory mutation/status; recall retrieves.',
-      'Mutations use action=core with op; status uses action=status.',
-      'Store only durable compact ENGLISH facts/rules/preferences.',
-    ].join(' '),
+    description: 'Core-memory mutation/status.',
     inputSchema: {
       type: 'object',
       properties: {

package/src/runtime/search/tool-defs.mjs

@@ -8,7 +8,7 @@ export const TOOL_DEFS = [
   {
     name: 'search',
     title: 'Mixdog Web Search',
-    description: `Web/docs/current-info search. ${TOOL_SYNC_EXECUTION_CONTRACT} Cached; query supports array fan-out.`,
+    description: `Cached web/docs/current-info search. ${TOOL_SYNC_EXECUTION_CONTRACT}`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -27,7 +27,7 @@ export const TOOL_DEFS = [
   {
     name: 'web_fetch',
     title: 'Mixdog Web Fetch',
-    description: 'Use after search. Fetch page/docs body from URL.',
+    description: 'Fetch page/docs body from URL.',
     inputSchema: {
       type: 'object',
       properties: {

package/src/runtime/shared/agent-route-config.mjs

@@ -0,0 +1,119 @@
+const LEGACY_AGENT_ROUTE_SLOTS = Object.freeze({
+  explore: Object.freeze({ workflow: 'explorer', maintenance: 'explore' }),
+  maintainer: Object.freeze({ alias: 'maintenance', workflow: 'memory', maintenance: 'memory' }),
+  worker: Object.freeze({ workflow: 'agent' }),
+});
+
+const REDUNDANT_WORKFLOW_PRESET_IDS = new Set([
+  'workflow-agent',
+  'workflow-explorer',
+  'workflow-memory',
+]);
+
+function record(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+export function isCompleteAgentRoute(value) {
+  return !!value
+    && typeof value === 'object'
+    && !Array.isArray(value)
+    && !!String(value.provider || '').trim()
+    && !!String(value.model || '').trim();
+}
+
+function generatedPresetAgentId(preset) {
+  const id = String(preset?.id || '').trim().toLowerCase();
+  if (id === 'workflow-agent') return 'worker';
+  if (id === 'workflow-explorer') return 'explore';
+  if (id === 'workflow-memory') return 'maintainer';
+  if (!id.startsWith('workflow-agent-')) return '';
+  const suffix = id.slice('workflow-agent-'.length);
+  if (suffix === 'explorer' || suffix === 'explore') return 'explore';
+  if (suffix === 'maintenance' || suffix === 'memory' || suffix === 'maintainer') return 'maintainer';
+  return suffix;
+}
+
+function routeFromGeneratedPreset(preset) {
+  const provider = String(preset?.provider || '').trim();
+  const model = String(preset?.model || '').trim();
+  if (!provider || !model) return null;
+  const route = { provider, model };
+  const effort = String(preset?.effort || '').trim();
+  if (effort) route.effort = effort;
+  if (preset?.fast === true) route.fast = true;
+  return route;
+}
+
+export function configuredAgentRouteCandidates(config, agentId) {
+  const id = String(agentId || '').trim();
+  if (!id) return [];
+  const agents = record(config?.agents);
+  const legacy = LEGACY_AGENT_ROUTE_SLOTS[id] || null;
+  const candidates = [agents[id]];
+  if (legacy?.alias) candidates.push(agents[legacy.alias]);
+  if (legacy?.workflow) candidates.push(record(config?.workflowRoutes)[legacy.workflow]);
+  if (legacy?.maintenance) candidates.push(record(config?.maintenance)[legacy.maintenance]);
+  return candidates.filter(Boolean);
+}
+
+export function canonicalizeAgentRoutes(config = {}) {
+  const sourceAgents = record(config.agents);
+  const agents = Object.fromEntries(
+    Object.entries(sourceAgents).filter(([, route]) => isCompleteAgentRoute(route)),
+  );
+  for (const id of Object.keys(LEGACY_AGENT_ROUTE_SLOTS)) {
+    if (agents[id]) continue;
+    const candidate = configuredAgentRouteCandidates({ ...config, agents: sourceAgents }, id)
+      .find((route) => isCompleteAgentRoute(route));
+    if (candidate) agents[id] = candidate;
+  }
+  delete agents.maintenance;
+  // Older settings saves generated one preset per fixed/custom agent. Promote
+  // a preset only when no higher-priority canonical/legacy route exists, then
+  // the redundant preset can be removed without discarding user assignments.
+  for (const preset of Array.isArray(config?.presets) ? config.presets : []) {
+    const id = generatedPresetAgentId(preset);
+    if (!id || agents[id]) continue;
+    const route = routeFromGeneratedPreset(preset);
+    if (route) agents[id] = route;
+  }
+  return agents;
+}
+
+export function isRedundantGeneratedRoutePreset(preset, defaultPreset = null) {
+  const id = String(preset?.id || '').trim();
+  if (!id || id === String(defaultPreset || '').trim()) return false;
+  return REDUNDANT_WORKFLOW_PRESET_IDS.has(id) || id.startsWith('workflow-agent-');
+}
+
+export function canonicalizeAgentRouteStorage(config = {}) {
+  const {
+    workflowRoutes: _legacyWorkflowRoutes,
+    ...rest
+  } = config || {};
+  const maintenance = { ...record(config?.maintenance) };
+  delete maintenance.explore;
+  delete maintenance.memory;
+  const presets = Array.isArray(config?.presets)
+    ? config.presets.filter((preset) => !isRedundantGeneratedRoutePreset(preset, config?.default))
+    : [];
+  return {
+    ...rest,
+    agents: canonicalizeAgentRoutes(config),
+    maintenance,
+    presets,
+  };
+}
+
+export function agentRouteStorageNeedsMigration(config = {}) {
+  const agents = record(config?.agents);
+  const maintenance = record(config?.maintenance);
+  return Object.prototype.hasOwnProperty.call(config || {}, 'workflowRoutes')
+    || Object.prototype.hasOwnProperty.call(agents, 'maintenance')
+    || Object.prototype.hasOwnProperty.call(maintenance, 'explore')
+    || Object.prototype.hasOwnProperty.call(maintenance, 'memory')
+    || Object.values(agents).some((route) => !isCompleteAgentRoute(route))
+    || (Array.isArray(config?.presets)
+      && config.presets.some((preset) => isRedundantGeneratedRoutePreset(preset, config?.default)));
+}

package/src/runtime/shared/atomic-file.mjs

@@ -28,6 +28,55 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 
 const _execFileAsync = promisify(execFile);
 
+// Async atomic writes from many daemon sessions share one disk. Keep enough
+// parallelism for SSD throughput, then use additive-increase/multiplicative-
+// decrease when latency shows the filesystem is saturated. This gate never
+// touches synchronous compatibility paths and never revokes in-flight writes.
+const _ioCeiling = Math.max(1, Math.floor(Number(process.env.MIXDOG_FILE_IO_MAX_CONCURRENCY) || 16));
+let _ioLimit = Math.min(4, _ioCeiling);
+let _ioActive = 0;
+let _ioFastStreak = 0;
+const _ioQueue = [];
+
+function _drainAdaptiveFileIo() {
+  while (_ioActive < _ioLimit && _ioQueue.length > 0) {
+    const item = _ioQueue.shift();
+    _ioActive += 1;
+    const startedAt = Date.now();
+    Promise.resolve()
+      .then(item.run)
+      .then(item.resolve, item.reject)
+      .finally(() => {
+        const elapsed = Date.now() - startedAt;
+        _ioActive = Math.max(0, _ioActive - 1);
+        if (elapsed >= 250) {
+          _ioLimit = Math.max(1, Math.ceil(_ioLimit / 2));
+          _ioFastStreak = 0;
+        } else if (elapsed <= 40 && _ioLimit < _ioCeiling) {
+          _ioFastStreak += 1;
+          if (_ioFastStreak >= _ioLimit * 4) {
+            _ioLimit += 1;
+            _ioFastStreak = 0;
+          }
+        } else {
+          _ioFastStreak = 0;
+        }
+        _drainAdaptiveFileIo();
+      });
+  }
+}
+
+function _runAdaptiveFileIo(run) {
+  return new Promise((resolve, reject) => {
+    _ioQueue.push({ run, resolve, reject });
+    _drainAdaptiveFileIo();
+  });
+}
+
+export function adaptiveFileIoSnapshot() {
+  return { active: _ioActive, queued: _ioQueue.length, limit: _ioLimit, ceiling: _ioCeiling };
+}
+
 const RETRY_CODES = new Set(['EPERM', 'EACCES', 'EBUSY', 'EEXIST']);
 const LOCK_WAIT_CODES = new Set(['EEXIST', 'EPERM', 'EACCES', 'EBUSY']);
 const DEFAULT_BACKOFFS_MS = Object.freeze([25, 50, 100, 200, 400, 800, 1200, 1600]);
@@ -79,6 +128,28 @@ function _describeLockHolder(lockPath) {
   }
 }
 
+// Lock-wait watchdog. A cross-process file lock is invisible in a profile: the
+// only symptom is "everything stopped". One bounded line per path names the
+// path and the wait, so the next stall is diagnosed from the log instead of a
+// live repro.
+const LOCK_WAIT_WARN_MS = 500;
+const LOCK_WAIT_WARN_INTERVAL_MS = 10_000;
+const _lockWaitWarnedAt = new Map();
+function _reportLockWait(lockPath, waitedMs, mode) {
+  if (waitedMs < LOCK_WAIT_WARN_MS) return;
+  const now = Date.now();
+  if (now - (_lockWaitWarnedAt.get(lockPath) || 0) < LOCK_WAIT_WARN_INTERVAL_MS) return;
+  _lockWaitWarnedAt.set(lockPath, now);
+  if (_lockWaitWarnedAt.size > 64) {
+    for (const [path, at] of _lockWaitWarnedAt) {
+      if (now - at >= LOCK_WAIT_WARN_INTERVAL_MS * 6) _lockWaitWarnedAt.delete(path);
+    }
+  }
+  try {
+    process.stderr.write(`[atomic-file] ${mode} lock wait ${waitedMs}ms: ${lockPath}\n`);
+  } catch { /* diagnostics only */ }
+}
+
 export function renameWithRetrySync(src, dst, opts = {}) {
   const backoffs = Array.isArray(opts.backoffs) && opts.backoffs.length > 0
     ? opts.backoffs
@@ -129,6 +200,7 @@ export function withFileLockSync(lockPath, fn, opts = {}) {
   }
   const deadline = Date.now() + timeoutMs;
   mkdirSync(dirname(lockPath), { recursive: true });
+  const waitStartedAt = Date.now();
   let attempt = 0;
   let lastErr = null;
   while (true) {
@@ -168,6 +240,7 @@ export function withFileLockSync(lockPath, fn, opts = {}) {
     // `<pid> <ts> <token>` is a superset of the old `<pid> <ts>`; a
     // tokenless (old-format) lock is still read as pid-authoritative.
     try { writeFileSync(fd, `${process.pid} ${Date.now()} ${_OWNER_TOKEN}\n`, 'utf8'); } catch {}
+    _reportLockWait(lockPath, Date.now() - waitStartedAt, 'sync');
     // For secret-bearing critical sections, the lock file sits beside
     // the secret in the same (shared-home) directory; clamp it owner-only
     // too. Fail-closed: an unenforceable ACL aborts before fn() runs.
@@ -362,6 +435,7 @@ async function _withOsFileLock(lockPath, fn, opts = {}) {
   const staleMs = Number.isFinite(opts.staleMs) ? opts.staleMs : 30000;
   const deadline = Date.now() + timeoutMs;
   mkdirSync(dirname(lockPath), { recursive: true });
+  const waitStartedAt = Date.now();
   let attempt = 0;
   let lastErr = null;
   while (true) {
@@ -393,6 +467,7 @@ async function _withOsFileLock(lockPath, fn, opts = {}) {
       continue;
     }
     try { writeFileSync(fd, `${process.pid} ${Date.now()} ${_OWNER_TOKEN}\n`, 'utf8'); } catch {}
+    _reportLockWait(lockPath, Date.now() - waitStartedAt, 'async');
     _osHeldPaths.add(lockPath);
     try {
       // Async ACL enforcement (promisified execFile) so a secret-bearing
@@ -738,10 +813,11 @@ export async function writeFileAtomicAsync(filePath, data, opts = {}) {
       throw err;
     }
   };
-  if (opts.lock === true) {
-    return withFileLock(`${filePath}.lock`, run, opts);
-  }
-  return run();
+  return _runAdaptiveFileIo(() => (
+    opts.lock === true
+      ? withFileLock(`${filePath}.lock`, run, opts)
+      : run()
+  ));
 }
 
 export function writeJsonAtomicAsync(filePath, value, opts = {}) {

package/src/runtime/shared/channel-notification-routing.mjs

@@ -7,8 +7,8 @@ export function channelNotificationModelContent(params = {}) {
 }
 
 export function shouldMirrorChannelNotificationToPending(meta = {}) {
-  // CC parity (reference messageQueueManager.ts): every inbound channel/
-  // schedule notification flows through the single queue — when no live
+  // Every inbound channel/schedule notification flows through the single
+  // queue — when no live
   // listener handled it (engine not subscribed yet, pane disposed, headless),
   // it is mirrored into the session pending queue for the next turn instead
   // of being dropped. Silent-to-agent stays excluded; the upstream content