mixdog 1.3.1 → 1.3.3

package/src/tui/paste-attachments.mjs

@@ -86,7 +86,6 @@ export {
   formatPastedTextRef,
   pastedTextLineCount,
   PASTE_TOKEN_MIN_CHARS,
-  PASTE_TOKEN_MIN_LINES,
   shouldFoldPastedText,
 } from './paste-text-policy.mjs';
 

package/src/tui/paste-text-policy.mjs

@@ -3,8 +3,9 @@
 // A big paste is replaced in the prompt by a compact token so the editor does
 // not choke on thousands of raw characters; the original text lives in the
 // surface's pasted-text map and is expanded back on submit.
-export const PASTE_TOKEN_MIN_LINES = 10;
-export const PASTE_TOKEN_MIN_CHARS = 200;
+// Same rule as Claude Code / Codex (LARGE_PASTE_CHAR_THRESHOLD): only a paste
+// longer than this many characters folds; the line count never matters.
+export const PASTE_TOKEN_MIN_CHARS = 1000;
 
 // VISIBLE lines: a copy that ends in a newline ("a\nb\n") is two lines, not
 // three. Counting the empty trailing chunk folded ordinary two-line copies
@@ -18,9 +19,7 @@ export function pastedTextLineCount(text) {
 }
 
 export function shouldFoldPastedText(text) {
-  const value = String(text ?? '');
-  if (!value) return false;
-  return pastedTextLineCount(value) >= PASTE_TOKEN_MIN_LINES || value.length > PASTE_TOKEN_MIN_CHARS;
+  return String(text ?? '').length > PASTE_TOKEN_MIN_CHARS;
 }
 
 export function formatPastedTextRef(id, text) {

package/src/tui/prompt-history-store.mjs

@@ -3,9 +3,10 @@
  * Stored under MIXDOG data dir (not the repo working tree).
  */
 import { createHash } from 'node:crypto';
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { chmod, mkdir, rename, writeFile } from 'node:fs/promises';
+import { mkdirSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
+import { readJsonStateSync, writeFileAtomicAsync, writeFileAtomicSync } from '../runtime/shared/atomic-file.mjs';
 import { resolvePluginData } from '../runtime/shared/plugin-paths.mjs';
 
 export const PROMPT_HISTORY_LIMIT = 50;
@@ -33,10 +34,18 @@ function historyFilePath(cwd) {
 }
 
 function readEntries(filePath) {
-  if (!filePath || !existsSync(filePath)) return [];
+  if (!filePath) return [];
   try {
-    const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
-    const entries = Array.isArray(parsed?.entries) ? parsed.entries : [];
+    // A damaged file (NUL, truncated) is kept aside as *.corrupt-<ts> and the
+    // history starts empty; the next flush writes a fresh file.
+    const parsed = readJsonStateSync(filePath, {
+      mode: 0o600,
+      validate: (value) => {
+        if (!Array.isArray(value?.entries)) throw new TypeError('prompt history has no entries');
+        return value;
+      },
+    });
+    const entries = parsed ? parsed.entries : [];
     return entries.map((entry) => String(entry || '').trim()).filter((entry) => promptHistoryKey(entry));
   } catch {
     return [];
@@ -52,14 +61,7 @@ function writeEntriesSync(filePath, entries) {
   try {
     // Prompt text may be sensitive; restrict directory/file to the owning user.
     mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
-    const tmp = `${filePath}.${process.pid}.tmp`;
-    writeFileSync(tmp, buildPayload(entries), { encoding: 'utf8', mode: 0o600 });
-    renameSync(tmp, filePath);
-    try {
-      chmodSync(filePath, 0o600);
-    } catch {
-      /* best-effort; Windows may ignore mode bits */
-    }
+    writeFileAtomicSync(filePath, buildPayload(entries), { mode: 0o600 });
     return true;
   } catch {
     return false;
@@ -72,14 +74,7 @@ async function writeEntriesAsync(filePath, entries) {
   if (!filePath) return false;
   try {
     await mkdir(dirname(filePath), { recursive: true, mode: 0o700 });
-    const tmp = `${filePath}.${process.pid}.tmp`;
-    await writeFile(tmp, buildPayload(entries), { encoding: 'utf8', mode: 0o600 });
-    await rename(tmp, filePath);
-    try {
-      await chmod(filePath, 0o600);
-    } catch {
-      /* best-effort; Windows may ignore mode bits */
-    }
+    await writeFileAtomicAsync(filePath, buildPayload(entries), { mode: 0o600 });
     return true;
   } catch {
     return false;

package/src/tui/session/agent-job-feed/execution-delivery.mjs

@@ -86,10 +86,13 @@ export function createExecutionDelivery({
     // active loop can attach them after the next tool batch. The immediate
     // response card was already pushed above, so the queued twin stays
     // model-visible but suppresses its drain-time transcript card.
-    const { execution } = markCompletionEntry(resumeBody, { executionId, meta: event?.meta });
+    const { execution, hop } = markCompletionEntry(resumeBody, { executionId, meta: event?.meta });
     const enqueued = enqueue(resumeBody, {
       mode: 'task-notification',
       ...(execution ? { execution } : {}),
+      // The launching turn's bot-chain hop: the turn this wakes, or the running
+      // turn this joins, resumes at it (bot-hops.mjs).
+      ...(hop ? { transcriptMeta: { hop } } : {}),
       priority: 'next',
       key: notificationKey || undefined,
       abortDiscardOnAbort: true,

package/src/tui/session/context-state.mjs

@@ -77,6 +77,10 @@ export function createContextState({
     autoClear: autoClearState(),
     workflow: runtime.workflow || null,
     orchestrationMode: runtime.orchestrationMode || 'none',
+    // A workflow / orchestration mode chosen during a turn: shown above,
+    // applied when the next turn starts (tool-policy-refresh.mjs).
+    pendingWorkflowSwitch: runtime.session?.pendingWorkflowId !== undefined,
+    pendingOrchestrationModeSwitch: runtime.session?.pendingOrchestrationMode !== undefined,
     // Every `set({ ...routeState() })` (the 2s runtime pulse, model/effort
     // switches, turn end, resume) republishes the Goal. It must read it
     // through the goal-continuation mask: the raw record still holds a

package/src/tui/session/notice-surface.mjs

@@ -1,6 +1,7 @@
 /**
  * src/tui/session/notice-surface.mjs - toasts, transcript notices, progress hint.
  */
+import { roomRowSender } from '../../runtime/agent/orchestrator/session/agent-room.mjs';
 import { polishNoticeText } from './notice-text.mjs';
 import { nextId } from './transcript-spill.mjs';
 
@@ -59,6 +60,8 @@ export function createNoticeSurface({ getState, set, isDisposed, pushItem, repla
       // A schedule result posted into a home thread (routine-result.mjs).
       ...(options.routine ? { routine: options.routine } : {}),
       ...(options.room ? { room: options.room } : {}),
+      // A room message another session sent shows its sender, as restored.
+      ...(userRow ? roomRowSender(options.room) : {}),
       // A room user row's files, in the fields a prompt row draws them from;
       // a task report's or member speech's returned files likewise.
       ...(Array.isArray(options.attachments) && options.attachments.length ? { attachments: options.attachments } : {}),

package/src/tui/session/session-api/intake/abort.mjs

@@ -2,12 +2,13 @@
 // during a turn cancels it and, unless a steering prompt is already queued,
 // reclaims the in-flight prompt, its history slot and its requeue entries.
 import { hydratePastedAttachments, hydrateRestorableFileParts } from '../../../../runtime/attachments/store.mjs';
+import { USER_CANCEL_KEEP_PROMPT_REASON } from '../../../../runtime/agent/orchestrator/session/manager/turn-interruption.mjs';
 import { abortGoalTurn } from '../../goal-turn-state.mjs';
 import { promptHistoryWithout } from '../../prompt-history.mjs';
 import { isQueuedEntryEditable } from '../../queue-helpers.mjs';
 
 // An attachment whose blob is gone is dropped alone; the prompt is kept.
-function hydrateTolerantly(pastedImages, pastedTexts, content = null) {
+export function hydrateTolerantly(pastedImages, pastedTexts, content = null) {
   let unreadable = 0;
   const onUnreadable = () => {
     unreadable += 1;
@@ -56,9 +57,13 @@ export function createAbortAction(bag) {
 
   // Pull the interrupted prompt back out of the transcript and history and
   // put its unsent requeue entries at the front of the queue.
-  const reclaimInFlightPrompt = (restoreState, { restoreText, requeueEntries, handoff = false }) => {
-    restoreState.reclaimed = true;
-    const idSet = new Set((restoreState.submittedIds || []).filter((id) => id != null));
+  // `keepPrompt` only requeues: the submitted rows stay in the transcript.
+  const reclaimInFlightPrompt = (
+    restoreState,
+    { restoreText, requeueEntries, handoff = false, keepPrompt = false }
+  ) => {
+    if (!keepPrompt) restoreState.reclaimed = true;
+    const idSet = new Set((keepPrompt ? [] : restoreState.submittedIds || []).filter((id) => id != null));
     const patch = { spinner: null, thinking: null, lastTurn: null };
     // Another device cancelled this turn: the prompt travels to the device that
     // sent it through the state, never through the canceller's reply.
@@ -124,14 +129,26 @@ export function createAbortAction(bag) {
     const canceller = typeof options?.device === 'string' ? options.device : '';
     const crossDevice = Boolean(canceller && restoreState?.device && canceller !== restoreState.device);
     const hasAttachments = Boolean(restoreState?.pastedImages || restoreState?.pastedTexts || restoreState?.content);
-    const canRestore =
+    const wantsRestore =
       options?.restorePrompt !== false &&
       restoreState?.restorable &&
       !hasPendingSteering &&
       !(crossDevice && hasAttachments);
+    // Hydrate BEFORE the turn is aborted or the prompt reclaimed: an attachment
+    // read error then cannot strand a prompt that left the transcript with no
+    // draft to land in. On failure the prompt is kept (like a Stop that hands
+    // nothing back) and the error is surfaced as the notice.
+    let restored = null;
+    let hydrateFailure = '';
+    if (wantsRestore) {
+      try {
+        restored = hydrateTolerantly(restoreState?.pastedImages, restoreState?.pastedTexts, restoreState?.content);
+      } catch (error) {
+        hydrateFailure = `Could not restore the attachments (${error?.message || error}); the prompt was kept.`;
+      }
+    }
+    const canRestore = wantsRestore && !hydrateFailure;
     const restoreText = canRestore ? restoreState.text : '';
-    const restorePastedImages = canRestore && restoreState?.pastedImages ? restoreState.pastedImages : null;
-    const restorePastedTexts = canRestore && restoreState?.pastedTexts ? restoreState.pastedTexts : null;
     // When steering suppresses the restore, the interrupted prompt's pasted
     // images never get committed (onCommitted won't fire) nor re-installed into
     // the draft, so hand them back for cleanup to avoid a stale `[Image #id]`
@@ -146,34 +163,51 @@ export function createAbortAction(bag) {
             (entry) => entry?.abortDiscardOnAbort !== true && entry?.mode !== 'pending-resume'
           )
         : [];
-    const aborted = abortGoalTurn(runtime, flags, hasPendingSteering, reason);
+    // A user Stop that hands the prompt back is rewound by the runtime (the
+    // prompt returns to the input box); one that does not keeps it in the
+    // stored transcript, as it stays in the visible one. A turn that already
+    // committed (output produced) needs neither.
+    const keepsPrompt = reason === 'user-cancel' && !canRestore && restoreState?.restorable && !restoreState.committed;
+    const aborted = abortGoalTurn(
+      runtime,
+      flags,
+      hasPendingSteering,
+      keepsPrompt ? USER_CANCEL_KEEP_PROMPT_REASON : reason
+    );
     if (restoreState) {
+      // A user Stop consumes this input even when no draft is requested.
+      // Explicit draft reclamation also releases it; automatic interruptions
+      // such as the watchdog must retain input that has not been committed.
+      if (aborted !== false && !restoreState.committed && (reason === 'user-cancel' || restoreText)) {
+        restoreState.onAborted?.();
+        restoreState.onAborted = null;
+      }
       if (aborted !== false && Array.isArray(restoreState.discardExecutionPendingResumeKeys)) {
         discardExecutionPendingResume?.(restoreState.discardExecutionPendingResumeKeys);
       }
       if ((restoreText || requeueEntries.length > 0) && aborted !== false) {
-        reclaimInFlightPrompt(restoreState, { restoreText, requeueEntries, handoff: crossDevice });
+        reclaimInFlightPrompt(restoreState, {
+          restoreText,
+          requeueEntries,
+          handoff: crossDevice,
+          keepPrompt: Boolean(hydrateFailure),
+        });
       }
       restoreState.restorable = false;
       restoreState.requeueEntries = [];
       restoreState.discardExecutionPendingResumeKeys = [];
     }
     kickDrainAfterAbort();
-    const restored = hydrateTolerantly(
-      restorePastedImages,
-      restorePastedTexts,
-      canRestore ? restoreState?.content : null
-    );
     // The canceller never receives another device's prompt.
     const handedOver = crossDevice && Boolean(restoreText) && aborted !== false;
     return {
       aborted,
       restoreText: handedOver ? '' : restoreText,
-      ...(restored.content ? { content: restored.content } : {}),
-      ...(restored.notice ? { notice: restored.notice } : {}),
-      pastedImages: restored.pastedImages,
+      ...(restored?.content ? { content: restored.content } : {}),
+      ...(restored?.notice || hydrateFailure ? { notice: restored?.notice || hydrateFailure } : {}),
+      pastedImages: restored?.pastedImages ?? null,
       discardPastedImages,
-      pastedTexts: restored.pastedTexts,
+      pastedTexts: restored?.pastedTexts ?? null,
       discardPastedTexts,
       restoredSubmissionIds:
         restoreText && !handedOver ? (restoreState?.submittedIds || []).map(String).filter(Boolean) : [],

package/src/tui/session/session-api/intake/rewind.mjs

@@ -1,13 +1,17 @@
 // Message selector ("jump back to a previous message"): rewind the
 // conversation to just before a user prompt and hand its text back for
 // editing. Idle-only — a live turn must be interrupted first.
+import { restorableAttachmentsFromPrompt } from '../../../../runtime/attachments/prompt-restore.mjs';
 import { promptHistoryWithout } from '../../prompt-history.mjs';
+import { hydrateTolerantly } from './abort.mjs';
 
 export function createRewindAction(bag) {
   const { runtime, getState, set, flushEmitImmediate, replaceItems, syncContextStats } = bag;
 
   return {
-    rewindToItem: async (itemId) => {
+    // `restoreFiles: false` is a composer that cannot hold PDF/Office file
+    // parts (the terminal one): a prompt carrying any is refused untouched.
+    rewindToItem: async (itemId, { restoreFiles = true } = {}) => {
       const target = String(itemId ?? '').trim();
       if (!target) return null;
       if (getState().busy || getState().commandBusy) return null;
@@ -19,8 +23,31 @@ export function createRewindAction(bag) {
       if (!text) return null;
       set({ commandBusy: true });
       try {
-        const rewound = await runtime.rewindMessages?.({ text });
-        if (!rewound) return null;
+        // Matched by the row's stable message id (the stored prompt is the
+        // expanded text); rows without one fall back to the text.
+        const messageId = String(items[index]?.messageId || '');
+        const rewindOptions = { text, ...(messageId ? { messageId } : {}) };
+        // Resolve the prompt and build the whole restore payload BEFORE any
+        // history changes: a refusal or an attachment read error then leaves the
+        // model history and the transcript both untouched.
+        const preview = await runtime.rewindMessages?.({ ...rewindOptions, dryRun: true });
+        if (!preview) return null;
+        // The stored prompt's attachment references become the restore payload
+        // the abort/queue restores use (pastedTexts / pastedImages / file parts).
+        const content = preview.message?.content;
+        if (!restoreFiles && Array.isArray(content) && content.some((part) => part?.type === 'file')) {
+          throw new Error(
+            'this message has PDF/Office attachments the terminal composer cannot restore; edit it in the desktop app'
+          );
+        }
+        const refs = restorableAttachmentsFromPrompt(content, text);
+        const attachments = hydrateTolerantly(refs.pastedImages, refs.pastedTexts, content);
+        // Refused when the history changed since the preview.
+        const rewound = await runtime.rewindMessages?.({
+          ...rewindOptions,
+          ...(preview.historyMarker ? { expectedHistoryMarker: preview.historyMarker } : {}),
+        });
+        if (!rewound) throw new Error('the conversation changed; select the message again');
         set({
           items: replaceItems(items.slice(0, index), {
             preserveSpill: true,
@@ -36,7 +63,15 @@ export function createRewindAction(bag) {
         syncContextStats({ allowEstimated: true });
         set({ stats: { ...getState().stats } });
         flushEmitImmediate?.();
-        return { text, removed: items.length - index, messages: rewound.removed };
+        return {
+          text,
+          removed: items.length - index,
+          messages: rewound.removed,
+          ...(attachments.pastedImages ? { pastedImages: attachments.pastedImages } : {}),
+          ...(attachments.pastedTexts ? { pastedTexts: attachments.pastedTexts } : {}),
+          ...(attachments.content ? { content: attachments.content } : {}),
+          ...(attachments.notice ? { notice: attachments.notice } : {}),
+        };
       } finally {
         set({ commandBusy: false });
       }

package/src/tui/session/session-api/media.mjs

@@ -119,7 +119,8 @@ export function createSessionMediaApi(bag) {
     // Media studio (image/video generation). Reads stay quiet, and there is no
     // notice on start either: the Studio surfaces progress on its own pending
     // tile, and a toast for a user-initiated generation is pure noise.
-    listMediaLanes: () => runtime.listMediaLanes?.(),
+    // `{ budgetMs }` bounds the per-lane catalog wait (Studio, Settings).
+    listMediaLanes: (options) => runtime.listMediaLanes?.(options),
     getMediaDefault: (kind) => runtime.getMediaDefault?.(kind),
     setMediaDefault: (input) => runtime.setMediaDefault?.(input),
     getMediaPins: () => runtime.getMediaPins?.(),

package/src/tui/session/session-api/routes-agent-definitions.mjs

@@ -0,0 +1,76 @@
+/**
+ * routes-agent-definitions.mjs — the session route surface's passthroughs to
+ * the runtime's agent, workflow-pack, connector and lead-identity services.
+ */
+export function createAgentDefinitionApi(runtime) {
+  return {
+    listAgents: () => {
+      return runtime.listAgents?.() || [];
+    },
+    listWorkflows: () => {
+      return runtime.listWorkflows?.() || [];
+    },
+    // Workflow pack editing (desktop Workflows page): direct passthroughs —
+    // the runtime owns validation, user-pack persistence, and delete guards.
+    getWorkflowPack: (workflowId) => runtime.getWorkflowPack?.(workflowId) ?? null,
+    saveWorkflowPack: async (payload) => runtime.saveWorkflowPack?.(payload) ?? null,
+    createWorkflow: async (payload) => runtime.createWorkflow?.(payload) ?? null,
+    deleteWorkflow: async (workflowId) => runtime.deleteWorkflow?.(workflowId) ?? null,
+    getAgentDefinition: (agentId) => runtime.getAgentDefinition?.(agentId) ?? null,
+    getAgentAvatarImage: (agentId) => runtime.getAgentAvatarImage?.(agentId) ?? null,
+    getAgentConnectors: (agentId) => runtime.getAgentConnectors?.(agentId) ?? [],
+    listConnectors: () => runtime.listConnectors?.() ?? [],
+    listConnectorTools: (connectorId) => runtime.listConnectorTools?.(connectorId) ?? [],
+    // `options.noWiden` is only ever added by the desktop's remote method table: the
+    // change is refused if it would give the agent more authority (checked atomically with the write).
+    setAgentConnectors: async (agentId, connectors, options) =>
+      runtime.setAgentConnectors?.(agentId, connectors, options) ?? null,
+    setAgentConnectorEnabled: async (agentId, connectorId, enabled, options) =>
+      runtime.setAgentConnectorEnabled?.(agentId, connectorId, enabled, options) ?? [],
+    getProjectConnectors: (projectPath) => runtime.getProjectConnectors?.(projectPath) ?? [],
+    setProjectConnectorEnabled: async (projectPath, connectorId, enabled, options) =>
+      runtime.setProjectConnectorEnabled?.(projectPath, connectorId, enabled, options) ?? [],
+    setAgentConnectorToolPermission: async (agentId, connectorId, toolName, permission, options) =>
+      runtime.setAgentConnectorToolPermission?.(agentId, connectorId, toolName, permission, options) ?? null,
+    getAgentAlwaysAllowedTools: (agentId) => runtime.getAgentAlwaysAllowedTools?.(agentId) ?? [],
+    // Per-agent action-kind permissions (ask / allow / block) for the profile.
+    getAgentPermissions: async (agentId) =>
+      (await import('../../../runtime/agent/orchestrator/session/human-gate/store.mjs')).agentPermissions(agentId),
+    setAgentPermission: async (agentId, action, mode, options) =>
+      (await import('../../../runtime/agent/orchestrator/session/human-gate/store.mjs')).setAgentPermission(
+        agentId,
+        action,
+        mode,
+        options
+      ),
+    recordAgentApprovalAudit: async (agentId, action, decision) =>
+      (await import('../../../runtime/agent/orchestrator/session/human-gate/store.mjs')).recordAgentApprovalAudit(
+        agentId,
+        action,
+        decision
+      ),
+    getLeadPersona: () => runtime.getLeadPersona?.() ?? '',
+    saveLeadPersona: async (text) => runtime.saveLeadPersona?.(text) ?? '',
+    getLeadAgentBody: () => runtime.getLeadAgentBody?.() ?? '',
+    saveLeadAgentBody: async (text) => runtime.saveLeadAgentBody?.(text) ?? '',
+    getLeadStatus: () =>
+      runtime.getLeadStatus?.() ?? { created: null, name: '', avatar: null, homeChatted: false, route: null },
+    getLeadHomeRoute: () => runtime.getLeadHomeRoute?.() ?? null,
+    saveLeadIdentity: async (payload) => runtime.saveLeadIdentity?.(payload) ?? null,
+    setLeadCreated: async (created, description) => runtime.setLeadCreated?.(created, description) ?? null,
+    saveAgentDefinition: async (payload, options) => runtime.saveAgentDefinition?.(payload, options) ?? null,
+    deleteAgentDefinition: async (agentId) => runtime.deleteAgentDefinition?.(agentId) ?? null,
+    agentDefinitionPresence: (agentIds) => runtime.agentDefinitionPresence?.(agentIds) ?? null,
+    restoreAgentDefinition: async (agentId) => runtime.restoreAgentDefinition?.(agentId) ?? null,
+    purgeAgentDefinition: async (agentId) => runtime.purgeAgentDefinition?.(agentId) ?? null,
+    archivedAgentIdentities: (agentIds) => runtime.archivedAgentIdentities?.(agentIds) ?? null,
+    // Group-room rows posted by the desktop host into a room's log session.
+    appendRoomRows: async (sessionId, rows) =>
+      (await import('../../../session-runtime/agent-room-delivery.mjs')).appendRoomRows(sessionId, rows),
+    // One group-room supervisor step on the Maintainer route.
+    decideRoomTurn: async (input) =>
+      (await import('../../../runtime/agent/orchestrator/agent-runtime/room-supervisor-completion.mjs')).decideRoomTurn(
+        input
+      ),
+  };
+}

package/src/tui/session/session-api/routes-write.mjs

@@ -0,0 +1,203 @@
+/**
+ * routes-write.mjs — the serialized, optimistic route write behind the
+ * session's setRoute (every model picker, presets, agent child routes).
+ */
+import { modelSwitchItem } from '../../../runtime/agent/orchestrator/session/transcript-restore/restore.mjs';
+import { selectedModel } from '../../../session-runtime/model-route/model-switch-target.mjs';
+
+// Optimistic route preview: the requested provider/model/effort/fast are
+// published before the runtime write settles. What is NOT previewed about the
+// route (effort options, Fast capability, context window) is provider
+// metadata the runtime resolves while the preview is already on screen.
+const ROUTE_PREVIEW_KEYS = [
+  'provider',
+  'model',
+  'effort',
+  'fast',
+  'autoEffort',
+  'modelParameters',
+  'contextPercent',
+  'contextTokens',
+];
+
+/**
+ * The patch that publishes a requested route before the runtime write settles.
+ * Returns null when the request carries nothing previewable.
+ */
+function optimisticRoutePatch(requested = {}, current = {}) {
+  const route = requested && typeof requested === 'object' ? requested : {};
+  const has = (key) => Object.hasOwn(route, key);
+  const patch = {};
+  for (const key of ROUTE_PREVIEW_KEYS) {
+    if (has(key)) patch[key] = route[key];
+  }
+  if (!has('provider') && !has('model')) {
+    return Object.keys(patch).length > 0 ? patch : null;
+  }
+  const sameModel =
+    String(patch.provider ?? current.provider ?? '') === String(current.provider ?? '') &&
+    String(patch.model ?? current.model ?? '') === String(current.model ?? '');
+  // A different model carries none of the previous model's tuning: an omitted
+  // key means "this model has no such control", not "keep the old value".
+  if (!sameModel) {
+    if (!has('effort')) patch.effort = null;
+    if (!has('fast')) patch.fast = false;
+    if (!has('modelParameters')) patch.modelParameters = {};
+  }
+  return patch;
+}
+
+const SESSION_ONLY_KEYS = new Set(['provider', 'model', 'effort', 'fast', 'autoEffort']);
+
+/**
+ * A session-only request (an agent child's route) may name just the model, just
+ * the tuning, or both. Completed here, inside the serialized route write,
+ * against the latest selected route — so a Fast-only change keeps the effort a
+ * previous write selected. `unchanged` when it asks for nothing the selected
+ * route does not already have.
+ */
+function completeSessionOnlyRequest(request, selected) {
+  const named = Boolean(request.provider || request.model);
+  const target = named ? request : { ...request, provider: selected.provider, model: selected.model };
+  const sameModel = target.provider === selected.provider && target.model === selected.model;
+  if (!sameModel) return { request: target, unchanged: false };
+  const unchanged =
+    Object.keys(request).every((key) => SESSION_ONLY_KEYS.has(key)) &&
+    (request.effort === undefined || request.effort === selected.effort) &&
+    (request.fast === undefined || request.fast === (selected.fast === true)) &&
+    (request.autoEffort === undefined || request.autoEffort === (selected.autoEffort !== false));
+  return {
+    unchanged,
+    request: {
+      ...(selected.effort ? { effort: selected.effort } : {}),
+      fast: selected.fast === true,
+      autoEffort: selected.autoEffort !== false,
+      ...target,
+    },
+  };
+}
+
+/** The live divider of an in-place model switch (restored from message meta
+ *  after a reload); every switch path publishes it the same way. */
+export function publishModelSwitch(bag, modelSwitch) {
+  if (modelSwitch) bag.pushItem(modelSwitchItem(bag.nextId(), modelSwitch));
+}
+
+export function createRouteWrite(
+  bag,
+  { runtime, getState, set, flushEmitImmediate, routeState, syncContextStats, publishRoute }
+) {
+  let routeWrite = null;
+  let routeSequence = 0;
+  // Whether this API (not another command) is the one holding commandBusy.
+  let routeLocked = false;
+
+  // A preset selector previews as the preset's model, never as its id.
+  const previewedRequest = (routeOpts) => {
+    if (routeOpts.provider || !routeOpts.model) return routeOpts;
+    const target = selectedModel(runtime, routeOpts, '', '');
+    return target.provider ? { ...routeOpts, ...target } : routeOpts;
+  };
+
+  const setRoute = async (opts) => {
+    const routeOpts = opts && typeof opts === 'object' ? opts : {};
+    // All model pickers save a selection for the conversation's next turn; a
+    // running turn keeps the session model it started on. A selection is never
+    // refused: another command's lock neither blocks it nor is released by it.
+    const token = ++routeSequence;
+    const previousWrite = routeWrite;
+    // The session generation this selection was made under. The write below
+    // waits behind earlier ones, so "current" is never read later: the runtime
+    // validates this token before every route side effect, and `settle` below
+    // is the only place the display is touched once the write has started.
+    const originGeneration = runtime.sessionGeneration;
+    const owned = () => runtime.sessionGeneration === originGeneration;
+    // A conditional fill (only when the route is still empty) may not apply, so
+    // it never previews: the runtime's answer is what gets published.
+    const onlyIfEmpty = routeOpts.onlyIfEmpty === true;
+    const preview = onlyIfEmpty ? null : optimisticRoutePatch(previewedRequest(routeOpts), getState());
+    // Preview immediately, serialize persistence without dropping a later
+    // click. Earlier completions cannot replace the newest visible choice.
+    if (!getState().commandBusy) routeLocked = true;
+    set({ ...(routeLocked ? { commandBusy: true } : {}), ...(preview || {}) });
+    flushEmitImmediate();
+    const write = (async () => {
+      if (previousWrite) await previousWrite.catch(() => {});
+      const previousRoute = routeState();
+      // A stale selection only republishes the route that is actually
+      // selected; it never restores or announces its own session's state.
+      const settle = ({ failed = false, sync = false, modelSwitch = null } = {}) => {
+        const stillOwned = owned();
+        if (stillOwned) publishModelSwitch(bag, modelSwitch);
+        // A newer selection publishes the final route itself.
+        if (token !== routeSequence) return;
+        if (stillOwned && failed) {
+          if (preview) set({ ...previousRoute, stats: { ...getState().stats } });
+          return;
+        }
+        if (stillOwned && sync) syncContextStats({ allowEstimated: true });
+        publishRoute();
+      };
+      try {
+        // Keep the durable session address while deferring route application.
+        const applyToCurrentSession = routeOpts.applyToCurrentSession === true;
+        const keepMainModel = routeOpts.keepMainModel !== false;
+        const sessionOnly = routeOpts.sessionOnly === true;
+        const {
+          applyToCurrentSession: _drop,
+          keepMainModel: _keep,
+          sessionOnly: _scope,
+          onlyIfEmpty: _fill,
+          ...requested
+        } = routeOpts;
+        let nextRoute = requested;
+        if (sessionOnly) {
+          const completed = completeSessionOnlyRequest(requested, previousRoute);
+          if (completed.unchanged) {
+            // An earlier failed write skipped its rollback because this one is
+            // newer, so the shown route may still be that write's preview.
+            settle();
+            return previousRoute;
+          }
+          nextRoute = completed.request;
+        }
+        const resolvedRoute = await runtime.setRoute(nextRoute, {
+          applyToCurrentSession,
+          keepMainModel,
+          ...(sessionOnly ? { sessionOnly } : {}),
+          ...(onlyIfEmpty ? { onlyIfEmpty } : {}),
+          ...(originGeneration !== undefined ? { originGeneration } : {}),
+          switchEstablished: true,
+          deferUntilNextTurn: true,
+        });
+        settle({
+          sync: applyToCurrentSession || Boolean(resolvedRoute?.modelSwitch),
+          modelSwitch: resolvedRoute?.modelSwitch,
+        });
+        return resolvedRoute;
+      } catch (error) {
+        settle({ failed: true });
+        throw error;
+      } finally {
+        if (token === routeSequence) {
+          if (routeLocked) set({ commandBusy: false });
+          routeLocked = false;
+          // Publish the resolved route (or rollback) before an RPC reply
+          // reads getState(), even while the display-frame clock is busy.
+          flushEmitImmediate();
+        }
+      }
+    })();
+    routeWrite = write;
+    try {
+      return await write;
+    } finally {
+      if (routeWrite === write) routeWrite = null;
+    }
+  };
+  // The settings surface's setModel (/model, presets) is the same user
+  // model choice and runs through this one path.
+  bag.setSessionRoute = setRoute;
+
+  return setRoute;
+}