mixdog 0.9.3 → 0.9.5

package/src/standalone/agent-tool.mjs

@@ -1,137 +1,66 @@
-import { existsSync, readFileSync, statSync } from 'node:fs';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
   cancelBackgroundTask,
   cleanupBackgroundTasks,
   getBackgroundTask,
   listBackgroundTasks,
-  renderBackgroundTask,
   reconcileBackgroundTask,
-  setBackgroundTaskEnqueueFallback,
   startBackgroundTask,
   sanitizeTaskMeta,
   taskIdFromArgs,
 } from '../runtime/shared/background-tasks.mjs';
-import { modelVisibleToolCompletionMessage } from '../runtime/shared/tool-execution-contract.mjs';
 import { presentErrorText, errorLine } from '../runtime/shared/err-text.mjs';
 import { updateJsonAtomicSync } from '../runtime/shared/atomic-file.mjs';
-import {
-  normalizeAgentPermission,
-  normalizeAgentPermissionOrNone,
-  parseMarkdownFrontmatter,
-} from '../runtime/shared/markdown-frontmatter.mjs';
+import { normalizeAgentPermission } from '../runtime/shared/markdown-frontmatter.mjs';
 import { prepareAgentSession } from '../runtime/agent/orchestrator/agent-runtime/session-builder.mjs';
 import {
   agentWatchdogPolicyActive,
   evaluateAgentWatchdogAbort,
   resolveAgentWatchdogPolicy,
 } from '../runtime/agent/orchestrator/agent-runtime/agent-progress-watchdog.mjs';
-import {
-  appendAgentProgressKv,
-  buildAgentTaskProgressFields,
-} from './agent-task-status.mjs';
+import { buildAgentTaskProgressFields } from './agent-task-status.mjs';
 import { AGENT_OWNER } from '../runtime/agent/orchestrator/agent-owner.mjs';
-import { clearGatewaySessionRoute, writeGatewaySessionRoute } from '../vendor/statusline/src/gateway/session-routes.mjs';
 import { isKnownProvider } from './provider-admin.mjs';
+import {
+  ACTIVE_STAGES,
+  AGENT_TOOL,
+  DEFAULT_AGENT_PRESETS,
+  DEFAULT_PROVIDER,
+  WORKER_INDEX_FILE,
+} from './agent-tool/tool-def.mjs';
+import {
+  agentPresetName,
+  agentScope,
+  agentTagOf,
+  clean,
+  clearAgentStatuslineRoute,
+  envTimeoutMs,
+  findPreset,
+  nonNegativeInt,
+  normalizeAgentName,
+  normalizeAgentRoute,
+  positiveInt,
+  presetKey,
+  readAgentFrontmatterPermission,
+  resolvePrompt,
+  rowMatchesContext,
+  sessionMatchesContext,
+  synthesizePreset,
+  terminalPidForContext,
+  withCwdHeader,
+  writeAgentStatuslineRoute,
+} from './agent-tool/helpers.mjs';
+import { abnormalEmptyFinishError, renderResult } from './agent-tool/render.mjs';
+import { createProviderInit } from './agent-tool/provider-init.mjs';
+import { createNotify } from './agent-tool/notify.mjs';
+// Re-export the static tool descriptor so importers of this facade keep the
+// identical public surface (`import { AGENT_TOOL } from './agent-tool.mjs'`).
+export { AGENT_TOOL };
 
 const STANDALONE_SOURCE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
