mixdog 1.2.2 → 1.2.4

package/src/rules/shared/45-destructive.md

@@ -3,6 +3,10 @@
 - Commit, push, release, deployment and any irreversible action only on the
   user's explicit request. Validate exact targets first: never roots, `~` or
   unresolved variables/globs.
+- Never stash, reset, checkout, restore or clean the working tree, or delete
+  files you did not create: it may hold other agents' or the user's
+  uncommitted work. Use a separate worktree or copy for before/after
+  comparisons.
 - Back up only when changes risk irreversible loss, not for routine code edits;
   keep backups unless the user requests removal. Report what is recoverable.
 - Temp workspaces come from a unique-directory allocator, never by clearing

package/src/runtime/agent/orchestrator/agent-runtime/agent-dispatch/preset.mjs

@@ -30,6 +30,7 @@ function maintenanceRouteToPreset(routeOrName, agent) {
     type: 'agent',
     provider,
     model,
+    ...(routeOrName.fallbacks?.length ? { fallbacks: routeOrName.fallbacks } : {}),
     tools: 'full',
   };
   const effort = String(routeOrName.effort || '').trim();

package/src/runtime/agent/orchestrator/agent-runtime/agent-progress-watchdog.mjs

@@ -11,6 +11,7 @@ import { appendAgentTrace } from '../agent-trace-io.mjs';
 import { getHiddenAgent } from '../internal-agents.mjs';
 import { envNonNegativeInt, envPresent } from '../../../shared/env.mjs';
 import {
+  PROVIDER_FIRST_BYTE_TIMEOUT_MS,
   PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS,
   PROVIDER_WS_SEMANTIC_IDLE_TIMEOUT_MS,
   STALL_TICK_MS,
@@ -45,7 +46,7 @@ export class AgentStallAbortError extends Error {
   }
 }
 
