mixdog 1.3.5 → 1.4.1

package/src/runtime/shared/session-turn-prelude.mjs

@@ -0,0 +1,18 @@
+// What must land in a session's transcript right before its next turn's
+// prompt, whoever starts that turn: the daemon registers one prelude
+// (agent-home-delivery.mjs postBeforeAgentTurn) and the prompt queue's drain
+// (tui/session/session-flow/drain.mjs) awaits it before presenting a batch.
+
+let prelude = null;
+
+/** Register `fn(sessionId)` (null or a promise per turn); a non-function clears it. */
+export function setSessionTurnPrelude(fn) {
+  prelude = typeof fn === 'function' ? fn : null;
+}
+
+/** The prelude's work before a turn of `sessionId`: a promise, or null when
+ *  there is none (no await, so a turn with nothing owed starts as before). */
+export function sessionTurnPrelude(sessionId) {
+  if (!prelude || !sessionId) return null;
+  return prelude(String(sessionId)) || null;
+}

package/src/runtime/shared/tool-card-model/agent-surface.mjs

@@ -38,9 +38,7 @@ function agentNameFromResult(resultText) {
 // The agent identity a card shows: the call's own fields, else the result
 // envelope when the call only carried a tag/task id.
 function agentDisplayName(args, resultText = '') {
-  return (
-    titleizeAgentName(args?.agent || args?.subagent_type || args?.name || '') || agentNameFromResult(resultText)
-  );
+  return titleizeAgentName(args?.agent || args?.subagent_type || args?.name || '') || agentNameFromResult(resultText);
 }
 
 function agentModelLabel(args) {

package/src/runtime/shared/tool-card-model/card-status.mjs

@@ -7,13 +7,26 @@ import { backgroundTaskFailureStatusLabel } from '../err-text.mjs';
 import { agentTerminalDetail, isAgentTool } from './agent-surface.mjs';
 import { backgroundTaskElapsed, backgroundTaskFailureDetail, isBackgroundTaskTool } from './background-task.mjs';
 import { shellDisplayStatus } from './shell-surface.mjs';
-import { normalizeTerminalStatus, resultControlStatus, resultEnvelopeStatus, shellResultElapsed } from './terminal-status.mjs';
+import {
+  normalizeTerminalStatus,
+  resultControlStatus,
+  resultEnvelopeStatus,
+  shellResultElapsed,
+} from './terminal-status.mjs';
 import { mediaTerminalStatus } from './media-result.mjs';
 import { gitTerminalStatus } from './git-result.mjs';
 import { isUserControlCancellation } from '../tool-status.mjs';
 
 // Tools whose result opens with a task/bridge envelope that reports the call's status.
-const ENVELOPE_STATUS_TOOLS = new Set(['agent', 'bridge', 'task', 'web_search', 'search_query', 'image_query', 'web_search_call']);
+const ENVELOPE_STATUS_TOOLS = new Set([
+  'agent',
+  'bridge',
+  'task',
+  'web_search',
+  'search_query',
+  'image_query',
+  'web_search_call',
+]);
 
 function shellFragments(base, display, isShellSurface) {
   if (!isShellSurface) return { shellStatus: '', shellElapsed: '' };

package/src/runtime/shared/tool-result-summary.mjs

@@ -526,20 +526,7 @@ function summarizeCodeGraphResult({ text, translate }) {
   return null;
 }
 
-function summarizeFetchResult({ text, trimmed, args, normalized, translate }) {
-  // Channel `fetch` (Discord message fetch — args carry channel/messageId/limit,
-  // never url/uri) is not a WEB fetch: the status/size probes would miss and
-  // the result fall to raw JSON, so it takes the generic JSON/text summarizer.
-  if (normalized === 'fetch') {
-    const a = parseToolArgs(args);
-    const isChannelFetch =
-      !firstText(a.url, a.uri) && Boolean(firstText(a.channel, a.channelId, a.chatId, a.messageId) || a.limit != null);
-    if (isChannelFetch) {
-      const n = countNonEmptyLines(text);
-      if (trimmed && looksLineOriented(text) && n > 0) return countLabel(translate, n, 'message');
-      return summarizeGenericResult(text, translate);
-    }
-  }
+function summarizeFetchResult({ text }) {
   // Status: require a status-like context (HTTP NNN, "Status: NNN",
   // or "NNN OK"/"NNN Not Found") rather than any bare 3-digit number.
   const status =
@@ -661,7 +648,7 @@ const summarizeAskUserResult = ({ text, translate }) => {
 
 const TOOL_RESULT_SUMMARIZERS = new Map(
   [
-    [['ask_user'], summarizeAskUserResult],
+    [['ask_user', 'handoff_user'], summarizeAskUserResult],
     [['read', 'view_image', 'read_mcp_resource'], summarizeReadResult],
     [['apply_patch'], summarizePatchResult],
     [['grep'], summarizeGrepResult],

package/src/runtime/shared/tool-surface.mjs

@@ -151,6 +151,7 @@ export function displayToolName(name, args = {}) {
     case 'request_user_input':
       return 'Ask User';
     case 'ask_user':
+    case 'handoff_user':
       return 'Question';
     case 'update_plan':
       return 'Plan';
@@ -239,6 +240,8 @@ export function summarizeToolArgs(name, args, { max = DEFAULT_SUMMARY_MAX } = {}
       return summarizeGithub(a, max);
     case 'goal':
       return compactParts([String(a.action || ''), truncateToolText(a.objective, max)]);
+    case 'handoff_user':
+      return '';
     case 'ask_user':
       return truncateToolText(
         (Array.isArray(a.questions) ? a.questions : [])

package/src/runtime/shared/tool-work-units.mjs

@@ -91,6 +91,7 @@ const TOOL_CATEGORY = new Map([
   ['goal', 'Setup'],
   ['request_user_input', 'Setup'],
   ['ask_user', 'Setup'],
+  ['handoff_user', 'Setup'],
   ['update_plan', 'Setup'],
   ['skill', 'Skill'],
   ['skill_execute', 'Skill'],
@@ -734,6 +735,7 @@ const TOOL_UNITS = new Map([
   ['code_graph', codeGraphUnit],
   ['request_user_input', () => unitDescriptor('Setup', { active: 'Asking', done: 'Asked', noun: 'user' })],
   ['ask_user', () => unitDescriptor('Setup', { active: 'Asking', done: 'Asked', noun: 'user' })],
+  ['handoff_user', () => unitDescriptor('Setup', { active: 'Asking', done: 'Asked', noun: 'user' })],
   ['update_plan', () => unitDescriptor('Setup', { active: 'Updating', done: 'Updated', noun: 'plan' })],
   ['list_mcp_resources', () => unitDescriptor('Setup', { active: 'Listing', done: 'Listed', noun: 'MCP resource' })],
   [

package/src/runtime/shared/turn-snapshot-store.mjs

@@ -117,16 +117,23 @@ function recordPath(sessionId) {
 function chain(sessionId, task) {
   const previous = writeChains.get(sessionId) || Promise.resolve();
   const next = previous.then(task, task);
-  writeChains.set(
-    sessionId,
-    next.then(
-      () => undefined,
-      () => undefined
-    )
+  const settled = next.then(
+    () => undefined,
+    () => undefined
   );
+  writeChains.set(sessionId, settled);
+  // A settled chain with nothing queued behind it holds no order to keep.
+  void settled.then(() => {
+    if (writeChains.get(sessionId) === settled) writeChains.delete(sessionId);
+  });
   return next;
 }
 
+/** Sessions with a write chain still held (tests). */
+export function _turnSnapshotWriteChainCountForTest() {
+  return writeChains.size;
+}
+
 async function readRecordFile(path) {
   try {
     const parsed = JSON.parse(await readFile(path, 'utf8'));

package/src/runtime/shared/worktrees/contract.mjs

@@ -27,6 +27,7 @@ const WORKTREE_ENTRY_STATES = Object.freeze(['creating', 'ready', 'deleting', 'r
 export const WORKTREE_ERROR_CODES = Object.freeze({
   WORKTREE_BUSY_JOBS: 'WORKTREE_BUSY_JOBS',
   WORKTREE_BRANCH_OCCUPIED: 'WORKTREE_BRANCH_OCCUPIED',
+  WORKTREE_DEFAULT_BRANCH: 'WORKTREE_DEFAULT_BRANCH',
   WORKTREE_DISK_INSUFFICIENT: 'WORKTREE_DISK_INSUFFICIENT',
   WORKTREE_LARGE_REPO_CONFIRM: 'WORKTREE_LARGE_REPO_CONFIRM',
   WORKTREE_DIRTY: 'WORKTREE_DIRTY',
@@ -54,6 +55,8 @@ export const WORKTREE_ERROR_CODES = Object.freeze({
 const DEFAULT_ERROR_MESSAGES = Object.freeze({
   WORKTREE_BUSY_JOBS: 'The session has running jobs; wait for them or stop them before changing its workspace.',
   WORKTREE_BRANCH_OCCUPIED: 'The branch is checked out in another worktree.',
+  WORKTREE_DEFAULT_BRANCH:
+    "The repository's default branch can't be opened in a worktree: the project folder could not switch to it while the worktree exists. Check it out in the project folder, or create a new branch for the worktree.",
   WORKTREE_DISK_INSUFFICIENT: 'Not enough free disk space to create the worktree.',
   WORKTREE_LARGE_REPO_CONFIRM: 'The repository is large; confirm before creating a worktree.',
   WORKTREE_DIRTY: 'The worktree has uncommitted changes.',
@@ -193,7 +196,7 @@ function record(value, name) {
  * @property {string|null} worktreeId Managed worktree id; null when running in the project folder.
  * @property {string|null} branch Checked-out branch at `cwd`; null when detached or not a repository.
  * @property {string|null} baseCommit Commit the worktree branch was created from.
- * @property {string|null} mergeTarget Branch the worktree merges into (the project folder's branch).
+ * @property {string|null} mergeTarget Branch the worktree merges into (the project folder's branch); null for an existing branch until a merge records it.
  * @property {number} revision Monotonic; advances on every committed workspace change.
  * @property {WorkspaceTransition} transition In-flight transition marker.
  */

package/src/runtime/shared/worktrees/git.mjs

@@ -186,6 +186,21 @@ export async function localBranches(cwd, { signal, prefix = '' } = {}) {
   return lines(result.stdout);
 }
 
+/** The local branch names the repository's remotes declare as their default (`refs/remotes/<remote>/HEAD`). */
+export async function remoteDefaultBranches(cwd) {
+  const result = await runGit(cwd, ['for-each-ref', '--format=%(refname) %(symref)', 'refs/remotes'], {
+    readOnly: true,
+  });
+  const names = [];
+  for (const line of lines(result.stdout)) {
+    const [ref, target] = line.split(' ');
+    if (!ref.endsWith('/HEAD') || !target) continue;
+    const remote = ref.slice(0, -'HEAD'.length);
+    if (target.startsWith(remote)) names.push(target.slice(remote.length));
+  }
+  return names;
+}
+
 export async function validBranchName(cwd, branch) {
   if (typeof branch !== 'string' || !branch.trim() || branch.startsWith('-')) return false;
   const result = await runGit(cwd, ['check-ref-format', '--branch', branch], { allowFailure: true });

package/src/runtime/shared/worktrees/manager.mjs

@@ -49,6 +49,7 @@ import {
   WORKTREE_SNAPSHOT_KIND,
   worktreeBranchName,
   worktreeError,
+  worktreeRefusal,
 } from './contract.mjs';
 import {
   assertCarryable,
@@ -68,6 +69,7 @@ import {
   listWorktrees,
   localBranches,
   parseStatusPaths,
+  remoteDefaultBranches,
   runGit,
   throwIfAborted,
   validBranchName,
@@ -757,6 +759,11 @@ export async function resolveBranchWorkspace({
         repoCommonDir: repo.repoCommonDir,
       };
     }
+    // Checked out in a managed worktree, the branch a remote declares its
+    // default would stay locked away from the project folder.
+    if (!create && (await remoteDefaultBranches(repo.projectPath)).includes(branch)) {
+      throw worktreeError('WORKTREE_DEFAULT_BRANCH', undefined, { branch });
+    }
     const entry = await createManagedWorktree({
       projectPath,
       sessionId,
@@ -770,10 +777,6 @@ export async function resolveBranchWorkspace({
       confirmLarge,
       signal,
     });
-    const record = await getRecord(entry.id);
-    record.mergeTarget = repo.currentBranch;
-    await putRecord(record);
-    entry.mergeTarget = repo.currentBranch;
     return { path: entry.path, branch, entry, created: true, repoCommonDir: repo.repoCommonDir };
   });
 }
@@ -1219,7 +1222,10 @@ export async function createManagedWorktree({
         path: managedWorktreePath(repo.repoCommonDir, slug),
         branch,
         baseCommit,
-        mergeTarget,
+        // An existing branch has no base it branched from: it merges where a
+        // merge first takes it (recorded then), and until that its own work is
+        // what it gained here since baseCommit.
+        mergeTarget: existingBranch ? null : mergeTarget,
         createdAt: Date.now(),
         ownerSessionId: owner.sessionId,
         existingBranch,
@@ -1400,9 +1406,7 @@ export async function removeSessionSnapshots(sessionId, { txIds = null } = {}) {
   const only = txIds ? new Set(txIds) : null;
   const held = Object.values((await readRegistry()).entries).filter(
     (record) =>
-      record.kind === WORKTREE_SNAPSHOT_KIND &&
-      record.holderSessionId === sessionId &&
-      (!only || only.has(record.txId))
+      record.kind === WORKTREE_SNAPSHOT_KIND && record.holderSessionId === sessionId && (!only || only.has(record.txId))
   );
   for (const record of held) {
     const row = { id: record.id, txId: record.txId };
@@ -1854,19 +1858,59 @@ export async function removeManagedWorktree({
       if (!current && !expected) throw worktreeError('WORKTREE_MISSING', undefined, { entryId });
       return skipped;
     }
-    assertNotShared(current, sessionId);
-    if (current.state === 'creating' || current.state === 'recovery') {
-      const rollback = await rollbackCreation(current);
-      return rollback.complete ? { removed: true } : { removed: false, retryable: true, remaining: rollback.remaining };
+    return removeLocked(current, { force, sessionId, preserveBranch, safeOnly });
+  });
+}
+
+/** The removal of `current`, under its repository lock. */
+async function removeLocked(current, { force, sessionId, preserveBranch = false, safeOnly = false }) {
+  assertNotShared(current, sessionId);
+  if (current.state === 'creating' || current.state === 'recovery') {
+    const rollback = await rollbackCreation(current);
+    return rollback.complete ? { removed: true } : { removed: false, retryable: true, remaining: rollback.remaining };
+  }
+  // Every deletion attempt of a snapshot, a resumed one included, waits
+  // for (refuses on) its consumers.
+  const release = current.kind === WORKTREE_SNAPSHOT_KIND ? holdSnapshotFolder(current) : () => {};
+  try {
+    return await decideAndFinishDeletion(current, { force, preserveBranch, safeOnly });
+  } finally {
+    release();
+  }
+}
+
+/**
+ * Remove a worktree whose owner is gone, on an explicit request: under the
+ * repository lock its retention is read again right before anything moves,
+ * so an owner that came back (a live session, a running lease holder) or a
+ * session the store still keeps it for refuses (WORKTREE_BUSY_JOBS). Then
+ * the ordinary removal guards apply (dirty or unmerged work needs `force`).
+ * @param {{ entryId: string, force?: boolean, liveSessionIds?: string[], retainedSessionIds?: string[] }} input
+ */
+export async function removeOrphanedWorktree({
+  entryId,
+  force = false,
+  liveSessionIds = [],
+  retainedSessionIds = [],
+} = {}) {
+  const record = await getRecord(entryId);
+  if (!record) throw worktreeError('WORKTREE_MISSING', undefined, { entryId });
+  return withRepoLock(record.repoCommonDir, async () => {
+    const current = await getRecord(entryId);
+    if (!current || current.kind === WORKTREE_SNAPSHOT_KIND) {
+      throw worktreeError('WORKTREE_MISSING', undefined, { entryId });
     }
-    // Every deletion attempt of a snapshot, a resumed one included, waits
-    // for (refuses on) its consumers.
-    const release = current.kind === WORKTREE_SNAPSHOT_KIND ? holdSnapshotFolder(current) : () => {};
-    try {
-      return await decideAndFinishDeletion(current, { force, preserveBranch, safeOnly });
-    } finally {
-      release();
+    const { ownerLive, removable } = await retentionOf(current, new Set(liveSessionIds), new Set(retainedSessionIds));
+    if (ownerLive) throw worktreeRefusal('workspace-lease', { entryId });
+    if (!removable) {
+      // Retained recovery data names itself; otherwise sessions still keep it.
+      await assertRecoveryStoresClear(current);
+      throw worktreeRefusal('workspace-retained', {
+        entryId,
+        sessions: [current.ownerSessionId, ...(current.sharedSessionIds ?? [])].filter(Boolean),
+      });
     }
+    return removeLocked(current, { force });
   });
 }
 
@@ -1900,25 +1944,7 @@ export async function listManagedWorktrees({ liveSessionIds = [], retainedSessio
   const retained = new Set(retainedSessionIds);
   const rows = [];
   for (const record of Object.values((await readRegistry()).entries)) {
-    const snapshot = record.kind === WORKTREE_SNAPSHOT_KIND;
-    const ownerLive = snapshot
-      ? await snapshotHolderLive(record, live)
-      : (!!record.ownerSessionId && live.has(record.ownerSessionId)) ||
-        leaseProcessAlive(await readOwnerLease(record));
-    const isRetained = !!record.ownerSessionId && retained.has(record.ownerSessionId);
-    // A snapshot outlives no holder: the prune removes it, changes and all.
-    let removable = snapshot
-      ? !ownerLive
-      : !record.sharedSessionIds?.length &&
-        (record.state !== 'ready' || (!ownerLive && (record.disposable === true || !isRetained)));
-    if (removable) {
-      try {
-        await assertRecoveryStoresClear(record);
-      } catch (error) {
-        if (error?.code !== 'WORKTREE_FILE_RECOVERY') throw error;
-        removable = false;
-      }
-    }
+    const { ownerLive, retained: isRetained, removable } = await retentionOf(record, live, retained);
     rows.push({
       ...entryView(record),
       projectPath: record.projectPath,
@@ -1930,6 +1956,29 @@ export async function listManagedWorktrees({ liveSessionIds = [], retainedSessio
   return rows;
 }
 
+/** Who keeps `record` (listManagedWorktrees): `live` and `retained` are session id sets. */
+async function retentionOf(record, live, retained) {
+  const snapshot = record.kind === WORKTREE_SNAPSHOT_KIND;
+  const ownerLive = snapshot
+    ? await snapshotHolderLive(record, live)
+    : (!!record.ownerSessionId && live.has(record.ownerSessionId)) || leaseProcessAlive(await readOwnerLease(record));
+  const isRetained = !!record.ownerSessionId && retained.has(record.ownerSessionId);
+  // A snapshot outlives no holder: the prune removes it, changes and all.
+  let removable = snapshot
+    ? !ownerLive
+    : !record.sharedSessionIds?.length &&
+      (record.state !== 'ready' || (!ownerLive && (record.disposable === true || !isRetained)));
+  if (removable) {
+    try {
+      await assertRecoveryStoresClear(record);
+    } catch (error) {
+      if (error?.code !== 'WORKTREE_FILE_RECOVERY') throw error;
+      removable = false;
+    }
+  }
+  return { ownerLive, retained: isRetained, removable };
+}
+
 /**
  * Conservative reconcile (daemon startup, and the manual prune). Always:
  * resumes interrupted deletions, rolls back interrupted creations of no

package/src/runtime/shared/worktrees/test-support.mjs

@@ -1,25 +1,22 @@
 // Temporary git repositories and data dirs for the worktree suites.
+import '../git-direct.test-support.mjs';
 import { execFileSync } from 'node:child_process';
-import { chmodSync, cpSync, existsSync, mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { appendFileSync, chmodSync, cpSync, existsSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { makeTempDirSync, removeTempDirSync } from '../../../../scripts/lib/scoped-temp.mjs';
 
 const created = [];
 
+// A suite that never calls cleanupTempDirs still has its directories removed
+// when the process exits.
 export function tempDir(prefix = 'mixdog-wt-') {
-  const dir = mkdtempSync(join(tmpdir(), prefix));
+  const dir = makeTempDirSync(prefix);
   created.push(dir);
   return dir;
 }
 
 export function cleanupTempDirs() {
-  for (const dir of created.splice(0)) {
-    try {
-      rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
-    } catch {
-      /* best effort */
-    }
-  }
+  for (const dir of created.splice(0)) removeTempDirSync(dir);
 }
 
 const GIT_ENV = { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_EDITOR: 'true' };
@@ -67,9 +64,13 @@ function repoTemplate(commit) {
   if (existing && existsSync(existing)) return existing;
   const dir = tempDir('mixdog-wt-template-');
   git(dir, 'init', '-q', '-b', 'main');
-  git(dir, 'config', 'user.name', 'Mixdog Test');
-  git(dir, 'config', 'user.email', 'mixdog@example.com');
-  git(dir, 'config', 'core.autocrlf', 'false');
+  // One config write instead of a `git config` process per key. Auto
+  // maintenance is off, so no commit (the test's or a merge's) starts a
+  // `git maintenance run` child.
+  appendFileSync(
+    join(dir, '.git', 'config'),
+    '[user]\n\tname = Mixdog Test\n\temail = mixdog@example.com\n[core]\n\tautocrlf = false\n[maintenance]\n\tauto = false\n'
+  );
   if (commit) commitFile(dir, 'README.md', 'hello\n', 'initial');
   templates.set(commit, dir);
   return dir;

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

@@ -262,10 +262,19 @@ function oldestRowsOverCap(rows) {
 function formatRun(value) {
   const cursor = Number.isSafeInteger(value?.cursor) ? value.cursor : 0;
   const tab = value?.tab !== undefined ? ` tab=${value.tab}` : '';
+  let where = '';
+  if (value?.shown === true) where = 'The terminal is shown in the desktop window.';
+  else if (value?.shown === false) {
+    where =
+      'The terminal is not shown in the desktop window right now (a paired phone may still show it); it keeps running.';
+  }
   return [
     `Terminal run: ${value?.id || `tab ${value?.tab}`} · ${tabLabel(value)} · cursor=${cursor}`,
     `Command sent to the side terminal. Read its output with action=read${tab} since=${cursor}.`,
-  ].join('\n');
+    where,
+  ]
+    .filter(Boolean)
+    .join('\n');
 }
 
 async function readJson(response) {

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

@@ -6,6 +6,7 @@
  * Response: { ok:true, text, tabs?, path? } | { ok:false, error }.
  */
 import { bridgeDiscoveryChanged, readBridgeDiscovery, readBridgeDiscoveryDetail } from '../bridge-discovery.mjs';
+import { visualizeOwnerToolMeta } from './tool-meta.mjs';
 
 const DISCOVERY_FILE = 'visualize-bridge.json';
 const REQUEST_TIMEOUT_MS = 30_000;
@@ -38,12 +39,14 @@ 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' };
+  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 (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? }' };
     }
@@ -79,7 +82,10 @@ export function validateVisualizeArgs(args) {
       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)) {
+  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') {
@@ -92,7 +98,10 @@ export function validateVisualizeArgs(args) {
         !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' };
+        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)) {
@@ -103,7 +112,8 @@ export function validateVisualizeArgs(args) {
     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 (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}` };
     }
@@ -153,6 +163,8 @@ export async function executeVisualizeTool(args, options = {}) {
     cwd: options.cwd || process.cwd(),
     action: validated.action,
     input: validated.input,
+    // The call's id: the host names it in its turn-end record of opens whose tab is gone.
+    ...(options.callId ? { callId: String(options.callId) } : {}),
   };
   let discovery = readBridgeDiscovery(DISCOVERY_FILE);
   if (!discovery) return toolError(unavailableMessage());
@@ -160,7 +172,11 @@ export async function executeVisualizeTool(args, options = {}) {
   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);
+      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');
@@ -175,7 +191,12 @@ export async function executeVisualizeTool(args, options = {}) {
   }
   const { body, status } = result;
   if (!body?.ok) {
-    return toolError(String(body?.error || `visualize bridge request failed (HTTP ${status})`).replace(/^Error:\s*/, ''));
+    return toolError(
+      String(body?.error || `visualize bridge request failed (HTTP ${status})`).replace(/^Error:\s*/, '')
+    );
   }
-  return { content: [{ type: 'text', text: formatSuccess(body) }] };
+  // The host ran it for another session's panel: the owner rides as a field
+  // (toolMeta, kept with the stored result), never only as prose.
+  const toolMeta = visualizeOwnerToolMeta(body.ownerSessionId);
+  return { content: [{ type: 'text', text: formatSuccess(body) }], ...(toolMeta ? { toolMeta } : {}) };
 }

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

@@ -10,8 +10,8 @@ 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). ' +
+      '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, relative to the working directory or absolute anywhere on this machine; 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). ' +
@@ -36,7 +36,8 @@ export const TOOL_DEFS = [
               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.',
+              description:
+                'open: 1-3 file paths (side by side), relative to the working directory or absolute in any folder, or exactly one http(s) URL as the only target.',
             },
             content: {
               type: 'object',
@@ -57,7 +58,8 @@ export const TOOL_DEFS = [
             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.',
+              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: {
@@ -72,9 +74,16 @@ export const TOOL_DEFS = [
             },
             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).' },
+            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/.' },
+            overwrite: {
+              type: 'boolean',
+              description: 'export: replace an existing output file; honored only for paths under design/.',
+            },
             viewport: {
               type: 'object',
               properties: {
@@ -83,9 +92,14 @@ export const TOOL_DEFS = [
               },
               required: ['width'],
               additionalProperties: false,
-              description: 'inspect: size to lay the page out at (height defaults to 800); omit for the panel\'s current size.',
+              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.',
             },
-            selector: { type: 'string', maxLength: 500, description: 'inspect: CSS selector scoping the read-out to one subtree.' },
           },
           additionalProperties: false,
         },

package/src/runtime/visualize-bridge/tool-meta.d.mts

@@ -0,0 +1,5 @@
+export declare const VISUALIZE_OWNER_META_CODE: 'visualize_owner';
+export declare function visualizeOwnerMetaSessionId(value: unknown): string;
+export declare function visualizeOwnerToolMeta(
+  ownerSessionId: unknown
+): { code: typeof VISUALIZE_OWNER_META_CODE; missing: string[]; ownerSessionId: string } | undefined;