-const PRESET_ALIASES = new Map([
-  ['opus-xhigh', { base: 'opus-high', effort: 'xhigh', id: 'opus-xhigh', name: 'OPUS XHIGH' }],
-]);
-
-const DEFAULT_AGENT_PRESETS = Object.freeze({
-  explore: 'sonnet-high',
-  maintainer: 'haiku',
-  worker: 'sonnet-high',
-  'heavy-worker': 'sonnet-high',
-  reviewer: 'opus-xhigh',
-  debugger: 'opus-xhigh',
-});
-
-// Mirrors DEFAULT_PROVIDER in mixdog-session-runtime.mjs. Used only as the
-// last-resort fallback when a stored agent route omits its provider and the
-// config carries no defaultProvider.
-const DEFAULT_PROVIDER = 'anthropic-oauth';
-
-export const AGENT_TOOL = {
-  name: 'agent',
-  title: 'Agent',
-  annotations: {
-    title: 'Agent',
-    readOnlyHint: false,
-    destructiveHint: true,
-    idempotentHint: false,
-    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.',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      type: { type: 'string', enum: ['spawn', 'send', 'list', 'close', 'cancel', 'status', 'read', 'cleanup'], description: 'Action. Default spawn.' },
-      task_id: { type: 'string', description: 'Manual recovery task ID.' },
-      agent: { type: 'string', description: 'Workflow agent id.' },
-      tag: { type: 'string', description: 'Stable scope handle. Reuse the same tag for follow-up on the same scope; use distinct tags only for independent scopes.' },
-      sessionId: { type: 'string', description: 'Raw sess_ id.' },
-      prompt: { type: 'string', description: 'Scoped task brief.' },
-      message: { type: 'string', description: 'Follow-up for send/reuse, or brief.' },
-      file: { type: 'string', description: 'Prompt file.' },
-      cwd: { type: 'string', description: 'Working directory.' },
-      context: { type: 'string', description: 'Extra agent context.' },
-    },
-    additionalProperties: true,
-  },
-};
-
-const WORKER_INDEX_FILE = 'agent-workers.json';
-
-// A worker that hits the loop iteration ceiling, gets truncated mid-synthesis,
-// or produces an empty terminal turn returns content:'' but never throws — so
-// the background task would otherwise reconcile as a benign `completed` empty
-// success. That is wrong: an empty final answer is an error. loop.mjs is the
-// single classifier: it tags result.terminationReason for abnormal finishes
-// (carried through manager.mjs terminalResultPreview). We key purely off that
-// here. iteration_cap / truncated are real problems for EVERY agent (hidden
-// too). The plain `empty` case is tagged by the loop ONLY for public agents;
-// hidden agents (explorer/cycle/…) legitimately emit empty terminal turns and
-// are left untagged, so they stay benign.
-function abnormalEmptyFinishError(result, agent) {
-  // The loop (loop.mjs) is the single classifier: it tags terminationReason
-  // ONLY for abnormal finishes, and gates the `empty` case behind !hidden.
-  // So we key purely off terminationReason here — no separate content/hidden
-  // check, which previously (a) exempted hidden agents from cap/truncated and
-  // (b) let a capped tool-call turn with preamble text slip through as success.
-  const reason = result?.terminationReason;
-  if (!reason) return null;
-  const iterations = result?.iterations ?? 0;
-  const toolCallsTotal = result?.toolCallsTotal ?? 0;
-  const maxLoopIterations = result?.maxLoopIterations ?? 0;
-  const stopReason = result?.stopReason ?? result?.stop_reason ?? null;
-  switch (reason) {
-    case 'iteration_cap':
-      // Real problem for EVERY agent (hidden too): the loop never terminated on
-      // its own contract, so any preamble text is not a trustworthy final answer.
-      return `agent '${agent}' hit the loop iteration ceiling (${maxLoopIterations} iterations, ${toolCallsTotal} tool calls) without producing a final answer`;
-    case 'truncated':
-      return `agent '${agent}' response was truncated (stopReason=${stopReason}) before a final answer (${iterations} iterations, ${toolCallsTotal} tool calls)`;
-    case 'empty':
-      // Only tagged for PUBLIC agents (hidden agents legitimately emit empty
-      // terminal turns and are left untagged by the loop).
-      return `agent '${agent}' finished without a final answer (stopReason=${stopReason ?? 'none'}, ${iterations} iterations, ${toolCallsTotal} tool calls)`;
-    default:
-      return null;
-  }
-}
-
-function envTimeoutMs(name, fallback) {
-  const raw = process.env[name];
-  if (raw === undefined || raw === '') return fallback;
-  const n = Number(raw);
-  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 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.
@@ -140,334 +69,52 @@ function envTimeoutMs(name, fallback) {
 // 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);
+// Provider-aware reap windows: the 5m default matches Anthropic's 5m agent
+// tail TTL, but providers with long-lived automatic prefix caches (OpenAI 24h
+// retention, DeepSeek hours-days, Groq 2h) keep a warm cache well past 5m, so
+// same-tag reuse stays cheaper than a respawn. Capped at 1h — holding closed
+// worker sessions longer hoards manager memory for a reuse pattern that
+// rarely spans hours. Explicit MIXDOG_AGENT_TERMINAL_REAP_MS overrides all.
+const PROVIDER_REAP_MS = {
+  'openai': 60 * 60_000,
+  'deepseek': 60 * 60_000,
+  'groq': 60 * 60_000,
+  'openai-oauth': 10 * 60_000,
+};
+function reapMsForProvider(provider) {
+  if (clean(process.env.MIXDOG_AGENT_TERMINAL_REAP_MS)) return TERMINAL_REAP_MS;
+  return PROVIDER_REAP_MS[clean(provider)] || TERMINAL_REAP_MS;
+}
 // 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
 // request starts. Set MIXDOG_AGENT_SPAWN_PREP_TIMEOUT_MS=0 to fully disable the
 // cap and restore strictly-unbounded prep.
 const DEFAULT_SPAWN_PREP_TIMEOUT_MS = envTimeoutMs('MIXDOG_AGENT_SPAWN_PREP_TIMEOUT_MS', 120_000);
-const ACTIVE_STAGES = new Set(['connecting', 'requesting', 'streaming', 'tool_running', 'running', 'cancelling']);
-
-// Process-wide TTL cache for agent AGENT.md frontmatter permission. The file
-// rarely changes, but readAgentFrontmatterPermission() otherwise pays several
-// existsSync()+readFileSync() calls on EVERY spawn — multiplied across a
-// parallel fanout that is pure redundant synchronous I/O on the event loop,
-// which blocks every other concurrent spawn. Short TTL keeps edits picked up
-// quickly while collapsing burst reads.
-const _frontmatterPermCache = new Map(); // key -> { value, atMs }
-const FRONTMATTER_PERM_CACHE_TTL_MS = envTimeoutMs('MIXDOG_AGENT_FRONTMATTER_TTL_MS', 5_000);
-
-function clean(value) {
-  return String(value ?? '').trim();
-}
-
-function agentTagOf(session) {
-  return clean(session?.agentTag);
-}
-
-function normalizeAgentName(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 id;
-}
-
-function readAgentFrontmatterPermission(agent, dataDir) {
-  const cleanAgent = clean(agent);
-  if (!cleanAgent) return null;
-  const cacheKey = `${dataDir || ''}\u0000${cleanAgent}`;
-  const cached = _frontmatterPermCache.get(cacheKey);
-  if (cached && Date.now() - cached.atMs < FRONTMATTER_PERM_CACHE_TTL_MS) {
-    return cached.value;
-  }
-  const candidates = [];
-  if (dataDir) {
-    candidates.push(join(dataDir, 'agents', cleanAgent, 'AGENT.md'));
-    candidates.push(join(dataDir, 'agents', `${cleanAgent}.md`));
-  }
-  candidates.push(join(STANDALONE_SOURCE_ROOT, 'agents', cleanAgent, 'AGENT.md'));
-  candidates.push(join(STANDALONE_SOURCE_ROOT, 'agents', `${cleanAgent}.md`));
-  let resolved = null;
-  for (const file of candidates) {
-    if (!existsSync(file)) continue;
-    const fm = parseMarkdownFrontmatter(readFileSync(file, 'utf8'));
-    const permission = normalizeAgentPermissionOrNone(fm.permission);
-    if (permission) { resolved = permission; break; }
-  }
-  _frontmatterPermCache.set(cacheKey, { value: resolved, atMs: Date.now() });
-  return resolved;
-}
-
-function positiveInt(value) {
-  const n = Number(value);
-  return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
-}
-
-function terminalPidForContext(context = {}) {
-  return positiveInt(context?.clientHostPid);
-}
-
-function agentScope(args = {}, context = {}) {
-  const scope = clean(args.scope || args.terminal || args.term).toLowerCase();
-  if (args.allTerminals === true || scope === 'all' || scope === 'global') return {};
-  return context || {};
-}
-
-function sessionMatchesContext(session, context = {}) {
-  const wantedPid = terminalPidForContext(context);
-  if (!wantedPid) return true;
-  const sessionPid = positiveInt(session?.clientHostPid);
-  return !!sessionPid && sessionPid === wantedPid;
-}
-
-function rowMatchesContext(row, context = {}) {
-  const wantedPid = terminalPidForContext(context);
-  if (!wantedPid) return true;
-  const rowPid = positiveInt(row?.clientHostPid);
-  return !!rowPid && rowPid === wantedPid;
-}
-
-function nonNegativeInt(value) {
-  if (value === undefined || value === null || value === '') return null;
-  const n = Number(value);
-  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null;
-}
-
-function presetKey(preset) {
-  return clean(preset?.id || preset?.name);
-}
-
-function bridgeRouteForStatusline(preset = {}) {
-  const provider = clean(preset.provider);
-  const model = clean(preset.model);
-  if (!provider || !model) return null;
-  const out = {
-    mode: 'fixed',
-    defaultProvider: provider,
-    defaultModel: model,
-  };
-  const id = clean(preset.id);
-  const name = clean(preset.name);
-  const modelDisplay = clean(preset.modelDisplay || preset.display || preset.displayName);
-  const effort = clean(preset.effort);
-  if (id) out.presetId = id;
-  if (name) out.presetName = name;
-  if (modelDisplay) out.modelDisplay = modelDisplay;
-  if (effort) {
-    out.effort = effort;
-    out.displayEffort = effort;
-  }
-  if (preset.fast === true || preset.fast === false) out.fast = preset.fast;
-  return out;
-}
-
-function writeAgentStatuslineRoute(sessionId, preset) {
-  const route = bridgeRouteForStatusline(preset);
-  if (!sessionId || !route) return false;
-  try { return writeGatewaySessionRoute(sessionId, route); } catch { return false; }
-}
-
-function clearAgentStatuslineRoute(sessionId) {
-  if (!sessionId) return false;
-  try { return clearGatewaySessionRoute(sessionId); } catch { return false; }
-}
-
-function findPreset(config, key) {
-  const wanted = clean(key).toLowerCase();
-  if (!wanted) return null;
-  const presets = Array.isArray(config?.presets) ? config.presets : [];
-  return presets.find((p) => {
-    return clean(p?.id).toLowerCase() === wanted || clean(p?.name).toLowerCase() === wanted;
-  }) || null;
-}
-
-function synthesizePreset(config, key) {
-  const alias = PRESET_ALIASES.get(clean(key).toLowerCase());
-  if (!alias) return null;
-  const base = findPreset(config, alias.base);
-  if (!base) return null;
-  return {
-    ...base,
-    id: alias.id,
-    name: alias.name,
-    effort: alias.effort,
-  };
-}
-
-function normalizeAgentRoute(routeLike, fallbackProvider = '') {
-  const provider = clean(routeLike?.provider) || clean(fallbackProvider);
-  const model = clean(routeLike?.model);
-  if (!provider || !model) return null;
-  return {
-    provider,
-    model,
-    effort: clean(routeLike?.effort) || undefined,
-    fast: routeLike?.fast === true,
-  };
-}
-
-function agentPresetName(agent) {
-  return `AGENT ${String(agent || '').toUpperCase()}`;
-}
-
-async function resolvePrompt(args, cwd) {
-  const prompt = clean(args.prompt || args.message);
-  const file = clean(args.file);
-  if (prompt && file) throw new Error('agent: provide only one of prompt/message or file');
-  if (prompt) return prompt;
-  if (file) {
-    const target = isAbsolute(file) ? file : resolve(cwd || process.cwd(), file);
-    return readFileSync(target, 'utf8');
-  }
-  throw new Error('agent: prompt/message/file is required');
-}
-
-function withCwdHeader(prompt, cwd) {
-  if (!cwd) return prompt;
-  if (String(prompt).startsWith('[effective-cwd]')) return prompt;
-  return `[effective-cwd] ${cwd}\n\n${prompt}`;
-}
 
-function oneLine(value, max = 180) {
-  const text = String(value ?? '').replace(/\s+/g, ' ').trim();
-  return text.length > max ? `${text.slice(0, max)}...` : text;
-}
-
-function compactIso(value) {
-  const text = clean(value);
-  if (!text) return '';
-  return text.replace('T', ' ').replace(/\.\d+Z$/, 'Z');
-}
-
-function formatElapsedMs(ms) {
-  const n = Number(ms);
-  if (!Number.isFinite(n) || n < 0) return '';
-  const totalSec = Math.floor(n / 1000);
-  if (totalSec < 60) return `${totalSec}s`;
-  const min = Math.floor(totalSec / 60);
-  const sec = totalSec % 60;
-  if (min < 60) return sec ? `${min}m${sec}s` : `${min}m`;
-  const hr = Math.floor(min / 60);
-  const remMin = min % 60;
-  return remMin ? `${hr}h${remMin}m` : `${hr}h`;
-}
-
-function elapsedFromStamps(startedAt, finishedAt, status) {
-  const start = Date.parse(clean(startedAt));
-  if (!Number.isFinite(start)) return null;
-  const finish = Date.parse(clean(finishedAt));
-  const end = Number.isFinite(finish) ? finish : Date.now();
-  const label = formatElapsedMs(end - start);
-  if (!label) return null;
-  return Number.isFinite(finish) ? label : `${label} (running)`;
-}
-
-function stripFinalAnswerWrapper(value) {
-  const text = String(value ?? '').trim();
-  const match = /^<final-answer\b[^>]*>([\s\S]*?)<\/final-answer>\s*$/i.exec(text);
-  return match ? match[1].trim() : text;
-}
-
-function renderResult(value) {
-  if (value === undefined || value === null) return '';
-  if (typeof value === 'string') return value;
-  if (value && typeof value === 'object') {
-    const lines = [];
-
-    if (Array.isArray(value.workers) || Array.isArray(value.jobs)) {
-      const workers = Array.isArray(value.workers) ? value.workers : [];
-      lines.push(`agents: ${workers.length}`);
-      for (const worker of workers) {
-        const tokens = worker.windowTokens ? ` ctx=${worker.windowTokens}${worker.windowCap ? `/${worker.windowCap}` : ''}` : '';
-        const terminal = worker.clientHostPid ? ` term=${worker.clientHostPid}` : '';
-        const base = `- ${worker.tag} ${worker.agent || 'agent'} ${worker.status || 'idle'}/${worker.worker_stage || worker.stage || 'idle'} ${worker.provider}/${worker.model}${terminal}${tokens}`;
-        lines.push(appendAgentProgressKv(base, worker));
-      }
-      const jobs = Array.isArray(value.jobs) ? value.jobs : [];
-      lines.push(`tasks: ${jobs.length}`);
-      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=${job.error}` : ''}`;
-        lines.push(appendAgentProgressKv(base, job));
-      }
-      if (workers.length === 0 && jobs.length === 0) lines.push('(no agents or tasks)');
-      return lines.join('\n');
-    }
-
-    if (value.task_id) {
-      lines.push(`agent task: ${value.task_id}`);
-      lines.push(`status: ${value.status}`);
-      if (value.type) lines.push(`type: ${value.type}`);
-      if (value.reused) lines.push('reused: true');
-      if (value.tag || value.sessionId) lines.push(`target: ${value.tag || '-'} ${value.sessionId || ''}`.trim());
-      if (value.agent) lines.push(`agent: ${value.agent}`);
-      if (value.provider && value.model) lines.push(`model: ${value.provider}/${value.model}`);
-      if (value.effort) lines.push(`effort: ${value.effort}`);
-      if (value.fast === true || value.fast === false) lines.push(`fast: ${value.fast ? 'on' : 'off'}`);
-      if (value.maxLoopIterations) {
-        const limitParts = [];
-        if (value.maxLoopIterations) limitParts.push(`loop=${value.maxLoopIterations}`);
-        lines.push(`limits: ${limitParts.join(' ')}`);
-      }
-      if (value.stage || value.workerStatus) lines.push(`worker: ${value.workerStatus || 'unknown'}/${value.stage || 'unknown'}`);
-      if (value.worker_stage) lines.push(`worker_stage: ${value.worker_stage}`);
-      if (value.last_progress) lines.push(`last_progress: ${value.last_progress}`);
-      if (Number.isFinite(value.silent_for)) lines.push(`silent_for: ${value.silent_for}s`);
-      if (value.watchdog) lines.push(`watchdog: ${value.watchdog}`);
-      if (Number.isFinite(value.queued_followups)) lines.push(`queued_followups: ${value.queued_followups}`);
-      if (value.diagnostic) lines.push(`diagnostic: ${value.diagnostic}`);
-      if (value.startedAt) lines.push(`started: ${compactIso(value.startedAt)}`);
-      if (value.finishedAt) lines.push(`finished: ${compactIso(value.finishedAt)}`);
-      {
-        const elapsed = elapsedFromStamps(value.startedAt, value.finishedAt, value.status);
-        if (elapsed) lines.push(`elapsed: ${elapsed}`);
-      }
-      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;
-        const content = typeof result === 'string' ? result : result?.content;
-        if (content) lines.push('', stripFinalAnswerWrapper(content));
-        else lines.push('', JSON.stringify(result, null, 2));
-      }
-      return lines.join('\n');
-    }
-
-    if (value.queued) {
-      return [
-        'agent message queued',
-        value.reused ? 'reused: true' : null,
-        `target: ${value.tag || '-'} ${value.sessionId || ''}`.trim(),
-        value.agent ? `agent: ${value.agent}` : null,
-        `queueDepth: ${value.queueDepth ?? 1}`,
-      ].filter(Boolean).join('\n');
-    }
-
-    if (value.closed !== undefined) {
-      return [
-        `agent close: ${value.closed ? 'ok' : 'not closed'}`,
-        value.tag ? `tag: ${value.tag}` : null,
-        value.sessionId ? `sessionId: ${value.sessionId}` : null,
-        value.task_id ? `task_id: ${value.task_id}` : null,
-        value.forgotten ? 'forgotten: true' : null,
-      ].filter(Boolean).join('\n');
-    }
-
-    if (value.content !== undefined) {
-      const header = [
-        value.respawned ? 'agent respawned' : 'agent result',
-        value.tag ? `tag=${value.tag}` : null,
-        value.agent ? `agent=${value.agent}` : null,
-        value.provider && value.model ? `${value.provider}/${value.model}` : null,
-      ].filter(Boolean).join(' ');
-      return `${header}\n${stripFinalAnswerWrapper(value.content)}`;
-    }
-  }
-  return JSON.stringify(value, null, 2);
+// 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 }) {
@@ -504,7 +151,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     const t = workerRowTime(row);
     if (!t) return true;
     if (!isTerminalWorkerStatus(row.status || row.stage)) return true;
-    return Date.now() - t < TERMINAL_REAP_MS;
+    return Date.now() - t < reapMsForProvider(row.provider);
   }
 
   function normalizeWorkerRows(value) {
@@ -913,9 +560,10 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     return true;
   }
 
