mixdog 0.9.171 → 0.9.173

package/src/standalone/agent-tool/execute-spawn.mjs

@@ -0,0 +1,76 @@
+import { clean, rowMatchesContext } from './helpers.mjs';
+
+// Spawn request dispatch: deciding what an explicitly tagged spawn means before
+// a job is started, and starting it.
+//
+// Inputs: `registry` (tag resolution, live sessions, tombstones),
+// `terminalTrace`, `sendFlow` (reuse path), `spawnFlow`, and `spawnResult`
+// (job -> rendered tool output). Output: { spawn }.
+export function createSpawnDispatch({ registry, terminalTrace, sendFlow, spawnFlow, spawnResult }) {
+  // Explicit-tag spawn priority (auto nextTag always creates a fresh session):
+  //   1) live + busy -> queue the prompt (reuse)
+  //   2) live + idle -> continue existing session (reuse)
+  //   3) lingering terminal trace -> reap trace and fresh spawn under same tag
+  //   4) genuinely new tag -> fresh deferred spawn
+  async function resolveExplicitTagSpawn(explicitTag, args, { scopedContext, context, notifyContext }) {
+    let liveSessionId = null;
+    try {
+      liveSessionId = registry.resolveTag(explicitTag, scopedContext, {
+        scanSessions: registry.wantsSessionScan(args),
+        excludeTerminalTraces: true,
+      });
+    } catch {
+      // Ambiguous across terminals — the normal spawn path surfaces the same
+      // error consistently.
+      liveSessionId = null;
+    }
+    if (liveSessionId && registry.getLiveSession(liveSessionId)) {
+      const prepared = await sendFlow.prepareSend({ ...args, tag: explicitTag }, scopedContext);
+      return { reused: sendFlow.dispatchToExistingSession(prepared, notifyContext, { reused: true }) };
+    }
+    if (terminalTrace.hasTerminalTrace(explicitTag, scopedContext)) {
+      terminalTrace.reapTerminalTraceForTag(explicitTag, scopedContext);
+      return { spawnArgs: args, respawned: true };
+    }
+    // Tombstone inheritance never honors allTerminals/global scope.
+    const tombstone = registry.tagTombstoneForTag(explicitTag, context);
+    if (tombstone) {
+      registry.consumeTagTombstone(tombstone);
+      return {
+        spawnArgs: {
+          ...args,
+          agent: clean(args.agent) || clean(tombstone.agent),
+          ...(clean(args.cwd) || !clean(tombstone.cwd) ? {} : { cwd: tombstone.cwd }),
+        },
+        respawned: true,
+      };
+    }
+    const foreignTombstone = registry
+      .readAllTagTombstones()
+      .find((row) => clean(row.tag) === explicitTag && !rowMatchesContext(row, context));
+    if (foreignTombstone) throw new Error(`agent spawn: tag "${explicitTag}" belongs to another terminal`);
+    return { spawnArgs: args, respawned: false };
+  }
+
+  async function spawn(args, request) {
+    const explicitTag = clean(args.tag);
+    let spawnArgs = args;
+    let respawned = false;
+    if (explicitTag) {
+      const plan = await resolveExplicitTagSpawn(explicitTag, args, request);
+      if (plan.reused) return plan.reused;
+      spawnArgs = plan.spawnArgs;
+      respawned = plan.respawned;
+    }
+    const job = spawnFlow.startDeferredSpawnJob(
+      spawnArgs,
+      request.callerCwd,
+      request.context,
+      request.notifyContext,
+      respawned ? { respawned: true } : {}
+    );
+    return spawnResult(job);
+  }
+
+  return { spawn };
+}

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

