mixdog 1.1.1 → 1.2.0

package/src/session-runtime/runtime-core.mjs

@@ -20,6 +20,7 @@ function bootParams({
   fast,
   modelParameters,
   contextPercent,
+  contextTokens,
   selectedContextWindow,
   cwd = process.cwd(),
   toolMode = 'full',
@@ -30,6 +31,7 @@ function bootParams({
   initialConfig = null,
   desktopSession = null,
   sessionProfile = null,
+  worktree = null,
   executeAgentControl = null,
 } = {}) {
   return {
@@ -39,6 +41,7 @@ function bootParams({
     fast,
     modelParameters,
     contextPercent,
+    contextTokens,
     selectedContextWindow,
     cwd,
     toolMode,
@@ -49,6 +52,8 @@ function bootParams({
     initialConfig,
     desktopSession,
     sessionProfile,
+    // Creation-time worktree intent (workspace/transitions.mjs creationIntent).
+    worktree,
     executeAgentControl,
   };
 }

package/src/session-runtime/runtime-facade.mjs

@@ -74,6 +74,10 @@ export function createRuntimeFacade({
     get fast() {
       return state.route.fast === true;
     },
+    // The route's Auto effort switch; absent means on.
+    get autoEffort() {
+      return state.route.autoEffort !== false;
+    },
     get fastCapable() {
       return state.route.fastCapable === true;
     },
@@ -94,6 +98,10 @@ export function createRuntimeFacade({
       // Picker preference for a new/inherited session, not the live gauge.
       return state.route?.contextPercent ?? state.session?.contextPercent ?? null;
     },
+    get contextTokens() {
+      // Exact window preference in tokens; null when the route uses a percent stop.
+      return state.route ? state.route.contextTokens || null : state.session?.contextTokens || null;
+    },
     get rawContextWindow() {
       return state.session?.rawContextWindow || state.session?.contextWindow || null;
     },

package/src/session-runtime/runtime-paths.mjs

@@ -6,7 +6,6 @@ export const RUNTIME = '../runtime/agent/orchestrator';
 export const WEB_SEARCH_RUNTIME = '../runtime/web-search/index.mjs';
 export const WEB_SEARCH_TOOL_DEFS = '../runtime/web-search/tool-defs.mjs';
 export const MEMORY_TOOL_DEFS = '../runtime/memory/tool-defs.mjs';
-export const CHANNEL_TOOL_DEFS = '../runtime/channels/tool-defs.mjs';
 export const CODE_GRAPH_TOOL_DEFS = '../runtime/agent/orchestrator/tools/code-graph-tool-defs.mjs';
 export const CODE_GRAPH_RUNTIME = '../runtime/agent/orchestrator/tools/code-graph.mjs';
 export const STATUSLINE_SESSION_ROUTES = '../vendor/statusline/src/gateway/session-routes.mjs';

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

@@ -2,7 +2,10 @@ import { registerCacheInvalidationListener } from '../runtime/agent/orchestrator
 import { turnReviewReply } from '../runtime/shared/turn-review-reply.mjs';
 import {
   getSessionReviewDiff,
+  getTurnChanges,
   getTurnReviewDiff,
+  reapplyTurnChanges,
+  revertTurnChanges,
   revertTurnReview,
   revertTurnReviewFile,
 } from '../runtime/shared/turn-snapshot.mjs';
@@ -22,5 +25,11 @@ export function createRuntimeReviewApi({ getCwd, getSessionId }) {
     getSessionReviewDiff: () => getSessionReviewDiff(getCwd(), getSessionId()),
     revertTurnReview: (checkpointId) => revertTurnReview(getCwd(), getSessionId(), checkpointId),
     revertTurnReviewFile: (file, checkpointId) => revertTurnReviewFile(getCwd(), getSessionId(), file, checkpointId),
+    // Historical per-turn changes, addressed by checkpointId (TurnChangesReply).
+    getTurnChanges: (options = {}) => getTurnChanges(getSessionId(), options),
+    revertTurnChanges: (checkpointId, file, revision) =>
+      revertTurnChanges(getSessionId(), checkpointId, file, revision),
+    reapplyTurnChanges: (checkpointId, file, revision) =>
+      reapplyTurnChanges(getSessionId(), checkpointId, file, revision),
   };
 }

package/src/session-runtime/services/agent-tool/helpers.mjs

@@ -12,6 +12,7 @@ import {
 import { PRESET_ALIASES } from './tool-def.mjs';
 import { positiveInt } from '../../../runtime/shared/numbers.mjs';
 import { clean } from '../../../runtime/shared/clean.mjs';
+import { normalizeContextTokens } from '../../../runtime/shared/llm/default-context-window.mjs';
 
 export { positiveInt };
 
@@ -220,10 +221,14 @@ export function normalizeAgentRoute(routeLike) {
     model,
     effort: clean(routeLike?.effort) || undefined,
     fast: routeLike?.fast === true,
+    ...(routeLike?.autoEffort === false ? { autoEffort: false } : {}),
     ...(routeLike?.modelParameters && typeof routeLike.modelParameters === 'object'
       ? { modelParameters: { ...routeLike.modelParameters } }
       : {}),
     ...(Number(routeLike?.contextPercent) > 0 ? { contextPercent: Number(routeLike.contextPercent) } : {}),
+    ...(normalizeContextTokens(routeLike?.contextTokens)
+      ? { contextTokens: normalizeContextTokens(routeLike.contextTokens) }
+      : {}),
   };
 }
 

package/src/session-runtime/services/agent-tool/job-views/agent-list.mjs

@@ -3,6 +3,7 @@
 // progress, filtered by default to workers that can still do work.
 import { ACTIVE_STAGES } from '../tool-def.mjs';
 import { isTerminalWorkerStatus } from '../worker-rows.mjs';
+import { sessionUsageTotals } from '../../../../runtime/shared/session-usage-totals.mjs';
 
 // Idle, closed, errored and reaped/unknown rows are history and stay reachable
 // through the task section (status/read keep their terminal result).
@@ -36,6 +37,7 @@ function agentRow({ tag, session, runtime, progress, now, indexRow = null }) {
     preset: session.presetName || null,
     effort: session.effort || null,
     fast: session.fast === true,
+    ...(session.autoEffort === false ? { autoEffort: false } : {}),
     // Additive: route model parameters (e.g. Daybreak Blue) when the route has any.
     ...(session.modelParameters && Object.keys(session.modelParameters).length
       ? { modelParameters: { ...session.modelParameters } }
@@ -51,6 +53,7 @@ function agentRow({ tag, session, runtime, progress, now, indexRow = null }) {
     clientHostPid: session.clientHostPid || null,
     lastStreamDeltaAt: runtime?.lastStreamDeltaAt ? new Date(runtime.lastStreamDeltaAt).toISOString() : null,
     staleSeconds: runtime?.lastStreamDeltaAt ? Math.floor((now - runtime.lastStreamDeltaAt) / 1000) : null,
+    ...sessionUsageTotals(session),
     windowTokens: Number(session.lastContextTokens ?? session.lastInputTokens) || 0,
     windowCap: Number(session.contextWindow) || null,
     permission: session.permission || null,

package/src/session-runtime/services/agent-tool/job-views/job-lookup.mjs

@@ -69,6 +69,7 @@ export function createJobLookup({ mgr, tags, refreshTagsFromSessions }) {
         model: session.model || null,
         effort: session.effort || null,
         fast: session.fast === true,
+        ...(session.autoEffort === false ? { autoEffort: false } : {}),
       },
     };
   }

package/src/session-runtime/services/agent-tool/job-views/spawn-meta.mjs

@@ -16,6 +16,7 @@ export function preparedSpawnMeta(prepared, extras = {}) {
     model: prepared.preset.model,
     effort: prepared.preset.effort || null,
     fast: prepared.preset.fast === true,
+    ...(prepared.preset.autoEffort === false ? { autoEffort: false } : {}),
   });
 }
 

package/src/session-runtime/services/agent-tool/lead-worker-index.mjs

@@ -72,6 +72,20 @@ export function createLeadWorkerIndex({ dataDir, cfgMod, workerRowFromSession })
     return true;
   }
 
+  /** A workspace transition moved the Lead: its existing row follows (status,
+   *  reap deadline and liveness stamps unchanged). No row: nothing to write. */
+  function updateLeadWorkerCwd(sessionId, cwd) {
+    const id = clean(sessionId);
+    const next = clean(cwd);
+    if (!id || !next) return false;
+    index.write((byKey) => {
+      const current = byKey.get(id);
+      if (!current || current.cwd === next) return;
+      byKey.set(id, { ...current, cwd: next });
+    });
+    return true;
+  }
+
   /** Graceful-exit settlement: every turn this process still claims goes idle
    *  before the runtime disappears. */
   function flushActiveLeadRows() {
@@ -147,6 +161,7 @@ export function createLeadWorkerIndex({ dataDir, cfgMod, workerRowFromSession })
     /** Resolves once every queued Lead index write is on disk. */
     flushLeadWorkerIndexWrites: index.flush,
     upsertLeadSession,
+    updateLeadWorkerCwd,
     removeLeadWorkerRow,
     flushActiveLeadRows,
     recoverStaleLeadRows,

package/src/session-runtime/services/agent-tool/send-flow.mjs

@@ -180,6 +180,7 @@ export function createSendFlow({ mgr, defaultCwd, sessionSurface, canUseSessionS
         preset: session.presetName || null,
         effort: session.effort || null,
         fast: session.fast === true,
+        ...(session.autoEffort === false ? { autoEffort: false } : {}),
       },
       (job, ownerNotifyContext) => runSend(prepared, ownerNotifyContext, job),
       notifyContext

package/src/session-runtime/services/agent-tool/spawn-flow/spawn-plan.mjs

@@ -17,6 +17,7 @@ import { isAgentDisabled } from '../../../../runtime/shared/agent-route-config.m
 import { normalizeAgentPermission } from '../../../../runtime/shared/markdown-frontmatter.mjs';
 import { resolveAgentSpawnPreset } from '../spawn-preset.mjs';
 import { AGENT_OWNER } from '../../../../runtime/agent/orchestrator/agent-owner.mjs';
+import { workspaceCwdLock } from '../../../workspace/admission-gate.mjs';
 
 export function createSpawnPlanner({
   cfgMod,
@@ -52,8 +53,15 @@ export function createSpawnPlanner({
     if (resolveTag(tag, context, { scanSessions: wantsSessionScan(args) })) {
       throw new Error(`agent spawn: tag "${tag}" already exists`);
     }
-    const baseCwd = resolve(callerCwd || defaultCwd || process.cwd());
-    const workerCwd = clean(args.cwd) ? resolve(baseCwd, args.cwd) : baseCwd;
+    // Workers share their Lead's execution root. While the Lead runs in its
+    // worktree, that root is locked: neither args.cwd nor an inherited
+    // (pre-transition) cwd can send a worker elsewhere.
+    const lockedCwd = workspaceCwdLock([
+      context?.ownerSessionId,
+      context?.callerSessionId || context?.sessionId,
+    ]);
+    const baseCwd = resolve(lockedCwd || callerCwd || defaultCwd || process.cwd());
+    const workerCwd = !lockedCwd && clean(args.cwd) ? resolve(baseCwd, args.cwd) : baseCwd;
     const prompt = await resolvePrompt(args, workerCwd);
     if (prepState?.timedOut) {
       throw new Error('agent spawn prep timed out before session bind');

package/src/session-runtime/services/agent-tool/spawn-flow/spawn-prep.mjs

@@ -10,6 +10,7 @@ import { prepareAgentSession } from '../../../../runtime/agent/orchestrator/agen
 import { getProvider } from '../../../../runtime/agent/orchestrator/providers/registry.mjs';
 import { resolveRouteContextState } from '../../../route-state.mjs';
 import { createSpawnPlanner } from './spawn-plan.mjs';
+import { enterWorkerSpawn } from '../../../workspace/admission-gate.mjs';
 
 /** The route fields every worker-row and tag record carries. */
 export function presetDescriptor(agent, preset, presetName) {
@@ -20,6 +21,7 @@ export function presetDescriptor(agent, preset, presetName) {
     model: preset.model,
     effort: preset.effort || null,
     fast: preset.fast === true,
+    ...(preset.autoEffort === false ? { autoEffort: false } : {}),
   };
 }
 
@@ -84,9 +86,9 @@ export function createSpawnPreparer({
     // A sub-100 context share needs the window it selects; a percent alone
     // keeps the full served window.
     const sessionSpec = { ...spec };
-    if (plan.preset.contextPercent) {
-      const { contextPercent, selectedContextWindow } = resolveRouteContextState(plan.preset, null);
-      Object.assign(sessionSpec, { contextPercent, selectedContextWindow });
+    if (plan.preset.contextPercent || plan.preset.contextTokens) {
+      const { contextPercent, selectedContextWindow, contextTokens } = resolveRouteContextState(plan.preset, null);
+      Object.assign(sessionSpec, { contextPercent, selectedContextWindow }, contextTokens ? { contextTokens } : {});
     }
     if (sessionSurface?.canonical === true && typeof sessionSurface.createChild === 'function') {
       return sessionSurface.createChild({ spec: sessionSpec, prompt: plan.prompt, tag: plan.tag });
@@ -99,10 +101,20 @@ export function createSpawnPreparer({
   }
 
   async function prepareSpawnInProcess(args, callerCwd = null, context = {}, prepState = null) {
-    const plan = await resolveSpawnPlan(args, callerCwd, context, prepState);
-    const spec = spawnSessionSpec(plan, args, context);
-    const { session, effectiveCwd } = await createSpawnedSession(plan, spec, prepState);
-    bindSpawnedSession(session, plan);
+    // Shared admission with Lead workspace transitions: no spawn is prepared
+    // while the Lead's workspace changes, no transition starts mid-spawn.
+    const leaveSpawn = enterWorkerSpawn([context?.ownerSessionId, context?.callerSessionId || context?.sessionId]);
+    let plan;
+    let session;
+    let effectiveCwd;
+    try {
+      plan = await resolveSpawnPlan(args, callerCwd, context, prepState);
+      const spec = spawnSessionSpec(plan, args, context);
+      ({ session, effectiveCwd } = await createSpawnedSession(plan, spec, prepState));
+      bindSpawnedSession(session, plan);
+    } finally {
+      leaveSpawn();
+    }
     if (sessionSurface?.canonical !== true) {
       maybePrewarmSpawnTransport(plan, session);
     }

package/src/session-runtime/services/agent-tool/spawn-preset.mjs

@@ -20,6 +20,7 @@ export function resolveAgentSpawnPreset(config, args = {}) {
         model: clean(args.model),
         effort: clean(args.effort) || undefined,
         fast: args.fast === true,
+        ...(args.autoEffort === false ? { autoEffort: false } : {}),
         tools: 'full',
       },
     };
@@ -42,8 +43,10 @@ export function resolveAgentSpawnPreset(config, args = {}) {
         model: agentRoute.model,
         effort: agentRoute.effort,
         fast: agentRoute.fast === true,
+        ...(agentRoute.autoEffort === false ? { autoEffort: false } : {}),
         ...(agentRoute.modelParameters ? { modelParameters: agentRoute.modelParameters } : {}),
         ...(agentRoute.contextPercent ? { contextPercent: agentRoute.contextPercent } : {}),
+        ...(agentRoute.contextTokens ? { contextTokens: agentRoute.contextTokens } : {}),
         tools: 'full',
       },
     };

package/src/session-runtime/services/agent-tool/tag-registry.mjs

@@ -29,7 +29,7 @@ export function createTagRegistry({ dataDir, cfgMod, mgr }) {
     workerRowFromSession: index.workerRowFromSession,
   });
 
-  const { upsertLeadSession } = leadIndex;
+  const { upsertLeadSession, updateLeadWorkerCwd } = leadIndex;
 
   function dispose(options) {
     try {
@@ -103,6 +103,7 @@ export function createTagRegistry({ dataDir, cfgMod, mgr }) {
     upsertWorkerSession: index.upsertWorkerSession,
     upsertWorkerSessionDeferred,
     upsertLeadSession,
+    updateLeadWorkerCwd,
     removeWorkerRow,
     refreshTagsFromIndex,
     tags,

package/src/session-runtime/services/agent-tool/worker-index/row-shape.mjs

@@ -38,6 +38,7 @@ export function normalizeWorkerRows(value) {
       preset: clean(row.preset) || null,
       effort: clean(row.effort) || null,
       fast: typeof row.fast === 'boolean' ? row.fast : null,
+      ...(row.autoEffort === false ? { autoEffort: false } : {}),
       status: clean(row.status) || 'idle',
       stage: clean(row.stage) || clean(row.status) || 'idle',
       createdAt: clean(row.createdAt) || null,
@@ -87,6 +88,10 @@ export function workerRowFromSession(session, fallbackTag = '', extra = {}, getS
     preset: clean(extra.preset) || clean(session?.presetName) || null,
     effort: clean(extra.effort) || clean(session?.effort) || null,
     fast: fastFlag(extra.fast, session?.fast),
+    // Absent means Auto effort is on; an explicit boolean wins over the session's.
+    ...((typeof extra.autoEffort === 'boolean' ? extra.autoEffort : session?.autoEffort) === false
+      ? { autoEffort: false }
+      : {}),
     status,
     stage,
     createdAt: clean(session?.createdAt) || clean(extra.createdAt) || nowIso,

package/src/session-runtime/services/agent-tool/worker-rows.mjs

@@ -133,6 +133,7 @@ export function workerRowToSession(row = {}) {
     presetName: row.preset || null,
     effort: row.effort || null,
     fast: row.fast === true,
+    ...(row.autoEffort === false ? { autoEffort: false } : {}),
     status: row.status || 'idle',
     stage: row.stage || row.status || 'idle',
     createdAt: row.createdAt || null,

package/src/session-runtime/services/agent-tool.mjs

@@ -146,6 +146,7 @@ export function createStandaloneAgent({
     getStatus,
     recoverWorkers,
     upsertLeadSession: registry.upsertLeadSession,
+    updateLeadWorkerCwd: registry.updateLeadWorkerCwd,
     closeAll: closeFlow.closeAll,
     dispose: (options) => registry.dispose(options),
   };

package/src/session-runtime/services/channel-worker.mjs

@@ -18,7 +18,7 @@ import { daemonEnv, spawnDaemonCandidate } from './channel-worker/daemon-spawn.m
 
 export { pruneStaleChannelClientHeartbeats };
 
-const CHANNEL_TOOLS = new Set(['activate_channel_bridge', 'reload_config', 'rebind_current_transcript']);
+const CHANNEL_TOOLS = new Set(['activate_channel_bridge', 'reload_config']);
 const CALL_RETRIES = 3;
 
 function logLine(path, line) {

package/src/session-runtime/services/daemon-candidate.mjs

@@ -5,7 +5,8 @@
 // ready handoff so the daemon's code/signal is recorded against its pid, boot
 // time and ready state. Resolves once the candidate reported ready, exited,
 // failed to spawn, or the timeout elapsed; the caller then re-reads discovery
-// and attaches to whoever won.
+// and attaches to whoever won. The resolved `summary()` describes this boot as
+// observed when called, for a caller that has to give up.
 import { fork } from 'node:child_process';
 import { beginDaemonSpawnCapture } from './daemon-crash-capture.mjs';
 
@@ -34,7 +35,7 @@ export function forkDaemonCandidate({
       // Boot diagnostics written to fd 2 reach this log exactly once, even when
       // the candidate never reached ready.
       capture.mirror();
-      resolve();
+      resolve({ summary: capture.summary });
     };
     let child;
     try {

package/src/session-runtime/services/daemon-crash-capture/spawn-capture.mjs

@@ -20,6 +20,11 @@ const CAPTURE_ID_ATTEMPTS = 8;
 const MIRROR_MAX_BYTES = 16 * 1024;
 const MESSAGE_MAX_CHARS = 512;
 const HEAP_FLAG_RE = /^--max-(?:old-space|semi-space|heap)-size=/;
+// Bytes of fd 2 a failure summary scans (the newest ones when larger).
+const SUMMARY_SCAN_MAX_BYTES = 256 * 1024;
+// Node's uncaught-error report (`TypeError: …`, `Error [ERR_…]: …`), V8's
+// fatal abort and the daemon's own `fatal boot error` log line.
+const STDERR_ERROR_LINE_RE = /\b[A-Z][A-Za-z]*Error\b(?: \[[A-Z0-9_]+\])?:|^Error\b|FATAL ERROR|(?<!non-)\bfatal\b/;
 
 function stamp(ms) {
   const iso = new Date(ms).toISOString();
@@ -256,6 +261,8 @@ function noteSpawnError(capture, error) {
 // this stream, so nothing here extends its lifetime.
 function drainStderrPipe(capture, stream) {
   const onData = (chunk) => {
+    // No capture file to read back: keep the newest bytes for summary().
+    capture.pipeText = `${capture.pipeText}${chunk}`.slice(-SUMMARY_SCAN_MAX_BYTES);
     mirrorText(capture.log, chunk);
   };
   stream.on('data', onData);
@@ -272,6 +279,52 @@ function drainStderrPipe(capture, stream) {
   });
 }
 
+/** The candidate's fd 2 as text: the capture file (its newest bytes when
+ *  large) or, when fd 2 fell back to a pipe, what that pipe delivered. */
+function stderrText(capture) {
+  if (!capture.capturePath || capture.removed) return capture.pipeText;
+  try {
+    const handle = fs.openSync(capture.capturePath, 'r');
+    try {
+      const size = fs.fstatSync(handle).size;
+      const length = Math.min(size, SUMMARY_SCAN_MAX_BYTES);
+      const buffer = Buffer.allocUnsafe(length);
+      const bytesRead = fs.readSync(handle, buffer, 0, length, size - length);
+      return buffer.subarray(0, bytesRead).toString('utf8');
+    } finally {
+      fs.closeSync(handle);
+    }
+  } catch {
+    return capture.pipeText;
+  }
+}
+
+/** What a launcher that gave up on this boot needs to name its cause: the
+ *  lifecycle as far as observed, the first error line on fd 2 (else its last
+ *  line, where a stalled boot stopped) and where the full text is. */
+function summarize(capture) {
+  const { record } = capture;
+  const lines = stderrText(capture)
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const errorLine = lines.find((line) => STDERR_ERROR_LINE_RE.test(line));
+  return {
+    pid: record.pid,
+    ready: record.ready,
+    spawnedAt: record.spawnedAt,
+    exitedAt: record.exitedAt,
+    exitCode: record.exitCode,
+    exitSignal: record.exitSignal,
+    exitReason: record.exitReason ?? null,
+    uptimeMs: record.uptimeMs,
+    error: record.error,
+    stderrErrorLine: errorLine ? boundedMessage(errorLine) : null,
+    stderrLastLine: lines.length > 0 ? boundedMessage(lines.at(-1)) : null,
+    stderrPath: capture.removed ? null : capture.capturePath,
+  };
+}
+
 /** Attach to the forked child: record its identity and keep a lifetime
  *  listener that survives the ready handoff, so a later exit is still
  *  correlated to this pid, boot time and ready state. */
@@ -347,6 +400,7 @@ export function beginDaemonSpawnCapture({
     readOffset: 0,
     removed: false,
     pipeDrained: null,
+    pipeText: '',
     stderrStdio: 'pipe',
   };
   openCapture(capture, { captureDir, prune, launcherPid, nonce });
@@ -377,5 +431,6 @@ export function beginDaemonSpawnCapture({
      *  recording anything — the child, if any, keeps its duplicate. */
     release: () => closeWriteFd(capture),
     snapshot: () => ({ ...capture.record }),
+    summary: () => summarize(capture),
   };
 }

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-profile-api.mjs

@@ -1,6 +1,13 @@
 // Onboarding, the user profile (/profile) and the disabled-skill list. Methods
 // reference `this.*` so cross-member calls resolve against the facade object
 // these are spread into.
+import {
+  mergeStarterGuide,
+  requiredStarterGuideState,
+  storedStarterGuide,
+  withStarterGuideOnCompletion,
+} from './starter-guide-state.mjs';
+
 export function createProfileSettings({
   getConfig,
   adoptConfig,
@@ -19,21 +26,39 @@ export function createProfileSettings({
         version: nextConfig?.onboarding?.version || 0,
         default: nextConfig?.default || null,
         workflowRoutes: summarizeWorkflowRoutes(nextConfig),
+        starterGuide: storedStarterGuide(nextConfig?.onboarding?.starterGuide),
       };
     },
+    // Persist the desktop "Getting started" guide state beside the onboarding
+    // flags so it survives a lost renderer localStorage. Malformed input is
+    // rejected; a valid save merges forward, so a stale one cannot reopen a
+    // closed guide or forget a visited step.
+    saveStarterGuideState(state) {
+      const next = requiredStarterGuideState(state);
+      const config = getConfig();
+      const onboarding = config.onboarding || {};
+      saveConfigAndAdopt({
+        ...config,
+        onboarding: {
+          ...onboarding,
+          starterGuide: mergeStarterGuide(storedStarterGuide(onboarding.starterGuide), next),
+        },
+      });
+      return this.getOnboardingStatus();
+    },
     // Mark onboarding as done WITHOUT touching routes/agents/provider. Used by
     // the TUI "skip" (Esc) path so the wizard doesn't reappear next launch,
     // while leaving any existing config routes untouched.
     skipOnboarding() {
       const config = getConfig();
       const nextConfig = { ...config };
-      nextConfig.onboarding = {
+      nextConfig.onboarding = withStarterGuideOnCompletion(config.onboarding, {
         ...(nextConfig.onboarding || {}),
         completed: true,
         version: ONBOARDING_VERSION,
         completedAt: new Date().toISOString(),
         skipped: true,
-      };
+      });
       saveConfigAndAdopt(nextConfig);
       return this.getOnboardingStatus();
     },

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();
+    },
+  };
+}