mixdog 0.9.2 → 0.9.3

package/src/session-runtime/workflow.mjs

@@ -0,0 +1,358 @@
+// Workflow/agent pack loading + route resolution, and search-route
+// normalization. Roots/dataDir and config-dependent helpers are injected to
+// keep this module free of the runtime's path/provider constants.
+import { basename, join } from 'node:path';
+import { existsSync, readdirSync } from 'node:fs';
+import { clean } from './session-text.mjs';
+import { normalizeEffortInput } from './effort.mjs';
+import { isLikelyRawModelId } from './config-helpers.mjs';
+import { readTextSafe, readJsonSafe } from './fs-utils.mjs';
+
+export const WORKFLOW_ROUTE_SLOTS = ['lead', 'agent', 'explorer', 'memory'];
+export const FIXED_AGENT_SLOTS = Object.freeze([
+  { id: 'explore', label: 'Explore', description: 'Broad repository exploration', workflowSlot: 'explorer' },
+  { id: 'maintainer', label: 'Maintainer', description: 'Background memory and upkeep', workflowSlot: 'memory' },
+  { id: 'worker', label: 'Worker', description: 'Scoped implementation' },
+  { id: 'heavy-worker', label: 'Heavy Worker', description: 'Broad or multi-file implementation' },
+  { id: 'reviewer', label: 'Reviewer', description: 'Diff review and risk checks' },
+  { 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';
+
+const SEARCH_CAPABLE_PROVIDERS = new Set([
+  'openai-oauth', 'openai', 'grok-oauth', 'xai', 'gemini', 'anthropic', 'anthropic-oauth',
+]);
+export const SEARCH_DEFAULT_PROVIDER = 'default';
+export const SEARCH_DEFAULT_MODEL = 'default';
+const SEARCH_PROVIDER_ALIASES = Object.freeze({
+  'openai-api': 'openai',
+  'xai-api': 'xai',
+  'gemini-api': 'gemini',
+  'anthropic-api': 'anthropic',
+});
+
+const agentDefinitionCache = new Map();
+const AGENT_DEFINITION_CACHE_LIMIT = 64;
+function setAgentDefinitionCache(key, value) {
+  if (!agentDefinitionCache.has(key) && agentDefinitionCache.size >= AGENT_DEFINITION_CACHE_LIMIT) {
+    const oldestKey = agentDefinitionCache.keys().next().value;
+    agentDefinitionCache.delete(oldestKey);
+  }
+  agentDefinitionCache.set(key, value);
+}
+
+export function workflowPresetId(slot) {
+  return `workflow-${slot}`;
+}
+
+function workflowPresetName(slot) {
+  return `WORKFLOW ${String(slot || '').toUpperCase()}`;
+}
+
+export function agentPresetSlot(agentId) {
+  return `agent-${String(agentId || '').replace(/[^a-z0-9_.-]+/gi, '-').toLowerCase()}`;
+}
+
+export function normalizeAgentId(value) {
+  const id = clean(value).toLowerCase().replace(/[\s_]+/g, '-');
+  if (id === 'explorer') return 'explore';
+  if (id === 'maint' || id === 'maintenance' || id === 'memory') return 'maintainer';
+  if (id === 'heavy' || id === 'heavyworker') return 'heavy-worker';
+  if (id === 'review') return 'reviewer';
+  if (id === 'debug') return 'debugger';
+  return AGENT_ROLE_IDS.has(id) ? id : '';
+}
+
+export function normalizeWorkflowId(value, fallback = '') {
+  const id = clean(value).toLowerCase().replace(/[\s_]+/g, '-');
+  return /^[a-z0-9][a-z0-9_.-]*$/.test(id) ? id : fallback;
+}
+
+// A workflow/agent pack loader is created per data/root layout via
+// createWorkflowHelpers, and the config-aware route helpers via
+// createWorkflowRouteHelpers.
+export function createWorkflowHelpers({ rootDir, dataDir, readMarkdownDocument, normalizeAgentPermissionOrNone }) {
+  function workflowSourceDirs(dir) {
+    return [
+      { root: join(rootDir, 'workflows'), source: 'built-in' },
+      { root: join(dir || dataDir, 'workflows'), source: 'user' },
+    ];
+  }
+
+  function agentSourceDirs(dir, id) {
+    return [
+      join(dir || dataDir, 'agents', id),
+      join(rootDir, 'agents', id),
+    ];
+  }
+
+  function readWorkflowPackFromDir(dir, source = 'built-in', dirName = '') {
+    const entry = 'WORKFLOW.md';
+    const doc = readMarkdownDocument(readTextSafe(join(dir, entry)));
+    const body = doc.body;
+    if (!body) return null;
+    const fm = doc.frontmatter || {};
+    const id = normalizeWorkflowId(clean(fm.id) || dirName || basename(dir));
+    if (!id) return null;
+    const agentsConfigured = Object.prototype.hasOwnProperty.call(fm, 'agents');
+    return {
+      id,
+      name: clean(fm.name) || id,
+      description: clean(fm.description),
+      entry,
+      agentsConfigured,
+      agents: agentsConfigured
+        ? String(fm.agents || '')
+            .split(',')
+            .map((agent) => normalizeAgentId(agent) || normalizeWorkflowId(agent))
+            .filter(Boolean)
+        : [],
+      body,
+      source,
+    };
+  }
+
+  function listWorkflowPacks(dir) {
+    const byId = new Map();
+    for (const { root, source } of workflowSourceDirs(dir)) {
+      if (!existsSync(root)) continue;
+      let entries = [];
+      try { entries = readdirSync(root, { withFileTypes: true }); } catch { entries = []; }
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const d = join(root, entry.name);
+        if (!existsSync(join(d, 'WORKFLOW.md'))) continue;
+        const pack = readWorkflowPackFromDir(d, source, entry.name);
+        if (pack) byId.set(pack.id, pack);
+      }
+    }
+    return [...byId.values()].sort((a, b) => {
+      if (a.id === DEFAULT_WORKFLOW_ID) return -1;
+      if (b.id === DEFAULT_WORKFLOW_ID) return 1;
+      return a.name.localeCompare(b.name);
+    });
+  }
+
+  function activeWorkflowId(config) {
+    return normalizeWorkflowId(config?.workflow?.active, DEFAULT_WORKFLOW_ID);
+  }
+
+  function loadWorkflowPack(dir, id) {
+    const wanted = normalizeWorkflowId(id, DEFAULT_WORKFLOW_ID);
+    for (const { root, source } of workflowSourceDirs(dir).reverse()) {
+      const pack = readWorkflowPackFromDir(join(root, wanted), source, wanted);
+      if (pack) return pack;
+    }
+    return readWorkflowPackFromDir(join(rootDir, 'workflows', DEFAULT_WORKFLOW_ID), 'built-in', DEFAULT_WORKFLOW_ID);
+  }
+
+  function workflowSummary(pack) {
+    const id = normalizeWorkflowId(pack?.id, DEFAULT_WORKFLOW_ID);
+    return {
+      id,
+      name: clean(pack?.name) || (id === DEFAULT_WORKFLOW_ID ? 'Default' : id),
+      description: clean(pack?.description),
+      source: clean(pack?.source),
+    };
+  }
+
+  function activeWorkflowSummary(config, dir) {
+    return workflowSummary(loadWorkflowPack(dir, activeWorkflowId(config)));
+  }
+
+  function loadAgentDefinition(dir, id) {
+    const agentId = normalizeAgentId(id) || normalizeWorkflowId(id);
+    if (!agentId) return null;
+    const cacheKey = `${dir || dataDir}\n${agentId}`;
+    if (agentDefinitionCache.has(cacheKey)) return agentDefinitionCache.get(cacheKey);
+    for (const d of agentSourceDirs(dir, agentId)) {
+      const manifest = readJsonSafe(join(d, 'agent.json')) || {};
+      const entry = clean(manifest.entry) || 'AGENT.md';
+      const doc = readMarkdownDocument(readTextSafe(join(d, entry)));
+      const body = doc.body;
+      if (!body) continue;
+      const definition = {
+        id: agentId,
+        name: clean(manifest.name) || FIXED_AGENT_SLOTS.find((agent) => agent.id === agentId)?.label || agentId,
+        description: clean(manifest.description) || FIXED_AGENT_SLOTS.find((agent) => agent.id === agentId)?.description || '',
+        permission: normalizeAgentPermissionOrNone(doc.frontmatter.permission),
+        frontmatter: doc.frontmatter,
+        body,
+      };
+      setAgentDefinitionCache(cacheKey, definition);
+      return definition;
+    }
+    const legacyDoc = readMarkdownDocument(readTextSafe(join(rootDir, 'agents', `${agentId}.md`)));
+    if (!legacyDoc.body) {
+      setAgentDefinitionCache(cacheKey, null);
+      return null;
+    }
+    const definition = {
+      id: agentId,
+      name: FIXED_AGENT_SLOTS.find((agent) => agent.id === agentId)?.label || agentId,
+      description: '',
+      permission: normalizeAgentPermissionOrNone(legacyDoc.frontmatter.permission),
+      frontmatter: legacyDoc.frontmatter,
+      body: legacyDoc.body,
+    };
+    setAgentDefinitionCache(cacheKey, definition);
+    return definition;
+  }
+
+  function workflowContextBlock(config, dir) {
+    const pack = loadWorkflowPack(dir, activeWorkflowId(config));
+    if (!pack) return '';
+    const lines = [`# Active Workflow: ${pack.name}`];
+    if (pack.description) lines.push(pack.description);
+    lines.push(pack.body);
+    const agentIds = pack.agentsConfigured ? pack.agents : FIXED_AGENT_SLOTS.map((agent) => agent.id);
+    const agentBlocks = agentIds.map((id) => loadAgentDefinition(dir, id)).filter(Boolean);
+    if (agentBlocks.length) {
+      lines.push('# Available Agents');
+      for (const agent of agentBlocks) {
+        lines.push(`## ${agent.name} (${agent.id})`);
+        if (agent.description) lines.push(agent.description);
+        lines.push(agent.body);
+      }
+    }
+    return lines.join('\n\n');
+  }
+
+  return {
+    listWorkflowPacks,
+    activeWorkflowId,
+    loadWorkflowPack,
+    workflowSummary,
+    activeWorkflowSummary,
+    loadAgentDefinition,
+    workflowContextBlock,
+  };
+}
+
+export function normalizeSearchProviderId(provider) {
+  const id = clean(provider);
+  return SEARCH_PROVIDER_ALIASES[id] || id;
+}
+
+export function isDefaultSearchRouteConfig(routeLike = {}) {
+  return normalizeSearchProviderId(routeLike?.provider) === SEARCH_DEFAULT_PROVIDER
+    && clean(routeLike?.model).toLowerCase() === SEARCH_DEFAULT_MODEL;
+}
+
+export function isSearchCapableProvider(provider) {
+  return SEARCH_CAPABLE_PROVIDERS.has(normalizeSearchProviderId(provider));
+}
+
+export function normalizeSearchRouteConfig(routeLike, fallback = {}) {
+  const provider = normalizeSearchProviderId(routeLike?.provider || fallback.provider);
+  const model = clean(routeLike?.model || fallback.model);
+  if (!provider || !model) return null;
+  let effort = null;
+  try {
+    effort = normalizeEffortInput(routeLike?.effort ?? fallback.effort);
+  } catch {
+    effort = null;
+  }
+  const fast = routeLike?.fast ?? fallback.fast;
+  const toolType = clean(routeLike?.toolType || fallback.toolType);
+  return {
+    provider,
+    model,
+    ...(effort ? { effort } : {}),
+    ...(fast === true ? { fast: true } : {}),
+    ...(toolType ? { toolType } : {}),
+  };
+}
+
+export function normalizeWorkflowRoute(routeLike, fallback = {}) {
+  const provider = clean(routeLike?.provider) || clean(fallback.provider);
+  const model = clean(routeLike?.model) || clean(fallback.model);
+  if (!provider || !model) return null;
+  // Defensive: a workflow/agent route must carry a real model id. Reject values
+  // that are obviously free-form text (whitespace, prose) so a bad string can
+  // never be persisted as a preset/workflow route.
+  if (!isLikelyRawModelId(model)) return null;
+  const effort = normalizeEffortInput(routeLike?.effort ?? fallback.effort);
+  const fast = routeLike?.fast ?? fallback.fast;
+  return {
+    provider,
+    model,
+    ...(effort ? { effort } : {}),
+    ...(fast === true ? { fast: true } : {}),
+  };
+}
+
+export function upsertWorkflowPreset(presets, slot, routeLike) {
+  const route = normalizeWorkflowRoute(routeLike);
+  if (!route) return presets;
+  const id = workflowPresetId(slot);
+  const preset = {
+    id,
+    name: workflowPresetName(slot),
+    type: 'agent',
+    provider: route.provider,
+    model: route.model,
+    ...(route.effort ? { effort: route.effort } : {}),
+    ...(route.fast === true ? { fast: true } : {}),
+    tools: 'full',
+  };
+  const next = (Array.isArray(presets) ? presets : []).filter((p) => clean(p?.id) !== id && clean(p?.name) !== preset.name);
+  next.push(preset);
+  return next;
+}
+
+// Config-aware route resolvers need resolveDefaultProvider + findPreset from
+// the runtime; created via this factory.
+export function createWorkflowRouteHelpers({ resolveDefaultProvider, findPreset }) {
+  function summarizeWorkflowRoutes(config) {
+    const routes = config?.workflowRoutes && typeof config.workflowRoutes === 'object' ? config.workflowRoutes : {};
+    const fallbackProvider = resolveDefaultProvider(config);
+    const out = {};
+    for (const slot of WORKFLOW_ROUTE_SLOTS) {
+      const route = routes[slot];
+      // Read/interpret path: a route with a model but no provider falls back to
+      // config.defaultProvider (then DEFAULT_PROVIDER).
+      if (route?.model && (route?.provider || fallbackProvider)) {
+        out[slot] = normalizeWorkflowRoute(route, { provider: fallbackProvider });
+      }
+    }
+    return out;
+  }
+
+  function routeFromPreset(config, slotValue) {
+    // Maintenance slots now store a direct {provider, model} route. Accept that
+    // shape first; fall back to the legacy preset-NAME string lookup so configs
+    // written before the route migration still resolve.
+    if (slotValue && typeof slotValue === 'object' && !Array.isArray(slotValue)) {
+      const direct = normalizeWorkflowRoute(slotValue);
+      if (direct) return direct;
+    }
+    const preset = findPreset(config, slotValue);
+    return preset ? normalizeWorkflowRoute(preset) : null;
+  }
+
+  function agentRouteFromConfig(config, agentId, _dataDir) {
+    const id = normalizeAgentId(agentId);
+    if (!id) return null;
+    // Read/interpret path: inject config.defaultProvider (then DEFAULT_PROVIDER)
+    // when a stored route omits its provider.
+    const fallback = { provider: resolveDefaultProvider(config) };
+    const explicit = normalizeWorkflowRoute(config?.agents?.[id], fallback)
+      || (id === 'maintainer' ? normalizeWorkflowRoute(config?.agents?.maintenance, fallback) : null);
+    if (explicit) return explicit;
+
+    const agent = FIXED_AGENT_SLOTS.find((item) => item.id === id);
+    if (agent?.workflowSlot) {
+      const workflowRoute = normalizeWorkflowRoute(config?.workflowRoutes?.[agent.workflowSlot], fallback);
+      if (workflowRoute) return workflowRoute;
+    }
+
+    if (id === 'explore') return routeFromPreset(config, config?.maintenance?.explore);
+    if (id === 'maintainer') return routeFromPreset(config, config?.maintenance?.memory);
+
+    return null;
+  }
+
+  return { summarizeWorkflowRoutes, routeFromPreset, agentRouteFromConfig };
+}

package/src/standalone/agent-tool.mjs

@@ -14,7 +14,7 @@ import {
   taskIdFromArgs,
 } from '../runtime/shared/background-tasks.mjs';
 import { modelVisibleToolCompletionMessage } from '../runtime/shared/tool-execution-contract.mjs';
-import { presentErrorText } from '../runtime/shared/err-text.mjs';
+import { presentErrorText, errorLine } from '../runtime/shared/err-text.mjs';
 import { updateJsonAtomicSync } from '../runtime/shared/atomic-file.mjs';
 import {
   normalizeAgentPermission,
@@ -135,7 +135,11 @@ function envTimeoutMs(name, fallback) {
 // Grace window during which a terminated/idle worker row is kept around so the
 // same terminal can re-use (or cleanly re-spawn) the same tag. Cached as a
 // constant like the other timeouts; override with MIXDOG_AGENT_TERMINAL_REAP_MS.
-const TERMINAL_REAP_MS = envTimeoutMs('MIXDOG_AGENT_TERMINAL_REAP_MS', 60 * 60_000);
+// 5m (was 1h): aligned with the BP4 message-tail cache TTL — past 5m the
+// session's prompt cache is cold anyway, so same-tag reuse pays a full prefix
+// rewrite; a fresh respawn (send dead-tag fallback) starts smaller and cheaper.
+// Trace replay (2026-07): agent tail cost 1h 1.77M -> 5m 1.11M (-37%).
+const TERMINAL_REAP_MS = envTimeoutMs('MIXDOG_AGENT_TERMINAL_REAP_MS', 5 * 60_000);
 // Independent hard cap for the spawn *prep* phase (ensureProvider /
 // prepareAgentSession / catalog+rules load). Kept separate from the
 // first-response watchdog so prep cannot hang a whole fanout before the model
@@ -387,7 +391,7 @@ function renderResult(value) {
       for (const job of jobs) {
         const target = job.tag || job.sessionId || '-';
         const terminal = job.clientHostPid ? ` term=${job.clientHostPid}` : '';
-        const base = `- ${job.task_id} ${job.type} ${job.status} target=${target}${terminal}${job.error ? ` error=${presentErrorText(job.error, { surface: 'agent' })}` : ''}`;
+        const base = `- ${job.task_id} ${job.type} ${job.status} target=${target}${terminal}${job.error ? ` error=${job.error}` : ''}`;
         lines.push(appendAgentProgressKv(base, job));
       }
       if (workers.length === 0 && jobs.length === 0) lines.push('(no agents or tasks)');
@@ -422,7 +426,7 @@ function renderResult(value) {
         const elapsed = elapsedFromStamps(value.startedAt, value.finishedAt, value.status);
         if (elapsed) lines.push(`elapsed: ${elapsed}`);
       }
-      if (value.error) lines.push(`error: ${presentErrorText(value.error, { surface: 'agent' })}`);
+      if (value.error) lines.push(`error: ${value.error}`);
       if (value.status === 'running') lines.push('notification: completion will be delivered to the owner session; use read/status only for manual recovery.');
       if (value.result !== undefined) {
         const result = value.result;
@@ -466,7 +470,13 @@ function renderResult(value) {
   return JSON.stringify(value, null, 2);
 }
 
-export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultCwd }) {
+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.
+  function emitSubagentEvent(phase, agent, extra = {}) {
+    if (typeof onSubagentEvent !== 'function') return;
+    try { onSubagentEvent(phase, { agent_type: agent || null, ...extra }); } catch { /* best-effort */ }
+  }
   const tags = new Map();
   const tagAgents = new Map();
   const tagCwds = new Map();
@@ -1246,6 +1256,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       tag: meta.tag || null,
       sessionId: meta.sessionId || null,
       agent: meta.agent || null,
+      ...(meta.respawned === true ? { respawned: true, note: 'previous session reaped — fresh session, no prior context; re-supply anchors if needed' } : {}),
       preset: meta.preset || null,
       provider: meta.provider || null,
       model: meta.model || null,
@@ -1619,6 +1630,8 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     const { args, tag, session, agent, preset, presetName, workerCwd, prompt, watchdogPolicy } = prepared;
     const watchdog = startProgressIdleWatchdog(session.id, watchdogPolicy);
     let finalStatus = 'idle';
+    // SubagentStart: a worker session is about to run its first turn.
+    emitSubagentEvent('start', agent, { session_id: session.id, tag });
     upsertWorkerSessionDeferred(session, tag, {
       agent,
       preset: presetKey(preset) || presetName,
@@ -1710,7 +1723,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
         try {
           reconcileBackgroundTask(job.taskId, {
             status: 'failed',
-            error: presentErrorText(error, { surface: 'agent' }),
+            error,
             terminalReason: 'agent-stream-stalled',
           });
         } catch {}
@@ -1747,6 +1760,8 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
         } catch {}
       }
       scheduleReap(session.id);
+      // SubagentStop: worker finished (terminal), regardless of outcome.
+      emitSubagentEvent('stop', agent, { session_id: session.id, tag, status: finalStatus });
     }
   }
 
@@ -1836,7 +1851,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
         try {
           reconcileBackgroundTask(job.taskId, {
             status: 'failed',
-            error: presentErrorText(error, { surface: 'agent' }),
+            error,
             terminalReason: 'agent-stream-stalled',
           });
         } catch {}
@@ -1996,8 +2011,32 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       if (type === 'cancel') return renderResult(close(args, scopedContext));
       if (type === 'close') return renderResult(close(args, scopedContext));
       if (type === 'send') {
-        const prepared = await prepareSend(args, scopedContext);
-        return dispatchToExistingSession(prepared, notifyContext);
+        try {
+          const prepared = await prepareSend(args, scopedContext);
+          return dispatchToExistingSession(prepared, notifyContext);
+        } catch (err) {
+          // Reaped/dead-tag fallback: with the 5m terminal-reap window a
+          // same-scope follow-up often lands after the session is gone.
+          // Instead of bouncing an error back to Lead (who would just
+          // re-issue the same content as a spawn), respawn a FRESH session
+          // under the same tag with the message as its brief. `respawned:
+          // true` in the result tells Lead the worker has no prior session
+          // context — re-supply anchors on the next send if needed.
+          // Only tag-addressed sends fall back; explicit sessionId sends
+          // keep erroring (caller pinned a specific session on purpose).
+          const fallbackTag = clean(args.tag);
+          const isDeadTarget = /not found|is closed/i.test(String(err?.message || ''));
+          if (!fallbackTag || fallbackTag.startsWith('sess_') || !isDeadTarget) throw err;
+          const prompt = clean(args.message || args.prompt);
+          if (!prompt) throw err;
+          // Clear the terminal trace so the fresh spawn isn't rejected by
+          // the lingering-trace guard, then run the normal deferred spawn.
+          try { forgetTag(fallbackTag); } catch {}
+          try { removeWorkerRow({ tag: fallbackTag }); } catch {}
+          const spawnArgs = { ...args, type: 'spawn', tag: fallbackTag, prompt, message: undefined };
+          const job = startDeferredSpawnJob(spawnArgs, callerCwd, context, notifyContext, { respawned: true });
+          return renderResult(renderJob(job, false));
+        }
       }
       if (type === 'spawn') {
         // Explicit-tag spawn priority (auto nextTag always creates a fresh session):
@@ -2033,7 +2072,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       }
       throw new Error(`agent: unknown type "${type}"`);
     } catch (err) {
-      return `Error: ${presentErrorText(err, { surface: 'agent' })}`;
+      return errorLine(err, { surface: 'agent' });
     }
   }
 

package/src/standalone/channel-worker.mjs

@@ -1,9 +1,10 @@
 import { execFile, fork, spawnSync } from 'node:child_process';
-import { appendFileSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { startChildGuardian } from '../runtime/shared/child-guardian.mjs';
+import { appendBuffered } from '../runtime/shared/buffered-appender.mjs';
 
 const CHANNEL_TOOLS = new Set([
   'reply',
@@ -24,7 +25,7 @@ const WORKER_PRELOAD = fileURLToPath(new URL('./channel-worker-preload.cjs', imp
 function logLine(path, line) {
   try {
     mkdirSync(dirname(path), { recursive: true });
-    appendFileSync(path, `[${new Date().toISOString()}] ${line}\n`);
+    appendBuffered(path, `[${new Date().toISOString()}] ${line}\n`);
   } catch {
     // Logging must never break the TUI.
   }

package/src/standalone/explore-tool.mjs

@@ -170,8 +170,12 @@ function findConfigPreset(config, presetName) {
 }
 
 async function ensureExploreProviderReady(config) {
-  const preset = findConfigPreset(config, config?.maintenance?.explore);
-  const provider = clean(preset?.provider);
+  const route = config?.maintenance?.explore;
+  // Route object ({provider,model}) is the current shape; a string is a
+  // legacy preset NAME resolved against config.presets.
+  const provider = (route && typeof route === 'object')
+    ? clean(route.provider)
+    : clean(findConfigPreset(config, route)?.provider);
   if (!provider) return;
   const providers = { ...(config?.providers || {}) };
   providers[provider] = { ...(providers[provider] || {}), enabled: true };
@@ -303,7 +307,10 @@ async function runExploreSync(args = {}, ctx = {}) {
   scheduleExploreCodeGraphPrewarm(resolvedCwd);
   const config = loadConfig();
   await ensureExploreProviderReady(config);
-  const presetName = config?.maintenance?.explore || '';
+  const route = config?.maintenance?.explore;
+  const presetName = (route && typeof route === 'object')
+    ? `${clean(route.provider)}/${clean(route.model)}`
+    : (route || '');
   const llm = makeAgentDispatch({
     agent: 'explorer',
     cwd: resolvedCwd,