@@ -0,0 +1,83 @@
+import { errorLine } from '../../runtime/shared/err-text.mjs';
+import { createSendDispatch } from './execute-send.mjs';
+import { createSpawnDispatch } from './execute-spawn.mjs';
+import { agentScope, clean } from './helpers.mjs';
+import { renderResult } from './render.mjs';
+
+// The agent tool's request dispatch: list/status/read/cleanup/cancel/close/
+// send/spawn. The dead-tag send fallback lives in execute-send.mjs and
+// explicit-tag spawn resolution in execute-spawn.mjs.
+export function createAgentExecute({
+  mgr,
+  defaultCwd,
+  awaitKeychainPrewarm,
+  registry,
+  views,
+  spawnFlow,
+  sendFlow,
+  closeFlow,
+  terminalTrace,
+}) {
+  const spawnResult = (job) => renderResult(views.renderJob(job, false));
+
+  async function readJob(args, scopedContext) {
+    const job = views.getJobOrWorker(args, scopedContext);
+    if (job?.taskId == null && typeof mgr.readSessionHandoff === 'function') {
+      const handoff = await mgr.readSessionHandoff(job.meta?.sessionId);
+      if (handoff) job.result = handoff;
+    }
+    return renderResult(views.renderJob(job, true));
+  }
+
+  const { send } = createSendDispatch({ registry, defaultCwd, sendFlow, spawnFlow, spawnResult });
+  const { spawn } = createSpawnDispatch({ registry, terminalTrace, sendFlow, spawnFlow, spawnResult });
+
+  return async function execute(args = {}, context = {}) {
+    try {
+      await awaitKeychainPrewarm();
+      const type = clean(args.type) || 'spawn';
+      const request = {
+        callerCwd: clean(context.cwd || context.callerCwd),
+        scopedContext: agentScope(args, context),
+        context,
+        notifyContext: context,
+      };
+      const { scopedContext } = request;
+      if (typeof mgr.rehydrateAgentSessions === 'function') {
+        await mgr.rehydrateAgentSessions();
+        // Rebuild tag ownership from canonical records even if a daemon crash
+        // happened before the auxiliary worker row was flushed.
+        registry.refreshTagsFromSessions({ scanSessions: true, context: scopedContext });
+      }
+      switch (type) {
+        case 'status':
+        case 'list':
+          if (type === 'status' && (clean(args.task_id) || clean(args.tag) || clean(args.sessionId))) {
+            return renderResult(views.renderJob(views.getJobOrWorker(args, scopedContext), false), {
+              includeDiagnostics: true,
+            });
+          }
+          // Targetless status is the same compact overview as list.
+          return renderResult({
+            workers: views.list({ scanSessions: registry.wantsSessionScan(args), context: scopedContext }),
+            jobs: views.listJobs(scopedContext),
+          });
+        case 'read':
+          return await readJob(args, scopedContext);
+        case 'cleanup':
+          return renderResult(closeFlow.cleanup(args, scopedContext));
+        case 'cancel':
+        case 'close':
+          return renderResult(await closeFlow.close(args, scopedContext));
+        case 'send':
+          return await send(args, request);
+        case 'spawn':
+          return await spawn(args, request);
+        default:
+          throw new Error(`agent: unknown type "${type}"`);
+      }
+    } catch (err) {
+      return errorLine(err, { surface: 'agent' });
+    }
+  };
+}

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

