mixdog 1.1.2 → 1.2.1

package/src/session-runtime/session-create/session-options.mjs

@@ -6,6 +6,7 @@ import { hasOwn } from '../../runtime/agent/orchestrator/runtime-core/session-te
 import { toolSpecForMode } from '../../runtime/agent/orchestrator/runtime-core/effort.mjs';
 import { pluginDataDir } from '../runtime-paths.mjs';
 import { LEAD_DISALLOWED_TOOLS } from '../../runtime/agent/orchestrator/runtime-core/tool-defs.mjs';
+import { HEADLESS_TOOL_PROFILE } from '../../runtime/agent/orchestrator/runtime-core/tool-profile.mjs';
 
 // Ownership and permission fields an agent-owned session inherits from its profile.
 function agentOwnedSessionFields(sessionProfile) {
@@ -47,7 +48,13 @@ export function sessionOptions(deps, coreMemoryContext) {
     owner: agentOwned ? 'agent' : 'cli',
     agent: agentOwned ? sessionProfile?.agent || 'worker' : 'lead',
     lane: agentOwned ? 'agent' : 'cli',
-    sourceType: agentOwned ? sessionProfile?.sourceType || 'agent' : 'lead',
+    // One-shot `mixdog exec` runs carry their own source so session catalogs
+    // can keep them out of the user's resumable list.
+    sourceType: agentOwned
+      ? sessionProfile?.sourceType || 'agent'
+      : rt.toolProfile === HEADLESS_TOOL_PROFILE
+        ? 'exec'
+        : 'lead',
     sourceName: agentOwned ? sessionProfile?.sourceName || sessionProfile?.agent || 'agent' : 'main',
     ...(rt.approvalMode ? { approvalMode: rt.approvalMode } : {}),
     clientHostPid: sessionProfile?.clientHostPid || process.pid,
@@ -64,8 +71,10 @@ export function sessionOptions(deps, coreMemoryContext) {
     workflowContext,
     orchestrationMode,
     fast: rt.route.fast === true,
+    autoEffort: rt.route.autoEffort !== false,
     modelParameters: rt.route.modelParameters || {},
     contextPercent: rt.route.contextPercent,
+    contextTokens: rt.route.contextTokens || null,
     selectedContextWindow: rt.route.selectedContextWindow || null,
     compaction:
       rt.config.compaction && typeof rt.config.compaction === 'object'

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

@@ -34,6 +34,7 @@ export function createSessionTurnApi(deps) {
     sessionOwnerGone: share.sessionOwnerGone,
     agentControl: agent.agentControl,
     taskControl: agent.taskControl,
+    stopShellJob: agent.stopShellJob,
     onNotification: agent.onNotification,
     toolsStatus: agent.toolsStatus,
     selectTools: agent.selectTools,

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

@@ -5,9 +5,9 @@
 // `this.*` resolve against the spread target, so cross-member calls (e.g.
 // setProfile -> this.getProfile) keep working when spread into the facade.
 //
-// The members live in five topic modules: profile/onboarding/skills,
+// The members live in six topic modules: profile/onboarding/skills,
 // compaction/auto-clear, built-in tool modules, system (channels, shell,
-// updates) and developer options; the local provider's own methods come from
+// updates), developer options and worktree defaults; the local provider's own methods come from
 // local-provider-settings.mjs.
 import { createLocalProviderSettings } from './local-provider-settings.mjs';
 import { createProfileSettings } from './settings-profile-api.mjs';
@@ -15,6 +15,7 @@ import { createCompactionSettings } from './settings-compaction-api.mjs';
 import { createBuiltinToolSettings } from './settings-builtin-tools-api.mjs';
 import { createSystemSettings } from './settings-system-api.mjs';
 import { createDeveloperSettings } from './settings-developer-api.mjs';
+import { createWorktreeSettings } from './settings-worktree-api.mjs';
 
 export function createSettingsApi(deps) {
   // Optional: callers without a live local provider / gate fall back to the
@@ -38,5 +39,6 @@ export function createSettingsApi(deps) {
     ...createBuiltinToolSettings(shared, localSettings),
     ...createSystemSettings(shared),
     ...createDeveloperSettings(shared),
+    ...createWorktreeSettings(shared),
   };
 }

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

@@ -7,6 +7,7 @@ import {
   builtinInstalled,
   setBuiltinInstalledInConfig,
 } from '../runtime/agent/orchestrator/runtime-core/builtin-features.mjs';
+import { featureEnvOverride, moduleEnabled } from '../runtime/agent/orchestrator/runtime-core/config-helpers.mjs';
 import { LOCAL_PROVIDER_ID } from '../runtime/local-provider/managed-runtime.mjs';
 import {
   INSTRUCTION_FILES_MODES,
@@ -23,7 +24,7 @@ import {
   shutdownEffortJudge,
 } from '../runtime/effort-judge/judge-client.mjs';
 
-const TOGGLEABLE_BUILTINS = ['git', 'office', 'tidy', 'localProvider', 'autoEffort'];
+const TOGGLEABLE_BUILTINS = ['git', 'office', 'tidy', 'localProvider', 'autoEffort', 'visualize'];
 
 function setLocalProviderEnabledInConfig(configLike, enabled) {
   const next = { ...(configLike || {}) };
@@ -97,6 +98,12 @@ export function createBuiltinToolSettings(
           enabled: tidyToolEnabledFn ? tidyToolEnabledFn() : builtinFeatureActive(config, 'tidy'),
           installed: builtinInstalled(config, 'tidy'),
         },
+        // Ships with the runtime and needs no install; the toggle reflects the
+        // module flag, not live bridge presence.
+        visualize: {
+          enabled: featureEnvOverride('MIXDOG_FEATURE_VISUALIZE') ?? moduleEnabled(config, 'visualize', true),
+          installed: true,
+        },
         localProvider: {
           ...localProvider,
           ...localSettings.status(),
@@ -152,7 +159,7 @@ export function createBuiltinToolSettings(
     },
     async setBuiltinToolEnabled(name, enabled) {
       if (!TOGGLEABLE_BUILTINS.includes(name)) {
-        throw new TypeError('Built-in tool must be git, office, tidy, localProvider, or autoEffort.');
+        throw new TypeError('Built-in tool must be git, office, tidy, localProvider, autoEffort, or visualize.');
       }
       if (name === 'autoEffort' && enabled !== false && !onnxRuntimeSupported()) {
         throw new Error(EFFORT_JUDGE_UNSUPPORTED);

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

@@ -0,0 +1,17 @@
+// Settings → Worktrees: defaults for Lead-session git worktrees
+// (runtime/shared/worktrees/settings.mjs). Values persist at agent config
+// `worktree.<key>`; defaults are not stored.
+import { applyWorktreeSettingsPatch, normalizeWorktreeSettings } from '../runtime/shared/worktrees/settings.mjs';
+
+export function createWorktreeSettings({ getConfig, saveConfigAndAdopt }) {
+  return {
+    getWorktreeSettings() {
+      return normalizeWorktreeSettings(getConfig()?.worktree);
+    },
+    setWorktreeSettings(patch) {
+      const config = getConfig() || {};
+      saveConfigAndAdopt({ ...config, worktree: applyWorktreeSettingsPatch(config.worktree, patch) });
+      return this.getWorktreeSettings();
+    },
+  };
+}

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;
 }
@@ -144,6 +146,7 @@ function publicAccounts(pool) {
   return {
     selectedId: pool.selectedId,
     auto: pool.auto,
+    ...(pool.policy ? { policy: pool.policy } : {}),
     useCredits: pool.useCredits === true,
     accounts: pool.accounts.map(({ id, label, authenticated, reauthRequired }) => ({
       id,
@@ -164,9 +167,15 @@ function mcpRows(status) {
       transport: server.transport || server.type || '',
       toolCount: Number(server.toolCount || 0),
       source: server.source || '',
+      ...(server.owner?.kind === 'plugin'
+        ? { plugin: server.owner.id, pluginServer: server.owner.key, disabledReason: server.disabledReason || null }
+        : {}),
       error: server.error || null,
+      ...(server.warnings?.length ? { warnings: server.warnings } : {}),
       scope: Array.isArray(server.scope) ? server.scope : null,
     })),
+    ...(status?.warnings?.length ? { warnings: status.warnings } : {}),
+    ...(status?.declarationErrors?.length ? { declarationErrors: status.declarationErrors } : {}),
   };
 }
 
@@ -178,6 +187,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 +313,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 +339,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 +520,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 +555,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));
@@ -570,7 +584,11 @@ const SETUP_ACTION_HANDLERS = {
     const plugin = ((await rt.pluginsStatus())?.plugins || []).find((row) => row.name === name || row.id === name);
     if (!plugin) throw new Error(`plugin "${name}" not found`);
     const result = await rt.enablePluginMcp(plugin);
-    return { serverName: result.serverName, mcp: mcpRows(result.status) };
+    return {
+      serverName: result.serverName,
+      ...(result.serverNames ? { serverNames: result.serverNames } : {}),
+      mcp: mcpRows(result.status),
+    };
   },
 };
 

package/src/session-runtime/setup-tool/extended-actions.mjs

@@ -34,6 +34,7 @@ function publicMcpConfig(row) {
   return {
     name: row.name,
     source: row.source,
+    ...(row.owner?.kind === 'plugin' ? { plugin: row.owner.id, pluginServer: row.owner.key, readOnly: true } : {}),
     enabled: row.enabled !== false,
     type: config.type || 'stdio',
     cwd: config.cwd || '',

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,
@@ -194,6 +196,7 @@ export const SETUP_EXTENDED_PROPERTIES = Object.freeze({
     runInBackground: boolean,
     turnNotifications: boolean,
     usagePinned: boolean,
+    usageRailShortLong: boolean,
     computerObserveOnly: boolean,
     notificationVolume: {
       type: 'integer',

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.' },
@@ -218,11 +227,11 @@ export const SETUP_TOOL_DEFS = Object.freeze([
           type: 'string',
           enum: [...INSTRUCTION_FILES_MODES],
           description:
-            'set_instruction_files: which user instruction files new sessions load (global ~/.codex/AGENTS.md, ~/.claude/CLAUDE.md, then the Project root\'s AGENTS.md/CLAUDE.md).',
+            "set_instruction_files: which user instruction files new sessions load (global ~/.codex/AGENTS.md, ~/.claude/CLAUDE.md, then the Project root's AGENTS.md/CLAUDE.md).",
         },
         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',
@@ -235,6 +244,12 @@ export const SETUP_TOOL_DEFS = Object.freeze([
           properties: {
             selectedId: { type: 'string', description: 'Account to use now.' },
             auto: { type: 'boolean', description: 'Automatic switching to another account when one is exhausted.' },
+            policy: {
+              type: 'string',
+              enum: ['manual', 'limit', 'headroom'],
+              description:
+                'Account switching: manual = selected account only; limit = switch when it reaches a limit; headroom = each new session starts on the account with the most headroom.',
+            },
             useCredits: { type: 'boolean', description: 'Allow paid credits once plan limits are reached.' },
             order: {
               type: 'array',
@@ -320,6 +335,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/skills-api.mjs

@@ -24,8 +24,8 @@ const DEFAULT_SKILL_BODY = '# Instructions\n\nDescribe how to use this skill.';
 export function createSkillsApi({ contextMod, getCwd, getTools = () => [] }) {
   const globalSkillsRoot = () => resolve(resolvePluginData(), 'skills');
 
-  function skillsStatus() {
-    const cwd = getCwd();
+  /** `cwd` overrides the session's folder (already validated by the caller). */
+  function skillsStatus({ cwd = getCwd() } = {}) {
     const skills = typeof contextMod.collectSkillsCached === 'function' ? contextMod.collectSkillsCached(cwd) : [];
     const norm = (value) =>
       String(value || '')
@@ -54,7 +54,10 @@ export function createSkillsApi({ contextMod, getCwd, getTools = () => [] }) {
         const source = sourceForSkill(skill);
         return {
           name: skill.name,
-          enabled: !(contextMod.isSkillDisabled?.(skill.name) || contextMod.skillMissingFeature?.(skill.name)),
+          enabled: !(
+            contextMod.isSkillDisabled?.(skill.name, null, skills) ||
+            contextMod.skillMissingFeature?.(skill.name, null, skills)
+          ),
           description: skill.description || '',
           whenToUse: skill.whenToUse || '',
           filePath: skill.filePath || null,
@@ -90,6 +93,7 @@ export function createSkillsApi({ contextMod, getCwd, getTools = () => [] }) {
     if (typeof contextMod.isSkillDisabled === 'function' && contextMod.isSkillDisabled(skillName)) {
       return `Error: skill "${skillName}" is disabled`;
     }
+    if (contextMod.skillOutsideScope?.(skillName, getCwd())) return contextMod.skillOutsideScopeError(skillName);
     const skill = skillContent(skillName);
     // The general tool envelope keeps the main/Lead session identical to agent
     // loops: the model-visible tool_result is the short stub and the SKILL.md

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,
@@ -81,6 +91,7 @@ export function createAskCallbacks({ transcript, notifyFnForSession, scheduleSea
       onStreamDelta: streamDelta(turn, options),
       drainSteering: options.drainSteering,
       onSteerMessage: options.onSteerMessage,
+      onSkillsApplied: options.onSkillsApplied,
       notifyFn: notifyFnForSession(session0.id),
       signal: turn.signal,
     };

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 {}