-function isAgentProgressWatchdogAbortError(err) {
+export function isAgentProgressWatchdogAbortError(err) {
   const msg = err?.message;
   return typeof msg === 'string' && WATCHDOG_ABORT_RE.test(msg);
 }
@@ -203,14 +204,34 @@ function resolveExplicitMs(value, fallback) {
   return fallback;
 }
 
+// One deadline floored one watchdog tick above the provider's own budget for
+// that phase (none when the provider names none); 0 stays disabled.
+function aboveProviderBudget(requestedMs, providerBudgetMs) {
+  if (!(requestedMs > 0) || !(providerBudgetMs > 0)) return requestedMs;
+  return Math.max(requestedMs, providerBudgetMs + STALL_TICK_MS);
+}
+
+// `providerFirstByteTimeoutMs` is how long the session's provider itself may
+// wait for response headers, and `providerFirstOutputTimeoutMs` for its first
+// output (headers plus first chunk), its own retries included
+// (providerFirstResponseBudget). Provider retries keep the request clock
+// running, so each first-response deadline sits one watchdog tick above that
+// budget: the provider's timeout and retry decide first, and a provider that
+// gives up is reported as the provider's failure.
 export function resolveAgentWatchdogPolicy(agent, overrides = {}) {
-  const firstTransportMs = resolveExplicitMs(
-    overrides.firstTransportTimeoutMs ?? overrides.firstResponseTimeoutMs,
-    DEFAULT_FIRST_RESPONSE_TIMEOUT_MS
+  const firstTransportMs = aboveProviderBudget(
+    resolveExplicitMs(
+      overrides.firstTransportTimeoutMs ?? overrides.firstResponseTimeoutMs,
+      DEFAULT_FIRST_RESPONSE_TIMEOUT_MS
+    ),
+    resolveExplicitMs(overrides.providerFirstByteTimeoutMs, PROVIDER_FIRST_BYTE_TIMEOUT_MS)
   );
-  const firstSemanticMs = resolveExplicitMs(
-    overrides.firstSemanticTimeoutMs ?? overrides.firstVisibleTimeoutMs,
-    DEFAULT_FIRST_VISIBLE_CEILING_MS
+  const firstSemanticMs = aboveProviderBudget(
+    resolveExplicitMs(
+      overrides.firstSemanticTimeoutMs ?? overrides.firstVisibleTimeoutMs,
+      DEFAULT_FIRST_VISIBLE_CEILING_MS
+    ),
+    resolveExplicitMs(overrides.providerFirstOutputTimeoutMs, 0)
   );
 
   let idleStaleMs;

package/src/runtime/agent/orchestrator/agent-runtime/cache-strategy.mjs

@@ -493,19 +493,10 @@ export function buildProviderCacheOpts(provider, _sessionId, agent, options = {}
   const ttls = resolveCacheStrategy(agent, options);
   const capability = cacheCapabilityForProvider(provider);
   if (capability === 'explicit-breakpoint') {
-    // 2026-03-06 Anthropic dropped default TTL 1h→5m. We send
-    // extended-cache-ttl-2025-04-11 header to retain 1h.
+    // 2026-03-06 Anthropic dropped default TTL 1h→5m. We request 1h via
+    // cache_control ttl:"1h"; no beta header is required.
     // Verified 2026-04-17 (ephemeral_1h_input_tokens=4722).
     return { cacheStrategy: ttls, ...oneShotPromptCacheOpts(agent) };
   }
-  // NOTE: createSession's direct-call site (manager.mjs) only invokes this
-  // for explicit-breakpoint (Anthropic-family) providers, so this branch
-  // stays reachable only from other callers (none in-tree today) — keeping
-  // it here preserves the documented public API/behavior of this function.
-  if (provider === 'openai') {
-    // Public OpenAI API: prompt_cache_retention extends prefix retention.
-    // openai-oauth rejects the header — falls through to default.
-    return { cacheRetention: '24h' };
-  }
   return {};
 }

package/src/runtime/agent/orchestrator/agent-trace-io.mjs

@@ -21,7 +21,8 @@ let _serviceUrl = null;
 // came from legacy active-instance.json). Lets a flush connect-failure distrust
 // a recycled-pid corpse advert so the next resolve falls back to legacy/buffer.
 let _serviceAdvertPort = null;
-let _flushInFlight = false;
+let _flushPromise = null;
+let _flushImmediate = null;
 let _localTracePath = null;
 let _localTraceIsExplicit = false;
 let _localTraceBuffer = [];
@@ -180,6 +181,8 @@ function _flushLocalTrace() {
       _localTraceFlushInFlight = false;
       _localTraceFlushPromise = null;
       if (_localTraceBuffer.length > 0) {
+        // An append during the write may already have armed a timer.
+        if (_localTraceTimer) clearTimeout(_localTraceTimer);
         _localTraceTimer = setTimeout(_flushLocalTrace, 0);
         _localTraceTimer.unref?.();
       }
@@ -220,11 +223,13 @@ try {
   // Ignore lifecycle hook failures in embedded runtimes.
 }
 
+const _deps = { readServicePort };
+
 function _resolveServiceUrl() {
   if (_serviceUrl) return _serviceUrl;
   try {
     // Standalone memory HTTP uses its pid-validated discovery advert.
-    const advertPort = readServicePort('memory', { requirePid: false });
+    const advertPort = _deps.readServicePort('memory', { requirePid: false });
     if (advertPort) {
       _serviceAdvertPort = advertPort;
       _serviceUrl = `http://127.0.0.1:${advertPort}`;
@@ -237,71 +242,78 @@ function _resolveServiceUrl() {
   }
 }
 
-async function _flush() {
-  _flushTimer = null;
-  if (_buffer.length === 0) return;
-  if (_flushInFlight) {
-    _scheduleFlush();
-    return;
+// Single entry point for every flush trigger (timer, immediate, drain). While a
+// flush is in flight, callers share its promise; its completion schedules the
+// continuation for whatever remains.
+function _flush() {
+  if (_flushTimer) {
+    clearTimeout(_flushTimer);
+    _flushTimer = null;
+  }
+  // This flush takes over any queued immediate; its completion reschedules.
+  if (_flushImmediate) {
+    clearImmediate(_flushImmediate);
+    _flushImmediate = null;
   }
-  _flushInFlight = true;
+  if (_flushPromise) return _flushPromise;
+  if (_buffer.length === 0) return Promise.resolve();
+  _flushPromise = _flushOnce().finally(() => {
+    _flushPromise = null;
+    _scheduleContinuation();
+  });
+  return _flushPromise;
+}
+
+async function _flushOnce() {
+  // Discovery runs here only (timer / drain / full-batch continuation), never per append.
+  const url = _resolveServiceUrl();
+  if (!url) return;
+  const batch = _buffer.splice(0, _FLUSH_BATCH_SIZE);
   try {
-    const url = _resolveServiceUrl();
-    if (!url) {
-      // Service not up yet — keep buffer, retry next timer tick
-      _scheduleFlush();
-      return;
-    }
-    const batch = _buffer.splice(0, _FLUSH_BATCH_SIZE);
+    const resp = await fetch(`${url}/admin/trace-record`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ events: batch }),
+      signal: AbortSignal.timeout(5000),
+    });
+    // Always drain the body. An undrained response body keeps the
+    // underlying keep-alive socket referenced, which can hold the event
+    // loop open and make a short-lived process (smoke scripts / one-shot
+    // agent tasks) appear to hang for seconds after its work is done.
     try {
-      const resp = await fetch(`${url}/admin/trace-record`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ events: batch }),
-        signal: AbortSignal.timeout(5000),
-      });
-      // Always drain the body. An undrained response body keeps the
-      // underlying keep-alive socket referenced, which can hold the event
-      // loop open and make a short-lived process (smoke scripts / one-shot
-      // agent tasks) appear to hang for seconds after its work is done.
-      try {
-        await resp.arrayBuffer();
-      } catch {
-        /* body already gone */
-      }
-      if (!resp.ok) {
-        warnAgentOnce(
-          'agent-trace:flush-error',
-          `[agent-trace] /admin/trace-record returned ${resp.status} — dropping batch`
-        );
-      }
-    } catch (err) {
-      _serviceUrl = null;
-      // Discovery-first consumer with no health probe: a connect failure
-      // means the pid-validated advert points at a dead (recycled-pid)
-      // port. Distrust it (connection-level errors ONLY — a timeout is a
-      // slow-but-alive daemon, not a corpse) so the next resolve falls back
-      // to legacy/buffer instead of re-trusting the same advert.
-      if (_serviceAdvertPort && isConnRefuseError(err)) markServiceUnreachable('memory', _serviceAdvertPort);
-      _serviceAdvertPort = null;
-      warnAgentOnce('agent-trace:flush-fetch', `[agent-trace] flush fetch failed (${err?.message}) — dropping batch`);
+      await resp.arrayBuffer();
+    } catch {
+      /* body already gone */
     }
-    if (_buffer.length >= _FLUSH_BATCH_SIZE) {
-      // More pending — schedule another flush immediately
-      setImmediate(_flush);
+    if (!resp.ok) {
+      warnAgentOnce(
+        'agent-trace:flush-error',
+        `[agent-trace] /admin/trace-record returned ${resp.status} — dropping batch`
+      );
     }
-  } finally {
-    _flushInFlight = false;
+  } catch (err) {
+    _serviceUrl = null;
+    // Discovery-first consumer with no health probe: a connect failure
+    // means the pid-validated advert points at a dead (recycled-pid)
+    // port. Distrust it (connection-level errors ONLY — a timeout is a
+    // slow-but-alive daemon, not a corpse) so the next resolve falls back
+    // to legacy/buffer instead of re-trusting the same advert.
+    if (_serviceAdvertPort && isConnRefuseError(err)) markServiceUnreachable('memory', _serviceAdvertPort);
+    _serviceAdvertPort = null;
+    warnAgentOnce('agent-trace:flush-fetch', `[agent-trace] flush fetch failed (${err?.message}) — dropping batch`);
   }
 }
 
-function _scheduleFlush(immediate = false) {
-  if (immediate) {
+// Full batch pending and the service is usable → one immediate; everything else
+// → the single non-resetting retry timer.
+function _scheduleContinuation() {
+  if (_buffer.length === 0) return;
+  if (_serviceUrl && _buffer.length >= _FLUSH_BATCH_SIZE) {
     if (_flushTimer) {
       clearTimeout(_flushTimer);
       _flushTimer = null;
     }
-    setImmediate(_flush);
+    if (!_flushImmediate) _flushImmediate = setImmediate(_flush);
   } else if (!_flushTimer) {
     _flushTimer = setTimeout(_flush, _FLUSH_INTERVAL_MS);
     // Never let the periodic trace flush keep the event loop alive: a
@@ -328,11 +340,10 @@ async function _drainLocalTrace() {
 async function drainAgentTrace() {
   await _drainLocalTrace();
   if (!_resolveServiceUrl()) return;
-  if (_flushTimer) {
-    clearTimeout(_flushTimer);
-    _flushTimer = null;
-  }
-  for (let i = 0; i < 10 && _buffer.length > 0; i++) {
+  // Each iteration either awaits the in-flight flush or delivers a batch, so
+  // this terminates; it stops early only when the service is unresolvable.
+  while (_buffer.length > 0 || _flushPromise) {
+    if (!_flushPromise && !_resolveServiceUrl()) break;
     await _flush();
   }
 }
@@ -363,7 +374,8 @@ function appendAgentTrace(record = {}) {
     }
     _appendLocalTrace(row);
     _buffer.push(row);
-    _scheduleFlush(_buffer.length >= _FLUSH_BATCH_SIZE);
+    // An in-flight flush schedules its own continuation on completion.
+    if (!_flushPromise) _scheduleContinuation();
   } catch {
     // Never break agent execution for telemetry
   }
@@ -464,7 +476,26 @@ function _flushToolFailuresSync() {
   }
 }
 
+// Test-only seams: inject discovery and reset module state between cases.
+const _traceIoTest = {
+  setReadServicePort(fn) {
+    _deps.readServicePort = fn;
+  },
+  // Resolves once the in-flight local spool write and its completion handler have run.
+  localWrite: () => _localTraceFlushPromise,
+  reset() {
+    _deps.readServicePort = readServicePort;
+    _buffer.length = 0;
+    _flushTimer = null;
+    _flushImmediate = null;
+    _flushPromise = null;
+    _serviceUrl = null;
+    _serviceAdvertPort = null;
+  },
+};
+
 export {
+  _traceIoTest,
   appendAgentTrace,
   drainAgentTrace,
   normalizeSessionId,

package/src/runtime/agent/orchestrator/cache-mtime.mjs

@@ -31,9 +31,18 @@ export function maxMtimeRecursive(paths, depth = 3) {
  * @returns {string}
  */
 export function mtimeSignatureRecursive(paths, depth = 3) {
+  return createHash('sha1').update(mtimeSignatureText(paths, depth)).digest('hex');
+}
+
+/**
+ * The raw text mtimeSignatureRecursive hashes (`path:mtime` lines). Texts of
+ * consecutive path groups joined with '\n' hash to the same signature as one
+ * call over all of them, so a caller can reuse an unchanged group's text.
+ */
+export function mtimeSignatureText(paths, depth = 3) {
   const parts = [];
   walkMtimes(paths, depth, (p, m) => parts.push(`${p}:${m}`));
-  return createHash('sha1').update(parts.join('\n')).digest('hex');
+  return parts.join('\n');
 }
 
 function walkMtimes(paths, depth, visit) {

package/src/runtime/agent/orchestrator/config-providers-merge.mjs

@@ -67,6 +67,13 @@ export function mergeStoredProviders({ raw, defaults, includeSecrets, presenceOn
   if (includeSecrets) {
     for (const [name, val] of Object.entries(mergedProviders)) {
       if (val?.type !== 'custom' || !name.startsWith('custom-') || val.auth === 'none') continue;
+      if (val.apiKeyEnv) {
+        // Env mode: the named variable is the only key source (no keychain).
+        const { apiKey: _dropped, ...rest } = val;
+        const envKey = process.env[val.apiKeyEnv];
+        mergedProviders[name] = envKey && !presenceOnly ? { ...rest, apiKey: envKey } : rest;
+        continue;
+      }
       const kc = storedKey(name);
       if (kc) mergedProviders[name] = withKey(val, name, kc);
     }

package/src/runtime/agent/orchestrator/config.mjs

@@ -280,6 +280,8 @@ export function loadConfig(options = {}) {
         shell: raw.shell && typeof raw.shell === 'object' ? raw.shell : {},
         update: raw.update && typeof raw.update === 'object' ? { ...raw.update } : {},
         recap: recapConfig,
+        // The model may title the session (session tool, action=rename); default on.
+        aiSessionTitles: raw.aiSessionTitles !== false,
         worktree: normalizeWorktreeSettings(raw.worktree),
         developer: normalizeDeveloperConfig(raw.developer),
         modules: canonicalizeModulesStorage(raw.modules) || {},
@@ -450,6 +452,9 @@ function buildAgentSaveBuilder(config) {
     } else Object.assign(next, disabledAgentDelta(canonicalRoutes.disabledAgents));
     if (config.memoryTools && typeof config.memoryTools === 'object') next.memoryTools = { ...config.memoryTools };
     else delete next.memoryTools;
+    // Default true lives in code: only the opt-out is stored.
+    if (config.aiSessionTitles === false) next.aiSessionTitles = false;
+    else delete next.aiSessionTitles;
     delete next.instructionFiles;
     Object.assign(next, storedInstructionFiles(config));
     delete next.workflowRoutes;

package/src/runtime/agent/orchestrator/context/collect.mjs

@@ -18,6 +18,7 @@ export {
   skillBodyPresentInSession,
   skillMissingFeature,
   skillOutsideScope,
+  skillEnabledFlags,
   skillOutsideScopeError,
 } from './skill-catalog.mjs';
 export {

package/src/runtime/agent/orchestrator/context/deferred-tools.mjs

@@ -1,5 +1,6 @@
 // Deferred-pool and MCP-instruction manifests injected into BP2.
 import { parseMcpToolName } from '../../../shared/tool-primitives.mjs';
+import { isToolBridgeEnabled, TOOL_BRIDGE_GUIDANCE } from '../runtime-core/tool-exposure.mjs';
 
 export function compactPromptManifestText(value, max = 250) {
   const text = String(value || '')
@@ -13,7 +14,10 @@ export function compactPromptManifestText(value, max = 250) {
   return `${cut.replace(/[\s,.;:!?/-]+$/, '')}...`;
 }
 
-const DEFERRED_TOOLS_BLOCK_RE = /(\n\n---\n*)?<available-deferred-tools>[\s\S]*?<\/available-deferred-tools>\s*/gi;
+// The native deferred-pool manifest and the static bridge guidance occupy the
+// same BP2 slot: one replaces the other when the exposure changes.
+const DEFERRED_TOOLS_BLOCK_RE =
+  /(\n\n---\n*)?<(available-deferred-tools|tool-bridge)>[\s\S]*?<\/(?:available-deferred-tools|tool-bridge)>\s*/gi;
 const MCP_INSTRUCTIONS_BLOCK_RE = /(\n\n---\n*)?<mcp-instructions>[\s\S]*?<\/mcp-instructions>\s*/gi;
 // Tool and MCP server names enter the manifests only as plain identifiers
 // (no markup can be smuggled into the prompt through a name).
@@ -47,6 +51,7 @@ function hasDeferredToolManifestBlock(text) {
   const raw = String(text || '');
   return (
     /<available-deferred-tools>[\s\S]*?<\/available-deferred-tools>/i.test(raw) ||
+    /<tool-bridge>[\s\S]*?<\/tool-bridge>/i.test(raw) ||
     /<mcp-instructions>[\s\S]*?<\/mcp-instructions>/i.test(raw)
   );
 }
@@ -173,11 +178,17 @@ function deferredManifestEntries(session, pool) {
 }
 
 function composeDeferredBp2Manifest(session, pool) {
+  // Bridge exposure gets the native roster and MCP instructions (the pool is
+  // already limited to what the session's policy lets it run), followed by
+  // the static bridge guidance. A tool-free bridge session gets nothing.
+  const bridge = isToolBridgeEnabled(session);
+  if (bridge && !(session.tools || []).some((tool) => tool?.name === 'call_tool')) return '';
   const parts = [];
   const deferredManifest = buildDeferredToolManifest(deferredManifestEntries(session, pool));
   if (deferredManifest) parts.push(deferredManifest);
   const mcpManifest = buildMcpInstructionsManifest(session.mcpServerInstructions, pool, session.deferredToolCatalog);
   if (mcpManifest) parts.push(mcpManifest);
+  if (bridge) parts.push(TOOL_BRIDGE_GUIDANCE);
   return parts.join('\n\n');
 }
 
@@ -186,12 +197,20 @@ function markDeferredBp2Applied(session) {
   delete session.deferredToolBp1Applied;
 }
 
+// Replace, never mutate: session-store delta saves treat stable message
+// references as an unchanged prefix, so a rewritten prompt block must be a
+// fresh object for the next save to persist it.
+function setSystemContent(session, index, content) {
+  const message = session.messages[index];
+  if (message.content !== content) session.messages[index] = { ...message, content };
+}
+
 function clearDeferredManifestBlocks(session) {
-  for (const message of session.messages) {
+  session.messages.forEach((message, index) => {
     if (message?.role === 'system' && typeof message.content === 'string') {
-      message.content = stripDeferredToolManifestBlock(message.content);
+      setSystemContent(session, index, stripDeferredToolManifestBlock(message.content));
     }
-  }
+  });
   session.messages = session.messages.filter(
     (message) => message?.role !== 'system' || String(message.content || '').trim()
   );
@@ -214,15 +233,15 @@ function writeDeferredManifestAt(session, idx, manifest, rebuild) {
   for (let i = 0; i < session.messages.length; i++) {
     if (i === idx || session.messages[i]?.role !== 'system' || typeof session.messages[i].content !== 'string')
       continue;
-    session.messages[i].content = stripDeferredToolManifestBlock(session.messages[i].content);
+    setSystemContent(session, i, stripDeferredToolManifestBlock(session.messages[i].content));
   }
   const raw = typeof session.messages[idx].content === 'string' ? session.messages[idx].content : '';
   if (rebuild && hasDeferredToolManifestBlock(raw)) {
-    session.messages[idx].content = rebuildDeferredToolManifestBlock(raw, manifest);
+    setSystemContent(session, idx, rebuildDeferredToolManifestBlock(raw, manifest));
     return;
   }
   const base = stripDeferredToolManifestBlock(raw);
-  session.messages[idx].content = base ? `${base}\n\n---\n\n${manifest}` : manifest;
+  setSystemContent(session, idx, base ? `${base}\n\n---\n\n${manifest}` : manifest);
 }
 
 /**

package/src/runtime/agent/orchestrator/context/skill-catalog.mjs

@@ -1,9 +1,10 @@
 // Skill discovery, cache, resource loading, envelopes, manifests, and the
 // Skill meta-tool.
 
-import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { readFileSync, existsSync, readdirSync, statSync, watch as watch_ } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
-import { maxMtimeRecursive, mtimeSignatureRecursive } from '../cache-mtime.mjs';
+import { maxMtimeRecursive, mtimeSignatureRecursive, mtimeSignatureText } from '../cache-mtime.mjs';
 import { mixdogHome, resolvePluginData, mixdogRoot } from '../../../shared/plugin-paths.mjs';
 import { PLUGIN_MANIFEST_FILES, pluginSkillsRoots } from '../../../shared/plugin-manifest.mjs';
 import {
@@ -257,6 +258,31 @@ export function isSkillDisabled(name, config = null, skills = null) {
   return Boolean(skill && missingFeature(skill, featureConfig(config)));
 }
 
+/**
+ * `enabled` for every skill of one collectSkillsCached() snapshot, exactly as
+ * `!(isSkillDisabled(name, config, skills) || skillMissingFeature(name, config,
+ * skills))` per skill — but with ONE config read, one disabled-name set and one
+ * name index for the whole list instead of three config reads and a linear
+ * lookup per skill (the status listing blocked the event loop on them).
+ */
+export function skillEnabledFlags(skills, config = null) {
+  const list = Array.isArray(skills) ? skills : [];
+  const cfg = config || loadConfig({ secrets: false });
+  const disabled = getDisabledSkillNameSet(cfg);
+  const features = featureConfig(cfg);
+  const byKey = new Map();
+  for (const entry of list) {
+    const key = normalizeSkillNameKey(entry.name);
+    if (!byKey.has(key)) byKey.set(key, entry);
+  }
+  return list.map((entry) => {
+    const key = normalizeSkillNameKey(entry.name);
+    const skill = byKey.get(key);
+    if (key && !followsBuiltinFeature(skill) && disabled.has(key)) return false;
+    return !(skill && missingFeature(skill, features));
+  });
+}
+
 /** The built-in feature a skill needs that is not active, or null. */
 export function skillMissingFeature(name, config = null, skills = null) {
   const skill = findCachedSkillByKey(normalizeSkillNameKey(name), skills);
@@ -303,6 +329,81 @@ export function collectPromptSkillsCached(cwd, config = null) {
 // --- Global skill cache (mtime-based) ---
 const _skillsCache = new Map();
 
+// Change watchers over the recursive skill roots. Re-walking every skill
+// folder (one stat per entry) on every status/prompt read blocked the event
+// loop for tens to hundreds of ms with a large skill set. A root whose
+// recursive watcher has reported nothing since its last walk reuses that
+// walk's signature text instead; any event, watcher error or explicit
+// invalidation re-walks it. A watched root is trusted only once an event-loop
+// turn has passed since its walk.
+// Freshness contract: every write made through the app (addSkill, saveSkill,
+// setDisabledSkills, reloadSkills, settings/plugin mutations, peer-runtime
+// announcements) calls invalidateSkillsCache synchronously, which drops every
+// watch, so the very next read re-walks and is exact. A passive edit made
+// outside the app is eventually consistent: it is seen once the watcher
+// delivers its event (watcher latency), or at the next explicit invalidation.
+// Roots that cannot be watched (missing, or unsupported by the platform) and
+// every plain-file gate path are stat'ed on every call as before.
+const _ROOT_WATCH_LIMIT = 64;
+const _rootWatches = new Map(); // root -> { watcher, dirty, text, settled }
+
+function _closeRootWatch(root) {
+  const watch = _rootWatches.get(root);
+  if (!watch) return;
+  _rootWatches.delete(root);
+  try {
+    watch.watcher.close();
+  } catch {
+    /* already closed */
+  }
+}
+
+function _closeAllRootWatches() {
+  for (const root of [..._rootWatches.keys()]) _closeRootWatch(root);
+}
+
+function _openRootWatch(root) {
+  let isDir = false;
+  try {
+    isDir = statSync(root).isDirectory();
+  } catch {
+    return null;
+  }
+  if (!isDir) return null;
+  if (_rootWatches.size >= _ROOT_WATCH_LIMIT) _closeAllRootWatches();
+  const watch = { watcher: null, dirty: true, text: null, settled: false };
+  try {
+    // A change anywhere below drops the root's reused walk; the watcher is
+    // closed with it (a re-walk re-opens one), so a churning folder never
+    // keeps a handle on directories being deleted.
+    watch.watcher = watch_(root, { recursive: true, persistent: false }, () => _closeRootWatch(root));
+    watch.watcher.on('error', () => _closeRootWatch(root));
+  } catch {
+    return null;
+  }
+  _rootWatches.set(root, watch);
+  return watch;
+}
+
+/** Signature text of one recursive gate root (see mtimeSignatureText). */
+function _rootSignatureText(root) {
+  const current = _rootWatches.get(root);
+  if (current && !current.dirty && current.settled) return current.text;
+  // Open the watcher BEFORE the walk: a change racing the walk then either
+  // shows in it or arrives as an event that drops the reused text.
+  const watch = current || _openRootWatch(root);
+  const text = mtimeSignatureText([root]);
+  if (watch && _rootWatches.get(root) === watch) {
+    watch.text = text;
+    watch.dirty = false;
+    watch.settled = false;
+    setImmediate(() => {
+      if (_rootWatches.get(root) === watch && watch.text === text) watch.settled = true;
+    }).unref?.();
+  }
+  return text;
+}
+
 export function collectSkillsCached(cwd) {
   if (skillsDisabled()) return [];
   void cwd;
@@ -313,12 +414,15 @@ export function collectSkillsCached(cwd) {
   skillsDirs.push(...pluginSkillDirs().map(({ dir }) => dir), ...builtinSkillDirs());
   // registry.json itself gates plugin add/remove: removal deletes the
   // plugin's skills dir (so no dir mtime advances), but saveRegistry()
-  // always rewrites this file. mtimeSignatureRecursive stats plain files directly.
+  // always rewrites this file. It is a plain file: stat'ed directly.
   const registryPath = pluginRegistryPath();
-  if (registryPath) skillsDirs.push(registryPath);
-  // Exact, un-timed gate: stat every call. The shallow watch list covers
-  // manifest edits and skill roots that do not exist yet.
-  const signature = `${mtimeSignatureRecursive(skillsDirs)}|${mtimeSignatureRecursive(pluginShallowWatchPaths(), 0)}`;
+  // Exact gate: unwatched roots and plain files are stat'ed every call; a
+  // watched root reuses its last walk only while its watcher stayed quiet.
+  // The shallow watch list covers manifest edits and skill roots that do not
+  // exist yet.
+  const rootTexts = skillsDirs.map((dir) => _rootSignatureText(dir));
+  if (registryPath) rootTexts.push(mtimeSignatureText([registryPath]));
+  const signature = `${createHash('sha1').update(rootTexts.join('\n')).digest('hex')}|${mtimeSignatureRecursive(pluginShallowWatchPaths(), 0)}`;
   const entry = _skillsCache.get(key);
   if (entry && entry.signature === signature) {
     return entry.value;
@@ -331,6 +435,7 @@ export function collectSkillsCached(cwd) {
 export function invalidateSkillsCache(cwd) {
   void cwd;
   _skillsCache.clear();
+  _closeAllRootWatches();
 }
 
 /**