mixdog 0.9.4 → 0.9.5

package/src/session-runtime/settings-api.mjs

@@ -24,6 +24,7 @@ export function createSettingsApi({
   normalizeCompactTypeSetting,
   normalizeSystemShellConfig,
   normalizeSystemShellCommand,
+  autoClearProviderDefaults,
   setConfiguredShell,
   setRecapEnabledInConfig,
   setModuleEnabledInConfig,
@@ -88,14 +89,29 @@ export function createSettingsApi({
       const route = getRoute();
       const normalized = normalizeAutoClearConfig(config.autoClear);
       const provider = route?.provider || null;
-      const providerDefault = autoClearIdleMsForProvider(provider);
+      const providerDefault = autoClearIdleMsForProvider(provider, normalized.providerIdleMs);
       const idleMs = normalized.custom ? normalized.idleMs : providerDefault;
+      // Advanced picker shows only providers the user actually has enabled
+      // (config.providers[*].enabled), plus the active route provider, any
+      // provider with a custom override, and the 'default' fallback row —
+      // not the full built-in table.
+      const enabledProviders = new Set(
+        Object.entries(config?.providers || {})
+          .filter(([, v]) => v && typeof v === 'object' && v.enabled !== false)
+          .map(([k]) => String(k).toLowerCase()),
+      );
+      if (provider) enabledProviders.add(String(provider).toLowerCase());
+      const providerDefaults = autoClearProviderDefaults(normalized.providerIdleMs)
+        .filter((entry) => entry.provider === 'default'
+          || entry.custom === true
+          || enabledProviders.has(entry.provider));
       return {
         enabled: normalized.enabled,
         idleMs,
         custom: normalized.custom,
         providerDefault,
         provider,
+        providerDefaults,
       };
     },
     // --- User profile (/profile statusline command) ---------------------
@@ -225,6 +241,23 @@ export function createSettingsApi({
       const current = normalizeAutoClearConfig(config.autoClear);
       const next = { ...current };
       if (hasOwn(input, 'enabled')) next.enabled = input.enabled !== false;
+      const providerKey = String(input.provider || '').trim().toLowerCase();
+      const editsProviderDefault = providerKey
+        && (input.resetProvider === true || hasOwn(input, 'duration') || hasOwn(input, 'idleMs'));
+      if (editsProviderDefault) {
+        const providerIdleMs = { ...(next.providerIdleMs || {}) };
+        if (input.resetProvider === true || (hasOwn(input, 'idleMs') && input.idleMs == null)) {
+          delete providerIdleMs[providerKey];
+        } else {
+          const idleMs = hasOwn(input, 'duration') ? parseDurationMs(input.duration) : Number(input.idleMs);
+          if (!idleMs || !Number.isFinite(idleMs) || idleMs <= 0) throw new Error('usage: duration like 10m, 1h, or 24h');
+          providerIdleMs[providerKey] = Math.max(60_000, Math.round(idleMs));
+        }
+        next.providerIdleMs = providerIdleMs;
+        saveConfigAndAdopt({ ...config, autoClear: next });
+        const resolved = this.getAutoClear();
+        return { ...resolved, label: formatDurationMs(resolved.idleMs) };
+      }
       if (input.reset === true || (hasOwn(input, 'idleMs') && input.idleMs == null)) {
         next.idleMs = null;
       } else if (hasOwn(input, 'idleMs')) {

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

@@ -36,7 +36,7 @@ export const CWD_TOOL = {
     openWorldHint: false,
     agentHidden: true,
   },
-  description: 'Show or set the session work project for tool execution.',
+  description: 'Show or set the session work project for tool execution. Use only for explicit project path changes.',
   inputSchema: {
     type: 'object',
     properties: {

package/src/session-runtime/workflow.mjs

@@ -18,7 +18,7 @@ export const FIXED_AGENT_SLOTS = Object.freeze([
   { id: 'debugger', label: 'Debugger', description: 'Root-cause analysis and failure tracing' },
 ]);
 const AGENT_ROLE_IDS = new Set(FIXED_AGENT_SLOTS.map((agent) => agent.id));
-const DEFAULT_WORKFLOW_ID = 'default';
+export const DEFAULT_WORKFLOW_ID = 'default';
 
 const SEARCH_CAPABLE_PROVIDERS = new Set([
   'openai-oauth', 'openai', 'grok-oauth', 'xai', 'gemini', 'anthropic', 'anthropic-oauth',

package/src/standalone/agent-tool/tool-def.mjs

@@ -35,7 +35,7 @@ export const AGENT_TOOL = {
     openWorldHint: true,
     agentHidden: true,
   },
-  description: 'Delegate scoped work. Agent handoffs always start background tasks and return task IDs immediately. Spawn independent scopes in parallel with distinct tags; for the same scope/tag, use send or spawn with the same tag to reuse the live session. Wait for the completion notification before dependent work. Do not call status/read after spawn; status/read are manual recovery only.',
+  description: 'Delegate scoped work. Agent handoffs always start background tasks and return task IDs immediately. Spawn independent scopes in parallel with distinct tags; for the same scope, use send or spawn with the same tag to reuse the live session. Wait for the completion notification before dependent work. Do not call status/read after spawn; they are manual recovery only.',
   inputSchema: {
     type: 'object',
     properties: {

package/src/standalone/agent-tool.mjs

@@ -92,6 +92,31 @@ function reapMsForProvider(provider) {
 // cap and restore strictly-unbounded prep.
 const DEFAULT_SPAWN_PREP_TIMEOUT_MS = envTimeoutMs('MIXDOG_AGENT_SPAWN_PREP_TIMEOUT_MS', 120_000);
 
+// Global spawn-start stagger: unlimited-N parallel fan-out otherwise fires all
+// first provider calls in the same instant, racing the server-side prompt-
+// cache write/propagation window. Bench (parallel-10, identical-ms starts):
+// 12.5% cache miss; 3000ms lane stagger: 4.3%; 166ms: 6.0%. 2000ms default
+// picked as a low-cost middle ground. Chain (not a fixed lane count) so it
+// scales to any N: each new spawn's start is pushed to at least STAGGER_MS
+// after the previous spawn's start; sequential/non-overlapping spawns (now
+// already past the window) pay zero added latency. MIXDOG_SPAWN_STAGGER_MS=0
+// disables. Applied inside the deferred job body (see startDeferredSpawnJob)
+// so the agent tool call itself still returns task_id immediately.
+const SPAWN_STAGGER_MS = envTimeoutMs('MIXDOG_SPAWN_STAGGER_MS', 2000);
+let lastSpawnStartAt = 0;
+async function waitForSpawnStagger() {
+  if (SPAWN_STAGGER_MS <= 0) return;
+  const now = Date.now();
+  const myStart = Math.max(now, lastSpawnStartAt + SPAWN_STAGGER_MS);
+  lastSpawnStartAt = myStart;
+  const delay = myStart - now;
+  if (delay <= 0) return;
+  await new Promise((resolve) => {
+    const t = setTimeout(resolve, delay);
+    t.unref?.();
+  });
+}
+
 export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultCwd, onSubagentEvent }) {
   // Optional bridge to the standard hook bus for SubagentStart / SubagentStop.
   // Best-effort: a hook error must never affect worker spawn/finish.
@@ -881,6 +906,11 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
 
   function startDeferredSpawnJob(args, callerCwd, context, notifyContext, extras = {}) {
     return startJob('spawn', pendingSpawnMeta(args, extras), async (job) => {
+      // Stagger concurrent spawn starts before prep/model-call begins (see
+      // SPAWN_STAGGER_MS above). Runs inside the job body, so the tool call
+      // that queued this job already returned task_id before this awaits.
+      await waitForSpawnStagger();
+      if (job?.status === 'cancelled') return null;
       // prepareSpawn (ensureProvider/prepareAgentSession) runs before runSpawn
       // installs its progress watchdog, so guard prep with an internal env-
       // backed cap rather than exposing per-call timeout knobs on the agent

package/src/standalone/channel-admin.mjs

@@ -22,20 +22,15 @@ import {
   updateSection,
 } from '../runtime/shared/config.mjs';
 import { resolvePluginData } from '../runtime/shared/plugin-paths.mjs';
-import { readMarkdownDocument } from '../runtime/shared/markdown-frontmatter.mjs';
+import { readMarkdownDocument, serializeFrontmatterDoc } from '../runtime/shared/markdown-frontmatter.mjs';
 
 const NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
 const DEFAULT_CHANNELS = Object.freeze({
   backend: 'discord',
   discord: {},
   access: { dmPolicy: 'allowlist', allowFrom: [], channels: {} },
-  mainChannel: 'main',
-  channelsConfig: {
-    main: { channelId: '', mode: 'interactive' },
-  },
-  quiet: { schedule: '23:00-09:00', holidays: false },
-  schedules: { respectQuiet: true },
-  webhook: { enabled: true, respectQuiet: false, port: 3333 },
+  channel: { channelId: '', discordChannelId: '', telegramChatId: '' },
+  webhook: { enabled: true, port: 3333 },
 });
 
 function dataDir() {
@@ -61,24 +56,6 @@ function writeTextAtomic(path, text) {
   renameSync(tmp, path);
 }
 
-// Serialize a single-file frontmatter markdown document:
-//   ---
-//   key: value
-//   ---
-//
-//   <body>
-// Values are stringified as-is (enabled:false -> "false"); the reader casts
-// types back. Mirrors the WORKFLOW.md / SKILL.md single-file convention.
-function serializeFrontmatterDoc(meta = {}, body = '') {
-  const lines = ['---'];
-  for (const [key, value] of Object.entries(meta)) {
-    if (value === undefined || value === null) continue;
-    lines.push(`${key}: ${value}`);
-  }
-  lines.push('---', '');
-  return `${lines.join('\n')}\n${String(body || '').trim()}\n`;
-}
-
 function assertName(name, kind = 'name') {
   const value = String(name || '').trim();
   if (!NAME_RE.test(value) || value !== basename(value)) {
@@ -93,9 +70,7 @@ function normalizeChannelsConfig(raw = {}) {
     ...(raw && typeof raw === 'object' ? raw : {}),
     discord: { ...DEFAULT_CHANNELS.discord, ...(raw?.discord || {}) },
     access: { ...DEFAULT_CHANNELS.access, ...(raw?.access || {}) },
-    channelsConfig: { ...DEFAULT_CHANNELS.channelsConfig, ...(raw?.channelsConfig || {}) },
-    quiet: { ...DEFAULT_CHANNELS.quiet, ...(raw?.quiet || {}) },
-    schedules: { ...DEFAULT_CHANNELS.schedules, ...(raw?.schedules || {}) },
+    channel: { ...DEFAULT_CHANNELS.channel, ...(raw?.channel || {}) },
     webhook: { ...DEFAULT_CHANNELS.webhook, ...(raw?.webhook || {}) },
   };
 }
@@ -116,11 +91,42 @@ function seedBackendChannelIds(entry = {}, backend = 'discord') {
   return next;
 }
 
+// Resolve the single-channel entry from the config: prefer the new `channel`
+// object; fall back (read-side only, no on-disk migration) to the legacy
+// channelsConfig[mainChannel ?? 'main'] entry, then the first entry with an id.
+function resolveChannelEntry(cfg = {}) {
+  if (cfg.channel && typeof cfg.channel === 'object'
+    && (cfg.channel.channelId || cfg.channel.discordChannelId || cfg.channel.telegramChatId)) {
+    return cfg.channel;
+  }
+  const legacy = cfg.channelsConfig && typeof cfg.channelsConfig === 'object' ? cfg.channelsConfig : null;
+  if (legacy) {
+    const mainName = cfg.mainChannel ?? 'main';
+    const preferred = legacy[mainName];
+    if (preferred && typeof preferred === 'object'
+      && (preferred.channelId || preferred.discordChannelId || preferred.telegramChatId)) {
+      return preferred;
+    }
+    for (const entry of Object.values(legacy)) {
+      if (entry && typeof entry === 'object'
+        && (entry.channelId || entry.discordChannelId || entry.telegramChatId)) {
+        return entry;
+      }
+    }
+  }
+  return cfg.channel && typeof cfg.channel === 'object' ? cfg.channel : {};
+}
+
 function updateChannelsSection(build) {
   let next;
   updateSection('channels', (current) => {
-    next = build(normalizeChannelsConfig(current));
-    return normalizeChannelsConfig(next);
+    // Preserve any legacy channelsConfig/mainChannel that already live on disk
+    // for read-side compat, but never re-emit them from our writers: strip them
+    // out of the returned shape so writes converge on the single `channel`.
+    const normalized = normalizeChannelsConfig(current);
+    next = build(normalized);
+    const { channelsConfig: _lc, mainChannel: _lm, ...clean } = normalizeChannelsConfig(next);
+    return clean;
   });
   return next;
 }
@@ -136,19 +142,17 @@ function listEntryDirs(dir) {
   }
 }
 
-export function listChannels(config = {}) {
+// Single-channel read: resolves `cfg.channel` (legacy channelsConfig fallback)
+// into the flat shape the settings/TUI layer consumes.
+export function getChannel(config = {}) {
   const cfg = normalizeChannelsConfig(config);
   const backend = cfg.backend === 'telegram' ? 'telegram' : 'discord';
-  return Object.entries(cfg.channelsConfig || {})
-    .sort(([a], [b]) => a.localeCompare(b))
-    .map(([name, value]) => ({
-      name,
-      channelId: channelIdForBackend(value, backend),
-      discordChannelId: String(value?.discordChannelId || ''),
-      telegramChatId: String(value?.telegramChatId || ''),
-      mode: value?.mode || 'interactive',
-      main: cfg.mainChannel === name,
-    }));
+  const entry = resolveChannelEntry(cfg);
+  return {
+    channelId: channelIdForBackend(entry, backend),
+    discordChannelId: String(entry?.discordChannelId || ''),
+    telegramChatId: String(entry?.telegramChatId || ''),
+  };
 }
 
 export function saveDiscordToken(token) {
@@ -187,40 +191,24 @@ export function forgetWebhookAuthtoken() {
   return { ok: true };
 }
 
-export function saveChannel({ name, channelId, mode = 'interactive', main = false, backend = null } = {}) {
-  const label = assertName(name, 'channel name');
+// Single-channel write: persists `cfg.channel`, keeping the per-backend id
+// fields (discordChannelId/telegramChatId) so a backend switch retains both
+// ids. `backend` selects which per-backend field the id updates; when omitted
+// the id lands on the active backend's field.
+export function setChannel({ channelId, backend = null } = {}) {
   const id = String(channelId || '').trim();
   if (!id) throw new Error('channelId is required');
-  const nextMode = mode === 'broadcast' ? 'broadcast' : 'interactive';
   const targetBackend = backend === 'telegram' || backend === 'discord' ? backend : null;
   return updateChannelsSection((cfg) => {
     const activeBackend = cfg.backend === 'telegram' ? 'telegram' : 'discord';
-    const current = seedBackendChannelIds(cfg.channelsConfig?.[label] || {}, activeBackend);
-    const nextEntry = { ...current, mode: nextMode };
-    if (targetBackend === 'telegram') nextEntry.telegramChatId = id;
-    else if (targetBackend === 'discord') nextEntry.discordChannelId = id;
-    else nextEntry.channelId = id;
-    nextEntry.channelId = targetBackend
-      ? (channelIdForBackend(nextEntry, activeBackend) || (targetBackend === activeBackend ? id : ''))
-      : id;
-    return {
-      ...cfg,
-      mainChannel: main || !cfg.mainChannel ? label : cfg.mainChannel,
-      channelsConfig: {
-        ...(cfg.channelsConfig || {}),
-        [label]: nextEntry,
-      },
-    };
-  });
-}
-
-export function deleteChannel(name) {
-  const label = assertName(name, 'channel name');
-  return updateChannelsSection((cfg) => {
-    const channelsConfig = { ...(cfg.channelsConfig || {}) };
-    delete channelsConfig[label];
-    const nextMain = cfg.mainChannel === label ? Object.keys(channelsConfig)[0] || 'main' : cfg.mainChannel;
-    return { ...cfg, channelsConfig, mainChannel: nextMain };
+    const writeBackend = targetBackend || activeBackend;
+    const current = seedBackendChannelIds(resolveChannelEntry(cfg), activeBackend);
+    const nextEntry = { ...current };
+    if (writeBackend === 'telegram') nextEntry.telegramChatId = id;
+    else nextEntry.discordChannelId = id;
+    // `channelId` mirrors the active backend's id for legacy readers.
+    nextEntry.channelId = channelIdForBackend(nextEntry, activeBackend);
+    return { ...cfg, channel: nextEntry };
   });
 }
 
@@ -230,7 +218,6 @@ export function setWebhookConfig(patch = {}) {
     webhook: {
       ...(cfg.webhook || {}),
       ...(Object.prototype.hasOwnProperty.call(patch, 'enabled') ? { enabled: patch.enabled === true } : {}),
-      ...(Object.prototype.hasOwnProperty.call(patch, 'respectQuiet') ? { respectQuiet: patch.respectQuiet === true } : {}),
       ...(patch.port ? { port: Number(patch.port) || 3333 } : {}),
       ...(patch.domain ? { domain: String(patch.domain).trim() } : {}),
       ...(patch.ngrokDomain ? { ngrokDomain: String(patch.ngrokDomain).trim() } : {}),
@@ -245,14 +232,11 @@ export function setBackend(name) {
   }
   updateChannelsSection((cfg) => {
     const activeBackend = cfg.backend === 'telegram' ? 'telegram' : 'discord';
-    const channelsConfig = Object.fromEntries(Object.entries(cfg.channelsConfig || {}).map(([key, entry]) => [
-      key,
-      (() => {
-        const seeded = seedBackendChannelIds(entry, activeBackend);
-        return { ...seeded, channelId: channelIdForBackend(seeded, value) };
-      })(),
-    ]));
-    return { ...cfg, channelsConfig, backend: value };
+    const seeded = seedBackendChannelIds(resolveChannelEntry(cfg), activeBackend);
+    // `channelId` now mirrors the newly-selected backend's id; both per-backend
+    // id fields are retained so switching back keeps the other id.
+    const channel = { ...seeded, channelId: channelIdForBackend(seeded, value) };
+    return { ...cfg, channel, backend: value };
   });
   return { ok: true, backend: value };
 }
@@ -274,8 +258,15 @@ export function listSchedules() {
     if (Object.prototype.hasOwnProperty.call(config, 'enabled')) {
       config.enabled = config.enabled !== 'false' && config.enabled !== false;
     }
+    // Dir name is canonical identity; frontmatter `name` is display-only and
+    // must never override the slug used for routing/deletion. `description`
+    // defaults to '' for old files with no such key (backward compat).
+    const description = String(config.description || '');
+    delete config.name;
+    delete config.description;
     return {
       name,
+      description,
       ...config,
       instructions: body,
       route: config.channel ? `channel:${config.channel}` : 'session',
@@ -285,6 +276,7 @@ export function listSchedules() {
 
 export function saveSchedule({
   name,
+  description = '',
   time,
   timezone,
   days,
@@ -302,7 +294,9 @@ export function saveSchedule({
   const dir = join(schedulesDir(), id);
   if (existsSync(dir) && overwrite !== true) throw new Error(`schedule "${id}" already exists`);
   mkdirSync(dir, { recursive: true });
-  const config = { time: cron };
+  // name (== dir slug) and description lead the frontmatter per the SKILL.md
+  // convention; operational keys follow.
+  const config = { name: id, description: String(description || '').trim(), time: cron };
   if (timezone) config.timezone = String(timezone).trim();
   if (days && days !== 'daily') config.days = String(days).trim();
   if (channel) config.channel = String(channel).trim();
@@ -324,7 +318,13 @@ export function setScheduleEnabled(name, enabled) {
   const mdPath = join(dir, 'SCHEDULE.md');
   if (!existsSync(mdPath)) throw new Error(`schedule "${id}" does not exist`);
   const { frontmatter, body } = readMarkdownDocument(readText(mdPath, ''));
-  writeTextAtomic(mdPath, serializeFrontmatterDoc({ ...frontmatter, enabled: enabled !== false }, body));
+  // Re-spread with name/description first so the round-trip keeps SKILL.md
+  // key order; name stays the dir slug regardless of stale frontmatter.
+  const { name: _staleName, description = '', ...rest } = frontmatter;
+  writeTextAtomic(mdPath, serializeFrontmatterDoc(
+    { name: id, description, ...rest, enabled: enabled !== false },
+    body,
+  ));
   return { name: id, enabled: enabled !== false };
 }
 
@@ -336,12 +336,19 @@ export function listWebhooks() {
     if (Object.prototype.hasOwnProperty.call(config, 'enabled')) {
       config.enabled = config.enabled !== 'false' && config.enabled !== false;
     }
+    // Dir name is canonical identity/URL routing key; frontmatter `name` is
+    // display-only and must not override the slug. `description` defaults to
+    // '' for old files with no such key (backward compat).
+    const description = String(config.description || '');
+    delete config.name;
+    delete config.description;
     // Secret lives in a side file (<name>/secret), never in frontmatter, so
     // an arbitrary user-supplied secret (quotes/colon/newline) round-trips
     // losslessly and setWebhookEnabled cannot corrupt it.
     const hasSecret = Boolean(readText(join(dir, 'secret'), '').trim());
     return {
       name,
+      description,
       ...config,
       secretSet: hasSecret,
       secret: undefined,
@@ -353,6 +360,7 @@ export function listWebhooks() {
 
 export function saveWebhook({
   name,
+  description = '',
   parser = 'github',
   secret,
   channel,
@@ -373,7 +381,9 @@ export function saveWebhook({
   if (existsSync(dir) && overwrite !== true) throw new Error(`webhook "${id}" already exists`);
   mkdirSync(dir, { recursive: true });
   const secretValue = String(secret || randomBytes(24).toString('hex')).trim();
-  const config = { parser: nextParser };
+  // name (== dir slug) and description lead the frontmatter per the SKILL.md
+  // convention; operational keys (parser/channel/model/enabled) follow.
+  const config = { name: id, description: String(description || '').trim(), parser: nextParser };
   if (channel) config.channel = String(channel).trim();
   if (model) config.model = String(model).trim();
   if (enabled === false) config.enabled = false;
@@ -397,7 +407,13 @@ export function setWebhookEnabled(name, enabled) {
   const mdPath = join(dir, 'WEBHOOK.md');
   if (!existsSync(mdPath)) throw new Error(`webhook "${id}" does not exist`);
   const { frontmatter, body } = readMarkdownDocument(readText(mdPath, ''));
-  writeTextAtomic(mdPath, serializeFrontmatterDoc({ ...frontmatter, enabled: enabled !== false }, body));
+  // Re-spread with name/description first so the round-trip keeps SKILL.md
+  // key order; name stays the dir slug regardless of stale frontmatter.
+  const { name: _staleName, description = '', ...rest } = frontmatter;
+  writeTextAtomic(mdPath, serializeFrontmatterDoc(
+    { name: id, description, ...rest, enabled: enabled !== false },
+    body,
+  ));
   return { name: id, enabled: enabled !== false };
 }
 
@@ -429,7 +445,7 @@ export function channelSetup(config = null) {
       stored: hasStoredSecret(SECRET_ACCOUNTS.webhookAuth),
       status: webhookAuth ? 'Set' : 'Off',
     },
-    channels: listChannels(cfg),
+    channel: getChannel(cfg),
     schedules: listSchedules(),
     webhooks: listWebhooks(),
   };
@@ -440,11 +456,7 @@ export function renderChannelStatus(config = null) {
   const lines = [];
   lines.push(`discord  ${setup.discord.status}${setup.discord.problem ? ` (${setup.discord.problem})` : ''}`);
   lines.push(`webhook  ${setup.webhook.enabled === false ? 'disabled' : 'enabled'} · auth ${setup.webhook.status} · port ${setup.webhook.port || 3333}`);
-  lines.push('channels');
-  if (setup.channels.length === 0) lines.push('  (none)');
-  for (const ch of setup.channels) {
-    lines.push(`  ${ch.name}${ch.main ? ' *' : ''}  ${ch.channelId || '(unset)'}  ${ch.mode}`);
-  }
+  lines.push(`channel  ${setup.channel.channelId || '(unset)'}`);
   lines.push('schedules');
   if (setup.schedules.length === 0) lines.push('  (none)');
   for (const item of setup.schedules) {

package/src/standalone/explore-tool.mjs

@@ -39,8 +39,28 @@ const EXPLORE_RESULT_CACHE_TTL_MS = (() => {
   const raw = Number(process.env.MIXDOG_EXPLORE_RESULT_CACHE_TTL_MS);
   return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : 5 * 60_000;
 })();
+// Hard ceiling for one explorer compute. The dispatch-level watchdog is the
+// primary abort; this race is the last line of defence so a wedged compute can
+// never hang the awaiting tool call (and its cache key) forever.
+export const EXPLORE_COMPUTE_HARD_TIMEOUT_MS = (() => {
+  const raw = Number(process.env.MIXDOG_EXPLORE_HARD_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : 10 * 60_000;
+})();
 const EXPLORE_RESULT_CACHE = new Map(); // key -> { ts, value?, promise? }
 
+function withExploreHardTimeout(promise) {
+  if (!(EXPLORE_COMPUTE_HARD_TIMEOUT_MS > 0)) return promise;
+  let timer = null;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(
+      () => reject(new Error(`explorer timed out after ${EXPLORE_COMPUTE_HARD_TIMEOUT_MS}ms`)),
+      EXPLORE_COMPUTE_HARD_TIMEOUT_MS,
+    );
+    if (typeof timer.unref === 'function') timer.unref();
+  });
+  return Promise.race([promise, timeout]).finally(() => { if (timer) clearTimeout(timer); });
+}
+
 function escapeXml(str) {
   return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
@@ -50,7 +70,7 @@ function escapeXml(str) {
 // reminder. The full no-verdict contract lives at system level
 // (rules/agent/30-explorer.md).
 export function buildExplorerPrompt(query) {
-  return `<query>${escapeXml(query)}</query>\nReminder: output only anchor lines formatted as path:line — symbol/name — short reason, or EXPLORATION_FAILED. No preamble, bullets, numbering, headings, summary, code quotes, analysis, verdicts, ratings, or recommendations.`;
+  return `<query>${escapeXml(query)}</query>\nReminder: budget 4 tool turns — batch every candidate lookup per turn, never one tool at a time. The moment you have credible anchors, STOP and answer; spend remaining turns only while you have zero anchors. Output only anchor lines formatted as path:line — symbol/name — short reason, or EXPLORATION_FAILED. No preamble, bullets, numbering, headings, summary, code quotes, analysis, verdicts, ratings, or recommendations.`;
 }
 
 export function normalizeExploreQueries(rawQuery) {
@@ -209,11 +229,19 @@ function getCachedExploreResult(key) {
 async function runExploreCached(key, compute) {
   const cached = getCachedExploreResult(key);
   if (cached !== null) return cached;
-  if (!exploreResultCacheEnabled()) return await compute();
-  const pending = EXPLORE_RESULT_CACHE.get(key)?.promise;
-  if (pending) return await pending;
+  if (!exploreResultCacheEnabled()) return await withExploreHardTimeout(compute());
+  const entry = EXPLORE_RESULT_CACHE.get(key);
+  if (entry?.promise) {
+    // Pending in-flight dedup — but never trust a pending entry forever: a
+    // compute that outlived the hard timeout is wedged (its own race should
+    // have rejected); drop the poisoned key and recompute fresh.
+    if (!(EXPLORE_COMPUTE_HARD_TIMEOUT_MS > 0) || Date.now() - entry.ts <= EXPLORE_COMPUTE_HARD_TIMEOUT_MS) {
+      return await entry.promise;
+    }
+    EXPLORE_RESULT_CACHE.delete(key);
+  }
   const promise = Promise.resolve()
-    .then(() => compute())
+    .then(() => withExploreHardTimeout(compute()))
     .then((value) => {
       const text = typeof value === 'string' ? value : responseText(value);
       const cleaned = cleanExplorerText(text);
@@ -327,15 +355,16 @@ async function runExploreSync(args = {}, ctx = {}) {
   const presetName = (route && typeof route === 'object')
     ? `${clean(route.provider)}/${clean(route.model)}`
     : (route || '');
-  // Explorer is a one-shot locator (one grep+code_graph turn, answer, stop —
-  // rules/agent/30-explorer.md). Pin a low hard cap so a drifting explorer
-  // cannot run an 11-call research loop; 3 leaves room for one lookup turn,
-  // one recovery turn, and the answer.
+  // Explorer self-manages its turn budget: the 4-turn budget lives ONLY in
+  // explorer-scoped surfaces (rules/agent/30-explorer.md + per-query prompt),
+  // never in shared loop policy. The cap here is a runaway guard, unchanged
+  // from the original value; B-round live tests showed hard targets
+  // legitimately need ~10.
   const llm = makeAgentDispatch({
     agent: 'explorer',
     cwd: resolvedCwd,
     brief: true,
-    maxLoopIterations: 3,
+    maxLoopIterations: 12,
     parentSessionId: ctx.callerSessionId || null,
     clientHostPid: ctx.clientHostPid || null,
     config,