mixdog 0.9.95 → 0.9.97

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

@@ -11,7 +11,9 @@ import {
 } from './tool-catalog.mjs';
 import { getMcpTools } from '../runtime/agent/orchestrator/mcp/client.mjs';
 import { traceTurnTiming } from '../runtime/agent/orchestrator/agent-trace.mjs';
-import { beginTurnSnapshot, completeTurnSnapshot } from '../runtime/shared/turn-snapshot.mjs';
+import { beginTurnSnapshot, cancelTurnSnapshot, completeTurnSnapshot } from '../runtime/shared/turn-snapshot.mjs';
+import { isVisibleStreamProgress } from '../runtime/shared/stream-progress.mjs';
+import { runAbortable, settleWithin, throwIfAborted } from '../runtime/shared/abort-race.mjs';
 
 export function splitToolStatusCounts(rows) {
   const list = Array.isArray(rows) ? rows : [];
@@ -44,8 +46,12 @@ export function createSessionTurnApi(deps) {
     scheduleProviderWarmup, scheduleProviderModelWarmup, invalidateContextStatusCache,
     agentTool, recreateCurrentSessionIfReady, invalidatePreSessionToolSurface,
     activeToolSurface, applyResolvedCwd, resolveCwdPath, agentStatusState, notificationListeners,
-    awaitInitialMcpConnect, mcpTurnGraceMs = 150, awaitRoutePreparation,
-    getReservedSessionId, sessionTitles,
+    awaitInitialMcpConnect, mcpTurnGraceMs = 0, awaitRoutePreparation,
+    getReservedSessionId, sessionTitles, registerActiveTurnController,
+    beginTurnSnapshotForTurn = beginTurnSnapshot,
+    cancelTurnSnapshotForTurn = cancelTurnSnapshot,
+    completeTurnSnapshotForTurn = completeTurnSnapshot,
+    turnCleanupSettleMs = 2_000,
   } = deps;
   const enqueueRemoteAttachedPrompt = (prompt) => {
     const attachedSession = getSession();
@@ -79,7 +85,14 @@ export function createSessionTurnApi(deps) {
       // a normal user turn and this surface refreshes from disk.
       const attachedSession = getSession();
       if (attachedSession?.remoteAttached) {
-        const delivered = enqueueRemoteAttachedPrompt(prompt);
+        // Carry the submission id into the spool: the owner reuses it for the
+        // queue entry and the settled user row, so the submitting surface's
+        // optimistic bubble is released instead of standing beside the
+        // mirrored twin (user: 같은 세션에서 메세지가 두 개로 보인다).
+        const submissionId = String(options.id || '').trim();
+        const delivered = enqueueRemoteAttachedPrompt(
+          submissionId ? { content: prompt, id: submissionId } : prompt,
+        );
         return {
           // This branch is only a race-safe fallback for callers that reached
           // ask() before the live pipe was ready. Never manufacture an
@@ -93,6 +106,12 @@ export function createSessionTurnApi(deps) {
       // actual turn waits, guaranteeing that it cannot run on a stale route.
       const timingStartedAt = performance.now();
       const timingStartedAtEpoch = Date.now();
+      const turnAbortController = new AbortController();
+      const unregisterTurnAbort = typeof registerActiveTurnController === 'function'
+        ? registerActiveTurnController(turnAbortController)
+        : () => {};
+      const turnSignal = turnAbortController.signal;
+      const awaitTurn = (task) => runAbortable(turnSignal, task, 'Turn aborted');
       const submittedAt = Number(options.submittedAt);
       const hasSubmittedAt = Number.isFinite(submittedAt) && submittedAt > 0;
       let turnSnapshotSessionId = null;
@@ -104,12 +123,13 @@ export function createSessionTurnApi(deps) {
         // Capture immediately, but do not put Git on the first-token critical
         // path. Every actual tool execution joins this same promise below, so
         // shell/apply_patch cannot mutate the worktree before the baseline.
-        turnSnapshotPromise = Promise.resolve(beginTurnSnapshot(getCurrentCwd(), id)).catch(() => undefined);
+        turnSnapshotPromise = Promise.resolve()
+          .then(() => beginTurnSnapshotForTurn(getCurrentCwd(), id))
+          .catch(() => undefined);
       };
       const routeStartedAt = performance.now();
       startTurnSnapshot(getSession()?.id || getReservedSessionId?.());
-      await awaitRoutePreparation?.();
-      const routeWaitMs = performance.now() - routeStartedAt;
+      let routeWaitMs = 0;
       setActiveTurnCount(getActiveTurnCount() + 1);
       let mcpWaitMs = 0;
       let providerStartedAt = 0;
@@ -117,9 +137,10 @@ export function createSessionTurnApi(deps) {
       let turnTimingEmitted = false;
       // Heavy runtime warmup is one-shot and demand-driven: idle desktop panes
       // never spawn shell/token/shard helpers or a code-graph worker. More
-      // importantly, do not start them until the provider has produced its
-      // first stream delta: launching PowerShell + graph workers before that
-      // point directly competes with the first-token critical path.
+      // importantly, do not start them until the provider has produced visible
+      // text/reasoning/tool progress: transport headers and response-created
+      // acknowledgements arrive earlier and would make PowerShell + graph
+      // workers compete with the actual first-token critical path.
       const heavyRuntimeWarmupPending = typeof getCodeGraphFirstTurnPrewarmDone === 'function'
         && !getCodeGraphFirstTurnPrewarmDone();
       if (heavyRuntimeWarmupPending) {
@@ -167,8 +188,13 @@ export function createSessionTurnApi(deps) {
       };
       const startedAt = Date.now();
       try {
-        await refreshSessionForCwdIfNeeded('cwd-change');
-        if (!getSession()?.id) await createCurrentSession('turn');
+        await awaitTurn(() => awaitRoutePreparation?.());
+        routeWaitMs = performance.now() - routeStartedAt;
+        await awaitTurn(() => refreshSessionForCwdIfNeeded('cwd-change'));
+        if (!getSession()?.id) {
+          await awaitTurn(() => createCurrentSession('turn', { signal: turnSignal }));
+        }
+        throwIfAborted(turnSignal);
         // Remote outbound: ensure a transcript writer bound to the current
         // session.id + cwd. Gated on remoteEnabled so non-remote sessions write nothing.
         if (getRemoteEnabled()) {
@@ -218,7 +244,7 @@ export function createSessionTurnApi(deps) {
           session0.deferredInitialRefreshPending = false;
           // Give an in-flight INITIAL MCP connect only a short TTFT grace.
           // Slower servers remain available through the late-tool path.
-          try { await awaitMcpGrace(); }
+          try { await awaitTurn(() => awaitMcpGrace()); }
           catch { /* gate must never break the turn */ }
           try { refreshInitialDeferredMcpSurface(session0, getMcpTools()); }
           catch { /* first-turn MCP fold must never break the turn */ }
@@ -234,7 +260,7 @@ export function createSessionTurnApi(deps) {
           // short TTFT grace BEFORE folding the catalog so a slow reconnect
           // cannot hold the provider request. No reconnect in flight →
           // immediate no-op.
-          try { await awaitMcpGrace(); }
+          try { await awaitTurn(() => awaitMcpGrace()); }
           catch { /* gate must never break the turn */ }
           try {
             reconcileDeferredMcpToolCatalog(session0, getMcpTools(), {
@@ -252,8 +278,13 @@ export function createSessionTurnApi(deps) {
         // UserPromptSubmit: a hook FAILURE must not block the turn, but blocked===true MUST throw.
         let promptDispatch = null;
         try {
-          promptDispatch = await hooks.dispatch('UserPromptSubmit', hookCommonPayload({ session_id: session0.id, prompt }));
-        } catch { /* hook failure never blocks the turn */ }
+          promptDispatch = await awaitTurn(
+            () => hooks.dispatch('UserPromptSubmit', hookCommonPayload({ session_id: session0.id, prompt })),
+          );
+        } catch {
+          throwIfAborted(turnSignal);
+          // Ordinary hook failure never blocks the turn.
+        }
         if (promptDispatch?.blocked === true) {
           throw new Error(`prompt blocked by hook: ${promptDispatch.reason || ''}`);
         }
@@ -264,7 +295,6 @@ export function createSessionTurnApi(deps) {
           .map((part) => String(part || '').trim())
           .filter(Boolean)
           .join('\n\n');
-        providerStartedAt = performance.now();
         const result = await mgr.askSession(
           session0.id,
           prompt,
@@ -322,22 +352,36 @@ export function createSessionTurnApi(deps) {
             onToolApproval: options.onToolApproval,
             onCompactEvent: options.onCompactEvent,
             onStageChange: options.onStageChange,
+            onProviderSendStarted: (...args) => {
+              // This callback is emitted immediately before provider.send,
+              // after session locking, history shaping and pre-send compact.
+              // The old timestamp above mgr.askSession mislabeled all of that
+              // Mixdog work as provider latency.
+              if (!providerStartedAt) providerStartedAt = performance.now();
+              return options.onProviderSendStarted?.(...args);
+            },
+            onToolPhaseStarted: options.onToolPhaseStarted,
+            onToolPhaseCompleted: options.onToolPhaseCompleted,
             onStreamDelta: (...args) => {
               let value;
               try {
                 value = options.onStreamDelta?.(...args);
               } finally {
-                turnTimingStatus = 'first-delta';
-                emitTurnTiming(turnTimingStatus);
-                armHeavyRuntimeWarmup('first-stream');
+                if (isVisibleStreamProgress(args[0])) {
+                  turnTimingStatus = 'first-visible';
+                  emitTurnTiming(turnTimingStatus);
+                  armHeavyRuntimeWarmup('first-visible');
+                }
               }
               return value;
             },
             drainSteering: options.drainSteering,
             onSteerMessage: options.onSteerMessage,
             notifyFn: notifyFnForSession(session0.id),
+            signal: turnSignal,
           },
         );
+        throwIfAborted(turnSignal);
         if (!turnTimingEmitted) turnTimingStatus = 'complete-no-delta';
         setSession(mgr.getSession(session0.id) || getSession());
         try { sessionTitles?.observeThird(getSession()); } catch { /* title refresh is best-effort */ }
@@ -354,8 +398,11 @@ export function createSessionTurnApi(deps) {
         }
         hooks.emit('turn:end', { sessionId: session0.id, elapsedMs: Date.now() - startedAt });
         try {
-          await hooks.dispatch('Stop', hookCommonPayload({ session_id: session0.id }));
-        } catch { /* best-effort: Stop hook must never break the turn */ }
+          await awaitTurn(() => hooks.dispatch('Stop', hookCommonPayload({ session_id: session0.id })));
+        } catch {
+          throwIfAborted(turnSignal);
+          // Ordinary Stop hook failure is best-effort.
+        }
         return { result, session: getSession() };
       } catch (error) {
         hooks.emit('turn:error', { sessionId: getSession()?.id || null, elapsedMs: Date.now() - startedAt, error: error?.message || String(error) });
@@ -372,8 +419,21 @@ export function createSessionTurnApi(deps) {
       } finally {
         emitTurnTiming(turnTimingStatus);
         armHeavyRuntimeWarmup('turn-settled');
-        try { await turnSnapshotPromise; } catch { /* Git snapshot is optional */ }
-        try { await completeTurnSnapshot(turnSnapshotSessionId); } catch { /* review cleanup never breaks a turn */ }
+        if (turnSignal.aborted) {
+          try { cancelTurnSnapshotForTurn(turnSnapshotSessionId); } catch {}
+          void Promise.resolve(turnSnapshotPromise).catch(() => {});
+        } else {
+          const snapshotCleanup = Promise.resolve(turnSnapshotPromise)
+            .then(() => completeTurnSnapshotForTurn(turnSnapshotSessionId));
+          snapshotCleanup.catch(() => {});
+          try {
+            await awaitTurn(() => settleWithin(snapshotCleanup, turnCleanupSettleMs));
+          } catch { /* optional review cleanup never overrides turn settlement */ }
+          if (turnSignal.aborted) {
+            try { cancelTurnSnapshotForTurn(turnSnapshotSessionId); } catch {}
+          }
+        }
+        try { unregisterTurnAbort?.(); } catch {}
         setActiveTurnCount(Math.max(0, getActiveTurnCount() - 1));
         if (!isFirstTurnCompleted()) {
           setFirstTurnCompleted(true);
@@ -399,6 +459,18 @@ export function createSessionTurnApi(deps) {
       pushTranscriptRebind?.();
       return true;
     },
+    // Message-selector rewind: drop the chosen user prompt and everything
+    // after it from the model history. Unlike clear() the session object is
+    // kept (same id, same provider/model/cwd) — only the tail is undone.
+    async rewindMessages(options = {}) {
+      const session = getSession();
+      if (!session?.id) return null;
+      const result = await mgr.rewindSessionMessagesTo?.(session.id, options);
+      if (!result) return null;
+      setSession(mgr.getSession(session.id) || session);
+      invalidateContextStatusCache();
+      return result;
+    },
     // session_manage tool handoff: the engine polls this at turn end and, if
     // set, runs the same clear path the idle auto-clear uses. One-shot read.
     consumePendingSessionReset() {

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

@@ -15,7 +15,7 @@ export function createSettingsApi({
   // config-lifecycle
   adoptConfig,
   saveConfigAndAdopt,
-  scheduleBackendSave,
+  scheduleChannelProviderSave,
   scheduleSkillsSave,
   // normalizers / helpers
   cfgMod,
@@ -35,7 +35,6 @@ export function createSettingsApi({
   formatDurationMs,
   localPackageVersion,
   // state getters / feature flags
-  memoryEnabled,
   recapEnabledFn,
   channelsEnabled,
   autoUpdateEnabled,
@@ -56,7 +55,7 @@ export function createSettingsApi({
   forgetDiscordToken,
   saveTelegramToken,
   forgetTelegramToken,
-  setBackend,
+  setChannelProvider,
 }) {
   return {
     getOnboardingStatus() {
@@ -173,11 +172,11 @@ export function createSettingsApi({
     },
     getCompactionSettings() {
       const config = getConfig();
-      return normalizeCompactionConfig(config.compaction, { memoryEnabled: memoryEnabled() });
+      return normalizeCompactionConfig(config.compaction);
     },
     setCompactionSettings(input = {}) {
       const config = getConfig();
-      const current = normalizeCompactionConfig(config.compaction, { memoryEnabled: memoryEnabled() });
+      const current = normalizeCompactionConfig(config.compaction);
       const next = { ...current };
       if (hasOwn(input, 'auto')) next.auto = input.auto !== false;
       if (hasOwn(input, 'enabled')) next.auto = input.enabled !== false;
@@ -193,23 +192,23 @@ export function createSettingsApi({
         if (hasOwn(input, key)) next[key] = input[key];
       }
       const nextConfig = { ...config };
-      nextConfig.compaction = normalizeCompactionConfig(next, { memoryEnabled: memoryEnabled() });
+      nextConfig.compaction = normalizeCompactionConfig(next);
       saveConfigAndAdopt(nextConfig);
       const config2 = getConfig();
       const session = getSession();
       if (session) {
         session.compaction = {
           ...(session.compaction || {}),
-          ...normalizeCompactionConfig(config2.compaction, { memoryEnabled: memoryEnabled() }),
+          ...normalizeCompactionConfig(config2.compaction),
         };
       }
       invalidateContextStatusCache();
-      return normalizeCompactionConfig(config2.compaction, { memoryEnabled: memoryEnabled() });
+      return normalizeCompactionConfig(config2.compaction);
     },
     // Recap toggle: user-facing switch that gates ONLY the background memory
     // cycles (1/2/3). The memory module (transcript watcher/ingest, on-demand
     // recall/fasttrack drains) is always-on. Persisted via the same
-    // saveConfigAndAdopt path as compaction/autoClear. The memory daemon
+    // saveConfigAndAdopt path as compaction/autoClear. The memory runtime
     // re-reads recap from the agent config section each cycle tick, so toggling
     // takes effect without a restart (no memory-service stop/start here).
     getRecapSettings() {
@@ -223,17 +222,6 @@ export function createSettingsApi({
       invalidateContextStatusCache();
       return this.getRecapSettings();
     },
-    // Thin aliases kept for the current TUI callsites (updated separately).
-    // enabled here reflects the recap toggle; memory itself is always-on.
-    getMemorySettings() {
-      return {
-        enabled: recapEnabledFn(),
-        compactFastTrackAvailable: true,
-      };
-    },
-    async setMemoryEnabled(enabled) {
-      return this.setRecapEnabled(enabled);
-    },
     getChannelSettings(options = {}) {
       return {
         enabled: channelsEnabled(),
@@ -362,7 +350,7 @@ export function createSettingsApi({
       reloadChannelsSoon();
       return result;
     },
-    setBackend(name) {
+    setChannelProvider(name) {
       // Validate synchronously (same contract as before: bad input throws on
       // this call so the TUI's try/catch can react immediately). The actual
       // channels-section file read-modify-write is the hitch source on the
@@ -371,10 +359,10 @@ export function createSettingsApi({
       // disk synchronously inside the key handler.
       const value = String(name || '').trim();
       if (value !== 'discord' && value !== 'telegram') {
-        throw new Error('backend must be discord or telegram');
+        throw new Error('provider must be discord or telegram');
       }
-      scheduleBackendSave(value);
-      return { ok: true, backend: value };
+      scheduleChannelProviderSave(value);
+      return { ok: true, provider: value };
     },
   };
 }

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

@@ -13,7 +13,7 @@ export const TOOL_SEARCH_TOOL = {
     openWorldHint: false,
     agentHidden: true,
   },
-  description: 'Load deferred tools by exact name via names[]; reports loaded/already-active/missing plus MCP servers still connecting or failed. Deferred tools also auto-load when called directly.',
+  description: 'Deferred-tool activation status; direct calls auto-load.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -34,7 +34,7 @@ export const CWD_TOOL = {
     openWorldHint: false,
     agentHidden: true,
   },
-  description: 'Show or set the session work project for tool execution. Use only for explicit project path changes.',
+  description: 'Show or set the session work project for tool execution.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -84,7 +84,7 @@ export const SESSION_MANAGE_TOOL = {
     openWorldHint: false,
     agentHidden: true,
   },
-  description: 'Reset this conversation on explicit user request. action=clear wipes all context (like /clear); action=compact_clear summarizes first and carries context forward (auto-clear style). Applies when the current turn ends.',
+  description: 'Schedule conversation reset at current-turn end.',
   inputSchema: {
     type: 'object',
     properties: {

package/src/session-runtime/workflow-agents-api.mjs

@@ -10,7 +10,6 @@ import {
   workflowPresetId,
   WORKFLOW_ROUTE_SLOTS,
   FIXED_AGENT_SLOTS,
-  agentPresetSlot,
   normalizeAgentId,
   normalizeWorkflowId,
   workflowIdFromName,
@@ -24,6 +23,7 @@ import { ONBOARDING_VERSION } from './quick-search-models.mjs';
 import { findOutputStyle } from './output-styles.mjs';
 import { ensureProviderEnabled } from './config-helpers.mjs';
 import { fastCapableFor } from './model-capabilities.mjs';
+import { canonicalizeAgentRouteStorage } from '../runtime/shared/agent-route-config.mjs';
 
 // Onboarding + agents/workflows/output-style selection surface. Extracted
 // verbatim from the runtime API object; stateless helpers are imported directly
@@ -46,67 +46,54 @@ export function createWorkflowAgentsApi(deps) {
       // Search/agent picks) omits defaultRoute entirely and must NOT persist the
       // current route as Main or recreate the session.
       const config = getConfig();
-      const defaultRoute = hasOwn(payload, 'defaultRoute')
-        ? normalizeWorkflowRoute(payload.defaultRoute, getRoute())
-        : null;
       const workflowInput = payload.workflowRoutes && typeof payload.workflowRoutes === 'object'
         ? payload.workflowRoutes
         : {};
       const nextConfig = { ...config };
-      if (hasOwn(payload, 'defaultProvider')) {
-        const requested = clean(payload.defaultProvider);
-        if (requested) {
-          if (!isKnownProvider(requested)) throw new Error(`unknown provider "${payload.defaultProvider}"`);
-          nextConfig.defaultProvider = requested;
-        }
-      }
+      const defaultRoute = hasOwn(payload, 'defaultRoute')
+        ? normalizeWorkflowRoute(payload.defaultRoute, getRoute())
+        : null;
       let presets = Array.isArray(nextConfig.presets) ? nextConfig.presets.slice() : [];
-      const workflowRoutes = { ...(nextConfig.workflowRoutes || {}) };
-      const touchedWorkflowSlots = new Set();
+      const agentRoutes = { ...(nextConfig.agents || {}) };
 
       if (defaultRoute) {
         presets = upsertWorkflowPreset(presets, 'lead', defaultRoute);
-        workflowRoutes.lead = defaultRoute;
         nextConfig.default = workflowPresetId('lead');
       }
 
       for (const slot of WORKFLOW_ROUTE_SLOTS) {
+        if (!hasOwn(workflowInput, slot)) continue;
         const normalized = normalizeWorkflowRoute(workflowInput[slot]);
-        if (!normalized) continue;
-        workflowRoutes[slot] = normalized;
-        presets = upsertWorkflowPreset(presets, slot, normalized);
-        touchedWorkflowSlots.add(slot);
+        if (slot === 'lead') {
+          if (!normalized) continue;
+          presets = upsertWorkflowPreset(presets, 'lead', normalized);
+          nextConfig.default = workflowPresetId('lead');
+        } else if (slot === 'agent') {
+          if (normalized) agentRoutes.worker = normalized;
+          else delete agentRoutes.worker;
+        } else if (slot === 'explorer') {
+          if (normalized) agentRoutes.explore = normalized;
+          else delete agentRoutes.explore;
+        } else if (slot === 'memory') {
+          if (normalized) agentRoutes.maintainer = normalized;
+          else delete agentRoutes.maintainer;
+        }
       }
 
       nextConfig.presets = presets;
-      nextConfig.workflowRoutes = workflowRoutes;
-      nextConfig.maintenance = {
-        ...(nextConfig.maintenance || {}),
-        ...(touchedWorkflowSlots.has('explorer') ? { explore: normalizeWorkflowRoute(workflowRoutes.explorer) } : {}),
-        ...(touchedWorkflowSlots.has('memory') ? { memory: normalizeWorkflowRoute(workflowRoutes.memory) } : {}),
-      };
+      nextConfig.agents = agentRoutes;
       const agentInput = payload.agentRoutes && typeof payload.agentRoutes === 'object'
         ? payload.agentRoutes
         : null;
       if (agentInput) {
-        const nextAgents = { ...(nextConfig.agents || {}) };
-        const nextMaintenance = { ...(nextConfig.maintenance || {}) };
+        const nextAgents = { ...agentRoutes };
         for (const agent of FIXED_AGENT_SLOTS) {
+          if (!hasOwn(agentInput, agent.id)) continue;
           const routeToSave = normalizeWorkflowRoute(agentInput[agent.id]);
-          if (!routeToSave) continue;
-          nextAgents[agent.id] = routeToSave;
-          presets = upsertWorkflowPreset(presets, agentPresetSlot(agent.id), routeToSave);
-          if (agent.workflowSlot) {
-            workflowRoutes[agent.workflowSlot] = routeToSave;
-            presets = upsertWorkflowPreset(presets, agent.workflowSlot, routeToSave);
-            if (agent.id === 'explore') nextMaintenance.explore = routeToSave;
-            if (agent.id === 'maintainer') nextMaintenance.memory = routeToSave;
-          }
+          if (routeToSave) nextAgents[agent.id] = routeToSave;
+          else delete nextAgents[agent.id];
         }
         nextConfig.agents = nextAgents;
-        nextConfig.presets = presets;
-        nextConfig.workflowRoutes = workflowRoutes;
-        nextConfig.maintenance = nextMaintenance;
       }
       nextConfig.onboarding = {
         ...(nextConfig.onboarding || {}),
@@ -116,11 +103,13 @@ export function createWorkflowAgentsApi(deps) {
       };
 
       if (payload.searchRoute) {
-        const searchToSave = normalizeSearchRouteConfig(payload.searchRoute);
+        const searchToSave = clean(payload.searchRoute.provider)
+          ? normalizeSearchRouteConfig(payload.searchRoute)
+          : normalizeSearchRouteConfig({ provider: 'default', model: 'default', toolType: payload.searchRoute.toolType });
         if (searchToSave) nextConfig.searchRoute = searchToSave;
       }
 
-      saveConfigAndAdopt(nextConfig);
+      saveConfigAndAdopt(canonicalizeAgentRouteStorage(nextConfig));
       if (defaultRoute) {
         setRouteState(resolveRoute(getConfig(), { provider: defaultRoute.provider, model: defaultRoute.model, effort: defaultRoute.effort }));
         const session = getSession();
@@ -362,12 +351,6 @@ export function createWorkflowAgentsApi(deps) {
       clearAgentDefinitionCache(id);
       if (payload.route) {
         await this.setAgentRoute(id, payload.route);
-      } else if (!FIXED_AGENT_SLOTS.some((agent) => agent.id === id)
-        && !agentRouteFromConfig(getConfig(), id, dataDir)) {
-        // Custom roles have no built-in preset fallback, so a model-less save
-        // would spawn as `agent "<id>" has no model assignment`. Seed the
-        // current default route; an unconfigured install just stays routeless.
-        try { await this.setAgentRoute(id, {}); } catch { /* no default route yet */ }
       }
       return this.getAgentDefinition(id);
     },
@@ -412,10 +395,7 @@ export function createWorkflowAgentsApi(deps) {
           delete agents[id];
           nextConfig.agents = agents;
         }
-        const presetId = workflowPresetId(agentPresetSlot(id));
-        nextConfig.presets = (Array.isArray(nextConfig.presets) ? nextConfig.presets : [])
-          .filter((preset) => clean(preset?.id) !== presetId);
-        saveConfigAndAdopt(nextConfig);
+        saveConfigAndAdopt(canonicalizeAgentRouteStorage(nextConfig));
       }
       return { id, deleted: true, revertedToBuiltIn };
     },
@@ -435,23 +415,31 @@ export function createWorkflowAgentsApi(deps) {
       const requested = { ...(next || {}) };
       const routeDataDir = cfgMod.getPluginData?.() || STANDALONE_DATA_DIR;
       const stored = agentRouteFromConfig(getConfig(), id, routeDataDir) || {};
-      // A request with neither provider nor model is the "seed from the current
-      // default" path (new custom agent) and inherits Main verbatim.
-      const inheritsDefault = !clean(requested.provider) && !clean(requested.model);
-      let selectedRoute = resolveRoute(getConfig(), requested);
-      if (!inheritsDefault) {
-        const sameModel = clean(selectedRoute.provider) === clean(stored.provider)
-          && clean(selectedRoute.model) === clean(stored.model);
-        selectedRoute = {
-          ...selectedRoute,
-          effort: requested.effort !== undefined
-            ? selectedRoute.effort
-            : (sameModel ? (stored.effort || null) : null),
-          fast: requested.fast !== undefined
-            ? selectedRoute.fast === true
-            : (sameModel && stored.fast === true),
-        };
+      // No provider means no explicit override. Remove the stored route so the
+      // agent follows Main dynamically; never synthesize a provider.
+      if (!clean(requested.provider)) {
+        const nextConfig = { ...getConfig() };
+        const agents = { ...(nextConfig.agents || {}) };
+        const hadOverride = Object.prototype.hasOwnProperty.call(agents, id);
+        delete agents[id];
+        nextConfig.agents = agents;
+        if (hadOverride) saveConfigAndAdopt(canonicalizeAgentRouteStorage(nextConfig));
+        const inherited = normalizeWorkflowRoute(resolveRoute(getConfig(), {}));
+        return { ...(inherited || {}), inherited: true };
       }
+      if (!clean(requested.model)) throw new Error('agent route requires provider and model');
+      let selectedRoute = resolveRoute(getConfig(), requested);
+      const sameModel = clean(selectedRoute.provider) === clean(stored.provider)
+        && clean(selectedRoute.model) === clean(stored.model);
+      selectedRoute = {
+        ...selectedRoute,
+        effort: requested.effort !== undefined
+          ? selectedRoute.effort
+          : (sameModel ? (stored.effort || null) : null),
+        fast: requested.fast !== undefined
+          ? selectedRoute.fast === true
+          : (sameModel && stored.fast === true),
+      };
       await ensureProvidersReady(ensureProviderEnabled(getConfig(), selectedRoute.provider));
       const modelMeta = await lookupModelMeta(selectedRoute.provider, selectedRoute.model);
       const fastCapable = fastCapableFor(selectedRoute.provider, modelMeta);
@@ -459,26 +447,12 @@ export function createWorkflowAgentsApi(deps) {
 
       const routeToSave = normalizeWorkflowRoute(selectedRoute);
       if (!routeToSave) throw new Error('agent route requires provider and model');
-      const agent = FIXED_AGENT_SLOTS.find((item) => item.id === id);
       const nextConfig = { ...getConfig() };
       nextConfig.agents = {
         ...(nextConfig.agents || {}),
         [id]: routeToSave,
       };
-      nextConfig.presets = upsertWorkflowPreset(nextConfig.presets, agentPresetSlot(id), routeToSave);
-      if (agent?.workflowSlot) {
-        nextConfig.workflowRoutes = {
-          ...(nextConfig.workflowRoutes || {}),
-          [agent.workflowSlot]: routeToSave,
-        };
-        nextConfig.presets = upsertWorkflowPreset(nextConfig.presets, agent.workflowSlot, routeToSave);
-        nextConfig.maintenance = {
-          ...(nextConfig.maintenance || {}),
-          ...(id === 'explore' ? { explore: routeToSave } : {}),
-          ...(id === 'maintainer' ? { memory: routeToSave } : {}),
-        };
-      }
-      saveConfigAndAdopt(nextConfig);
+      saveConfigAndAdopt(canonicalizeAgentRouteStorage(nextConfig));
       return routeToSave;
     },
   };

package/src/session-runtime/workflow.mjs

@@ -9,6 +9,7 @@ import { normalizeEffortInput } from './effort.mjs';
 import { isLikelyRawModelId } from './config-helpers.mjs';
 import { readTextSafe, readJsonSafe } from './fs-utils.mjs';
 import { isHiddenAgent } from '../runtime/agent/orchestrator/internal-agents.mjs';
+import { configuredAgentRouteCandidates } from '../runtime/shared/agent-route-config.mjs';
 
 export const WORKFLOW_ROUTE_SLOTS = ['lead', 'agent', 'explorer', 'memory'];
 export const FIXED_AGENT_SLOTS = Object.freeze([
@@ -415,16 +416,16 @@ export function upsertWorkflowPreset(presets, slot, routeLike) {
 // the runtime; created via this factory.
 export function createWorkflowRouteHelpers({ resolveDefaultProvider, findPreset }) {
   function summarizeWorkflowRoutes(config) {
-    const routes = config?.workflowRoutes && typeof config.workflowRoutes === 'object' ? config.workflowRoutes : {};
-    const fallbackProvider = resolveDefaultProvider(config);
     const out = {};
-    for (const slot of WORKFLOW_ROUTE_SLOTS) {
-      const route = routes[slot];
-      // Read/interpret path: a route with a model but no provider falls back to
-      // config.defaultProvider (then DEFAULT_PROVIDER).
-      if (route?.model && (route?.provider || fallbackProvider)) {
-        out[slot] = normalizeWorkflowRoute(route, { provider: fallbackProvider });
-      }
+    const lead = routeFromPreset(config, config?.default);
+    if (lead) out.lead = lead;
+    for (const [slot, agentId] of [
+      ['agent', 'worker'],
+      ['explorer', 'explore'],
+      ['memory', 'maintainer'],
+    ]) {
+      const route = agentRouteFromConfig(config, agentId);
+      if (route) out[slot] = route;
     }
     return out;
   }
@@ -446,22 +447,11 @@ export function createWorkflowRouteHelpers({ resolveDefaultProvider, findPreset
     // their routes live in config.agents[<id>] like the fixed roles.
     const id = normalizeAgentId(agentId) || normalizeWorkflowId(agentId);
     if (!id) return null;
-    // Read/interpret path: inject config.defaultProvider (then DEFAULT_PROVIDER)
-    // when a stored route omits its provider.
-    const fallback = { provider: resolveDefaultProvider(config) };
-    const explicit = normalizeWorkflowRoute(config?.agents?.[id], fallback)
-      || (id === 'maintainer' ? normalizeWorkflowRoute(config?.agents?.maintenance, fallback) : null);
-    if (explicit) return explicit;
-
-    const agent = FIXED_AGENT_SLOTS.find((item) => item.id === id);
-    if (agent?.workflowSlot) {
-      const workflowRoute = normalizeWorkflowRoute(config?.workflowRoutes?.[agent.workflowSlot], fallback);
-      if (workflowRoute) return workflowRoute;
+    for (const candidate of configuredAgentRouteCandidates(config, id)) {
+      const route = normalizeWorkflowRoute(candidate)
+        || routeFromPreset(config, candidate);
+      if (route) return route;
     }
-
-    if (id === 'explore') return routeFromPreset(config, config?.maintenance?.explore);
-    if (id === 'maintainer') return routeFromPreset(config, config?.maintenance?.memory);
-
     return null;
   }