mixdog 1.1.2 → 1.2.0

package/src/runtime/visualize-bridge/client.mjs

@@ -0,0 +1,181 @@
+/**
+ * Loopback client for the desktop app's visualize bridge. The desktop app
+ * advertises { port, token } through `visualize-bridge.json`; this runtime
+ * half is the sync availability probe and the executor behind tool calls.
+ * Request: POST /command { sessionId, cwd, action, input }.
+ * Response: { ok:true, text, tabs?, path? } | { ok:false, error }.
+ */
+import { bridgeDiscoveryChanged, readBridgeDiscovery, readBridgeDiscoveryDetail } from '../bridge-discovery.mjs';
+
+const DISCOVERY_FILE = 'visualize-bridge.json';
+const REQUEST_TIMEOUT_MS = 30_000;
+/** `export` renders a page and writes a file; the desktop host's own deadline
+ *  for it (45 s) is shorter, so a timeout is reported by the host, which then
+ *  writes nothing, rather than raced by this client. */
+const EXPORT_REQUEST_TIMEOUT_MS = 60_000;
+const MAX_RESPONSE_BYTES = 1024 * 1024;
+const ACTIONS = new Set(['open', 'close', 'annotate', 'capture', 'export', 'check', 'inspect']);
+const INLINE_KINDS = ['mermaid', 'svg', 'chart', 'html', 'markdown'];
+const MAX_INLINE_BYTES = 512 * 1024;
+const BRIDGE_UNAVAILABLE_MESSAGE = 'visualize is unavailable; the Mixdog desktop app must be running';
+
+export function visualizeBridgeAvailableSync() {
+  return readBridgeDiscovery(DISCOVERY_FILE) !== null;
+}
+
+function toolError(message) {
+  return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+}
+
+function unavailableMessage() {
+  const { reason } = readBridgeDiscoveryDetail(DISCOVERY_FILE);
+  return reason && reason !== 'missing'
+    ? `${BRIDGE_UNAVAILABLE_MESSAGE} (discovery ${reason})`
+    : BRIDGE_UNAVAILABLE_MESSAGE;
+}
+
+export function validateVisualizeArgs(args) {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    return { ok: false, error: 'visualize arguments must be an object' };
+  }
+  if (!ACTIONS.has(args.action)) return { ok: false, error: 'action must be open, close, annotate, capture, export, check, or inspect' };
+  const input = args.input ?? {};
+  if (typeof input !== 'object' || Array.isArray(input)) return { ok: false, error: 'input must be an object' };
+  if (args.action === 'open' && input.content != null) {
+    const content = input.content;
+    if (input.targets != null) return { ok: false, error: 'open takes either input.targets or input.content, not both' };
+    if (typeof content !== 'object' || Array.isArray(content)) {
+      return { ok: false, error: 'open input.content must be { kind, source, title? }' };
+    }
+    if (!INLINE_KINDS.includes(content.kind)) {
+      return { ok: false, error: `open input.content.kind must be one of ${INLINE_KINDS.join(', ')}` };
+    }
+    if (typeof content.source !== 'string' || !content.source.trim()) {
+      return { ok: false, error: 'open input.content.source must be a non-empty string' };
+    }
+    if (Buffer.byteLength(content.source) > MAX_INLINE_BYTES) {
+      return { ok: false, error: `open input.content.source must be at most ${MAX_INLINE_BYTES / 1024} KiB` };
+    }
+    if (content.title != null && typeof content.title !== 'string') {
+      return { ok: false, error: 'open input.content.title must be a string' };
+    }
+    if (input.version != null && !(Number.isInteger(input.version) && input.version >= 1)) {
+      return { ok: false, error: 'open input.version must be a positive integer (a kept version number)' };
+    }
+  } else if (args.action === 'open') {
+    const targets = input.targets;
+    if (
+      !Array.isArray(targets) ||
+      targets.length < 1 ||
+      targets.length > 3 ||
+      targets.some((target) => typeof target !== 'string' || !target.trim())
+    ) {
+      return { ok: false, error: 'open requires input.targets: 1-3 non-empty strings' };
+    }
+    if (targets.some((target) => /^https?:\/\//i.test(target.trim())) && targets.length > 1) {
+      return { ok: false, error: 'a web URL must be the only target; do not mix it with files or other URLs' };
+    }
+    if (input.version != null && !(Number.isInteger(input.version) && input.version >= 1)) {
+      return { ok: false, error: 'open input.version must be a positive integer (a kept version number)' };
+    }
+  }
+  if (['annotate', 'capture', 'export', 'check', 'inspect'].includes(args.action) && (typeof input.tab !== 'string' || !input.tab)) {
+    return { ok: false, error: `${args.action} requires input.tab` };
+  }
+  if (args.action === 'inspect') {
+    const { viewport, selector } = input;
+    if (viewport != null) {
+      const sized = (value, min, max) => Number.isInteger(value) && value >= min && value <= max;
+      if (
+        typeof viewport !== 'object' ||
+        Array.isArray(viewport) ||
+        !sized(viewport.width, 200, 3000) ||
+        (viewport.height != null && !sized(viewport.height, 200, 4000))
+      ) {
+        return { ok: false, error: 'inspect input.viewport must be { width: 200-3000, height?: 200-4000 } in whole pixels' };
+      }
+    }
+    if (selector != null && (typeof selector !== 'string' || !selector.trim() || selector.length > 500)) {
+      return { ok: false, error: 'inspect input.selector must be a non-empty CSS selector of at most 500 characters' };
+    }
+  }
+  if (args.action === 'capture' && !(typeof input.output === 'string' && /\.png$/i.test(input.output.trim()))) {
+    return { ok: false, error: 'capture requires input.output ending in .png' };
+  }
+  if (args.action === 'export') {
+    if (input.format !== 'png' && input.format !== 'pdf') return { ok: false, error: 'export requires input.format png or pdf' };
+    if (typeof input.output !== 'string' || !new RegExp('\\.' + input.format + '$', 'i').test(input.output.trim())) {
+      return { ok: false, error: `export requires input.output ending in .${input.format}` };
+    }
+    if (input.version != null && !(Number.isInteger(input.version) && input.version >= 1)) {
+      return { ok: false, error: 'export input.version must be a positive integer (a kept version number)' };
+    }
+    if (input.overwrite != null && typeof input.overwrite !== 'boolean') {
+      return { ok: false, error: 'export input.overwrite must be a boolean' };
+    }
+  }
+  return { ok: true, action: args.action, input };
+}
+
+async function requestBridge(discovery, payload, signal) {
+  const response = await fetch(`http://127.0.0.1:${discovery.port}/command`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${discovery.token}` },
+    body: JSON.stringify(payload),
+    signal,
+  });
+  try {
+    const text = await response.text();
+    if (text.length > MAX_RESPONSE_BYTES) throw new Error('too large');
+    return { body: JSON.parse(text), status: response.status };
+  } catch {
+    throw new Error(`visualize bridge returned an invalid response (HTTP ${response.status})`);
+  }
+}
+
+function formatSuccess(body) {
+  const lines = [String(body.text ?? '')];
+  if (Array.isArray(body.tabs) && body.tabs.length) {
+    lines.push(...body.tabs.map((tab) => `${tab.id} ${tab.kind} ${tab.label} → ${tab.target}`));
+  }
+  if (typeof body.path === 'string' && body.path) lines.push(`path: ${body.path}`);
+  return lines.filter(Boolean).join('\n');
+}
+
+/** Execute one `visualize` tool call. */
+export async function executeVisualizeTool(args, options = {}) {
+  const validated = validateVisualizeArgs(args);
+  if (!validated.ok) return toolError(validated.error);
+  const sessionId = String(options.sessionId || '').trim();
+  if (!sessionId) return toolError('visualize session context is unavailable');
+  const payload = {
+    sessionId,
+    cwd: options.cwd || process.cwd(),
+    action: validated.action,
+    input: validated.input,
+  };
+  let discovery = readBridgeDiscovery(DISCOVERY_FILE);
+  if (!discovery) return toolError(unavailableMessage());
+  let result;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const timeout = AbortSignal.timeout(validated.action === 'export' ? EXPORT_REQUEST_TIMEOUT_MS : REQUEST_TIMEOUT_MS);
+    try {
+      result = await requestBridge(discovery, payload, options.signal ? AbortSignal.any([timeout, options.signal]) : timeout);
+      break;
+    } catch (error) {
+      if (error?.name === 'TimeoutError') return toolError('visualize bridge timed out');
+      if (options.signal?.aborted) return toolError('visualize command cancelled');
+      const replacement = readBridgeDiscovery(DISCOVERY_FILE);
+      if (attempt === 0 && bridgeDiscoveryChanged(discovery, replacement)) {
+        discovery = replacement;
+        continue;
+      }
+      return toolError(error?.message?.startsWith('visualize bridge') ? error.message : unavailableMessage());
+    }
+  }
+  const { body, status } = result;
+  if (!body?.ok) {
+    return toolError(String(body?.error || `visualize bridge request failed (HTTP ${status})`).replace(/^Error:\s*/, ''));
+  }
+  return { content: [{ type: 'text', text: formatSuccess(body) }] };
+}

package/src/runtime/visualize-bridge/tool-defs.mjs

@@ -0,0 +1,97 @@
+import { TOOL_SYNC_EXECUTION_CONTRACT } from '../shared/tool-execution-contract.mjs';
+
+/**
+ * `visualize` shows produced artifacts in the Mixdog desktop app's side panel
+ * over a loopback bridge. Deferred, and present only while the desktop
+ * Visualize bridge is up and the feature is on.
+ */
+export const TOOL_DEFS = [
+  {
+    name: 'visualize',
+    title: 'Mixdog Visualize',
+    description:
+      "Show the user any artifact you produced or changed (mockups, docs, decks, sheets, PDFs, images, video, local dev pages) in the desktop side panel beside the chat. Panel tabs auto-reload when a file changes, so re-opening after edits is unnecessary. " +
+      'open: input.targets (1-3 file paths, 2-3 = side-by-side comparison; or a single http(s) URL alone, never mixed with files or other URLs), optional label, optional version (show that kept version of a file tab read-only; each open/reload that changes the files keeps a version). close: optional tab (omit = all). ' +
+      'annotate: tab + add [{selector,label?}] | remove [selector] | clear; HTML pages only, never edits the file. capture: tab + output (.png path). ' +
+      'export: tab + format (png|pdf) + output (project-relative path ending .png/.pdf) + optional version (a kept version of the tab) + optional overwrite (true replaces an existing file, only under design/; otherwise an existing file is refused). Writes a record of the approved page inside the project and returns its project-relative path, size/dimensions and the page problems seen while rendering. A single HTML page (file, or inline html/chart) is rendered whole in a hidden window, so the tab need not be on screen (PDF: HTML pages only; PNG has a pixel cap, over it export pdf or shorten the page); any other tab exports as capture does (the displayed tab, PNG only). Same project containment as capture: links and paths outside the working directory are refused. ' +
+      'check: tab; HTML pages only; waits briefly for the page to settle and returns only its runtime problems (uncaught errors, unhandled rejections, CSP violations, console errors/warnings, missing local assets). ' +
+      'inspect: tab + optional viewport {width,height} (e.g. 375x812 to look at a mobile layout) + optional selector (scope); HTML pages with scripts/styles only (not static mermaid/svg/markdown). Returns a compact text read-out of the rendered page without a screenshot: viewport, landmarks and headings, interactive elements (role, accessible name, selector, x/y/w/h), and layout findings (horizontal overflow, clipped text, overlapping or tiny tap targets, low text contrast, images without alt, unlabeled inputs). Run it (desktop width and, for responsive designs, a mobile width) and fix the findings before reporting; `check` also says when findings exist. Secret field values are never included. ' +
+      'Any result about a tab ends with a "Page problems" section when the page has problems: fix them in the file and re-check before reporting; never report a page with unresolved problems as done. ' +
+      'HTML pages run their scripts, but outside network (CDNs, web fonts, APIs, any other http(s)/ws address) is blocked unless the user allows it for the tab, so mockups must be self-contained; a blocked request appears as a "blocked-network" page problem on open/check. ' +
+      'Direct renderers: instead of targets, open takes input.content {kind: mermaid|svg|chart|html|markdown, source, title?} (max 512 KiB; chart = an ECharts option as JSON) and shows it with no file written. ' +
+      'Prefer inline content for diagrams, charts and quick sketches; write a file for real mockups that need iteration, scripts or versioning on disk. ' +
+      'mermaid, svg and markdown render as static, sanitized output (no scripts, no network). chart (ECharts option JSON, interactive: tooltips, zoom) and html (scripts run) open as in-memory pages with the same protections as HTML file pages (outside network blocked, page problems captured); html content must be self-contained. Re-open with the same title to add a version. A render error (Mermaid parse error, bad chart JSON) is returned as a page problem: fix the source and open again. ' +
+      'Tweaks: an HTML page (file or inline html/chart) can declare adjustable parameters in <script type="application/json" id="mx-tweaks">[{id,label,type:color|range|select|toggle,var:"--name" or attr:"data-name",min,max,step,unit,options:[{value,label}],default}] (max 16, keep it to a few meaningful ones). The panel shows a Tweaks drawer and applies changes live to the page root (CSS variables / data attributes your CSS and script read); the chosen values come back with their next message under tweaks: to bake into the file. A malformed block is a "tweaks: <reason>" page problem. ' +
+      'Does not replace browser for clicking/typing. ' +
+      TOOL_SYNC_EXECUTION_CONTRACT,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['open', 'close', 'annotate', 'capture', 'export', 'check', 'inspect'] },
+        input: {
+          type: 'object',
+          properties: {
+            targets: {
+              type: 'array',
+              items: { type: 'string' },
+              minItems: 1,
+              maxItems: 3,
+              description: 'open: 1-3 project-relative/absolute file paths (side by side), or exactly one http(s) URL as the only target.',
+            },
+            content: {
+              type: 'object',
+              properties: {
+                kind: { type: 'string', enum: ['mermaid', 'svg', 'chart', 'html', 'markdown'] },
+                source: {
+                  type: 'string',
+                  maxLength: 524288,
+                  description: 'Diagram text, SVG/HTML/Markdown source, or an ECharts option as JSON (chart).',
+                },
+                title: { type: 'string', description: 'Tab title; re-opening the same title adds a version.' },
+              },
+              required: ['kind', 'source'],
+              additionalProperties: false,
+              description: 'open: render this directly instead of files. Exclusive with targets.',
+            },
+            label: { type: 'string', description: 'open: tab label.' },
+            version: {
+              type: 'integer',
+              minimum: 1,
+              description: 'open (file tabs): kept version number to show read-only instead of the live files. export: kept version number to render instead of the live page.',
+            },
+            tab: { type: 'string', description: 'Tab id from open (close: omit for all).' },
+            add: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: { selector: { type: 'string' }, label: { type: 'string' } },
+                required: ['selector'],
+                additionalProperties: false,
+              },
+              description: 'annotate: CSS selectors to outline.',
+            },
+            remove: { type: 'array', items: { type: 'string' }, description: 'annotate: selectors to un-outline.' },
+            clear: { type: 'boolean', description: 'annotate: remove all outlines.' },
+            output: { type: 'string', description: 'capture: project path ending .png. export: project path ending .png or .pdf (matching format).' },
+            format: { type: 'string', enum: ['png', 'pdf'], description: 'export: file format.' },
+            overwrite: { type: 'boolean', description: 'export: replace an existing output file; honored only for paths under design/.' },
+            viewport: {
+              type: 'object',
+              properties: {
+                width: { type: 'integer', minimum: 200, maximum: 3000 },
+                height: { type: 'integer', minimum: 200, maximum: 4000 },
+              },
+              required: ['width'],
+              additionalProperties: false,
+              description: 'inspect: size to lay the page out at (height defaults to 800); omit for the panel\'s current size.',
+            },
+            selector: { type: 'string', maxLength: 500, description: 'inspect: CSS selector scoping the read-out to one subtree.' },
+          },
+          additionalProperties: false,
+        },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+  },
+];

package/src/session-runtime/boot/apis.mjs

@@ -58,6 +58,8 @@ import { loadInstructionFilesContext } from '../../runtime/agent/orchestrator/co
 import { createSessionTurnApi } from '../session-turn-api.mjs';
 import { createGoalFacadeApi } from '../goal-facade-api.mjs';
 import { createRuntimeReviewApi } from '../runtime-review-api.mjs';
+import { createWorkspaceTransitions, refreshWorkspacePrompt } from '../workspace/transitions.mjs';
+import { saveSession } from '../../runtime/agent/orchestrator/session/store.mjs';
 import { bootProfile } from '../boot-profile.mjs';
 import { STANDALONE_DATA_DIR } from '../runtime-paths.mjs';
 import {
@@ -98,6 +100,7 @@ export function wireApis(boot) {
   };
   boot.modelRouteApi = modelRouteApiFor(boot);
   boot.workflowAgentsApi = workflowAgentsApiFor(boot);
+  boot.workspaceApi = workspaceApiFor(boot);
   boot.sessionTurnApi = sessionTurnApiFor(boot);
   const getFacadeSessionId = () => boot.rt.session?.id || boot.rt.reservedSessionId || null;
   boot.runtimeReviewApi = createRuntimeReviewApi({
@@ -364,6 +367,8 @@ function lifecycleApiFor(boot) {
     invalidateContextStatusCache: boot.invalidateContextStatusCache,
     invalidatePreSessionToolSurface: boot.invalidatePreSessionToolSurface,
     applyResolvedCwd: boot.applyResolvedCwd,
+    // Created after the lifecycle API, so resolved at call time.
+    cleanupDeletedSessionWorktree: (sessionId) => boot.workspaceApi?.cleanupDeletedSession?.(sessionId),
     resolveRoute,
     applyDeferredToolSurface,
     beginRoutePreparation: (task) => routePreparation.start(task),
@@ -486,9 +491,39 @@ function workflowAgentsApiFor(boot) {
   });
 }
 
+// The Lead workspace transition authority (worktree / project branch / remove)
+// and the turn-start workspace gate. Facade-facing methods are spread by
+// buildFacade; prepareTurnWorkspace feeds the turn runner.
+function workspaceApiFor(boot) {
+  const { rt } = boot;
+  return createWorkspaceTransitions({
+    getSession: () => rt.session,
+    getReservedSessionId: () => rt.reservedSessionId,
+    getCurrentCwd: () => rt.currentCwd,
+    getDesktopSession: () => rt.desktopSession,
+    getConfig: () => rt.config,
+    createCurrentSession: (reason) => boot.createCurrentSession(reason),
+    applyResolvedCwd: (cwd) => boot.applyResolvedCwd(cwd),
+    persistSession: (session) => saveSession(session, { immediate: true }),
+    refreshWorkspaceContext: (session, cwd) =>
+      refreshWorkspacePrompt(session, cwd, { loadCoreMemoryContext: boot.loadCoreMemoryContext }),
+    invalidateCaches: () => {
+      boot.invalidateContextStatusCache();
+      boot.invalidatePreSessionToolSurface();
+    },
+    getActiveTurnCount: () => rt.activeTurnCount || 0,
+    agentStatusState: boot.agentStatusState,
+    updateLeadWorkerCwd: (sessionId, cwd) => boot.agentTool?.updateLeadWorkerCwd?.(sessionId, cwd),
+    sessionManager: boot.mgr,
+    initialIntent: boot.params.worktree,
+  });
+}
+
 function sessionTurnApiFor(boot) {
   const { rt, tunables, remoteTranscript, routePreparation } = boot;
   return createSessionTurnApi({
+    prepareTurnWorkspace: boot.workspaceApi.prepareTurnWorkspace,
+    admitTurnWorkspace: boot.workspaceApi.admitTurnWorkspace,
     getSession: () => rt.session,
     setSession: boot.adoptSession,
     getCurrentCwd: () => rt.currentCwd,

package/src/session-runtime/boot/config.mjs

@@ -30,8 +30,10 @@ export async function resolveConfig(boot) {
     model: params.model,
     effort: params.effort,
     fast: params.fast,
+    autoEffort: params.autoEffort,
     modelParameters: params.modelParameters,
     contextPercent: params.contextPercent,
+    contextTokens: params.contextTokens,
     selectedContextWindow: params.selectedContextWindow,
   }));
   configureLocalProviderIdleTtl(rt.config.providers?.[LOCAL_PROVIDER_ID]?.idleTtlSeconds);

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

@@ -27,6 +27,26 @@ export function buildFacade(boot) {
       ...boot.modelRouteApi,
       ...boot.workflowAgentsApi,
       ...boot.sessionTurnApi,
+      // A surface registers its idle auto-clear here; returns an unregister.
+      setCompletionWakeGate: (gate) => {
+        const next = typeof gate === 'function' ? gate : null;
+        boot.completionWakeGate = next;
+        return () => {
+          if (boot.completionWakeGate === next) boot.completionWakeGate = null;
+        };
+      },
+      applyWorkspaceTransition: boot.workspaceApi.applyWorkspaceTransition,
+      getWorkspace: boot.workspaceApi.getWorkspace,
+      getBranchMenu: boot.workspaceApi.getBranchMenu,
+      getProjectBranchMenu: boot.workspaceApi.getProjectBranchMenu,
+      selectBranch: boot.workspaceApi.selectBranch,
+      selectProjectBranch: boot.workspaceApi.selectProjectBranch,
+      mergeProjectBranch: boot.workspaceApi.mergeProjectBranch,
+      requestWorktree: boot.workspaceApi.requestWorktree,
+      mergeWorkspace: boot.workspaceApi.mergeWorkspace,
+      removeWorktree: boot.workspaceApi.removeWorktree,
+      listWorktrees: boot.workspaceApi.listWorktrees,
+      pruneWorktrees: boot.workspaceApi.pruneWorktrees,
       claimSetupRequest: setupTool.claimSetupRequest,
       isSetupRequestActive: setupTool.isSetupRequestActive,
       completeSetupRequest: setupTool.completeSetupRequest,

package/src/session-runtime/boot/infrastructure.mjs

@@ -119,6 +119,7 @@ function wireNotifications(boot) {
     getCurrentSessionId: () => rt.session?.id || rt.reservedSessionId || null,
     getTurnApi: () => boot.sessionTurnApi,
     getOwnerLifecycle: (sessionId) => ownerLifecycle(rt, sessionId),
+    beforeWake: (sessionId) => boot.completionWakeGate?.(sessionId),
   });
   const {
     emitRuntimeNotification,

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

@@ -20,6 +20,7 @@ export function wireSessionLifecycle(boot) {
       params.model !== undefined ||
       params.effort !== undefined ||
       params.fast !== undefined ||
+      params.autoEffort !== undefined ||
       params.modelParameters !== undefined,
     invalidatePreSessionToolSurface: boot.invalidatePreSessionToolSurface,
     invalidateOutputStyleStatusCache: boot.invalidateOutputStyleStatusCache,

package/src/session-runtime/boot/tools.mjs

@@ -20,6 +20,7 @@ import { TOOL_DEFS as TERMINAL_BRIDGE_TOOL_DEFS } from '../../runtime/terminal-b
 import { TOOL_DEFS as OFFICE_TOOL_DEFS } from '../../runtime/office/tool-defs.mjs';
 import { TOOL_DEFS as MEDIA_TOOL_DEFS } from '../../runtime/media/tool-defs.mjs';
 import { TOOL_DEFS as TIDY_TOOL_DEFS } from '../../runtime/tidy/tool-defs.mjs';
+import { TOOL_DEFS as VISUALIZE_BRIDGE_TOOL_DEFS } from '../../runtime/visualize-bridge/tool-defs.mjs';
 import { SETUP_TOOL_DEFS } from '../setup-tool/tool-defs.mjs';
 import { createSetupToolExecutor } from '../setup-tool/executor.mjs';
 import { bootProfile } from '../boot-profile.mjs';
@@ -156,6 +157,7 @@ function wireToolSurface(boot) {
     officeToolDefs: OFFICE_TOOL_DEFS,
     mediaToolDefs: MEDIA_TOOL_DEFS,
     tidyToolDefs: TIDY_TOOL_DEFS,
+    visualizeToolDefs: VISUALIZE_BRIDGE_TOOL_DEFS,
     setupToolDefs: SETUP_TOOL_DEFS,
     goalTools: goalRuntime.tools,
     agentTools: agentTool.tools,
@@ -246,6 +248,8 @@ function wireInternalTools(boot) {
       mcpStatus: boot.mcpStatus,
       applyResolvedCwd: boot.applyResolvedCwd,
       skillToolContent: boot.skillToolContent,
+      // Late-bound: the workspace authority is built with the API slices.
+      getWorkspaceApi: () => boot.workspaceApi || null,
     }),
   });
   Object.assign(boot, { setupTool, disposeInternalTools });

package/src/session-runtime/config-lifecycle.mjs

@@ -10,6 +10,7 @@
 import { withGrandfatheredBuiltins } from '../runtime/agent/orchestrator/runtime-core/builtin-features.mjs';
 import { webSearchRouteOrDefault } from '../runtime/agent/orchestrator/runtime-core/workflow.mjs';
 import { applyConfigPatch } from '../runtime/shared/config-patch.mjs';
+import { normalizeContextTokens } from '../runtime/shared/llm/default-context-window.mjs';
 import { withEffectiveDisabledAgents, withStoredDisabledAgents } from '../runtime/shared/agent-route-config.mjs';
 import {
   DEFAULT_MAINTENANCE,
@@ -40,19 +41,27 @@ export function resolveInitialConfigState({
   model,
   effort,
   fast,
+  autoEffort,
   modelParameters,
   contextPercent,
+  contextTokens,
   selectedContextWindow,
 }) {
   const config = withGrandfatheredBuiltins(
     initialConfig && typeof initialConfig === 'object' ? initialConfig : loadConfig()
   );
+  // A requested percent replaces a saved token window; requested tokens
+  // replace both (resolveRouteContextState lets tokens win).
+  const { contextTokens: savedTokens, ...resolved } = resolveRoute(config, { provider, model });
+  const tokens = normalizeContextTokens(contextTokens) || (contextPercent > 0 ? undefined : savedTokens);
   return {
     config,
     route: {
-      ...resolveRoute(config, { provider, model }),
+      ...resolved,
+      ...(tokens ? { contextTokens: tokens } : {}),
       ...(effort === undefined ? {} : { effort: effort || null }),
       ...(fast === true || fast === false ? { fast } : {}),
+      ...(autoEffort === true || autoEffort === false ? { autoEffort } : {}),
       ...(modelParameters && typeof modelParameters === 'object' ? { modelParameters: { ...modelParameters } } : {}),
       ...(contextPercent > 0 ? { contextPercent } : {}),
       ...(selectedContextWindow > 0 ? { selectedContextWindow } : {}),

package/src/session-runtime/cwd-plugins/cwd-apply.mjs

@@ -1,6 +1,9 @@
 // cwd-plugins/cwd-apply.mjs — resolving a requested cwd and retargeting the
 // live session to it (project selection persistence, code-graph prewarm,
 // CwdChanged hook) without recreating the session.
+import { setWorkspaceCwdLock } from '../workspace/admission-gate.mjs';
+import { workspaceForProjectSelection } from '../workspace/workspace-state.mjs';
+
 export function createCwdApply({
   getCurrentCwd,
   setCurrentCwd,
@@ -31,9 +34,16 @@ export function createCwdApply({
   }
 
   function persistProjectSelection(session, currentCwd) {
+    // A Lead in its worktree keeps the registered Project as projectPath; a
+    // switch elsewhere leaves the worktree at a new workspace revision.
+    const { workspace, projectPath } = workspaceForProjectSelection(session, currentCwd);
+    if (session && workspace !== (session.workspace ?? null)) {
+      session.workspace = workspace;
+      setWorkspaceCwdLock(session.id, null);
+    }
     const desktop = getDesktopSession?.() || session?.desktopSession;
     if (desktop && typeof desktop === 'object') {
-      const nextDesktop = { classification: 'project', projectPath: currentCwd };
+      const nextDesktop = { classification: 'project', projectPath };
       setDesktopSession?.(nextDesktop);
       if (session) session.desktopSession = nextDesktop;
     }

package/src/session-runtime/global-extensions.mjs

@@ -16,11 +16,11 @@ export function subscribeGlobalExtensionChanges(listener) {
   };
 }
 
-export async function publishGlobalExtensionChange(kind, originId = null) {
+export async function publishGlobalExtensionChange(kind, originId = null, detail = null) {
   const jobs = [];
   for (const [id, listener] of subscribers) {
     if (id === originId) continue;
-    jobs.push(Promise.resolve().then(() => listener(kind)));
+    jobs.push(Promise.resolve().then(() => listener(kind, detail)));
   }
   await Promise.allSettled(jobs);
 }

package/src/session-runtime/internal-tool-executor/bridge-tools.mjs

@@ -3,7 +3,8 @@
 import { executeBrowserTool } from '../../runtime/browser-bridge/client.mjs';
 import { executeComputerTool } from '../../runtime/computer-bridge/client.mjs';
 import { executeTerminalTool } from '../../runtime/terminal-bridge/client.mjs';
-import { featureEnvOverride } from '../../runtime/agent/orchestrator/runtime-core/config-helpers.mjs';
+import { executeVisualizeTool } from '../../runtime/visualize-bridge/client.mjs';
+import { featureEnvOverride, moduleEnabled } from '../../runtime/agent/orchestrator/runtime-core/config-helpers.mjs';
 import { createCallerContextResolvers } from './caller-context.mjs';
 
 export function createBridgeToolHandlers({ rt }) {
@@ -50,5 +51,29 @@ export function createBridgeToolHandlers({ rt }) {
     });
   };
 
-  return { browser, browser_devtools: browser, computer, terminal };
+  const visualize = async (args, { callerCtx, callerCwd }) => {
+    if (environmentDisabled(callerCtx, 'MIXDOG_FEATURE_VISUALIZE')) {
+      throw new Error('the visualize tool is disabled in this environment');
+    }
+    // A conversation keeps its frozen tool list, so honor the Settings toggle
+    // at execution time too (an env override wins, as in builtinFeatureActive).
+    if (!(featureEnvOverride('MIXDOG_FEATURE_VISUALIZE') ?? moduleEnabled(rt.config, 'visualize', true))) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'Error: Visualize is turned off in Settings by the user. Do not turn it back on unless the user asks; give the file path instead.',
+          },
+        ],
+        isError: true,
+      };
+    }
+    return await executeVisualizeTool(args, {
+      sessionId: sessionIdFor(callerCtx),
+      cwd: callerCwd,
+      signal: signalFor(callerCtx),
+    });
+  };
+
+  return { browser, browser_devtools: browser, computer, terminal, visualize };
 }

package/src/session-runtime/internal-tool-executor/workspace-tools.mjs

@@ -5,9 +5,40 @@ import { resolve } from 'node:path';
 import { listProjects } from '../../runtime/shared/projects.mjs';
 import { clean } from '../../runtime/agent/orchestrator/runtime-core/session-text.mjs';
 
-export function createWorkspaceToolHandlers({ rt, goalRuntime, agentTool, notifyFnForSession, applyResolvedCwd }) {
+export function createWorkspaceToolHandlers({
+  rt,
+  goalRuntime,
+  agentTool,
+  notifyFnForSession,
+  applyResolvedCwd,
+  getWorkspaceApi = () => null,
+}) {
+  // The Lead's own worktree, on the user's request: the same authority the
+  // branch chip menu drives, tolerating the calling turn but nothing else
+  // running (workers, background shells).
+  const worktreeAction = async (action, args, callerCtx) => {
+    const workspace = getWorkspaceApi();
+    if (!workspace) throw new Error(`cwd: ${action} is unavailable in this runtime`);
+    const callerSessionId = callerCtx?.callerSessionId || rt.session?.id || null;
+    if (!rt.session?.id || callerSessionId !== rt.session.id) {
+      throw new Error(`cwd: ${action} belongs to the Lead session`);
+    }
+    const result =
+      action === 'merge-worktree'
+        ? await workspace.mergeWorkspace({ confirmed: true }, { ownTurn: true })
+        : action === 'remove-worktree'
+          ? await workspace.removeWorktree({ force: args?.force === true }, { ownTurn: true })
+          : action === 'list-worktrees'
+            ? await workspace.listWorktrees()
+            : await workspace.pruneWorktrees();
+    return JSON.stringify({ action, cwd: rt.currentCwd, result }, null, 2);
+  };
+
+  const WORKTREE_ACTIONS = new Set(['merge-worktree', 'remove-worktree', 'list-worktrees', 'prune-worktrees']);
+
   const cwd = async (args, { callerCtx, callerCwd }) => {
     const action = clean(args?.action || (args?.path ? 'set' : 'get')).toLowerCase();
+    if (WORKTREE_ACTIONS.has(action)) return worktreeAction(action, args, callerCtx);
     let currentCwd = callerCwd;
     if (action === 'list') {
       return JSON.stringify(

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

@@ -31,6 +31,7 @@ export function createInternalToolExecutor({
   mcpStatus,
   applyResolvedCwd,
   skillToolContent,
+  getWorkspaceApi,
 }) {
   const handlers = {
     ...createBridgeToolHandlers({ rt }),
@@ -46,7 +47,14 @@ export function createInternalToolExecutor({
       mcpStatus,
       skillToolContent,
     }),
-    ...createWorkspaceToolHandlers({ rt, goalRuntime, agentTool, notifyFnForSession, applyResolvedCwd }),
+    ...createWorkspaceToolHandlers({
+      rt,
+      goalRuntime,
+      agentTool,
+      notifyFnForSession,
+      applyResolvedCwd,
+      getWorkspaceApi,
+    }),
   };
 
   // Settings-disabled features are refused for model-initiated calls before

package/src/session-runtime/lifecycle/session-catalog.mjs

@@ -8,7 +8,12 @@ import {
   isRootLeadSession,
 } from '../../runtime/agent/orchestrator/session/store-summary-visibility.mjs';
 import { listSessionHeartbeatMtimes } from '../../runtime/agent/orchestrator/session/store/paths-heartbeat.mjs';
-import { sessionMessageText, isSessionPreviewNoise, cleanSessionPreview, clean } from '../../runtime/agent/orchestrator/runtime-core/session-text.mjs';
+import {
+  sessionMessageText,
+  isSessionPreviewNoise,
+  cleanSessionPreview,
+  clean,
+} from '../../runtime/agent/orchestrator/runtime-core/session-text.mjs';
 
 const VISIBLE_OWNERS = ['cli', 'user', 'mixdog'];
 
@@ -58,6 +63,8 @@ function leadSessionRow(s, heartbeatMtimes) {
   // it remains an ordinary resumable session, not a child dispatch.
   if (!isRootLeadSession(s) && owner && !VISIBLE_OWNERS.includes(owner)) return null;
   const sourceType = clean(s.sourceType || '').toLowerCase();
+  // One-shot `mixdog exec` runs are never resumable conversations.
+  if (sourceType === 'exec') return null;
   if (!isLeadShaped(s, owner, sourceType)) return null;
   const { preview, messageCount } = previewOf(s);
   if (!preview && messageCount === 0) return null;