mixdog 1.1.1 → 1.2.0

package/src/session-runtime/setup-tool/executor.mjs

@@ -30,6 +30,7 @@ const PROFILE_VALUE_IDS = Object.freeze({
 const ACTION_APPLIES_TO = {
   set_recap_enabled: 'background Memory cycles; no restart required',
   set_auto_update: 'subsequent automatic update checks',
+  set_worktree_settings: 'new tasks and worktrees created afterwards; existing worktrees are unchanged',
   set_system_shell: 'subsequent shell calls',
   save_automation: 'the automation worker; scheduled runs follow the saved timing',
   delete_automation: 'future automation runs',
@@ -93,6 +94,7 @@ function routeInput(source) {
   if (typeof source.fast === 'boolean') next.fast = source.fast;
   if (Object.hasOwn(source, 'modelParameters')) next.modelParameters = { ...source.modelParameters };
   if (Object.hasOwn(source, 'contextPercent')) next.contextPercent = source.contextPercent;
+  if (Object.hasOwn(source, 'contextTokens')) next.contextTokens = source.contextTokens;
   if (Object.hasOwn(source, 'disabled')) next.disabled = source.disabled;
   return next;
 }
@@ -178,6 +180,7 @@ const mainRoute = (rt) => ({
   fastCapable: rt.fastCapable === true,
   modelParameters: rt.modelParameters || {},
   contextPercent: rt.contextPercent ?? null,
+  contextTokens: rt.contextTokens ?? null,
 });
 
 async function automationStatus(rt, { domain }) {
@@ -303,6 +306,7 @@ const SETUP_STATUS_READERS = {
   plugins: (rt) => rt.pluginsStatus?.() || {},
   update: (rt) => rt.getUpdateSettings?.() || {},
   onboarding: (rt) => rt.getOnboardingStatus?.() || {},
+  worktree: (rt) => rt.getWorktreeSettings(),
   schedules: automationStatus,
   webhooks: automationStatus,
   hooks: hookStatus,
@@ -328,11 +332,13 @@ function validateSetupInput(args) {
     if (action !== 'set_agent_route' && Object.hasOwn(args.route, 'disabled')) {
       throw new Error('route.disabled is only accepted by set_agent_route');
     }
-    if (action !== 'set_route' && action !== 'set_agent_route' && Object.hasOwn(args.route, 'contextPercent')) {
-      throw new Error('route.contextPercent is only accepted by set_route and set_agent_route');
+    for (const field of ['contextPercent', 'contextTokens']) {
+      if (action !== 'set_route' && action !== 'set_agent_route' && Object.hasOwn(args.route, field)) {
+        throw new Error(`route.${field} is only accepted by set_route and set_agent_route`);
+      }
     }
   }
-  for (const field of ['desktop', 'appearance', 'webhook', 'compaction', 'providerAccount']) {
+  for (const field of ['desktop', 'appearance', 'webhook', 'compaction', 'providerAccount', 'worktree']) {
     if (args[field] && !Object.keys(args[field]).length) throw new Error(`${field} requires at least one setting`);
   }
   return action;
@@ -507,6 +513,7 @@ const SETUP_ACTION_HANDLERS = {
     rt.deleteLocalProviderModel(requireText(args.confirmationToken, 'confirmationToken')),
   set_system_shell: (rt, args) => rt.setSystemShell({ command: clean(args.command) }),
   set_auto_update: (rt, args) => rt.setAutoUpdate(requireBoolean(args.enabled)),
+  set_worktree_settings: (rt, args) => rt.setWorktreeSettings(args.worktree),
   forget_provider_auth: async (rt, args) => {
     const name = requireText(args.name, 'name');
     const setup = await rt.getProviderSetup({});
@@ -541,7 +548,7 @@ const SETUP_ACTION_HANDLERS = {
   set_mcp_enabled: async (rt, args) => ({
     mcp: mcpRows(await rt.setMcpServerEnabled(requireText(args.name, 'name'), requireBoolean(args.enabled))),
   }),
-  reconnect_mcp: async (rt) => ({ mcp: mcpRows(await rt.reconnectMcp()) }),
+  reconnect_mcp: async (rt, args) => ({ mcp: mcpRows(await rt.reconnectMcp(clean(args.name) || undefined)) }),
   set_disabled_skills: (rt, args) => {
     if (!Array.isArray(args.skills)) throw new Error('skills (array of names) is required');
     return rt.setDisabledSkills(args.skills.map(clean).filter(Boolean));

package/src/session-runtime/setup-tool/settings-contract.mjs

@@ -108,6 +108,8 @@ export const SETUP_MCP_SCHEMA = object({
     additionalProperties: removableText,
     description: 'HTTP header names mapped to existing environment variable names.',
   },
+  startupTimeoutSec: { type: 'number', description: 'Connect/handshake timeout in seconds (>0, default 30).' },
+  toolTimeoutSec: { type: 'number', description: 'Per tool-call timeout in seconds (>0, default 120).' },
 });
 
 export const SETUP_EXTENDED_PROPERTIES = Object.freeze({
@@ -158,7 +160,7 @@ export const SETUP_EXTENDED_PROPERTIES = Object.freeze({
       model: {
         ...text,
         description:
-          'Required for new schedules; no default-model fallback. Use provider/model[@effort][+fast][?parameter=value] or an existing preset name. On overwrite, omission preserves the saved model, which must be non-empty.',
+          'Required for new schedules; no default-model fallback. Use provider/model[@effort][+fast][+noauto][?parameter=value] (+noauto: Auto reasoning off; absent = on) or an existing preset name. On overwrite, omission preserves the saved model, which must be non-empty.',
       },
       cwd: text,
       workflow: text,

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

@@ -6,6 +6,7 @@ import {
 } from './settings-contract.mjs';
 import { MEDIA_KINDS } from '../../runtime/media/tool-defs.mjs';
 import { INSTRUCTION_FILES_MODES } from '../../runtime/shared/instruction-files-mode.mjs';
+import { WORKTREE_NEW_TASK_DEFAULTS } from '../../runtime/shared/worktrees/settings.mjs';
 
 /** Built-in `setup` tool: the model's handle on a Mixdog user's persisted
  *  configuration. The description is a contract only; how to use each action
@@ -31,6 +32,7 @@ export const SETUP_STATUS_DOMAINS = Object.freeze([
   'plugins',
   'update',
   'onboarding',
+  'worktree',
   ...SETUP_EXTENDED_DOMAINS,
 ]);
 
@@ -100,7 +102,7 @@ export const SETUP_ACTION_FIELDS = Object.freeze({
   save_mcp_server: 'server',
   remove_mcp_server: 'name',
   set_mcp_enabled: 'name enabled',
-  reconnect_mcp: '',
+  reconnect_mcp: 'name?',
   set_disabled_skills: 'skills',
   set_extension_scope: 'kind name projects',
   add_plugin: 'source',
@@ -108,6 +110,7 @@ export const SETUP_ACTION_FIELDS = Object.freeze({
   set_plugin_enabled: 'name enabled',
   remove_plugin: 'name',
   enable_plugin_mcp: 'name',
+  set_worktree_settings: 'worktree',
   ...SETUP_EXTENDED_ACTION_FIELDS,
 });
 
@@ -122,6 +125,7 @@ export const SETUP_BUILTIN_TOGGLE_FEATURES = Object.freeze([
   'browser',
   'computer',
   'voice',
+  'visualize',
 ]);
 
 const ROUTE_SCHEMA = {
@@ -136,6 +140,11 @@ const ROUTE_SCHEMA = {
     // A typed enum is unrepresentable on Gemini; the bounds project everywhere
     // and the executor rejects values that are not a multiple of 10.
     contextPercent: { type: 'integer', minimum: 10, maximum: 100, description: 'A multiple of 10.' },
+    contextTokens: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Exact context window in tokens; overrides contextPercent, clamped to 10%-100% of the model window.',
+    },
     disabled: {
       type: 'boolean',
       description: 'Agent routes only: true disables without losing the route; false re-enables.',
@@ -176,7 +185,7 @@ export const SETUP_TOOL_DEFS = Object.freeze([
         route: {
           ...ROUTE_SCHEMA,
           description:
-            'Partial route update; omitted fields are preserved. Agent or Web Search provider "" restores Main inheritance. contextPercent applies to Main and agent routes only.',
+            'Partial route update; omitted fields are preserved. Agent or Web Search provider "" restores Main inheritance. contextPercent and contextTokens apply to Main and agent routes only.',
         },
         agent: { type: 'string', description: 'set_agent_route: agent id.' },
         workflow: { type: 'string', description: 'set_workflow: pack id.' },
@@ -222,7 +231,7 @@ export const SETUP_TOOL_DEFS = Object.freeze([
         },
         name: {
           type: 'string',
-          description: `set_builtin_enabled: ${SETUP_BUILTIN_TOGGLE_FEATURES.join('|')}; install_builtin also accepts memory. Memory toggles use set_memory_enabled. revoke_linked_device: client id from status connection, not its display name; set_developer_option: option id from status developer; read_definition/delete_definition: the definition id; else MCP/plugin/provider id.`,
+          description: `set_builtin_enabled: ${SETUP_BUILTIN_TOGGLE_FEATURES.join('|')}; install_builtin also accepts memory. Memory toggles use set_memory_enabled. revoke_linked_device: client id from status connection, not its display name; set_developer_option: option id from status developer; read_definition/delete_definition: the definition id; reconnect_mcp: optional MCP server name (omit for all); else MCP/plugin/provider id.`,
         },
         accountId: {
           type: 'string',
@@ -320,6 +329,25 @@ export const SETUP_TOOL_DEFS = Object.freeze([
           items: { type: 'string', minLength: 1, pattern: '\\S' },
           description: 'set_extension_scope: required project roots; [] = every project.',
         },
+        worktree: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            newTaskDefault: {
+              type: 'string',
+              enum: [...WORKTREE_NEW_TASK_DEFAULTS],
+              description: 'branch = new tasks use the current branch (default); worktree = a new worktree.',
+            },
+            branchPrefix: { type: 'string', description: 'Ref prefix ending with "/"; default "mixdog/".' },
+            sizeWarnBytes: {
+              type: 'integer',
+              minimum: 0,
+              description: 'Repository size that asks for confirmation first; 0 never asks.',
+            },
+            autoCleanup: { type: 'boolean', description: 'Remove clean, merged worktrees when their task ends.' },
+          },
+          description: 'set_worktree_settings: only the given fields change.',
+        },
         ...SETUP_EXTENDED_PROPERTIES,
       },
     },

package/src/session-runtime/starter-guide-state.mjs

@@ -0,0 +1,62 @@
+// The desktop "Getting started" guide state, kept in the config beside the
+// onboarding flags (`onboarding.starterGuide`) so it outlives the renderer's
+// localStorage. The desktop IPC gate (ipc-validation.ts) mirrors the schema.
+export const STARTER_GUIDE_STEPS = Object.freeze(['provider', 'project', 'workflow', 'extensions', 'remote']);
+const STARTER_GUIDE_KEYS = new Set(['closed', 'welcomed', 'visited']);
+
+const plainObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+/** The guide state of a user who has not answered it yet. */
+export function freshStarterGuide() {
+  return { closed: false, welcomed: false, visited: [] };
+}
+
+/** The stored copy, read tolerantly; null when there is none. */
+export function storedStarterGuide(value) {
+  if (!plainObject(value)) return null;
+  const visited = Array.isArray(value.visited) ? value.visited : [];
+  return {
+    closed: value.closed === true,
+    welcomed: value.welcomed === true,
+    visited: STARTER_GUIDE_STEPS.filter((step) => visited.includes(step)),
+  };
+}
+
+/** A save request, read strictly: anything off-schema is rejected, never coerced. */
+export function requiredStarterGuideState(value) {
+  if (!plainObject(value)) throw new TypeError('starter guide state must be an object.');
+  for (const key of Object.keys(value)) {
+    if (!STARTER_GUIDE_KEYS.has(key)) throw new TypeError(`starter guide state has an unknown field: ${key}.`);
+  }
+  if (typeof value.closed !== 'boolean' || typeof value.welcomed !== 'boolean') {
+    throw new TypeError('starter guide closed and welcomed must be booleans.');
+  }
+  if (
+    !Array.isArray(value.visited) ||
+    value.visited.length > STARTER_GUIDE_STEPS.length * 2 ||
+    value.visited.some((step) => !STARTER_GUIDE_STEPS.includes(step))
+  ) {
+    throw new TypeError('starter guide visited must list known steps.');
+  }
+  return storedStarterGuide(value);
+}
+
+/** Every field only moves forward: a stale save can add, never undo. */
+export function mergeStarterGuide(stored, next) {
+  const base = stored || freshStarterGuide();
+  return {
+    closed: base.closed || next.closed,
+    welcomed: base.welcomed || next.welcomed,
+    visited: STARTER_GUIDE_STEPS.filter((step) => base.visited.includes(step) || next.visited.includes(step)),
+  };
+}
+
+/**
+ * The onboarding section after a completion: a first completion starts the
+ * guide fresh, so an absent copy afterwards means a profile onboarded before
+ * the guide was persisted here.
+ */
+export function withStarterGuideOnCompletion(previous, onboarding) {
+  if (previous?.completed === true || storedStarterGuide(previous?.starterGuide)) return onboarding;
+  return { ...onboarding, starterGuide: freshStarterGuide() };
+}

package/src/session-runtime/turn/agent-ops.mjs

@@ -56,6 +56,17 @@ export function createAgentOps(deps) {
     });
   }
 
+  // Stop one background shell job of THIS session through the task tool's
+  // cancel path; the answer is structured so a surface never parses text.
+  async function stopShellJob(taskId) {
+    const session = getSession();
+    const { stopBackgroundShellJob } = await import('../../runtime/agent/orchestrator/tools/builtin/task-tool.mjs');
+    return stopBackgroundShellJob(taskId, {
+      callerSessionId: session?.id || null,
+      clientHostPid: session?.clientHostPid || process.pid,
+    });
+  }
+
   function onNotification(listener) {
     if (typeof listener !== 'function') return () => {};
     const sessionId = getSession()?.id || getReservedSessionId?.() || '';
@@ -94,5 +105,5 @@ export function createAgentOps(deps) {
     return { ...result, status: toolsStatus() };
   }
 
-  return { agentControl, taskControl, onNotification, toolsStatus, selectTools };
+  return { agentControl, taskControl, stopShellJob, onNotification, toolsStatus, selectTools };
 }

package/src/session-runtime/turn/turn-run/ask-callbacks.mjs

@@ -55,18 +55,28 @@ export function createAskCallbacks({ transcript, notifyFnForSession, scheduleSea
     };
   }
 
+  // The turn's change-record key rides the caller's transcript metadata (in
+  // place: the stream stamps assistantAt on this same object), so the
+  // persisted user row and completion carry it across restore.
+  function stampCheckpoint(options) {
+    const meta = options.transcriptMeta;
+    const checkpointId = String(options.id || '').trim();
+    if (checkpointId && meta && typeof meta === 'object') meta.checkpointId = checkpointId;
+    return meta;
+  }
+
   function askCallbacks(turn, session0, options) {
     return {
       beforeToolExecution: () => turn.snapshot.promise || Promise.resolve(),
-      transcriptMeta: options.transcriptMeta,
+      transcriptMeta: stampCheckpoint(options),
       promptSource: options.promptSource,
       retryFailedTurn: options.retryFailedTurn === true,
       onTextDelta: options.onTextDelta,
       onTextReset: options.onTextReset,
       onReasoningDelta: options.onReasoningDelta,
-      onAssistantText: (text) => {
+      onAssistantText: (text, detail) => {
         transcript.appendAssistantText(text);
-        return options.onAssistantText?.(text);
+        return options.onAssistantText?.(text, detail);
       },
       onUsageDelta: options.onUsageDelta,
       onAssistantToolCallObserved: options.onAssistantToolCallObserved,

package/src/session-runtime/turn/turn-run/snapshot-tracker.mjs

@@ -1,25 +1,21 @@
 import { settleWithin } from '../../../runtime/shared/abort-race.mjs';
 
-// Worktree snapshot for the turn review. Captured immediately, but never on
-// the first-token critical path: every actual tool execution joins the same
-// promise, so shell/apply_patch cannot mutate the worktree before the baseline.
+// Worktree snapshot for the turn review. Captured as soon as the turn's
+// workspace is final (after any lazy worktree provisioning, so the baseline is
+// taken in the root the turn runs in), but never on the first-token critical
+// path: every actual tool execution joins the same promise, so
+// shell/apply_patch cannot mutate the worktree before the baseline.
 export function createSnapshotTrackerFactory({
   getCurrentCwd,
   beginTurnSnapshotForTurn,
-  cancelTurnSnapshotForTurn,
   completeTurnSnapshotForTurn,
   turnCleanupSettleMs,
 }) {
   return function createSnapshotTracker(options) {
+    // `promise` resolves to the turn token beginTurnSnapshot returns
+    // (`{ generation, checkpointId }`), or undefined when nothing began.
     const tracker = { sessionId: null, promise: null };
-    // A completion wake continues the user turn whose review already exists;
-    // aborting the wake seals that review instead of discarding it.
     const continueTurn = options.continueTurn === true;
-    const cancel = () => {
-      try {
-        cancelTurnSnapshotForTurn(tracker.sessionId);
-      } catch {}
-    };
     tracker.start = (sessionId) => {
       const id = typeof sessionId === 'string' ? sessionId.trim() : '';
       if (!id || (tracker.promise && tracker.sessionId === id)) return;
@@ -36,19 +32,28 @@ export function createSnapshotTrackerFactory({
         .catch(() => undefined);
     };
     tracker.finish = async (signal, awaitTurn) => {
+      // A turn refused before its workspace was final never began a review.
+      if (!tracker.promise) return;
+      // Captured now: a later start (or the next turn) cannot redirect this seal.
+      const sessionId = tracker.sessionId;
+      const started = Promise.resolve(tracker.promise);
       if (signal.aborted && !continueTurn) {
-        cancel();
-        void Promise.resolve(tracker.promise).catch(() => {});
+        // A cancelled turn keeps its edits as a change record. Sealing waits
+        // for the snapshot start, never for the abort's settlement, and only
+        // seals the generation this turn began: delayed cleanup cannot seal
+        // a newer turn.
+        void started
+          .then((token) => (token ? completeTurnSnapshotForTurn(sessionId, token) : undefined))
+          .catch(() => {});
         return;
       }
-      const cleanup = Promise.resolve(tracker.promise).then(() => completeTurnSnapshotForTurn(tracker.sessionId));
+      const cleanup = started.then((token) => completeTurnSnapshotForTurn(sessionId, token));
       cleanup.catch(() => {});
       try {
         await awaitTurn(() => settleWithin(cleanup, turnCleanupSettleMs));
       } catch {
         /* optional review cleanup never overrides turn settlement */
       }
-      if (signal.aborted && !continueTurn) cancel();
     };
     return tracker;
   };

package/src/session-runtime/turn/turn-run/turn-open.mjs

@@ -1,13 +1,11 @@
 import { runAbortable } from '../../../runtime/shared/abort-race.mjs';
 
 // Opens one turn: abort controller registration, timing, the worktree
-// snapshot tracker, the active-turn count and the one-shot heavy-runtime
-// warmup arm.
+// snapshot tracker (started by session preparation once the turn's workspace
+// is final), the active-turn count and the one-shot heavy-runtime warmup arm.
 export function createTurnOpener({
   createTiming,
   createSnapshot,
-  getSession,
-  getReservedSessionId,
   registerActiveTurnController,
   getActiveTurnCount,
   setActiveTurnCount,
@@ -41,7 +39,6 @@ export function createTurnOpener({
     const signal = controller.signal;
     const snapshot = createSnapshot(options);
     const routeStartedAt = performance.now();
-    snapshot.start(getSession()?.id || getReservedSessionId?.());
     setActiveTurnCount(getActiveTurnCount() + 1);
     return {
       signal,
@@ -54,6 +51,8 @@ export function createTurnOpener({
       armHeavyRuntimeWarmup: heavyRuntimeWarmupArm(),
       session0: null,
       releaseFirstTitle: null,
+      /** Set by turn admission (admitTurnWorkspace); released by settleTurn. */
+      releaseWorkspace: null,
       startedAt: Date.now(),
     };
   };

package/src/session-runtime/turn/turn-run/turn-prepare.mjs

@@ -21,6 +21,8 @@ export function createTurnPreparation({
   agentTool,
   getConfig,
   assertSessionAdmission,
+  prepareTurnWorkspace,
+  admitTurnWorkspace,
 }) {
   const scopedMcpTools = (session) => scopedMcpToolsFor(session, getConfig());
 
@@ -84,7 +86,7 @@ export function createTurnPreparation({
   // Historical-session resume publishes its transcript immediately while
   // provider/model metadata initializes in the background. Only the next
   // actual turn waits, guaranteeing that it cannot run on a stale route.
-  async function prepareSession(turn, prompt) {
+  async function prepareSession(turn, prompt, options = {}) {
     // A closing/closed addressed runtime admits no turn (checked again after
     // every await that could have outlived a close).
     assertSessionAdmission?.();
@@ -96,6 +98,32 @@ export function createTurnPreparation({
     }
     throwIfAborted(turn.signal);
     assertSessionAdmission?.();
+    // Turn admission: waits while this session's workspace transitions or
+    // another session changes the checkout this session works in, then holds
+    // the turn registered (released by settleTurn) so no checkout changes
+    // under it.
+    if (typeof admitTurnWorkspace === 'function') {
+      turn.releaseWorkspace = await admitTurnWorkspace({ signal: turn.signal });
+      throwIfAborted(turn.signal);
+      assertSessionAdmission?.();
+    }
+    // Workspace gate: a session in recovery refuses the turn, and a pending
+    // worktree intent is provisioned and applied (cwd, record, prompt context)
+    // BEFORE the user row, the review snapshot, hooks, the provider and any
+    // worker spawn. The submission id is the provisioning transaction id, so a
+    // retried or duplicate send reuses the same worktree.
+    if (typeof prepareTurnWorkspace === 'function') {
+      await turn.awaitTurn(() =>
+        prepareTurnWorkspace({
+          submissionId: String(options.id || '').trim(),
+          prompt,
+          signal: turn.signal,
+          confirmLarge: options.confirmLarge === true,
+        })
+      );
+      throwIfAborted(turn.signal);
+      assertSessionAdmission?.();
+    }
     ensureSessionTranscriptWriter?.();
     transcript.appendUser(prompt);
     const session0 = getSession();

package/src/session-runtime/turn/turn-run/turn-settle.mjs

@@ -84,7 +84,12 @@ export function createTurnSettlement({
     turn.releaseFirstTitle?.();
     turn.emitTiming(turn.timing.status);
     turn.armHeavyRuntimeWarmup('turn-settled');
-    await turn.snapshot.finish(turn.signal, turn.awaitTurn);
+    try {
+      await turn.snapshot.finish(turn.signal, turn.awaitTurn);
+    } finally {
+      // The turn no longer works in its checkout: transitions may proceed.
+      turn.releaseWorkspace?.();
+    }
     try {
       turn.unregister?.();
     } catch {}

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

@@ -1,10 +1,11 @@
 /**
  * src/session-runtime/turn/turn-run.mjs - one user turn end to end: viewer
- * forwarding, turn open (abort controller, timing, worktree snapshot, warmup
- * arming), session preparation, the askSession callback bridge, and the
- * settlement that always runs. The phases live under turn-run/.
+ * forwarding, turn open (abort controller, timing, warmup arming), session
+ * preparation (workspace provisioning, then the worktree review snapshot), the
+ * askSession callback bridge, and the settlement that always runs. The phases
+ * live under turn-run/.
  */
-import { beginTurnSnapshot, cancelTurnSnapshot, completeTurnSnapshot } from '../../runtime/shared/turn-snapshot.mjs';
+import { beginTurnSnapshot, completeTurnSnapshot } from '../../runtime/shared/turn-snapshot.mjs';
 import { runWithCwdOverride } from '../../runtime/shared/user-cwd.mjs';
 import { createTurnTranscript } from './turn-run/transcript.mjs';
 import { createTurnTimingFactory } from './turn-run/turn-timing.mjs';
@@ -23,7 +24,6 @@ export function createTurnRunner(deps) {
     endComputerExecution = async () => false,
     deferComputerSessionRelease = () => false,
     beginTurnSnapshotForTurn = beginTurnSnapshot,
-    cancelTurnSnapshotForTurn = cancelTurnSnapshot,
     completeTurnSnapshotForTurn = completeTurnSnapshot,
     turnCleanupSettleMs = 2_000,
     getConfig = () => null,
@@ -35,7 +35,6 @@ export function createTurnRunner(deps) {
     createSnapshot: createSnapshotTrackerFactory({
       getCurrentCwd,
       beginTurnSnapshotForTurn,
-      cancelTurnSnapshotForTurn,
       completeTurnSnapshotForTurn,
       turnCleanupSettleMs,
     }),
@@ -93,7 +92,7 @@ export function createTurnRunner(deps) {
     if (attachedSession?.remoteAttached) return forwardAttachedPrompt(attachedSession, prompt, options);
     const turn = openTurn(options);
     try {
-      const session0 = await prepareSession(turn, prompt);
+      const session0 = await prepareSession(turn, prompt, options);
       const turnContext = await dispatchPromptSubmit(turn, session0, prompt, options);
       const result = await mgr.askSession(
         session0.id,

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

@@ -3,7 +3,7 @@ import { hasOwn } from '../../runtime/shared/object.mjs';
 import { isHiddenAgent } from '../../runtime/agent/orchestrator/internal-agents.mjs';
 import { normalizeWorkflowRoute } from '../../runtime/agent/orchestrator/runtime-core/workflow.mjs';
 import { ensureProviderEnabled } from '../../runtime/agent/orchestrator/runtime-core/config-helpers.mjs';
-import { selectionFastCapable } from '../route-state.mjs';
+import { resolveRouteContextState, selectionFastCapable } from '../route-state.mjs';
 import { canonicalizeAgentRouteStorage, withAgentDisabled } from '../../runtime/shared/agent-route-config.mjs';
 import { agentEditorId } from './shared.mjs';
 
@@ -43,19 +43,31 @@ export function createAgentRouteApi(deps) {
       clean(selectedRoute.provider) === clean(stored.provider) && clean(selectedRoute.model) === clean(stored.model);
     const inheritedEffort = sameModel ? stored.effort || null : null;
     const inheritedModelParameters = sameModel ? stored.modelParameters || {} : {};
-    const inheritedContextPercent = sameModel ? stored.contextPercent : undefined;
+    // A requested percent replaces the stored exact window and requested
+    // tokens replace the stored percent.
+    const requestsPercent = requested.contextPercent !== undefined;
+    const requestsTokens = requested.contextTokens !== undefined;
+    const inheritedContextPercent = sameModel && !requestsTokens ? stored.contextPercent : undefined;
+    const inheritedContextTokens = sameModel && !requestsPercent ? stored.contextTokens : undefined;
     selectedRoute = {
       ...selectedRoute,
       effort: requested.effort !== undefined ? selectedRoute.effort : inheritedEffort,
       fast: requested.fast !== undefined ? selectedRoute.fast === true : sameModel && stored.fast === true,
+      // Main's modelSettings bucket must not decide an agent's Auto effort.
+      autoEffort:
+        requested.autoEffort !== undefined ? requested.autoEffort !== false : !sameModel || stored.autoEffort !== false,
       modelParameters:
         requested.modelParameters !== undefined ? selectedRoute.modelParameters : inheritedModelParameters,
       // resolveRoute reads contextPercent from Main's modelSettings bucket;
       // an agent route owns its own.
-      contextPercent: requested.contextPercent !== undefined ? requested.contextPercent : inheritedContextPercent,
+      contextPercent: requestsPercent ? requested.contextPercent : inheritedContextPercent,
+      contextTokens: requestsTokens ? requested.contextTokens : inheritedContextTokens,
     };
     await ensureProvidersReady(ensureProviderEnabled(getConfig(), selectedRoute.provider));
     const modelMeta = await lookupModelMeta(selectedRoute.provider, selectedRoute.model);
+    // Stored clamped, and not at all at the default window, as for Main.
+    const contextState = resolveRouteContextState(selectedRoute, modelMeta);
+    if (contextState.contextDefaultPercent !== undefined) selectedRoute.contextTokens = contextState.contextTokens;
     const fastCapable = selectionFastCapable(
       selectedRoute.provider,
       modelMeta,

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

@@ -12,6 +12,7 @@ import {
 } from '../../runtime/agent/orchestrator/runtime-core/workflow.mjs';
 import { ONBOARDING_VERSION } from '../quick-web-search-models.mjs';
 import { canonicalizeAgentRouteStorage } from '../../runtime/shared/agent-route-config.mjs';
+import { withStarterGuideOnCompletion } from '../starter-guide-state.mjs';
 import { resolveDataDir } from './shared.mjs';
 
 // Onboarding slot picks: lead → default preset, agent → worker route,
@@ -91,12 +92,12 @@ export function createOnboardingApi(deps) {
         ]);
         nextConfig.agents = applyAgentRouteInput(agentInput, draft.agentRoutes, configurableIds);
       }
-      nextConfig.onboarding = {
+      nextConfig.onboarding = withStarterGuideOnCompletion(config.onboarding, {
         ...(nextConfig.onboarding || {}),
         completed: true,
         version: ONBOARDING_VERSION,
         completedAt: new Date().toISOString(),
-      };
+      });
       if (payload.webSearchRoute) {
         const webSearchToSave = webSearchRouteToSave(payload.webSearchRoute);
         if (webSearchToSave) nextConfig.webSearchRoute = webSearchToSave;