@@ -1,4 +1,4 @@
-// Dependency-light helpers extracted from the agent-tool facade.
+// Dependency-light helpers for the agent-tool facade.
 import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 import {
@@ -59,21 +59,7 @@ export function agentTagOf(session) {
   return clean(session?.agentTag);
 }
 
-/** Timestamps reach the agent tool in three shapes: ISO strings, epoch-ms
- * NUMBERS (session-service stamps `Date.now()`) and numeric strings once such a
- * stamp round-trips through the JSON row store. Date.parse() returns NaN for
- * the latter two, so every stamp comparison must go through here. Mirrors
- * stampMs() in runtime/agent/orchestrator/session/store-summary-reader.mjs,
- * which is module-private there. Never returns NaN. */
-export function stampMs(value) {
-  if (typeof value === 'number') return Number.isFinite(value) && value > 0 ? value : 0;
-  const text = clean(value);
-  if (!text) return 0;
-  const numeric = Number(text);
-  if (Number.isFinite(numeric) && numeric > 0 && !/^\d{4}-/.test(text)) return numeric;
-  const parsed = Date.parse(text);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
-}
+export { stampMs } from '../../runtime/shared/agent-reap-state.mjs';
 
 export function normalizeAgentName(value) {
   const id = clean(value)
@@ -114,13 +100,10 @@ export function sessionMatchesContext(session, context = {}) {
   return !!sessionPid && sessionPid === wantedPid;
 }
 
+// A persisted worker row carries the same ownership fields as the session it
+// describes, so it is scoped by exactly the same rule.
 export function rowMatchesContext(row, context = {}) {
-  const wantedSession = callerSessionForContext(context);
-  if (wantedSession) return clean(row?.parentSessionId || row?.ownerSessionId) === wantedSession;
-  const wantedPid = terminalPidForContext(context);
-  if (!wantedPid) return true;
-  const rowPid = positiveInt(row?.clientHostPid);
-  return !!rowPid && rowPid === wantedPid;
+  return sessionMatchesContext(row, context);
 }
 
 export function nonNegativeInt(value) {
@@ -273,7 +256,7 @@ function formatElapsedMs(ms) {
   return remMin ? `${hr}h${remMin}m` : `${hr}h`;
 }
 
-export function elapsedFromStamps(startedAt, finishedAt, status) {
+export function elapsedFromStamps(startedAt, finishedAt, _status) {
   const start = Date.parse(clean(startedAt));
   if (!Number.isFinite(start)) return null;
   const finish = Date.parse(clean(finishedAt));

package/src/standalone/agent-tool/job-views/agent-list.mjs

@@ -0,0 +1,71 @@
+// job-views/agent-list.mjs
+// The /agents list projection: one row per tagged agent session with its live
+// progress, filtered by default to workers that can still do work.
+import { ACTIVE_STAGES } from '../tool-def.mjs';
+import { isTerminalWorkerStatus } from '../worker-rows.mjs';
+
+// Idle, closed, errored and reaped/unknown rows are history and stay reachable
+// through the task section (status/read keep their terminal result).
+export function isActiveWorkerRow(row = {}) {
+  const stage = String(row.stage ?? '')
+    .trim()
+    .toLowerCase();
+  const status = String(row.status ?? '')
+    .trim()
+    .toLowerCase();
+  if (ACTIVE_STAGES.has(stage) || ACTIVE_STAGES.has(status)) return true;
+  const effective = stage || status;
+  if (!effective || effective === 'unknown') return false;
+  return !isTerminalWorkerStatus(effective);
+}
+
+function agentRow({ tag, session, runtime, progress, now }) {
+  const status = session.closed === true ? 'closed' : session.status || 'idle';
+  const stage =
+    session.stage ||
+    (status === 'idle' || status === 'error' || status === 'closed' ? status : runtime?.stage || status);
+  return {
+    tag,
+    sessionId: session.id,
+    agent: session.agent || null,
+    provider: session.provider,
+    model: session.model,
+    preset: session.presetName || null,
+    effort: session.effort || null,
+    fast: session.fast === true,
+    status,
+    stage,
+    ...progress,
+    createdAt: session.createdAt || null,
+    updatedAt: session.updatedAt || null,
+    lastUsedAt: session.lastUsedAt || null,
+    clientHostPid: session.clientHostPid || null,
+    lastStreamDeltaAt: runtime?.lastStreamDeltaAt ? new Date(runtime.lastStreamDeltaAt).toISOString() : null,
+    staleSeconds: runtime?.lastStreamDeltaAt ? Math.floor((now - runtime.lastStreamDeltaAt) / 1000) : null,
+    windowTokens: Number(session.lastContextTokens ?? session.lastInputTokens) || 0,
+    windowCap: Number(session.contextWindow) || null,
+    permission: session.permission || null,
+    toolPermission: session.toolPermission || null,
+    messages: Array.isArray(session.messages)
+      ? session.messages.length
+      : Math.max(0, Number(session.messageCount || 0)),
+    tools: Array.isArray(session.tools) ? session.tools.length : Math.max(0, Number(session.toolCount || 0)),
+  };
+}
+
+export function createAgentList({ mgr, refreshTagsFromSessions, agentSessionEntries, progress }) {
+  return function list({ scanSessions = false, context = {}, includeTerminal = false } = {}) {
+    refreshTagsFromSessions({ scanSessions, context });
+    const now = Date.now();
+    const rows = agentSessionEntries({ scanSessions, context }).map(({ tag, session }) =>
+      agentRow({
+        tag,
+        session,
+        runtime: mgr.getSessionRuntime?.(session.id),
+        progress: progress.sessionProgressExtras(session.id, session.agent || null, now),
+        now,
+      })
+    );
+    return includeTerminal ? rows : rows.filter((row) => isActiveWorkerRow(row));
+  };
+}

package/src/standalone/agent-tool/job-views/job-lookup.mjs

@@ -0,0 +1,84 @@
+// job-views/job-lookup.mjs
+// Resolving read/status arguments to a job: by task id, then by tag/sessionId
+// against the background-task registry, then — because background tasks are
+// process-memory only while a worker SESSION can outlive its spawn task (task
+// pruned, engine restarted) — a synthetic job built from the worker session.
+import { getBackgroundTask, listBackgroundTasks, taskIdFromArgs } from '../../../runtime/shared/background-tasks.mjs';
+import { clean } from '../helpers.mjs';
+
+/** The worker's readable result: its last non-empty assistant message, else
+ *  its last handoff, else a placeholder. */
+function workerResultText(session) {
+  const msgs = Array.isArray(session.messages) ? session.messages : [];
+  const lastAssistant = msgs.findLast(
+    (m) => m?.role === 'assistant' && (typeof m.content === 'string' ? m.content.trim() : m.content)
+  );
+  if (lastAssistant) {
+    return typeof lastAssistant.content === 'string' ? lastAssistant.content : JSON.stringify(lastAssistant.content);
+  }
+  if (typeof session.lastHandoff === 'string' && session.lastHandoff.trim()) return session.lastHandoff;
+  return '(worker session has no assistant output yet)';
+}
+
+export function createJobLookup({ mgr, tags, refreshTagsFromSessions }) {
+  function getJob(args, context = {}) {
+    const taskId = taskIdFromArgs(args);
+    if (taskId) {
+      const task = getBackgroundTask(taskId, { surface: 'agent', context });
+      if (!task) throw new Error(`agent read/status: task "${taskId}" not found`);
+      return task;
+    }
+    // Same precedence as 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;
+  }
+
+  function workerFallbackJob(target, context = {}) {
+    refreshTagsFromSessions({ scanSessions: true, context });
+    const sessionId = tags.get(target) || (mgr.getSession(target) ? target : null);
+    if (!sessionId) return null;
+    const session = mgr.getSession(sessionId);
+    if (!session) return null;
+    return {
+      taskId: null,
+      operation: 'worker',
+      status: session.closed === true ? 'closed' : session.status || 'idle',
+      startedAt: session.createdAt || null,
+      finishedAt: null,
+      error: null,
+      result: workerResultText(session),
+      meta: {
+        tag: tags.has(target) ? target : session.tag || null,
+        sessionId,
+        agent: session.agent || null,
+        preset: session.presetName || null,
+        provider: session.provider || null,
+        model: session.model || null,
+        effort: session.effort || null,
+        fast: session.fast === true,
+      },
+    };
+  }
+
+  function getJobOrWorker(args, context = {}) {
+    try {
+      return getJob(args, context);
+    } catch (error) {
+      const target = clean(args.tag || args.sessionId);
+      const fallback = target ? workerFallbackJob(target, context) : null;
+      if (fallback) return fallback;
+      throw error;
+    }
+  }
+
+  return { getJob, workerFallbackJob, getJobOrWorker };
+}

package/src/standalone/agent-tool/job-views/job-render.mjs

@@ -0,0 +1,98 @@
+// job-views/job-render.mjs
+// Shaping jobs for callers: the job list rows and the single-job status card,
+// each pairing the task's own fields with either live worker progress or the
+// frozen terminal view.
+import { listBackgroundTasks } from '../../../runtime/shared/background-tasks.mjs';
+import { positiveInt, terminalPidForContext } from '../helpers.mjs';
+import { isTerminalJobStatus, terminalJobFrozenFields } from './session-progress.mjs';
+
+/** The identity/route fields every job view starts with. `source` supplies the
+ *  routing fields (a task summary or a job's meta); `afterAgent` slots extra
+ *  fields right after `agent`. */
+function jobHead({ taskId, type, status, startedAt, finishedAt, error }, source, afterAgent = {}) {
+  return {
+    task_id: taskId,
+    type,
+    status,
+    tag: source.tag || null,
+    sessionId: source.sessionId || null,
+    agent: source.agent || null,
+    ...afterAgent,
+    preset: source.preset || null,
+    provider: source.provider || null,
+    model: source.model || null,
+    effort: source.effort || null,
+    fast: source.fast === true || source.fast === false ? source.fast : null,
+    startedAt,
+    finishedAt: finishedAt || null,
+    error: error || null,
+  };
+}
+
+export function createJobRender({ progress }) {
+  function listJobs(context = {}) {
+    const wantedPid = terminalPidForContext(context);
+    const now = Date.now();
+    const rows = listBackgroundTasks({ surface: 'agent', context }).map((task) => {
+      const head = jobHead({ ...task, taskId: task.task_id, type: task.operation }, task);
+      if (isTerminalJobStatus(task.status)) return { ...head, ...terminalJobFrozenFields(task.status, now) };
+      return {
+        ...head,
+        ...progress.jobWorkerSnapshot(task.sessionId),
+        ...progress.sessionProgressExtras(task.sessionId, task.agent || null, now, task.status),
+      };
+    });
+    if (!wantedPid) return rows;
+    return rows.filter((row) => {
+      const pid = positiveInt(row.clientHostPid);
+      // Spawn-prep rows have no worker session (and therefore no pid) yet;
+      // they already passed taskMatchesScope, so the queued spawn stays
+      // visible instead of vanishing until a pool slot frees up (user bug:
+      // "spawned 5, only 4 listed").
+      return pid ? pid === wantedPid : true;
+    });
+  }
+
+  /** Before the worker session exists, live progress is empty and the status
+   *  card would show only "status: running"; a minimal stage tells the caller
+   *  the job is still spinning up rather than silently stalled. */
+  function spawningProgress(status) {
+    const spawning = status === 'running';
+    return {
+      worker_stage: spawning ? 'spawning' : status || 'unknown',
+      last_progress: spawning ? 'spawning worker session' : status || 'unknown',
+      diagnostic: spawning ? 'worker session not started yet' : status || 'unknown',
+    };
+  }
+
+  function renderJob(job, includeResult = false) {
+    const meta = job.meta || {};
+    const head = jobHead(
+      { ...job, type: job.operation },
+      meta,
+      meta.respawned === true
+        ? {
+            respawned: true,
+            note: 'previous session reaped — fresh session, no prior context; re-supply anchors if needed',
+          }
+        : {}
+    );
+    const tail = includeResult && job.result !== undefined ? { result: job.result } : {};
+    // Frozen terminal view: never re-read the (possibly reused) live session.
+    if (isTerminalJobStatus(job.status)) {
+      return { ...head, ...terminalJobFrozenFields(job.status), ...tail };
+    }
+    let liveProgress = progress.sessionProgressExtras(meta.sessionId, meta.agent || null, Date.now(), job.status);
+    if (!meta.sessionId && (!liveProgress || Object.keys(liveProgress).length === 0)) {
+      liveProgress = spawningProgress(job.status);
+    }
+    return {
+      ...head,
+      ...progress.jobWorkerSnapshot(meta.sessionId),
+      ...liveProgress,
+      ...tail,
+    };
+  }
+
+  return { listJobs, renderJob };
+}

package/src/standalone/agent-tool/job-views/session-progress.mjs

@@ -0,0 +1,81 @@
+// job-views/session-progress.mjs
+// Live progress of a worker session (stage, silence, watchdog, queued
+// follow-ups) and the frozen fields a finished job reports instead.
+import { resolveAgentWatchdogPolicy } from '../../../runtime/agent/orchestrator/agent-runtime/agent-progress-watchdog.mjs';
+import { buildAgentTaskProgressFields } from '../../agent-task-status.mjs';
+import { getProgressWatchdogState } from '../../agent-watchdog-registry.mjs';
+
+// Job statuses that can never progress again (mirrors TERMINAL_STATUSES in
+// runtime/shared/background-tasks.mjs; 'canceled' accepted defensively).
+const TERMINAL_JOB_STATUSES = new Set(['completed', 'failed', 'cancelled', 'canceled']);
+
+export function isTerminalJobStatus(status) {
+  return TERMINAL_JOB_STATUSES.has(
+    String(status ?? '')
+      .trim()
+      .toLowerCase()
+  );
+}
+
+// A finished job is frozen history. Tags are reused, so its meta.sessionId can
+// point at a session that is NOW running a *different* job; reading live
+// progress for it made every old completed row inherit the current worker's
+// stage ("20 completed rows all reporting streaming/model active"). Terminal
+// rows therefore report only their own recorded status: no live worker
+// snapshot, no silent_for/watchdog/queued_followups.
+export function terminalJobFrozenFields(status, now = Date.now()) {
+  const stage =
+    String(status ?? '')
+      .trim()
+      .toLowerCase() || 'unknown';
+  return {
+    workerStatus: stage,
+    stage,
+    clientHostPid: null,
+    lastStreamDeltaAt: null,
+    ...buildAgentTaskProgressFields({ now, runtimeStage: stage, taskStatus: stage }),
+  };
+}
+
+export function createSessionProgress({ mgr }) {
+  function sessionProgressExtras(sessionId, role, now = Date.now(), taskStatus = null) {
+    if (!sessionId) return {};
+    const session = mgr.getSession(sessionId);
+    const runtime = mgr.getSessionRuntime?.(sessionId) || null;
+    const snapshot =
+      typeof mgr.getSessionProgressSnapshot === 'function' ? mgr.getSessionProgressSnapshot(sessionId) : null;
+    const policy = role ? resolveAgentWatchdogPolicy(role) : null;
+    const queuedFollowups =
+      typeof mgr.getSessionPendingMessageDepth === 'function' ? mgr.getSessionPendingMessageDepth(sessionId) : null;
+    return buildAgentTaskProgressFields({
+      now,
+      sessionStatus: session?.status || null,
+      runtimeStage: runtime?.stage || snapshot?.stage || session?.status || null,
+      snapshot,
+      runtime,
+      policy,
+      watchdogState: getProgressWatchdogState(mgr, sessionId),
+      queuedFollowups,
+      taskStatus,
+      lastToolCall: runtime?.lastToolCall || null,
+    });
+  }
+
+  function jobWorkerSnapshot(sessionId) {
+    if (!sessionId) return null;
+    const session = mgr.getSession(sessionId);
+    if (!session) return null;
+    const runtime = mgr.getSessionRuntime?.(sessionId);
+    const status = session.closed === true ? 'closed' : session.status || 'idle';
+    const progress = sessionProgressExtras(sessionId, session.agent || null);
+    return {
+      workerStatus: status,
+      stage: progress.worker_stage || runtime?.stage || status,
+      clientHostPid: session.clientHostPid || null,
+      lastStreamDeltaAt: runtime?.lastStreamDeltaAt ? new Date(runtime.lastStreamDeltaAt).toISOString() : null,
+      ...progress,
+    };
+  }
+
+  return { sessionProgressExtras, jobWorkerSnapshot };
+}

package/src/standalone/agent-tool/job-views/spawn-meta.mjs

@@ -0,0 +1,62 @@
+// job-views/spawn-meta.mjs
+// The task meta a spawn carries: from a prepared spawn, from raw args while
+// the spawn is still pending, and merging later updates into a job.
+import { sanitizeTaskMeta } from '../../../runtime/shared/background-tasks.mjs';
+import { clean, normalizeAgentName, presetKey } from '../helpers.mjs';
+import { resolveAgentSpawnPreset } from '../spawn-preset.mjs';
+
+export function preparedSpawnMeta(prepared, extras = {}) {
+  return sanitizeTaskMeta({
+    ...(extras || {}),
+    tag: prepared.tag,
+    sessionId: prepared.session.id,
+    agent: prepared.agent,
+    preset: presetKey(prepared.preset) || prepared.presetName,
+    provider: prepared.preset.provider,
+    model: prepared.preset.model,
+    effort: prepared.preset.effort || null,
+    fast: prepared.preset.fast === true,
+  });
+}
+
+/** 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 throws: falls back to
+ *  whatever raw args carry. */
+export function pendingSpawnMeta(cfgMod, args = {}, extras = {}) {
+  const agent = normalizeAgentName(args.agent);
+  let resolved = null;
+  if (!clean(args.model) || !clean(args.provider)) {
+    try {
+      resolved = resolveAgentSpawnPreset(cfgMod.loadConfig(), args)?.preset || null;
+    } catch {
+      resolved = null;
+    }
+  }
+  return sanitizeTaskMeta({
+    ...(extras || {}),
+    tag: clean(args.tag) || null,
+    sessionId: 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,
+    effort: clean(args.effort) || clean(resolved?.effort) || null,
+    fast: args.fast === true || resolved?.fast === true ? true : null,
+  });
+}
+
+export function mergeJobMeta(job, meta = {}) {
+  if (!job || !meta || typeof meta !== 'object') return;
+  const next = sanitizeTaskMeta({ ...(job.meta || {}), ...meta });
+  job.meta = next;
+  if (job.input && typeof job.input === 'object') {
+    job.input = {
+      ...job.input,
+      tag: next.tag || job.input.tag || null,
+      sessionId: next.sessionId || job.input.sessionId || null,
+      agent: next.agent || job.input.agent || null,
+    };
+  }
+  job.label = next.tag || next.sessionId || job.label;
+}