mixdog 1.4.1 → 1.4.3

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

@@ -11,9 +11,17 @@ export const WORKTREE_NEW_TASK_DEFAULTS = Object.freeze(['branch', 'worktree']);
 /**
  * @typedef {object} WorktreeSettings
  * @property {'branch'|'worktree'} newTaskDefault
- * @property {string} branchPrefix Ref prefix for created branches; ends with "/".
+ * @property {string} branchPrefix Ref prefix for created branches, ending with "/";
+ *   "" (default) names the branch after the task alone.
  * @property {number} sizeWarnBytes Repository size that asks for confirmation; 0 never asks.
  * @property {boolean} autoCleanup Remove clean, merged worktrees when their session ends.
+ *   The four settings below apply only while it is on.
+ * @property {number} maxWorktrees Keep at most this many managed worktrees (oldest
+ *   activity cleaned first); 0 keeps any number.
+ * @property {number} unusedDays Clean up worktrees unused this many days; 0 never.
+ * @property {boolean} cleanupArchived Archiving a session makes its worktrees disposable.
+ * @property {boolean} deleteBranch Cleanup deletes the worktree's branch too (its tip
+ *   stays under the recovery ref); off keeps the branch.
  */
 
 /** @type {Readonly<WorktreeSettings>} */
@@ -22,8 +30,15 @@ export const WORKTREE_SETTINGS_DEFAULTS = Object.freeze({
   branchPrefix: DEFAULT_WORKTREE_BRANCH_PREFIX,
   sizeWarnBytes: 2 * 1024 ** 3,
   autoCleanup: true,
+  maxWorktrees: 15,
+  unusedDays: 30,
+  cleanupArchived: true,
+  deleteBranch: false,
 });
 
+const WORKTREE_MAX_WORKTREES_LIMIT = 1000;
+const WORKTREE_UNUSED_DAYS_LIMIT = 3650;
+
 const KEYS = Object.keys(WORKTREE_SETTINGS_DEFAULTS);
 const PREFIX_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*(\/[A-Za-z0-9][A-Za-z0-9._-]*)*\/$/;
 
