mixdog 0.9.1 → 0.9.3

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,
@@ -33,6 +33,7 @@ import {
 } 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';
 
 const STANDALONE_SOURCE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -44,11 +45,16 @@ const DEFAULT_AGENT_PRESETS = Object.freeze({
   explore: 'sonnet-high',
   maintainer: 'haiku',
   worker: 'sonnet-high',
-  'heavy-worker': 'opus-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',
@@ -60,17 +66,17 @@ 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 agents in parallel with distinct tags; keep Lead work moving. 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/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 distinct handle; choose a role-index tag by role, e.g. worker01, heavy-worker01, reviewer01.' },
+      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 or 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.' },
@@ -80,6 +86,45 @@ export const AGENT_TOOL = {
 };
 
 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;
@@ -90,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
@@ -126,21 +175,21 @@ function normalizeAgentName(value) {
   return id;
 }
 
-function readAgentFrontmatterPermission(role, dataDir) {
-  const cleanRole = clean(role);
-  if (!cleanRole) return null;
-  const cacheKey = `${dataDir || ''}\u0000${cleanRole}`;
+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', cleanRole, 'AGENT.md'));
-    candidates.push(join(dataDir, 'agents', `${cleanRole}.md`));
+    candidates.push(join(dataDir, 'agents', cleanAgent, 'AGENT.md'));
+    candidates.push(join(dataDir, 'agents', `${cleanAgent}.md`));
   }
-  candidates.push(join(STANDALONE_SOURCE_ROOT, 'agents', cleanRole, 'AGENT.md'));
-  candidates.push(join(STANDALONE_SOURCE_ROOT, 'agents', `${cleanRole}.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;
@@ -248,8 +297,8 @@ function synthesizePreset(config, key) {
   };
 }
 
-function normalizeAgentRoute(routeLike) {
-  const provider = clean(routeLike?.provider);
+function normalizeAgentRoute(routeLike, fallbackProvider = '') {
+  const provider = clean(routeLike?.provider) || clean(fallbackProvider);
   const model = clean(routeLike?.model);
   if (!provider || !model) return null;
   return {
@@ -260,8 +309,8 @@ function normalizeAgentRoute(routeLike) {
   };
 }
 
-function agentPresetName(role) {
-  return `AGENT ${String(role || '').toUpperCase()}`;
+function agentPresetName(agent) {
+  return `AGENT ${String(agent || '').toUpperCase()}`;
 }
 
 async function resolvePrompt(args, cwd) {
@@ -334,7 +383,7 @@ function renderResult(value) {
       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.role || 'agent'} ${worker.status || 'idle'}/${worker.worker_stage || worker.stage || 'idle'} ${worker.provider}/${worker.model}${terminal}${tokens}`;
+        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 : [];
@@ -342,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)');
@@ -355,7 +404,7 @@ function renderResult(value) {
       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.role) lines.push(`agent: ${value.role}`);
+      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'}`);
@@ -377,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;
@@ -393,7 +442,7 @@ function renderResult(value) {
         'agent message queued',
         value.reused ? 'reused: true' : null,
         `target: ${value.tag || '-'} ${value.sessionId || ''}`.trim(),
-        value.role ? `agent: ${value.role}` : null,
+        value.agent ? `agent: ${value.agent}` : null,
         `queueDepth: ${value.queueDepth ?? 1}`,
       ].filter(Boolean).join('\n');
     }
@@ -412,7 +461,7 @@ function renderResult(value) {
       const header = [
         value.respawned ? 'agent respawned' : 'agent result',
         value.tag ? `tag=${value.tag}` : null,
-        value.role ? `agent=${value.role}` : 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)}`;
@@ -421,9 +470,15 @@ 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 tagRoles = new Map();
+  const tagAgents = new Map();
   const tagCwds = new Map();
   const reapTimers = new Map();
   const workerIndexMutators = [];
@@ -463,7 +518,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       .map((row) => ({
         tag: clean(row.tag),
         sessionId: clean(row.sessionId),
-        role: clean(row.role) || null,
+        agent: clean(row.agent) || null,
         provider: clean(row.provider) || null,
         model: clean(row.model) || null,
         preset: clean(row.preset) || null,
@@ -562,7 +617,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     if (!key) return;
     const prev = byKey.get(key) || {};
     const merged = { ...prev, ...normalized };
-    for (const field of ['role', 'provider', 'model', 'preset', 'effort', 'fast', 'clientHostPid', 'cwd', 'task_id', 'permission', 'toolPermission']) {
+    for (const field of ['agent', 'provider', 'model', 'preset', 'effort', 'fast', 'clientHostPid', 'cwd', 'task_id', 'permission', 'toolPermission']) {
       if ((merged[field] === null || merged[field] === '') && prev[field] != null && prev[field] !== '') {
         merged[field] = prev[field];
       }
@@ -610,7 +665,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     return {
       tag,
       sessionId,
-      role: clean(extra.role) || clean(session?.role) || null,
+      agent: clean(extra.agent) || clean(session?.agent) || null,
       provider: clean(extra.provider) || clean(session?.provider) || null,
       model: clean(extra.model) || clean(session?.model) || null,
       preset: clean(extra.preset) || clean(session?.presetName) || null,
@@ -637,7 +692,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     return {
       id: row.sessionId,
       agentTag: row.tag,
-      role: row.role || null,
+      agent: row.agent || null,
       provider: row.provider || null,
       model: row.model || null,
       presetName: row.preset || null,
@@ -661,7 +716,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     const normalized = normalizeWorkerRows({ workers: [row] })[0];
     if (!normalized) return false;
     tags.set(normalized.tag, normalized.sessionId);
-    if (normalized.role) tagRoles.set(normalized.tag, normalized.role);
+    if (normalized.agent) tagAgents.set(normalized.tag, normalized.agent);
     if (normalized.cwd) tagCwds.set(normalized.tag, normalized.cwd);
     if (defer) {
       return queueWorkerIndexMutation((byKey) => applyWorkerRowUpsert(byKey, normalized));
@@ -698,7 +753,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     for (const row of rows) {
       if (!row.tag || !row.sessionId) continue;
       tags.set(row.tag, row.sessionId);
-      if (row.role) tagRoles.set(row.tag, row.role);
+      if (row.agent) tagAgents.set(row.tag, row.agent);
       if (row.cwd) tagCwds.set(row.tag, row.cwd);
     }
     return rows;
@@ -790,14 +845,14 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     return rows;
   }
 
-  function nextTag(role, context = {}) {
+  function nextTag(agent, context = {}) {
     refreshTagsFromSessions({ context });
-    // Auto tags are role + a per-role local index with NO hyphen
-    // ("worker3", "heavy-worker7", or "agent1" when the role is unset). The
-    // index is the max existing `^role(\d+)$` + 1, escaping the role so a
-    // hyphenated role ("heavy-worker") is matched literally. Keep incrementing
+    // Auto tags are agent + a per-agent local index with NO hyphen
+    // ("worker3", "heavy-worker7", or "agent1" when the agent is unset). The
+    // index is the max existing `^agent(\d+)$` + 1, escaping the agent so a
+    // hyphenated agent ("heavy-worker") is matched literally. Keep incrementing
     // on any live collision.
-    const base = clean(role) || 'agent';
+    const base = clean(agent) || 'agent';
     const escaped = base.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     const re = new RegExp(`^${escaped}(\\d+)$`);
     let maxN = 0;
@@ -827,7 +882,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       if (!tag || tags.has(tag)) continue;
       if (!sessionMatchesContext(session, context)) continue;
       tags.set(tag, session.id);
-      if (session.role) tagRoles.set(tag, session.role);
+      if (session.agent) tagAgents.set(tag, session.agent);
       if (session.cwd) tagCwds.set(tag, session.cwd);
       upsertWorkerSessionDeferred(session, tag);
     }
@@ -836,7 +891,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
   function bindTag(tag, session, extra = {}) {
     if (!tag || !session?.id) return;
     tags.set(tag, session.id);
-    if (session.role) tagRoles.set(tag, session.role);
+    if (session.agent) tagAgents.set(tag, session.agent);
     if (session.cwd) tagCwds.set(tag, session.cwd);
     upsertWorkerSessionDeferred(session, tag, extra);
   }
@@ -845,7 +900,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     if (!tag) return;
     const sessionId = tags.get(tag) || '';
     tags.delete(tag);
-    tagRoles.delete(tag);
+    tagAgents.delete(tag);
     tagCwds.delete(tag);
     removeWorkerRow({ tag, sessionId });
   }
@@ -1034,10 +1089,14 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       };
     }
 
-    const agentName = normalizeAgentName(args.agent || args.role);
+    const agentName = normalizeAgentName(args.agent);
+    const configuredDefault = clean(config?.defaultProvider);
+    const fallbackProvider = configuredDefault && isKnownProvider(configuredDefault)
+      ? configuredDefault
+      : DEFAULT_PROVIDER;
     const agentRoute = !clean(args.preset)
-      ? (normalizeAgentRoute(config?.agents?.[agentName])
-        || (agentName === 'maintainer' ? normalizeAgentRoute(config?.agents?.maintenance) : null))
+      ? (normalizeAgentRoute(config?.agents?.[agentName], fallbackProvider)
+        || (agentName === 'maintainer' ? normalizeAgentRoute(config?.agents?.maintenance, fallbackProvider) : null))
       : null;
     if (agentRoute) {
       return {
@@ -1073,11 +1132,11 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       const stage = session.stage || (status === 'idle' || status === 'error' || status === 'closed'
         ? status
         : (runtime?.stage || status));
-      const progress = sessionProgressExtras(sessionId, session.role || null, now);
+      const progress = sessionProgressExtras(sessionId, session.agent || null, now);
       rows.push({
         tag,
         sessionId,
-        role: session.role || null,
+        agent: session.agent || null,
         provider: session.provider,
         model: session.model,
         preset: session.presetName || null,
@@ -1133,7 +1192,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     if (!session) return null;
     const runtime = mgr.getSessionRuntime?.(sessionId);
     const status = session.closed === true ? 'closed' : (session.status || 'idle');
-    const progress = sessionProgressExtras(sessionId, session.role || null);
+    const progress = sessionProgressExtras(sessionId, session.agent || null);
     return {
       workerStatus: status,
       stage: progress.worker_stage || runtime?.stage || status,
@@ -1151,7 +1210,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       status: task.status,
       tag: task.tag || null,
       sessionId: task.sessionId || null,
-      role: task.role || null,
+      agent: task.agent || null,
       preset: task.preset || null,
       provider: task.provider || null,
       model: task.model || null,
@@ -1162,7 +1221,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       finishedAt: task.finishedAt || null,
       error: task.error || null,
       ...jobWorkerSnapshot(task.sessionId),
-      ...sessionProgressExtras(task.sessionId, task.role || null, Date.now(), task.status),
+      ...sessionProgressExtras(task.sessionId, task.agent || null, Date.now(), task.status),
     }));
     return wantedPid ? rows.filter((row) => positiveInt(row.clientHostPid) === wantedPid) : rows;
   }
@@ -1177,7 +1236,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
 
   function renderJob(job, includeResult = false) {
     const meta = job.meta || {};
-    let progress = sessionProgressExtras(meta.sessionId, meta.role || null, Date.now(), job.status);
+    let progress = sessionProgressExtras(meta.sessionId, meta.agent || null, Date.now(), job.status);
     // Spawn is deferred: before the worker session exists, sessionProgressExtras
     // returns {} and the status card would show only "status: running" with no
     // stage/progress. Fill a minimal stage so the caller can tell the job is
@@ -1196,7 +1255,8 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       status: job.status,
       tag: meta.tag || null,
       sessionId: meta.sessionId || null,
-      role: meta.role || 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,
@@ -1217,7 +1277,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       ...(extras || {}),
       tag: prepared.tag,
       sessionId: prepared.session.id,
-      role: prepared.role,
+      agent: prepared.agent,
       preset: presetKey(prepared.preset) || prepared.presetName,
       provider: prepared.preset.provider,
       model: prepared.preset.model,
@@ -1228,7 +1288,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
   }
 
   function pendingSpawnMeta(args = {}, extras = {}) {
-    const role = normalizeAgentName(args.agent || args.role);
+    const agent = normalizeAgentName(args.agent);
     // Best-effort resolve the default preset so the pending "Spawn …" card can
     // already show the model (e.g. "Spawn Heavy Worker (Opus 4.8)") even when
     // the caller did not pass an explicit provider/model. Never throw: fall back
@@ -1242,7 +1302,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       ...(extras || {}),
       tag: clean(args.tag) || null,
       sessionId: null,
-      role: role || null,
+      agent: agent || null,
       preset: clean(args.preset) || presetKey(resolved) || null,
       provider: clean(args.provider) || clean(resolved?.provider) || null,
       model: clean(args.model) || clean(resolved?.model) || null,
@@ -1260,7 +1320,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
         ...job.input,
         tag: next.tag || job.input.tag || null,
         sessionId: next.sessionId || job.input.sessionId || null,
-        role: next.role || job.input.role || null,
+        agent: next.agent || job.input.agent || null,
       };
     }
     job.label = next.tag || next.sessionId || job.label;
@@ -1321,14 +1381,19 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     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: 'completed',
+      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
@@ -1341,8 +1406,8 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       type: snapshot.resultType,
       execution_surface: 'agent',
       execution_id: job.taskId || null,
-      status: 'completed',
-      instruction: `The async agent task ${job.taskId || ''} has finished (completed) - review this result in your next step.`,
+      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;
@@ -1377,7 +1442,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       surface: 'agent',
       operation: type,
       label: jobMeta?.tag || jobMeta?.sessionId || type,
-      input: { type, tag: jobMeta?.tag || null, sessionId: jobMeta?.sessionId || null, role: jobMeta?.role || null },
+      input: { type, tag: jobMeta?.tag || null, sessionId: jobMeta?.sessionId || null, agent: jobMeta?.agent || null },
       context: notifyContext,
       meta: jobMeta,
       resultType: 'agent_task_result',
@@ -1406,8 +1471,10 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       // installs its progress watchdog, so guard prep with an internal env-
       // backed cap rather than exposing per-call timeout knobs on the agent
       // tool surface.
-      const prepDeadlineMs = DEFAULT_SPAWN_PREP_TIMEOUT_MS;
+      const prepDeadlineMs = nonNegativeInt(args.spawnPrepTimeoutMs ?? args.prepTimeoutMs)
+        ?? DEFAULT_SPAWN_PREP_TIMEOUT_MS;
       let prepared;
+      const prepState = { timedOut: false };
       if (prepDeadlineMs > 0) {
         let prepTimer = null;
         let timedOut = false;
@@ -1415,13 +1482,14 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
         // prepareSpawn promise may still resolve later with a fully-built
         // session/tag/route — attach a cleanup so the late-arriving prepared is
         // torn down, otherwise the orphaned tag would collide on re-spawn.
-        const prepPromise = prepareSpawn(args, callerCwd, context);
+        const prepPromise = prepareSpawn(args, callerCwd, context, prepState);
         prepPromise.then((late) => {
           if (timedOut) closePreparedSpawn(late, 'agent-spawn-prep-timeout');
         }, () => {});
         const timeout = new Promise((_resolve, reject) => {
           prepTimer = setTimeout(() => {
             timedOut = true;
+            prepState.timedOut = true;
             reject(new Error(`agent spawn prep timed out (${prepDeadlineMs}ms) before model request`));
           }, prepDeadlineMs);
           prepTimer.unref?.();
@@ -1432,7 +1500,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
           if (prepTimer) clearTimeout(prepTimer);
         }
       } else {
-        prepared = await prepareSpawn(args, callerCwd, context);
+        prepared = await prepareSpawn(args, callerCwd, context, prepState);
       }
       mergeJobMeta(job, preparedSpawnMeta(prepared, extras));
       upsertWorkerSessionDeferred(prepared.session, prepared.tag, {
@@ -1483,17 +1551,20 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     };
   }
 
-  async function prepareSpawn(args, callerCwd = null, context = {}) {
+  async function prepareSpawn(args, callerCwd = null, context = {}, prepState = null) {
     refreshTagsFromSessions({ context });
     const config = cfgMod.loadConfig();
-    const role = normalizeAgentName(args.agent || args.role);
-    if (!role) throw new Error('agent spawn: agent is required');
-    const agentPermission = readAgentFrontmatterPermission(role, dataDir);
-    const rolePermission = normalizeAgentPermission(agentPermission) || null;
+    const agent = normalizeAgentName(args.agent);
+    if (!agent) throw new Error('agent spawn: agent is required');
+    const agentPermission = readAgentFrontmatterPermission(agent, dataDir);
+    const agentPerm = normalizeAgentPermission(agentPermission) || null;
     const { presetName, preset } = resolvePreset(config, args);
     await ensureProvider(config, preset.provider);
+    if (prepState?.timedOut) {
+      throw new Error('agent spawn prep timed out before session bind');
+    }
 
-    const tag = clean(args.tag) || nextTag(role, context);
+    const tag = clean(args.tag) || nextTag(agent, context);
     // Any resolved same-tag binding in this terminal (live or lingering trace)
     // blocks a fresh spawn. execute() routes live reuse before prepareSpawn.
     if (resolveTag(tag, context, { scanSessions: wantsSessionScan(args) })) {
@@ -1502,25 +1573,28 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     const baseCwd = resolve(callerCwd || defaultCwd || process.cwd());
     const workerCwd = clean(args.cwd) ? resolve(baseCwd, args.cwd) : baseCwd;
     const prompt = withCwdHeader(await resolvePrompt(args, workerCwd), workerCwd);
+    if (prepState?.timedOut) {
+      throw new Error('agent spawn prep timed out before session bind');
+    }
     const runtimeSpec = cfgMod.resolveRuntimeSpec(preset, { lane: 'agent', agentId: tag });
     const maxLoopIterations = positiveInt(args.maxLoopIterations) || null;
-    const watchdogPolicy = resolveAgentWatchdogPolicy(role);
+    const watchdogPolicy = resolveAgentWatchdogPolicy(agent);
     const { session, effectiveCwd } = prepareAgentSession({
-      role,
+      agent,
       presetName,
       preset,
       runtimeSpec,
       owner: AGENT_OWNER,
       cwd: workerCwd,
       sourceType: 'cli',
-      sourceName: role,
+      sourceName: agent,
       parentSessionId: clean(context?.callerSessionId || context?.sessionId) || null,
       ownerSessionId: clean(context?.callerSessionId || context?.sessionId) || null,
       clientHostPid: terminalPidForContext(context) || null,
       agentTag: tag,
       taskType: clean(args.taskType) || clean(args.typeHint) || undefined,
       maxLoopIterations: maxLoopIterations || undefined,
-      permission: rolePermission || undefined,
+      permission: agentPerm || undefined,
       cacheKeyOverride: args.cacheKey || undefined,
     });
     // Lead sessions write a gateway-session route when created; agent sessions
@@ -1528,7 +1602,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     // or the vendored L1/L2 statusline cannot resolve the agent route/model.
     writeAgentStatuslineRoute(session.id, preset);
     bindTag(tag, session, {
-      role,
+      agent,
       preset: presetKey(preset) || presetName,
       provider: preset.provider,
       model: preset.model,
@@ -1542,7 +1616,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       args,
       tag,
       session,
-      role,
+      agent,
       preset,
       presetName,
       workerCwd: effectiveCwd || workerCwd,
@@ -1553,11 +1627,13 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
   }
 
   async function runSpawn(prepared, notifyContext = null, job = null) {
-    const { args, tag, session, role, preset, presetName, workerCwd, prompt, watchdogPolicy } = prepared;
+    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, {
-      role,
+      agent,
       preset: presetKey(preset) || presetName,
       provider: preset.provider,
       model: preset.model,
@@ -1567,17 +1643,26 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       stage: 'running',
     });
     try {
-      const completionValue = (result) => ({
-        tag,
-        sessionId: session.id,
-        role,
-        preset: presetKey(preset) || presetName,
-        provider: preset.provider,
-        model: preset.model,
-        effort: preset.effort || null,
-        fast: preset.fast === true,
-        content: result?.content || '',
-      });
+      const completionValue = (result) => {
+        // Promote an abnormal finish (iteration cap, truncation, or a public
+        // agent's empty terminal turn) to an explicit error, so the Lead
+        // receives it as a failure with an accurate reason instead of a silent
+        // `completed` empty result. Keyed off loop.mjs terminationReason;
+        // hidden agents finishing normally-empty are left untagged (benign).
+        const abnormalError = abnormalEmptyFinishError(result, agent);
+        return {
+          tag,
+          sessionId: session.id,
+          agent,
+          preset: presetKey(preset) || presetName,
+          provider: preset.provider,
+          model: preset.model,
+          effort: preset.effort || null,
+          fast: preset.fast === true,
+          content: result?.content || '',
+          ...(abnormalError ? { error: abnormalError } : {}),
+        };
+      };
       const result = await mgr.askSession(session.id, prompt, args.context || null, null, workerCwd, null, {
         notifyFn: workerNotifyFn(session.id, notifyContext || {}),
         ...(job ? {
@@ -1591,11 +1676,21 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
             // reconcile remains a backup for the error/no-terminal-result path.
             if (job?.taskId) {
               try {
-                reconcileBackgroundTask(job.taskId, {
-                  status: 'completed',
-                  result: value,
-                  terminalReason: 'agent-terminal-result',
-                });
+                // An empty/abnormal finish is a failure, not a completion:
+                // reconcile as `failed` with the accurate error so the Lead
+                // card renders `error: …` instead of a header-only empty card.
+                reconcileBackgroundTask(job.taskId, value.error
+                  ? {
+                      status: 'failed',
+                      result: value,
+                      error: value.error,
+                      terminalReason: 'agent-empty-final',
+                    }
+                  : {
+                      status: 'completed',
+                      result: value,
+                      terminalReason: 'agent-terminal-result',
+                    });
               } catch {}
             }
           },
@@ -1604,14 +1699,40 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       // The early preview no longer promises body suppression, so the canonical
       // notifyTaskCompletion is left to fire exactly once with output via the
       // resolve/reconcile/finally path.
-      return completionValue(result);
+      const finalValue = completionValue(result);
+      // Non-job return path (or job path where the terminal-result reconcile
+      // already ran): if the finish was abnormal-empty, surface it as a thrown
+      // error so finalStatus becomes 'error' and the caller's error path (and
+      // the finally reconcile below, as `failed`) render the accurate reason.
+      if (finalValue.error) {
+        finalStatus = 'error';
+        if (job) job._terminalResultValue = finalValue;
+        throw new Error(finalValue.error);
+      }
+      return finalValue;
     } catch (error) {
       finalStatus = 'error';
+      // Part C: a mid-stream stall (StreamStalledError / ESTREAMSTALL) throws
+      // here WITHOUT a terminal result, so the finally reconcile below (gated on
+      // _terminalResultValue) would be skipped and only the outer task-reject
+      // path would notify. Belt-and-suspenders: reconcile this job to `failed`
+      // now so the owner (Lead) always gets a failure notification instead of a
+      // task stranded in `running`. Idempotent — completeBackgroundTask no-ops
+      // once terminal, so the outer reject path can't double-notify.
+      if (job?.taskId && job._terminalResultValue === undefined) {
+        try {
+          reconcileBackgroundTask(job.taskId, {
+            status: 'failed',
+            error,
+            terminalReason: 'agent-stream-stalled',
+          });
+        } catch {}
+      }
       throw error;
     } finally {
       watchdog?.stop?.();
       upsertWorkerSessionDeferred(session, tag, {
-        role,
+        agent,
         preset: presetKey(preset) || presetName,
         provider: preset.provider,
         model: preset.model,
@@ -1631,11 +1752,16 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
           reconcileBackgroundTask(job.taskId, {
             status: finalStatus === 'error' ? 'failed' : 'completed',
             result: job._terminalResultValue,
+            ...(finalStatus === 'error' && job._terminalResultValue?.error
+              ? { error: job._terminalResultValue.error }
+              : {}),
             terminalReason: 'agent-finally-reconcile',
           });
         } catch {}
       }
       scheduleReap(session.id);
+      // SubagentStop: worker finished (terminal), regardless of outcome.
+      emitSubagentEvent('stop', agent, { session_id: session.id, tag, status: finalStatus });
     }
   }
 
@@ -1658,20 +1784,27 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
 
   async function runSend(prepared, notifyContext = null, job = null) {
     const { args, session, sessionId, prompt } = prepared;
-    const sendRole = session.role || normalizeAgentName(args.agent || args.role);
-    const watchdog = startProgressIdleWatchdog(sessionId, resolveAgentWatchdogPolicy(sendRole));
+    const sendAgent = session.agent || normalizeAgentName(args.agent);
+    const watchdog = startProgressIdleWatchdog(sessionId, resolveAgentWatchdogPolicy(sendAgent));
     const tag = tagForSession(sessionId);
     let finalStatus = 'idle';
     upsertWorkerSessionDeferred(session, tag, { status: 'running', stage: 'running' });
     try {
-      const completionValue = (result) => ({
-        tag,
-        sessionId,
-        role: session.role || null,
-        provider: session.provider,
-        model: session.model,
-        content: result?.content || '',
-      });
+      const completionValue = (result) => {
+        // Same abnormal-empty → error promotion as runSpawn: a reused/`send`
+        // worker that hits the cap, truncates, or finishes empty must surface
+        // as a failure with an accurate reason, not a silent completed empty.
+        const abnormalError = abnormalEmptyFinishError(result, session.agent || sendAgent);
+        return {
+          tag,
+          sessionId,
+          agent: session.agent || null,
+          provider: session.provider,
+          model: session.model,
+          content: result?.content || '',
+          ...(abnormalError ? { error: abnormalError } : {}),
+        };
+      };
       const result = await mgr.askSession(sessionId, prompt, args.context || null, null, session.cwd || defaultCwd, null, {
         notifyFn: workerNotifyFn(sessionId, notifyContext || {}),
         ...(job ? {
@@ -1683,11 +1816,18 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
             // post-result save can't strand the task in `running`. Idempotent.
             if (job?.taskId) {
               try {
-                reconcileBackgroundTask(job.taskId, {
-                  status: 'completed',
-                  result: value,
-                  terminalReason: 'agent-terminal-result',
-                });
+                reconcileBackgroundTask(job.taskId, value.error
+                  ? {
+                      status: 'failed',
+                      result: value,
+                      error: value.error,
+                      terminalReason: 'agent-empty-final',
+                    }
+                  : {
+                      status: 'completed',
+                      result: value,
+                      terminalReason: 'agent-terminal-result',
+                    });
               } catch {}
             }
           },
@@ -1695,9 +1835,27 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
       });
       // Early preview no longer suppresses the canonical body notification;
       // notifyTaskCompletion fires once with output via resolve/reconcile.
-      return completionValue(result);
+      const finalValue = completionValue(result);
+      if (finalValue.error) {
+        finalStatus = 'error';
+        if (job) job._terminalResultValue = finalValue;
+        throw new Error(finalValue.error);
+      }
+      return finalValue;
     } catch (error) {
       finalStatus = 'error';
+      // Part C (send path mirror): a mid-stream stall throws with no terminal
+      // result — reconcile to `failed` so the owner is notified rather than the
+      // task hanging in `running`. Idempotent (see runSpawn note).
+      if (job?.taskId && job._terminalResultValue === undefined) {
+        try {
+          reconcileBackgroundTask(job.taskId, {
+            status: 'failed',
+            error,
+            terminalReason: 'agent-stream-stalled',
+          });
+        } catch {}
+      }
       throw error;
     } finally {
       watchdog?.stop?.();
@@ -1713,6 +1871,9 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
           reconcileBackgroundTask(job.taskId, {
             status: finalStatus === 'error' ? 'failed' : 'completed',
             result: job._terminalResultValue,
+            ...(finalStatus === 'error' && job._terminalResultValue?.error
+              ? { error: job._terminalResultValue.error }
+              : {}),
             terminalReason: 'agent-finally-reconcile',
           });
         } catch {}
@@ -1737,14 +1898,14 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
         ...extras,
         tag: tagForSession(prepared.sessionId),
         sessionId: prepared.sessionId,
-        role: prepared.session.role || null,
+        agent: prepared.session.agent || null,
         queueDepth,
       });
     }
     const job = startJob('send', {
       tag: tagForSession(prepared.sessionId),
       sessionId: prepared.sessionId,
-      role: prepared.session.role || null,
+      agent: prepared.session.agent || null,
       provider: prepared.session.provider || null,
       model: prepared.session.model || null,
       preset: prepared.session.presetName || null,
@@ -1770,7 +1931,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     }
     const sessionId = resolveTag(target, scopedContext, { scanSessions: wantsSessionScan(args) });
     if (!sessionId) {
-      if (!target.startsWith('sess_') && tagRoles.has(target)) {
+      if (!target.startsWith('sess_') && tagAgents.has(target)) {
         forgetTag(target);
         if (task?.taskId) cancelBackgroundTask(task.taskId, 'cancelled by agent close');
         return { closed: true, forgotten: true, tag: target, sessionId: null, task_id: task?.taskId || null };
@@ -1829,7 +1990,7 @@ export function createStandaloneAgent({ cfgMod, reg, mgr, dataDir, cwd: defaultC
     const value = clean(tag);
     if (!value || value.startsWith('sess_')) return false;
     if (resolveTag(value, context, { excludeTerminalTraces: true })) return false; // live -> reuse, not trace
-    if (tagRoles.has(value)) return true;
+    if (tagAgents.has(value)) return true;
     return readWorkerRows(context).some((row) => clean(row.tag) === value);
   }
 
@@ -1850,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):
@@ -1887,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' });
     }
   }