-  function scheduleReap(sessionId) {
+  function scheduleReap(sessionId, provider = null) {
     if (!sessionId) return;
     cancelReap(sessionId);
+    const reapProvider = provider || getLiveSession(sessionId)?.provider || null;
     const handle = setTimeout(() => {
       reapTimers.delete(sessionId);
       try { mgr.hideSessionFromList?.(sessionId); } catch {}
@@ -924,7 +572,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       removeWorkerRow({ tag, sessionId });
       clearAgentStatuslineRoute(sessionId);
       try { mgr.closeSession(sessionId, 'terminal-reap'); } catch {}
-    }, TERMINAL_REAP_MS);
+    }, reapMsForProvider(reapProvider));
     handle.unref?.();
     reapTimers.set(sessionId, handle);
   }
@@ -937,140 +585,10 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     return ACTIVE_STAGES.has(session?.status || '');
   }
 
-  // Provider init de-dup. Four goals that must not conflict:
-  //   (a) a parallel spawn fanout that all targets the SAME provider with the
-  //       SAME effective config performs at most ONE initProviders() pass
-  //       instead of N serially-awaited registry rebuilds,
-  //   (b) a provider CONFIG CHANGE still reaches initProviders() so the
-  //       registry's own signature guard can re-initialize it,
-  //   (c) two DIFFERENT config signatures for the same provider never init
-  //       concurrently — otherwise a slow init of the OLD config could land
-  //       after a fast init of the NEW config and revert the live registry to
-  //       stale config, and
-  //   (d) a SUPERSEDED request never resolves before the provider is actually
-  //       ready: even when its own (stale) init is dropped to satisfy (c), the
-  //       caller (a spawn about to run prepareSpawn) must still WAIT for the
-  //       latest init to finish, or it would proceed against an unprepared /
-  //       stale provider.
-  //
-  // Skip cache + in-flight collapse are keyed on `provider + signature(effective
-  // config)`. To satisfy (c) we SERIALIZE all inits per provider on a chain
-  // promise and re-check the latest-requested signature inside the chain: a
-  // request superseded by a newer signature drops its own init. To satisfy (d)
-  // such a dropped request does not resolve immediately — it awaits the
-  // provider's latest settled init (tracked as a rolling "ready" promise) so the
-  // caller only proceeds once the newest config is live.
-  // Per-provider state. `chain` serializes the ACTUAL initProviders() calls so
-  // two different config signatures never run concurrently (goal c). `latestGen`
-  // / `latestSig` track the newest requested config. `ready` is a rolling
-  // deferred that resolves only when the LATEST requested init has completed —
-  // a superseded caller awaits the ready deferred captured at call time, and
-  // when a newer request arrives the older deferred ADOPTS the newer one, so a
-  // superseded caller transitively waits for the latest init (goal d).
-  const _providerState = new Map(); // provider -> state
-  const _providerInitPending = new Map(); // provider -> { sigKey, promise } identical-sig collapse
-  // Upper bound on how long a queued init waits for the PRIOR chain link before
-  // proceeding anyway. A prior init that HANGS (never settles) must not poison
-  // the chain and wedge every later request behind it. A hung init can never
-  // *complete* against the registry, so it cannot land-after and clobber a
-  // newer config (goal c only fears slow-but-completing inits) — so proceeding
-  // once the gate expires is safe. Defaults to the spawn-prep cap; 0 disables.
-  const PROVIDER_CHAIN_GATE_MS = DEFAULT_SPAWN_PREP_TIMEOUT_MS;
-  function providerRegistered(provider) {
-    return typeof reg.getProvider !== 'function' || Boolean(reg.getProvider(provider));
-  }
-  function effectiveProviderConfig(config, provider) {
-    const providers = { ...(config.providers || {}) };
-    providers[provider] = { ...(providers[provider] || {}), enabled: true };
-    return providers;
-  }
-  function providerStateFor(provider) {
-    let s = _providerState.get(provider);
-    if (!s) {
-      s = { chain: Promise.resolve(), completedSig: null, latestSig: null, latestGen: 0, ready: null };
-      _providerState.set(provider, s);
-    }
-    return s;
-  }
-  function providerInitSignature(provider, effectiveProviders) {
-    let body;
-    try { body = JSON.stringify(effectiveProviders); }
-    catch { body = String(Date.now()); } // unserializable → force a fresh init
-    return `${provider}\u0000${body}`;
-  }
-  function gateOnPrior(prior) {
-    const settled = Promise.resolve(prior).catch(() => {});
-    if (!(PROVIDER_CHAIN_GATE_MS > 0)) return settled;
-    return new Promise((resolve) => {
-      let done = false;
-      const finish = () => { if (!done) { done = true; resolve(); } };
-      const timer = setTimeout(finish, PROVIDER_CHAIN_GATE_MS);
-      timer.unref?.();
-      settled.then(() => { clearTimeout(timer); finish(); }, () => { clearTimeout(timer); finish(); });
-    });
-  }
-  function ensureProvider(config, provider) {
-    const effective = effectiveProviderConfig(config, provider);
-    const sigKey = providerInitSignature(provider, effective);
-    const registered = () => providerRegistered(provider);
-    const s = providerStateFor(provider);
-    // Completed-skip: this exact effective config is already live for this
-    // provider. A config change flips sigKey so we fall through; a torn-down
-    // provider (no longer registered) also does.
-    if (s.completedSig === sigKey && registered()) return Promise.resolve();
-    // Identical-sig collapse: a request with the SAME sigKey is already in
-    // flight — share its caller promise.
-    const pending = _providerInitPending.get(provider);
-    if (pending && pending.sigKey === sigKey) return pending.promise;
-    // New generation. Repoint the rolling `ready` deferred to THIS gen and make
-    // the previous gen's deferred ADOPT the new one, so any superseded caller
-    // awaiting an older deferred transitively waits for the newest init (d).
-    const gen = ++s.latestGen;
-    s.latestSig = sigKey;
-    const prevReady = s.ready;
-    let resolveReady;
-    const readyPromise = new Promise((r) => { resolveReady = r; });
-    s.ready = { gen, promise: readyPromise, resolve: resolveReady };
-    if (prevReady && prevReady.gen < gen) {
-      try { prevReady.resolve(readyPromise); } catch { /* already settled */ }
-    }
-    // Serialize the ACTUAL init behind the prior chain link (gated so a hung
-    // prior cannot wedge the chain). A superseded gen's chain link settles
-    // quickly — it never awaits a later gen — so there is no deadlock.
-    const prior = s.chain;
-    const chainLink = gateOnPrior(prior).then(async () => {
-      if (s.latestGen !== gen) {
-        // Superseded before we ran: drop our (stale) init entirely (goal c).
-        // Our `ready` deferred already adopts the newer gen, so the caller below
-        // still waits for the latest init. Settle now to release the chain.
-        return;
-      }
-      try {
-        if (!(s.completedSig === sigKey && registered())) {
-          await reg.initProviders(effective);
-          s.completedSig = sigKey;
-        }
-      } finally {
-        // ALWAYS release this gen's waiters once we are the latest — even on a
-        // registry init failure. Adopting (superseded) callers chained onto this
-        // deferred would otherwise hang forever; instead they proceed and their
-        // own createSession()/prep-timeout surfaces the unprepared provider.
-        resolveReady();
-      }
-    });
-    // Next chain link waits on us (settled, never poisoned).
-    s.chain = chainLink.catch(() => {});
-    // The CALLER awaits the ready deferred (resolves only when the LATEST init
-    // for this provider completes), not just the chain link — so a superseded
-    // caller blocks until the newest config is live (goal d). chainLink is
-    // awaited first so a registry init error surfaces to this caller.
-    const callerPromise = chainLink.then(() => readyPromise).finally(() => {
-      const cur = _providerInitPending.get(provider);
-      if (cur && cur.promise === callerPromise) _providerInitPending.delete(provider);
-    });
-    _providerInitPending.set(provider, { sigKey, promise: callerPromise });
-    return callerPromise;
-  }
+  // Provider init de-dup lives in ./agent-tool/provider-init.mjs; the factory
+  // keeps its per-provider chain/ready state private per agent instance. The
+  // chain-gate defaults to the spawn-prep cap (see provider-init.mjs comments).
+  const { ensureProvider } = createProviderInit(reg, DEFAULT_SPAWN_PREP_TIMEOUT_MS);
 
   function resolvePreset(config, args) {
     if (args.provider && args.model) {
@@ -1228,9 +746,23 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
 
   function getJob(args, context = {}) {
     const taskId = taskIdFromArgs(args);
-    if (!taskId) throw new Error('agent read/status: task_id is required');
-    const task = getBackgroundTask(taskId, { surface: 'agent', context });
-    if (!task) throw new Error(`agent read/status: task "${taskId}" not found`);
+    if (taskId) {
+      const task = getBackgroundTask(taskId, { surface: 'agent', context });
+      if (!task) throw new Error(`agent read/status: task "${taskId}" not found`);
+      return task;
+    }
+    // Fall back to tag/sessionId resolution, same precedence as close()
+    // (agent-tool.mjs close()): clean(args.tag || args.sessionId || ...).
+    const target = clean(args.tag || args.sessionId);
+    if (!target) throw new Error('agent read/status: task_id, tag, or sessionId is required');
+    const candidates = listBackgroundTasks({ surface: 'agent', context })
+      .filter(Boolean)
+      .filter((row) => row.tag === target || row.sessionId === target);
+    if (!candidates.length) throw new Error(`agent read/status: no task found for tag/sessionId "${target}"`);
+    // Prefer most recent when multiple tasks match the same tag.
+    candidates.sort((a, b) => new Date(b.startedAt || 0) - new Date(a.startedAt || 0));
+    const task = getBackgroundTask(candidates[0].task_id, { surface: 'agent', context });
+    if (!task) throw new Error(`agent read/status: task "${candidates[0].task_id}" not found`);
     return task;
   }
 
@@ -1334,102 +866,9 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     removeWorkerRow({ tag: prepared.tag, sessionId: prepared.session.id });
   }
 
-  function enqueueCompletionMessage(sessionId, text, meta = {}) {
-    const target = clean(sessionId);
-    if (!target || typeof mgr.enqueuePendingMessage !== 'function') return false;
-    try {
-      const visible = modelVisibleToolCompletionMessage(text, meta);
-      return Boolean(visible && mgr.enqueuePendingMessage(target, visible) > 0);
-    } catch {
-      return false;
-    }
-  }
-
-  // Wire the canonical completion fallback to this agent surface's owner-session
-  // enqueue so notifyTaskCompletion can deliver via callerSessionId when no
-  // notifyFn is present or it declines. Registered once per agent (the closure
-  // captures mgr); signatures align: (callerSessionId, message, meta).
-  setBackgroundTaskEnqueueFallback((sessionId, text, meta) => enqueueCompletionMessage(sessionId, text, meta));
-
-  function workerNotifyFn(workerSessionId, notifyContext = {}) {
-    const workerId = clean(workerSessionId);
-    const ownerSessionId = clean(notifyContext?.callerSessionId || notifyContext?.sessionId);
-    const upstream = typeof notifyContext?.notifyFn === 'function' ? notifyContext.notifyFn : null;
-    return (text, meta = {}) => {
-      let ownerDelivered = false;
-      if (upstream) {
-        try {
-          const result = upstream(text, meta);
-          ownerDelivered = result !== false;
-          if (ownerDelivered) Promise.resolve(result).catch(() => {});
-        } catch {
-          ownerDelivered = false;
-        }
-      }
-      if (!ownerDelivered && ownerSessionId) {
-        ownerDelivered = enqueueCompletionMessage(ownerSessionId, text, meta);
-      }
-      const workerDelivered = workerId && workerId !== ownerSessionId
-        ? enqueueCompletionMessage(workerId, text, meta)
-        : ownerDelivered;
-      return ownerSessionId ? ownerDelivered : workerDelivered;
-    };
-  }
-
-  function notifyOwnerAgentCompletionEarly(job, resultValue, notifyContext = {}) {
-    if (!job || job._earlyCompletionNotified === true) return false;
-    const ownerSessionId = clean(notifyContext?.callerSessionId || notifyContext?.sessionId);
-    const upstream = typeof notifyContext?.notifyFn === 'function' ? notifyContext.notifyFn : null;
-    const finishedAt = new Date().toISOString();
-    // An abnormal-empty finish carries an `error` — the early preview must NOT
-    // present it as a benign `completed` card, or the Lead sees success before
-    // the later `failed` reconcile lands. Mirror the terminal status/instruction.
-    const earlyStatus = resultValue && resultValue.error ? 'failed' : 'completed';
-    const snapshot = {
-      ...job,
-      status: earlyStatus,
-      finishedAt,
-      finishedAtMs: Date.now(),
-      result: resultValue,
-      resultType: job.resultType || 'agent_task_result',
-      meta: sanitizeTaskMeta(job.meta || {}),
-      ...(resultValue && resultValue.error ? { error: resultValue.error } : {}),
-    };
-    // An early notification is only a header-only *preview*: it fires before
-    // the worker's session is persisted to signal the running→completed
-    // transition. It deliberately carries NO result body — the canonical
-    // notifyTaskCompletion delivers the body exactly once via the
-    // reconcile/finally path, so omitting it here keeps notifications
-    // exact-once with no duplicate body.
-    const text = renderBackgroundTask(snapshot, { includeResult: false });
-    const meta = {
-      type: snapshot.resultType,
-      execution_surface: 'agent',
-      execution_id: job.taskId || null,
-      status: earlyStatus,
-      instruction: `The async agent task ${job.taskId || ''} has finished (${earlyStatus}) - review this result in your next step.`,
-      ...(ownerSessionId ? { caller_session_id: ownerSessionId } : {}),
-    };
-    let delivered = false;
-    if (upstream) {
-      try {
-        const result = upstream(text, meta);
-        delivered = result !== false;
-        if (delivered) Promise.resolve(result).catch(() => {});
-      } catch {
-        delivered = false;
-      }
-    }
-    if (!delivered && ownerSessionId) {
-      delivered = enqueueCompletionMessage(ownerSessionId, text, meta);
-    }
-    if (delivered) {
-      // Mark only that a header-only preview fired. The canonical
-      // notifyTaskCompletion still owns the single body-carrying notification.
-      job._earlyCompletionNotified = true;
-    }
-    return delivered;
-  }
+  // Owner/worker completion notification lives in ./agent-tool/notify.mjs; the
+  // factory captures mgr and registers the canonical completion fallback.
+  const { workerNotifyFn, notifyOwnerAgentCompletionEarly } = createNotify(mgr);
 
   function startJob(type, meta, run, notifyContext = null) {
     const clientHostPid = terminalPidForContext(notifyContext);
@@ -1467,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
@@ -1556,7 +1000,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     const config = cfgMod.loadConfig();
     const agent = normalizeAgentName(args.agent);
     if (!agent) throw new Error('agent spawn: agent is required');
-    const agentPermission = readAgentFrontmatterPermission(agent, dataDir);
+    const agentPermission = readAgentFrontmatterPermission(agent, dataDir, STANDALONE_SOURCE_ROOT);
     const agentPerm = normalizeAgentPermission(agentPermission) || null;
     const { presetName, preset } = resolvePreset(config, args);
     await ensureProvider(config, preset.provider);
@@ -1943,6 +1387,16 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     if (tag) forgetTag(tag);
     removeWorkerRow({ tag, sessionId });
     clearAgentStatuslineRoute(sessionId);
+    // Cancel any running background task bound to this session BEFORE closing
+    // the session. Otherwise closeSession rejects the in-flight runSpawn with
+    // "Session closed: closeSession" and the catch path reconciles the task as
+    // `failed` — a user-initiated close must surface as `cancelled` instead.
+    // (The explicit task_id path below stays as a no-op fallback: cancel is
+    // idempotent once terminal.)
+    for (const row of listBackgroundTasks({ surface: 'agent', context: scopedContext })) {
+      if (row.sessionId !== sessionId && row.tag !== target) continue;
+      cancelBackgroundTask(row.task_id, 'cancelled by agent close');
+    }
     const ok = mgr.closeSession(sessionId, 'cli-agent-close');
     if (task?.taskId) cancelBackgroundTask(task.taskId, 'cancelled by agent close');
     return { closed: ok, tag, sessionId, task_id: task?.taskId || null };
@@ -2029,11 +1483,26 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
           if (!fallbackTag || fallbackTag.startsWith('sess_') || !isDeadTarget) throw err;
           const prompt = clean(args.message || args.prompt);
           if (!prompt) throw err;
+          // Inherit the dead session's agent/cwd from the tag registry so the
+          // auto-respawn doesn't die on "agent spawn: agent is required" when
+          // Lead's send (correctly) omitted them. Read BEFORE forgetTag wipes
+          // the registry entries.
+          const inheritedAgent = clean(args.agent) || clean(tagAgents.get(fallbackTag));
+          const inheritedCwd = clean(args.cwd) || clean(tagCwds.get(fallbackTag));
+          if (!inheritedAgent) 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 spawnArgs = {
+            ...args,
+            type: 'spawn',
+            tag: fallbackTag,
+            prompt,
+            message: undefined,
+            agent: inheritedAgent,
+            ...(inheritedCwd ? { cwd: inheritedCwd } : {}),
+          };
           const job = startDeferredSpawnJob(spawnArgs, callerCwd, context, notifyContext, { respawned: true });
           return renderResult(renderJob(job, false));
         }