@@ -35,16 +50,27 @@ function fieldError(key, value) {
         ? null
         : `must be one of ${WORKTREE_NEW_TASK_DEFAULTS.join(', ')}`;
     case 'branchPrefix':
-      return typeof value === 'string' &&
-        value.length <= 64 &&
-        PREFIX_PATTERN.test(value) &&
-        !value.includes('..') &&
-        !/\.lock\//i.test(value)
+      return value === '' ||
+        (typeof value === 'string' &&
+          value.length <= 64 &&
+          PREFIX_PATTERN.test(value) &&
+          !value.includes('..') &&
+          !/\.lock\//i.test(value))
         ? null
-        : 'must be a ref path ending with "/", e.g. "mixdog/"';
+        : 'must be empty or a ref path ending with "/", e.g. "mixdog/"';
     case 'sizeWarnBytes':
       return Number.isSafeInteger(value) && value >= 0 ? null : 'must be a non-negative integer';
+    case 'maxWorktrees':
+      return Number.isSafeInteger(value) && value >= 0 && value <= WORKTREE_MAX_WORKTREES_LIMIT
+        ? null
+        : `must be an integer from 0 to ${WORKTREE_MAX_WORKTREES_LIMIT}`;
+    case 'unusedDays':
+      return Number.isSafeInteger(value) && value >= 0 && value <= WORKTREE_UNUSED_DAYS_LIMIT
+        ? null
+        : `must be an integer from 0 to ${WORKTREE_UNUSED_DAYS_LIMIT}`;
     case 'autoCleanup':
+    case 'cleanupArchived':
+    case 'deleteBranch':
       return typeof value === 'boolean' ? null : 'must be a boolean';
     default:
       return 'is not a worktree setting';

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

@@ -106,7 +106,11 @@ export async function createTestWorktree(projectPath, extra = {}) {
   return { entry, ...id, ...extra };
 }
 
-/** The repository's branches under the default managed prefix. */
+/** The branch prefix the suites configure (the default is none), so their
+ *  managed branches are told apart from the repository's own. */
+export const TEST_BRANCH_PREFIX = 'mixdog/';
+
+/** The repository's branches under TEST_BRANCH_PREFIX. */
 export function prefixedBranches(repo) {
   return git(repo, 'for-each-ref', '--format=%(refname:short)', 'refs/heads/mixdog/').split('\n').filter(Boolean);
 }

package/src/runtime/shared/worktrees/worker-snapshots.mjs

@@ -0,0 +1,82 @@
+// Read-only snapshot worktrees of delegated workers (`git worktree add
+// --detach` through the git tool): the worker's session holds each one, and
+// it is removed when that worker's turn settles (the session runtime's
+// unload), like the Lead's turn snapshots. What a removal leaves (something
+// still runs there, the process ends first) is the prune's and the startup
+// reconcile's: a snapshot never outlives its holder.
+//
+// Dependency-free at load (the manager loads on first use) and shared through
+// a global symbol, so every bundle copy of this module sees one ledger.
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+
+const STATE_KEY = Symbol.for('mixdog.workerSnapshots.v1');
+const RETRY_MS = 2_000;
+const RETRY_LIMIT = 5;
+
+const loadManager = () => import('./manager.mjs');
+
+function state() {
+  globalThis[STATE_KEY] ??= { runtimeToken: `worker-snapshots-${randomUUID()}`, turns: new Map() };
+  return globalThis[STATE_KEY];
+}
+
+/**
+ * A snapshot of `commit` in the repository at `projectPath`, held by worker
+ * session `sessionId` until its turn settles (releaseWorkerSnapshots).
+ * @param {{ sessionId: string, projectPath: string, commit: string, txId?: string, confirmLarge?: boolean, manager?: object }} input
+ */
+export async function createWorkerSnapshot({
+  sessionId,
+  projectPath,
+  commit,
+  txId = '',
+  confirmLarge = false,
+  manager = null,
+}) {
+  const id = String(sessionId || '').trim();
+  if (!id) throw new Error('A worker snapshot needs the worker session.');
+  const tx = String(txId || '').trim() || `worker-snapshot-${randomUUID()}`;
+  const backend = manager || (await loadManager());
+  const entry = await backend.createSnapshotWorktree({
+    projectPath,
+    sessionId: id,
+    runtimeToken: state().runtimeToken,
+    commit,
+    txId: tx,
+    confirmLarge: confirmLarge === true,
+  });
+  const { turns } = state();
+  if (!turns.has(id)) turns.set(id, new Set());
+  turns.get(id).add(tx);
+  return entry;
+}
+
+/**
+ * The worker's turn settled: remove the snapshots it made. One a worker or
+ * background shell still runs in is retried with a doubling delay a few
+ * times; the rest stays for the prune / startup reconcile.
+ * @returns {Promise<{ removed: string[], kept: object[] }>}
+ */
+export async function releaseWorkerSnapshots(
+  sessionId,
+  { manager = null, retryMs = RETRY_MS, retryLimit = RETRY_LIMIT } = {}
+) {
+  const id = String(sessionId || '');
+  const { turns } = state();
+  const made = turns.get(id);
+  const report = { removed: [], kept: [] };
+  if (!made?.size) return report;
+  turns.delete(id);
+  const backend = manager || (await loadManager());
+  let pending = [...made];
+  for (let attempt = 0; pending.length && attempt < retryLimit; attempt++) {
+    if (attempt > 0) await delay(retryMs * 2 ** (attempt - 1), undefined, { ref: false });
+    const result = await backend.removeSessionSnapshots(id, { txIds: pending });
+    report.removed.push(...result.removed);
+    const inUse = result.kept.filter((row) => row.reason === 'in-use');
+    report.kept = result.kept;
+    pending = inUse.map((row) => row.txId);
+  }
+  return report;
+}

package/src/runtime/tidy/install.mjs

@@ -4,12 +4,22 @@
 // Policy gating happens BEFORE any network call: 'never' refuses, 'ask' returns
 // needsApproval unless the call carried approveDownloads:true, 'auto' proceeds.
 // Toolchain engines (rustfmt, gofmt, zig fmt, ...) are never downloadable.
-import { chmodSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from 'node:fs';
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { join } from 'node:path';
 import { MAX_NATIVE_BINARY_DOWNLOAD_BYTES, streamResponseToFile } from '../shared/bounded-download.mjs';
-import { platformEntryKey, platformKey, sha256File } from '../shared/native-asset.mjs';
-import { fileHasData } from '../shared/file-has-data.mjs';
+import { platformEntryKey, platformKey, sha256File, validSha256 } from '../shared/native-asset.mjs';
+import { fileHasDataAsync } from '../shared/file-has-data.mjs';
 import { readJsonSafe } from '../shared/json-file.mjs';
 import { ENGINE_CATALOG } from './engines.mjs';
 import { extractArchive } from './extract.mjs';
@@ -45,14 +55,73 @@ export function manifestAsset(manifest, id, pkey = platformEntryKey(manifest?.en
   return { entry, asset, version: String(entry.version || '0'), pkey: entry?.assets?.[pkey] ? pkey : 'any' };
 }
 
-/** An already-installed managed binary for `id`, or null. Sync, no network. */
-export function managedEngineBinary({ id, manifest, pluginData }) {
+// The installer records the extracted binary's sha256 beside it; a reuse
+// re-hashes the binary against that record. Like the other managed binaries
+// (mixdog-spawn / patch / graph resolve their path once per process), the hash
+// runs once per process per binary, again only when its size or mtime changes.
+// An install from before the record existed has no digest file: its first use
+// records the digest (trust on first use). An existing record that is invalid
+// or does not match is never overwritten; that binary is tampered or corrupt.
+export const ENGINE_DIGEST_FILE = '.engine.sha256';
+const verifiedEngineBins = new Map();
+
+function recordEngineDigest(digestFile, digest) {
+  const tmp = `${digestFile}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    writeFileSync(tmp, digest);
+    renameSync(tmp, digestFile);
+  } catch {
+    /* unrecorded: this install is trusted for this process only */
+  } finally {
+    try {
+      rmSync(tmp, { force: true });
+    } catch {
+      /* a leftover temp file never matches the digest path */
+    }
+  }
+}
+
+// The recorded digest decides whether a binary is intact. Only an install from
+// before the record existed has none; there alone the content probe keeps a
+// crash-torn (empty or NUL-filled) binary from becoming the digest it is
+// trusted by. A binary that cannot be statted, read or hashed cannot be
+// verified, so it is not reused.
+async function engineBinaryIntact(dir, full) {
+  try {
+    const stamp = statSync(full);
+    const key = `${stamp.size}:${stamp.mtimeMs}`;
+    if (verifiedEngineBins.get(full) === key) return true;
+    const digestFile = join(dir, ENGINE_DIGEST_FILE);
+    let recorded = null;
+    try {
+      recorded = readFileSync(digestFile, 'utf8').trim().toLowerCase();
+    } catch (error) {
+      if (error?.code !== 'ENOENT') return false;
+    }
+    if (recorded === null && !(await fileHasDataAsync(full))) return false;
+    const actual = await sha256File(full);
+    if (recorded === null) {
+      recordEngineDigest(digestFile, actual);
+      recorded = actual;
+    }
+    if (!validSha256(recorded) || actual !== recorded) return false;
+    verifiedEngineBins.set(full, key);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** An already-installed managed binary for `id`, or null. No network; the
+ *  binary probe is async so a slow (scanned) open never stalls the event loop. */
+export async function managedEngineBinary({ id, manifest, pluginData }) {
   const found = manifestAsset(manifest, id);
   if (!found || !pluginData) return null;
   const binPath = String(found.asset.binPath || '');
   if (!binPath) return null;
-  const full = join(managedEngineDir(pluginData, id, found.version), binPath);
-  return fileHasData(full) ? { path: full, version: found.version } : null;
+  const dir = managedEngineDir(pluginData, id, found.version);
+  const full = join(dir, binPath);
+  return (await engineBinaryIntact(dir, full)) ? { path: full, version: found.version } : null;
 }
 
 /** Throws unless `filePath` hashes to `expected`. */
@@ -72,7 +141,13 @@ export async function verifyDownloadDigest(filePath, expected, label = LABEL) {
  * Decide what an install call may do, without touching the network.
  * Returns { targets, present, needsApproval, errors }.
  */
-export function planInstall({ ids = [], manifest, pluginData = '', policy = 'auto', approveDownloads = false } = {}) {
+export async function planInstall({
+  ids = [],
+  manifest,
+  pluginData = '',
+  policy = 'auto',
+  approveDownloads = false,
+} = {}) {
   const targets = [];
   const present = [];
   const errors = [];
@@ -101,7 +176,7 @@ export function planInstall({ ids = [], manifest, pluginData = '', policy = 'aut
       });
       continue;
     }
-    const installed = managedEngineBinary({ id, manifest, pluginData });
+    const installed = await managedEngineBinary({ id, manifest, pluginData });
     if (installed) {
       present.push({ id, version: installed.version, path: installed.path });
       continue;
@@ -242,8 +317,9 @@ export async function installEngine(
   const engineRoot = join(managedToolsDir(pluginData), target.id);
   const finalDir = managedEngineDir(pluginData, target.id, target.version);
   const binFull = join(finalDir, target.binPath);
-  // An engine binary a crash left NUL-filled is not present: it is installed again.
-  if (fileHasData(binFull)) {
+  // An engine binary a crash left NUL-filled, or that no longer matches its
+  // recorded digest, is not present: it is installed again.
+  if (await engineBinaryIntact(finalDir, binFull)) {
     return { id: target.id, version: target.version, path: binFull, bytes: 0, status: 'present' };
   }
   mkdirSync(engineRoot, { recursive: true });
@@ -272,12 +348,16 @@ export async function installEngine(
         /* best-effort */
       }
     }
+    writeFileSync(join(stageDir, ENGINE_DIGEST_FILE), await sha256File(stagedBin));
     try {
-      if (existsSync(finalDir) && !fileHasData(binFull)) rmSync(finalDir, { recursive: true, force: true });
+      if (existsSync(finalDir) && !(await engineBinaryIntact(finalDir, binFull))) {
+        verifiedEngineBins.delete(binFull);
+        rmSync(finalDir, { recursive: true, force: true });
+      }
       renameSync(stageDir, finalDir);
     } catch (error) {
-      // A concurrent install won the race; its verified copy is equivalent.
-      if (!existsSync(binFull)) throw error;
+      // A concurrent install won the race only if the surviving copy verifies.
+      if (!(await engineBinaryIntact(finalDir, binFull))) throw error;
     }
     return { id: target.id, version: target.version, path: binFull, bytes, status: 'installed' };
   } finally {
@@ -305,7 +385,7 @@ export async function installEngines({
   stallTimeoutMs = undefined,
 } = {}) {
   const loaded = manifest || readEnginesManifest();
-  const plan = planInstall({ ids, manifest: loaded, pluginData, policy, approveDownloads });
+  const plan = await planInstall({ ids, manifest: loaded, pluginData, policy, approveDownloads });
   const installed = [...plan.present];
   const errors = [...plan.errors];
   if (!pluginData && plan.targets.length > 0) {

package/src/runtime/tidy/languages.mjs

@@ -6,6 +6,7 @@
 // on the id. AUX_LANGUAGE_EXTENSIONS adds the config/markup languages the graph
 // never parses but formatters do (PowerShell, JSON, TOML, ...).
 import { extname } from 'node:path';
+import { startGit } from '../shared/git-launch.mjs';
 import { runProcess } from './process.mjs';
 
 export const CODE_LANGUAGE_EXTENSIONS = Object.freeze({
@@ -156,21 +157,22 @@ export function parseGraphLangs(stdout) {
 
 /** git-tracked files under `cwd`, filtered to the requested scope paths. */
 async function listScopedFiles({ cwd, paths = [], signal = null, timeoutMs = 20_000 } = {}) {
-  const result = await runProcess(
-    'git',
-    [
-      '-c',
-      'core.quotepath=false',
-      '--literal-pathspecs',
-      'ls-files',
-      '--cached',
-      '--others',
-      '--exclude-standard',
-      '-z',
-      '--',
-      ...paths,
-    ],
-    { cwd, signal, timeoutMs }
+  const args = [
+    '-c',
+    'core.quotepath=false',
+    '--literal-pathspecs',
+    'ls-files',
+    '--cached',
+    '--others',
+    '--exclude-standard',
+    '-z',
+    '--',
+    ...paths,
+  ];
+  const result = await startGit(
+    process.env,
+    (command, env) => runProcess(command, args, { cwd, signal, timeoutMs, env }),
+    (outcome) => ({ code: outcome.errorCode })
   );
   if (result.code !== 0) {
     return {

package/src/runtime/tidy/process.mjs

@@ -5,6 +5,7 @@
 // parser.
 import { spawn } from 'node:child_process';
 import { existsSync, readdirSync, statSync } from 'node:fs';
+import { spawnTreeKill } from '../agent/orchestrator/mcp/child-tree.mjs';
 import { delimiter, extname, isAbsolute, join } from 'node:path';
 
 const DEFAULT_PROCESS_TIMEOUT_MS = 90_000;
@@ -108,8 +109,9 @@ function captureInto(state, key, chunk, cap) {
 
 /**
  * Spawn `bin` with `args` and collect its output.
- * Resolves `{code, signal, stdout, stderr, timedOut, error}` — a failed spawn is
- * reported, never thrown, so one broken engine cannot abort the multiplexer.
+ * Resolves `{code, signal, stdout, stderr, timedOut, error, errorCode}` — a
+ * failed spawn is reported (`errorCode`: its code, e.g. ENOENT), never thrown,
+ * so one broken engine cannot abort the multiplexer.
  */
 export function runProcess(
   bin,
@@ -151,6 +153,7 @@ export function runProcess(
         timedOut: false,
         truncated: false,
         error: error?.message || String(error),
+        errorCode: error?.code || '',
       });
       return;
     }
@@ -164,7 +167,7 @@ export function runProcess(
       if (child.exitCode != null || child.signalCode != null) return;
       try {
         if (process.platform === 'win32' && child.pid) {
-          spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' });
+          spawnTreeKill([child.pid], { root: child });
         } else {
           child.kill('SIGKILL');
         }
@@ -209,7 +212,7 @@ export function runProcess(
 
     // One exit path for both outcomes: whoever settles first reports the
     // captured output and clears the timers.
-    const settle = (code, exitSignal, error) => {
+    const settle = (code, exitSignal, error, errorCode = '') => {
       if (settled) return;
       settled = true;
       clearTimers();
@@ -221,12 +224,13 @@ export function runProcess(
         timedOut,
         truncated: Boolean(state.stdoutTruncated || state.stderrTruncated),
         error,
+        errorCode,
       });
     };
 
     child.stdout?.on('data', (chunk) => captureInto(state, 'stdout', chunk, cap));
     child.stderr?.on('data', (chunk) => captureInto(state, 'stderr', chunk, cap));
-    child.on('error', (error) => settle(-1, null, error?.message || String(error)));
+    child.on('error', (error) => settle(-1, null, error?.message || String(error), error?.code || ''));
     if (input != null && child.stdin) {
       child.stdin.on('error', () => {
         /* child may close stdin early */

package/src/runtime/tidy/resolve.mjs

@@ -135,7 +135,7 @@ function installableFlag(entry, manifest) {
   return entry.managed && manifestAsset(manifest, entry.id) ? { installable: true } : {};
 }
 
-function resolveOne({ cwd, entry, config, env, manifest, pluginData, pathIndex }) {
+async function resolveOne({ cwd, entry, config, env, manifest, pluginData, pathIndex }) {
   const base = {
     id: entry.id,
     kind: entry.kind,
@@ -169,7 +169,8 @@ function resolveOne({ cwd, entry, config, env, manifest, pluginData, pathIndex }
         installHint: entry.hostInstallHint || entry.installHint,
       };
     }
-    const managed = entry.managed && pluginData ? managedEngineBinary({ id: entry.id, manifest, pluginData }) : null;
+    const managed =
+      entry.managed && pluginData ? await managedEngineBinary({ id: entry.id, manifest, pluginData }) : null;
     if (managed) {
       return {
         ...base,
@@ -194,7 +195,7 @@ function resolveOne({ cwd, entry, config, env, manifest, pluginData, pathIndex }
   const onPath = pathBinary(entry, env, pathIndex);
   if (onPath) return { ...base, source: 'path', path: onPath.path, ...commandFor(entry, onPath.path) };
   if (entry.managed && pluginData) {
-    const managed = managedEngineBinary({ id: entry.id, manifest, pluginData });
+    const managed = await managedEngineBinary({ id: entry.id, manifest, pluginData });
     if (managed) {
       return {
         ...base,
@@ -282,20 +283,22 @@ export async function resolveEngines({
   else if (languages.length > 0) requested = enginesForLanguages(languages);
   const unknown = engineIds.filter((id) => !ENGINE_IDS.includes(id));
 
-  // One listing per PATH dir for the whole batch: this runs synchronously on
-  // the host loop (the desktop's Code Tidy status read at startup).
+  // One listing per PATH dir for the whole batch (the desktop's Code Tidy
+  // status read at startup runs this on the host loop).
   const pathIndex = createPathIndex(env);
-  const resolved = requested.map((id) => {
-    const entry = ENGINE_CATALOG[id];
-    const result = resolveOne({ cwd, entry, config, env, manifest: loadedManifest, pluginData, pathIndex });
-    const configFile = projectConfigFileFor(cwd, entry);
-    if (configFile) result.configFile = configFile;
-    if (entry.requiresConfig && !configFile && result.source !== 'project-config') {
-      result.skipped = 'no project config for this engine';
-    }
-    if (entry.toolchain) result.toolchain = true;
-    return result;
-  });
+  const resolved = await Promise.all(
+    requested.map(async (id) => {
+      const entry = ENGINE_CATALOG[id];
+      const result = await resolveOne({ cwd, entry, config, env, manifest: loadedManifest, pluginData, pathIndex });
+      const configFile = projectConfigFileFor(cwd, entry);
+      if (configFile) result.configFile = configFile;
+      if (entry.requiresConfig && !configFile && result.source !== 'project-config') {
+        result.skipped = 'no project config for this engine';
+      }
+      if (entry.toolchain) result.toolchain = true;
+      return result;
+    })
+  );
 
   // A project driving Prettier/ESLint from node_modules/.bin keeps them: Biome
   // stands down rather than reformatting against the project's own config.

package/src/runtime/tidy/runners/biome.mjs

@@ -1,5 +1,4 @@
 // Biome — JSON reporter for check, `--write` (1.x: `--apply`) for fix.
-import { availableParallelism } from 'node:os';
 import { mapLimit, runProcess } from '../process.mjs';
 import {
   FILES_PER_SPAWN,
@@ -19,8 +18,9 @@ export const BIOME_CHECK_ARGS = ['check', '--reporter=json', '--max-diagnostics=
 export const BIOME_TRUNCATED_NOTE =
   'biome JSON output was truncated; split the scope and re-run to get complete diagnostics';
 const EXPLAIN_TIMEOUT_MS = 8_000;
-// One short single-rule process each; scale the fan-out with the host.
-const EXPLAIN_CONCURRENCY = Math.max(4, Math.ceil(availableParallelism() / 2));
+// One short single-rule process each, a few at a time: the host is the
+// user's working machine, so the fan-out does not grow with its core count.
+const EXPLAIN_CONCURRENCY = 4;
 
 function severityOf(value) {
   const level = String(value || '').toLowerCase();

package/src/runtime/tidy/tool.mjs

@@ -214,7 +214,7 @@ async function satisfyMissingEngines({ resolution, cwd, engineFilter, approveDow
   if (policy === 'never') return { resolution, needsApproval: null, installed: null };
   const { installEngines, planInstall } = await import('./install.mjs');
   if (policy !== 'auto' && !approveDownloads) {
-    const plan = planInstall({
+    const plan = await planInstall({
       ids: installable,
       manifest: resolution.manifest,
       pluginData: resolution.pluginData,

package/src/runtime/tidy/worktree.mjs

@@ -7,6 +7,7 @@
 // already non-conforming in HEAD had to be reverted by hand. Scope still comes
 // from `paths` and nothing here derives one from a diff: the split is a report
 // the caller reads before writing, so they can pass a precise file list.
+import { startGit } from '../shared/git-launch.mjs';
 import { normalizeRel } from './languages.mjs';
 import { runProcess, which } from './process.mjs';
 
@@ -44,13 +45,16 @@ export async function listWorkingTreeChanges({
   env = process.env,
 } = {}) {
   if (!which('git', { env })) return { files: null, error: '', skipped: NO_GIT_REASON };
+  // The git the caller's own PATH names, as the lookup above found it.
+  const git = (args) =>
+    startGit(
+      env,
+      (command, childEnv) => runProcess(command, args, { cwd, signal, timeoutMs, env: childEnv }),
+      (result) => ({ code: result.errorCode })
+    );
   const [status, prefix] = await Promise.all([
-    runProcess(
-      'git',
-      ['-c', 'core.quotepath=false', '--literal-pathspecs', 'status', '--porcelain', '-z', '--untracked-files=all'],
-      { cwd, signal, timeoutMs, env }
-    ),
-    runProcess('git', ['rev-parse', '--show-prefix'], { cwd, signal, timeoutMs, env }),
+    git(['-c', 'core.quotepath=false', '--literal-pathspecs', 'status', '--porcelain', '-z', '--untracked-files=all']),
+    git(['rev-parse', '--show-prefix']),
   ]);
   const failed = [status, prefix].find((result) => result.code !== 0);
   if (failed) {

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

@@ -43,6 +43,9 @@ export function validateVisualizeArgs(args) {
     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.verify != null && typeof input.verify !== 'boolean') {
+    return { ok: false, error: 'open input.verify must be a boolean' };
+  }
   if (args.action === 'open' && input.content != null) {
     const content = input.content;
     if (input.targets != null)
@@ -114,7 +117,7 @@ export function validateVisualizeArgs(args) {
   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())) {
+    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)) {

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, 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). ' +
+      'Show the user a finished deliverable you produced or changed (mockups, docs, decks, sheets, PDFs, images, video, local dev pages) in the desktop side panel beside the chat. A summary, plan or report of your own work is not one either: it stays in the chat. Your own check screenshots are not deliverables: look at them with read; open with verify: true only to run check/inspect/capture/export. 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), optional verify (true = you open only to check your own work with check/inspect/capture/export: the user is not shown the tab and it closes when the turn ends; leave it off for anything the user should see). 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). ' +
@@ -61,6 +61,11 @@ export const TOOL_DEFS = [
               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.',
             },
+            verify: {
+              type: 'boolean',
+              description:
+                'open (files or content): true to check your own work only; the user is not shown the tab and it closes when the turn ends.',
+            },
             tab: { type: 'string', description: 'Tab id from open (close: omit for all).' },
             add: {
               type: 'array',