mixdog 1.3.2 → 1.3.3

package/src/runtime/agent/orchestrator/session/store/sweep/sweep-row.mjs

@@ -13,6 +13,7 @@ import { _queueSessionSummaryUpsert, _queueSessionSummaryRemoval } from '../summ
 import { deleteSession } from '../session-delete.mjs';
 import { markSessionClosed } from '../lifecycle-barriers.mjs';
 import { BLANK_SCRATCH_MAX_AGE_MS, RUNNING_STALL_MS, SWEEP_RECORD_NO_DATA, readSweepRecord } from './sweep-record.mjs';
+import { subAgentMember } from './sub-agent-retention.mjs';
 import { isAgentHomeSessionId } from '../../agent-home.mjs';
 import { isRoomThreadSessionId } from '../../agent-room.mjs';
 
@@ -28,6 +29,14 @@ const effectiveFields = (actual, row) => ({
   createdAt: Number(actual?.createdAt) > 0 ? Number(actual.createdAt) : row.createdAt || 0,
 });
 
+/** Every sub-agent record, open or closed, fresh or not, for the tree
+ *  retention its caller applies (sub-agent-retention.mjs). */
+function noteSubAgent(ctx, id, doc) {
+  if (!ctx.plan.retainSubAgents) return;
+  const member = subAgentMember(id, doc);
+  if (member) ctx.tally.subAgents.push(member);
+}
+
 /** A closed record: a mature tombstone is deleted; otherwise a stale summary
  *  row that still claims the session open is repaired and the row is kept. */
 function sweepClosedRecord(ctx, row, actual, jsonPath) {
@@ -153,6 +162,7 @@ function sweepOpenRecord(ctx, row, record, { jsonMtime }) {
     tally.remaining++;
     return;
   }
+  noteSubAgent(ctx, row.id, record.doc);
   const eff = effectiveFields(record.doc, row);
   const ownerNamed = typeof eff.owner === 'string' && eff.owner.length > 0;
   // Freshness gate — recently-touched open sessions are skipped cheaply here.
@@ -277,7 +287,10 @@ export function sweepRow(ctx, row) {
     return;
   }
   if (record.closed === true || actual.status === 'closed') {
+    const cleanedBefore = ctx.tally.tombstonesCleaned;
     sweepClosedRecord(ctx, row, actual, jsonPath);
+    // A tombstone this sweep just deleted is gone, not a member.
+    if (ctx.tally.tombstonesCleaned === cleanedBefore) noteSubAgent(ctx, row.id, actual);
     return;
   }
   sweepOpenRecord(ctx, row, record, { jsonMtime: jsonProbe.mtimeMs || 0 });

package/src/runtime/agent/orchestrator/session/store-summary-catalog.mjs

@@ -12,6 +12,7 @@
 import { readdirSync, readFileSync } from 'node:fs';
 import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { performance } from 'node:perf_hooks';
 // Leaf helpers only: the three-way present/absent/unreadable classification
 // and the strict record parser the authoritative store uses, so the catalog
 // cannot disagree with it.
@@ -384,6 +385,66 @@ function scanSessionEntries(directory, indexRowsById, forceRead) {
   return { entries };
 }
 
+// The async rescan yields a turn once a slice of reconciles has run this long:
+// a full authoritative rescan strict-reads every session file (≈4 s for 1.8k
+// files / 1.3 GB), which must not hold the daemon loop in one piece.
+let scanSliceMs = 25;
+
+/** Test seam: the async rescan's slice budget (0 yields after every file). */
+export function _setCatalogScanSliceMsForTest(ms) {
+  scanSliceMs = Math.max(0, Number(ms) || 0);
+}
+
+const nextTurn = () => new Promise((resolve) => setImmediate(resolve));
+
+/** The entry a file still has: `entry` when the file's stamp is unchanged
+ *  since it was reconciled, else a fresh reconcile (null once it is gone). */
+function settledEntry(directory, storageId, entry, retained, forceRead) {
+  if (entry?.stamp) {
+    let stamp = null;
+    try {
+      stamp = statSessionStamp(join(directory, `${storageId}.json`));
+    } catch {
+      // Gone or unstatable: the reconcile below decides which.
+    }
+    if (stamp && sameSessionStamp(entry.stamp, stamp)) return entry;
+  }
+  return reconcileSessionFile(directory, storageId, retained, forceRead);
+}
+
+/** scanSessionEntries in slices, yielding the loop between them. Files can
+ *  change while it yields, so the answer is settled in one synchronous pass at
+ *  the end: the directory is listed again, a file whose stamp moved since its
+ *  read (or that appeared) is reconciled again, and a file that is no longer
+ *  listed is dropped — the entries match storage when they are returned, as
+ *  the one-piece scan's do. That pass is a stat per file (≈20 ms for 1.5k). */
+async function scanSessionEntriesAsync(directory, indexRowsById, forceRead, onSettle) {
+  const sessionIds = listSessionIds(directory);
+  if (!sessionIds) {
+    onSettle?.();
+    return null;
+  }
+  const scanned = new Map();
+  let sliceStart = performance.now();
+  for (const storageId of sessionIds) {
+    if (performance.now() - sliceStart >= scanSliceMs) {
+      await nextTurn();
+      sliceStart = performance.now();
+    }
+    const entry = reconcileSessionFile(directory, storageId, indexRowsById.get(storageId), forceRead);
+    if (entry) scanned.set(storageId, entry);
+  }
+  onSettle?.();
+  const settledIds = listSessionIds(directory);
+  if (!settledIds) return null;
+  const entries = new Map();
+  for (const storageId of settledIds) {
+    const entry = settledEntry(directory, storageId, scanned.get(storageId), indexRowsById.get(storageId), forceRead);
+    if (entry) entries.set(storageId, entry);
+  }
+  return { entries };
+}
+
 /** The row an entry contributes, or null. */
 function entryRow(entry, id, indexRowsById) {
   if (!entry || entry.kind === 'none') return null;
@@ -419,6 +480,21 @@ export function scanSessionFiles(indexRowsById, forceRead) {
   return scan && assembleCatalog(scan.entries, indexRowsById);
 }
 
+/** scanSessionFiles with the same answer, its file reconciles run in slices
+ *  that yield the event loop (the daemon's session.list storage refresh).
+ *  `onSettle` runs once, when the answer's final synchronous part begins: from
+ *  then on storage changes are no longer seen by this scan. */
+export async function scanSessionFilesAsync(indexRowsById, forceRead, { onSettle } = {}) {
+  const directory = join(dataDir(), 'sessions');
+  const dirProbe = probePath(directory);
+  if (dirProbe.state !== PROBE_PRESENT) {
+    onSettle?.();
+    return dirProbe.state === PROBE_ABSENT ? [] : null;
+  }
+  const scan = await scanSessionEntriesAsync(directory, indexRowsById, forceRead, onSettle);
+  return scan && assembleCatalog(scan.entries, indexRowsById);
+}
+
 /** Listing from the index rows alone, or null without a valid index. */
 export function indexListing(index) {
   return index.rows && leadRows(index.rows.map((row) => ({ ...row }))).sort(byCatalogOrder);

package/src/runtime/agent/orchestrator/session/store-summary-reader.mjs

@@ -20,6 +20,7 @@ import {
   indexListing,
   observeStamp,
   scanSessionFiles,
+  scanSessionFilesAsync,
   stampedDerivation,
 } from './store-summary-catalog.mjs';
 import { createStoredTranscriptCache, nextProjectionStamp } from './store-transcript-cache.mjs';
@@ -155,6 +156,30 @@ async function catalogDbListing(page) {
   return answer;
 }
 
+// The running storage refresh a new caller may still join: only until its
+// final synchronous settle begins, since a caller arriving after that asked
+// after the answer was fixed (a scan that never yields settles before its own
+// caller awaits it).
+let storageRefreshFlight = null;
+
+async function refreshFromStorageOnce(onSettle) {
+  const index = ordinaryCatalog.loadIndex();
+  return (await scanSessionFilesAsync(index.rowsById, true, { onSettle })) ?? indexListing(index) ?? [];
+}
+
+function storageRefresh() {
+  if (storageRefreshFlight?.joinable) return storageRefreshFlight.rows;
+  const flight = { joinable: true, rows: null };
+  storageRefreshFlight = flight;
+  flight.rows = refreshFromStorageOnce(() => {
+    flight.joinable = false;
+  }).finally(() => {
+    // A newer flight is never cleared by an older one's end.
+    if (storageRefreshFlight === flight) storageRefreshFlight = null;
+  });
+  return flight.rows;
+}
+
 /**
  * listStoredSessionSummaries for async callers (the daemon's session views).
  * In the daemon the ordinary listing comes from the session catalog DB
@@ -163,7 +188,14 @@ async function catalogDbListing(page) {
  * JSON/file path.
  */
 export async function listStoredSessionSummariesAsync(options = {}) {
-  if (options.refreshFromStorage === true || options.rebuildIfMissing === false) {
+  if (options.refreshFromStorage === true) {
+    // The same authoritative rescan as the sync path, in slices that yield.
+    // Concurrent refreshes share one scan while it can still see their
+    // request (it settles against storage when it ends); each caller gets its
+    // own rows.
+    return (await storageRefresh()).map((row) => ({ ...row }));
+  }
+  if (options.rebuildIfMissing === false) {
     return listStoredSessionSummaries(options);
   }
   const answer = await catalogDbListing(null);

package/src/runtime/agent/orchestrator/session/store-summary-visibility.d.mts

@@ -0,0 +1,5 @@
+export function isRootLeadSession(value: unknown): boolean;
+export function sessionVisibility(value: unknown): 'ordinary' | 'agent-only';
+export function isAgentOnlySession(value: unknown): boolean;
+export function agentParentIds(value: unknown): string[];
+export function agentDescendantIds(rows: readonly unknown[], rootId: unknown): string[];

package/src/runtime/agent/orchestrator/session/store-summary-visibility.mjs

@@ -49,3 +49,40 @@ export function sessionVisibility(value) {
 export function isAgentOnlySession(value) {
   return sessionVisibility(value) === SESSION_VISIBILITY_AGENT_ONLY;
 }
+
+/** Every session a record links itself to as its owner or parent (both links,
+ *  never itself): the links the descendant walk and the sub-agent retention
+ *  trees follow. */
+export function agentParentIds(value) {
+  const id = clean(value?.id);
+  return [...new Set([clean(value?.ownerSessionId), clean(value?.parentSessionId)])].filter(
+    (parent) => parent && parent !== id
+  );
+}
+
+/** The agent-only sessions under `rootId` at any depth, from session rows. A
+ *  catalog row links a sub-agent to its root Lead (`ownerSessionId`) or, on a
+ *  legacy row, to its parent, so the walk follows every link a row names. */
+export function agentDescendantIds(rows, rootId) {
+  const root = clean(rootId);
+  const children = new Map();
+  for (const row of Array.isArray(rows) ? rows : []) {
+    if (!isAgentOnlySession(row)) continue;
+    const id = clean(row.id);
+    if (!id) continue;
+    for (const parent of agentParentIds(row)) {
+      if (!children.has(parent)) children.set(parent, []);
+      children.get(parent).push(id);
+    }
+  }
+  const found = new Set();
+  const queue = [root];
+  while (queue.length) {
+    for (const child of children.get(queue.pop()) || []) {
+      if (child === root || found.has(child)) continue;
+      found.add(child);
+      queue.push(child);
+    }
+  }
+  return [...found];
+}

package/src/runtime/agent/orchestrator/session/store.mjs

@@ -722,4 +722,5 @@ export { fenceSessionWrites } from './store/live-state.mjs';
 // session-store entry point.
 export { listStoredSessions, listStoredSessionSummaries, getStoredSessionsRaw } from './store/listing.mjs';
 export { sweepStaleSessions, sweepStaleSessionsCooperative } from './store/sweep/stale-sweep.mjs';
+export { applySubAgentRetention } from './store/sweep/sub-agent-retention.mjs';
 export { _savePending } from './store/pending-saves.mjs';

package/src/runtime/agent/orchestrator/tools/builtin/advisory-lock.mjs

@@ -3,10 +3,11 @@
 // clean up after crashed holders. Pair with the in-process withPathLock for
 // the same target: in-process serialises async callers in this Node, advisory
 // lock serialises across Node processes.
-import { openSync, closeSync, writeSync, readFileSync, unlinkSync, mkdirSync, realpathSync } from 'node:fs';
+import { openSync, closeSync, writeSync, readFileSync, unlinkSync, realpathSync } from 'node:fs';
 import { compareCodePoints } from '../../../../shared/code-point-order.mjs';
-import { resolvePluginData } from '../../../../shared/plugin-paths.mjs';
+import { ensurePrivateRuntimeRoot } from '../../../../shared/runtime-root.mjs';
 import { sleep } from '../../../../shared/sleep.mjs';
+import { homedir } from 'node:os';
 import { dirname, basename, join, resolve } from 'node:path';
 import { createHash, randomBytes } from 'node:crypto';
 
@@ -28,14 +29,24 @@ function canonicalLockTarget(targetPath) {
   }
 }
 
-// Lockfiles live in the local data dir, keyed by the target's canonical path,
-// never beside the target: sync-drive folders (e.g. Naver MYBOX) refuse
-// dot-prefixed sibling files, and the pid liveness check only spans this host.
+// External files can be shared by profiles, so neither MIXDOG_HOME/DATA_DIR
+// nor MIXDOG_RUNTIME_ROOT may choose this namespace. Temp directories can
+// differ between processes too. Keep locks in the OS user's local home,
+// never beside the target: sync drives such as MYBOX refuse sibling dotfiles.
+// The pid liveness check coordinates only processes on this host.
+function lockDirectory() {
+  const root =
+    process.platform === 'win32'
+      ? join(process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local'), 'mixdog')
+      : join(homedir(), '.mixdog');
+  return join(root, 'locks');
+}
+
 function lockFileFor(targetPath) {
   const canonical = canonicalLockTarget(targetPath);
   const key = process.platform === 'win32' ? canonical.toLowerCase() : canonical;
   const hash = createHash('sha256').update(key).digest('hex');
-  return join(resolvePluginData(), 'locks', `${hash}.mixdog-lock`);
+  return join(lockDirectory(), `${hash}.mixdog-lock`);
 }
 
 function isPidAlive(pid) {
@@ -112,7 +123,7 @@ function tryCreateLock(lockFile, token) {
 
 async function acquireAdvisoryLock(targetPath, { timeoutMs = 5000, pollMs = 25 } = {}) {
   const lockFile = lockFileFor(targetPath);
-  mkdirSync(dirname(lockFile), { recursive: true });
+  ensurePrivateRuntimeRoot(dirname(lockFile));
   const token = `${process.pid}.${randomBytes(8).toString('hex')}`;
   const deadline = Date.now() + timeoutMs;
   let stalePostDeadlineRetryUsed = false;

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool/backgrounded-result.mjs

@@ -19,6 +19,7 @@ export function shellTaskIdentity(command, options) {
       callerSessionId: options?.callerSessionId || options?.sessionId || null,
       routingSessionId: options?.routingSessionId || options?.sessionId || null,
       clientHostPid: options?.clientHostPid,
+      hop: options?.hop,
     },
   };
 }
@@ -61,6 +62,7 @@ export function renderBackgroundedResult({ result, command, cwd, options, starte
         callerSessionId: options?.callerSessionId || options?.sessionId,
         routingSessionId: options?.routingSessionId || options?.sessionId,
         clientHostPid: options?.clientHostPid,
+        hop: options?.hop,
       });
     } catch {
       /* best effort */

package/src/runtime/agent/orchestrator/tools/builtin/git-command-tool.mjs

@@ -1,3 +1,4 @@
+import { isUtf8 } from 'node:buffer';
 import { existsSync } from 'node:fs';
 import { mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
@@ -8,6 +9,10 @@ import { withBuiltinPathLocks } from './path-locks.mjs';
 import { withAdvisoryLocks } from './advisory-lock.mjs';
 import { gitRepoLockKey, withGitWorktreeWriteLock } from './git-repo-rw-lock.mjs';
 import { invalidateBuiltinResultCache } from './cache-layers.mjs';
+import { tryAdmitWorkspaceActivity } from '../../../../shared/worktrees/activity-gate.mjs';
+import { WORKTREE_SNAPSHOT_KIND } from '../../../../shared/worktrees/contract.mjs';
+import { isWithin } from '../../../../shared/worktrees/paths.mjs';
+import { readRegistrySync } from '../../../../shared/worktrees/registry.mjs';
 import { runAbortable } from '../../../../shared/abort-race.mjs';
 import { sleep } from '../../../../shared/sleep.mjs';
 import { capMarker } from '../../../../shared/tool-output-marker.mjs';
@@ -26,6 +31,12 @@ import {
   diffSnapshotMatches,
   getDiffSnapshot,
 } from './git-partial-stage.mjs';
+import {
+  executeRawWorktree,
+  executeWorktreeAction,
+  WORKTREE_INPUT_FIELDS,
+  WORKTREE_TOOL_ACTIONS,
+} from './git-worktree-tool.mjs';
 
 const DEFAULT_TIMEOUT_MS = 120_000;
 const MAX_CAPTURE_BYTES = 128 * 1024 * 1024;
@@ -84,14 +95,15 @@ export const GIT_TOOL_DEF = {
     compressible: true,
   },
   description:
-    'Run Git here, never through shell. An array (max 10) runs in order and stops on failure; batch read-only commands in one. diff for known changes, status to discover them; history only when needed. git diff or git diff -- <paths> includes untracked files. Set include_stage_ids:true to select changes, then action:stage with diff_id/change_ids. Staging rejects stale or cross-Project diffs and returns per-file staged counts.',
+    'Run Git here, never through shell. An array (max 10) runs in order and stops on failure; batch read-only commands in one. diff for known changes, status to discover them; history only when needed. git diff or git diff -- <paths> includes untracked files. Set include_stage_ids:true to select changes, then action:stage with diff_id/change_ids. Staging rejects stale or cross-Project diffs and returns per-file staged counts. Worktrees are managed only: action:worktree (Lead only) moves a session into/out of its managed worktree, merges, removes, lists, prunes; git worktree add/remove/list/prune map to managed operations (add -b keeps the session in place; add --detach makes a read-only snapshot worktree, removed when its turn ends; list --porcelain stays raw git; move/lock/unlock/repair are refused). Merge or remove only when the user asks; carry and large-size answers come from the user; force only on explicit request.',
   inputSchema: {
     type: 'object',
     properties: {
       action: {
         type: 'string',
-        enum: ['command', 'stage'],
-        description: 'Default command. stage uses diff_id/change_ids instead of command.',
+        enum: ['command', 'stage', 'worktree'],
+        description:
+          'Default command. stage uses diff_id/change_ids instead of command. worktree uses worktree_action and its fields.',
       },
       command: {
         anyOf: [
@@ -118,6 +130,29 @@ export const GIT_TOOL_DEF = {
         anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 50 }],
         description: 'stage: exact change ID or IDs to stage, including new files.',
       },
+      worktree_action: {
+        type: 'string',
+        enum: [...WORKTREE_TOOL_ACTIONS],
+        description:
+          'enter: create or re-enter the managed worktree (branch: that branch, create: new); return: back to the project folder, worktree kept; merge: into its merge target; remove; list; prune.',
+      },
+      session_id: {
+        type: 'string',
+        description: 'enter/return/merge/remove: another session (it must be idle); default the caller.',
+      },
+      name: { type: 'string', description: 'enter: the new worktree name (branch <prefix><name>).' },
+      branch: { type: 'string', description: 'enter: use the worktree of this branch instead.' },
+      create: { type: 'boolean', description: 'enter with branch: create that branch.' },
+      carry: {
+        type: 'string',
+        enum: ['leave', 'carry'],
+        description: 'enter: the user answer to WORKTREE_DIRTY_CHOICE (uncommitted project-folder changes).',
+      },
+      confirm_large: {
+        type: 'boolean',
+        description: 'enter or git worktree add: the user accepted the WORKTREE_LARGE_REPO_CONFIRM size.',
+      },
+      force: { type: 'boolean', description: 'remove: discard dirty/unmerged work; only on explicit user request.' },
     },
     additionalProperties: false,
   },
@@ -136,6 +171,9 @@ function ok(data = {}) {
   });
 }
 
+const NOT_UTF8_STAGE_NOTE =
+  'staging ids unavailable: this diff has bytes that are not UTF-8 (a file in another encoding), and staging its text would replace them; stage those files whole with git add -- <paths>';
+
 function fail(message) {
   return `error: ${message}`;
 }
@@ -398,6 +436,9 @@ async function runProcess(program, argv, { cwd, signal, maxBytes = MAX_CAPTURE_B
           ...(optionalLocks ? {} : { GIT_OPTIONAL_LOCKS: '0' }),
         },
         outputLimit: maxBytes,
+        // Bytes as git wrote them, decoded once by the caller: a multibyte
+        // character split across two pipe reads must not become U+FFFD.
+        rawOutput: true,
       },
     });
     if (!native?.child)
@@ -561,9 +602,13 @@ function prepare(plan) {
   return { argv: [operation, ...args] };
 }
 
+// A stage applies the text of this diff, so a patch with bytes that are not
+// UTF-8 (a legacy-encoded file) would be applied with U+FFFD in their place.
+// `notUtf8` marks such a diff: it is shown, but never staged by id.
 async function runStageableDiff(plan, argv, repo, signal) {
   const result = await runGit(plan, argv, { signal, readOnly: true });
   if (!succeeded(result)) return result;
+  result.notUtf8 = !isUtf8(result.stdout);
   result.stdout = String(result.stdout);
   result.stderr = String(result.stderr);
   const paths = plan.args.slice(1);
@@ -593,6 +638,7 @@ async function runStageableDiff(plan, argv, repo, signal) {
     );
     // --no-index uses exit 1 for a successfully produced patch.
     if (!succeeded({ ...added, exitCode: added.exitCode === 1 ? 0 : added.exitCode })) return added;
+    if (!isUtf8(added.stdout)) result.notUtf8 = true;
     result.stdout = appendText(result.stdout, String(added.stdout));
     result.stderr = appendText(result.stderr, String(added.stderr));
   }
@@ -763,26 +809,14 @@ function creationTarget(plan) {
 // --prune=now as unsafe beside a concurrent writer), so these hold the whole
 // repository.
 const REPO_WIDE_OPERATIONS = new Set(['gc', 'maintenance', 'prune', 'prune-packed', 'repack']);
-const WORKTREE_VALUE_FLAGS = new Set(['-b', '-B', '--reason']);
 
 // The worktrees a mutating plan touches; null holds the whole repository. A
-// write changes its cwd's worktree, except that `git worktree add/remove/move`
-// change the target worktree (plus the shared admin dir, which git itself
-// guards), so writes on different worktrees never wait for each other.
+// write changes its cwd's worktree, so writes on different worktrees never
+// wait for each other. (`git worktree` never runs as a git write here: it
+// maps to managed operations, which take the repository lock themselves.)
 function writeScopes(plan, root) {
   if (REPO_WIDE_OPERATIONS.has(plan.operation)) return null;
-  if (plan.operation !== 'worktree') return [root];
-  const [action, ...paths] = optionFreePositionals(plan.args, WORKTREE_VALUE_FLAGS);
-  const target = (path) => resolve(plan.cwd, path);
-  // git also names a worktree by a unique path suffix, which no cwd-relative
-  // path resolves; an argument that is not a worktree here holds the whole
-  // repository instead of guessing (so do prune and an argument-less repair).
-  const existing = (path) => (existsSync(join(target(path), '.git')) ? target(path) : null);
-  let scopes = null;
-  if (action === 'add') scopes = paths.slice(0, 1).map(target);
-  else if (action === 'move' && paths.length === 2) scopes = [existing(paths[0]), target(paths[1])];
-  else if (['remove', 'lock', 'unlock', 'repair'].includes(action)) scopes = paths.map(existing);
-  return scopes?.length && scopes.every(Boolean) ? scopes : null;
+  return [root];
 }
 
 // A mutating git call holds the in-process and cross-process locks on its
@@ -804,6 +838,34 @@ function withGitWriteLocks(lockKey, scopes, root, signal, callback) {
   );
 }
 
+// The managed snapshot worktree `repo` lies in, else null. A registry that
+// cannot be read names none: commands elsewhere run as before.
+function snapshotContaining(repo) {
+  let entries;
+  try {
+    entries = readRegistrySync().entries;
+  } catch {
+    return null;
+  }
+  return (
+    Object.values(entries).find(
+      (record) => record?.kind === WORKTREE_SNAPSHOT_KIND && typeof record.path === 'string' && isWithin(record.path, repo)
+    ) ?? null
+  );
+}
+
+// A command run in a snapshot worktree is one of its consumers: the workspace
+// lease it holds (activity-gate, the same as a background shell's) keeps the
+// snapshot from being removed in any process until it ends, and a snapshot
+// whose removal is under way refuses it. Returns the release.
+function admitSnapshotCommand(repo, sessionId) {
+  const snapshot = snapshotContaining(repo);
+  if (!snapshot) return () => {};
+  const leave = tryAdmitWorkspaceActivity(sessionId || 'git-tool', repo, { kind: 'command' });
+  if (!leave) throw new Error(`the snapshot worktree ${snapshot.path} is being removed; nothing ran`);
+  return leave;
+}
+
 function invalidateAfterGitMutation() {
   invalidateBuiltinResultCache();
   drainCodeGraphCache();
@@ -873,6 +935,7 @@ async function executeGitStage(input, workDir, options = {}) {
     };
     const current = await runStageableDiff(snapshot.plan, snapshot.argv, repo, signal);
     if (!succeeded(current)) return noted(commandFailure(snapshot.plan, current, limit));
+    if (current.notUtf8) return noted(fail(NOT_UTF8_STAGE_NOTE));
     const raw = current.stdout;
     if (!diffSnapshotMatches(snapshot, raw)) {
       return answer({
@@ -919,6 +982,15 @@ async function executeSingleGitTool(input, workDir, options = {}) {
   } catch (error) {
     return rejected(error.message);
   }
+  // No unmanaged worktree is ever made here: worktree commands run as their
+  // managed operations (git-worktree-tool.mjs); only `list --porcelain` stays git.
+  if (plan.operation === 'worktree') {
+    const mapped = await executeRawWorktree(plan, input, options);
+    if (mapped) {
+      if (!isReadOnly(plan)) invalidateAfterGitMutation();
+      return mapped;
+    }
+  }
   if (
     plan.operation === 'archive' &&
     !plan.args.some((value) => value === '-o' || value === '--output' || value.startsWith('--output='))
@@ -954,6 +1026,23 @@ async function executeSingleGitTool(input, workDir, options = {}) {
     const missing = probe ?? (await runGit(plan, ['rev-parse', '--show-toplevel'], { signal }));
     return commandResult(plan, missing, limit);
   }
+  // A command in a snapshot worktree uses it like a worker would: it holds a
+  // workspace lease there while it runs, so the snapshot is never removed
+  // under it, and a snapshot being removed refuses it.
+  let leaveSnapshot;
+  try {
+    leaveSnapshot = admitSnapshotCommand(repo, options.sessionId);
+  } catch (error) {
+    return rejected(error.message);
+  }
+  try {
+    return await runInRepository(input, plan, { repo, lockKey, limit, signal, workDir });
+  } finally {
+    leaveSnapshot();
+  }
+}
+
+async function runInRepository(input, plan, { repo, lockKey, limit, signal, workDir }) {
   const prepared = prepare(plan);
   const stageableRequest = plan.operation === 'diff' && (plan.args.length === 0 || plan.args[0] === '--');
   if (stageableRequest) prepared.argv.splice(1, 0, '--no-textconv', '--src-prefix=a/', '--dst-prefix=b/');
@@ -965,6 +1054,11 @@ async function executeSingleGitTool(input, workDir, options = {}) {
       : await runGit(plan, prepared.argv, { signal, readOnly: true });
     if (!succeeded(result)) return commandResult(plan, result, limit);
     if (stageableRequest && input.include_stage_ids === true) {
+      if (result.notUtf8) {
+        const rendered = commandResult(plan, result, limit);
+        rendered.text = appendText(rendered.text, NOT_UTF8_STAGE_NOTE);
+        return rendered;
+      }
       const snapshot = createDiffSnapshot({
         repo,
         scope: resolve(workDir || process.cwd()),
@@ -977,6 +1071,9 @@ async function executeSingleGitTool(input, workDir, options = {}) {
     return commandResult(plan, result, limit);
   }
   return withGitWriteLocks(lockKey, writeScopes(plan, repo), repo, signal, async (waitedMs) => {
+    // A managed removal holds the same folder lock while it deletes: once it
+    // is ours, a folder that is gone was removed, and nothing runs there.
+    if (!existsSync(repo)) return rejected(`the worktree folder ${repo} was removed meanwhile; nothing ran`);
     const result = await runGitWrite(plan, prepared.argv, { signal });
     invalidateAfterGitMutation();
     const rendered = commandResult(plan, result, limit);
@@ -1064,13 +1161,23 @@ export async function executeGitTool(rawInput, workDir, options = {}) {
   if (rawInput.change_ids !== undefined) input.change_ids = parseStringifiedArray(rawInput.change_ids);
   if (rawInput.command === undefined) delete input.command;
   const action = input.action ?? 'command';
+  if (action === 'worktree') {
+    const text = await executeWorktreeAction(input, workDir, options);
+    if (input.worktree_action !== 'list') invalidateAfterGitMutation();
+    return text;
+  }
+  const worktreeField = WORKTREE_INPUT_FIELDS.find((field) => input[field] !== undefined);
+  if (worktreeField) return fail(`git ${worktreeField} requires action:worktree`);
+  if (input.confirm_large !== undefined && action !== 'command') {
+    return fail('git confirm_large applies to action:worktree or a git worktree add command');
+  }
   if (action === 'stage') {
     if (input.command !== undefined || input.include_stage_ids !== undefined) {
       return fail('git action:stage accepts diff_id/change_ids, not command/include_stage_ids');
     }
     return executeGitStage(input, workDir, options);
   }
-  if (action !== 'command') return fail('git action must be command or stage');
+  if (action !== 'command') return fail('git action must be command, stage or worktree');
   if (input.diff_id !== undefined || input.change_ids !== undefined) {
     return fail('git diff_id/change_ids require action:stage');
   }