mixdog 1.3.1 → 1.3.3

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

@@ -1,16 +1,52 @@
-// Cross-process advisory lock for patch/write operations. Uses a sibling
-// lockfile written exclusively (`wx`) and a process.kill(pid, 0) liveness
-// check to 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 } from 'node:fs';
+// Cross-process advisory lock for patch/write operations. Uses a lockfile
+// written exclusively (`wx`) and a process.kill(pid, 0) liveness check to
+// 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, realpathSync } from 'node:fs';
 import { compareCodePoints } from '../../../../shared/code-point-order.mjs';
+import { ensurePrivateRuntimeRoot } from '../../../../shared/runtime-root.mjs';
 import { sleep } from '../../../../shared/sleep.mjs';
-import { dirname, basename, join } from 'node:path';
-import { randomBytes } from 'node:crypto';
+import { homedir } from 'node:os';
+import { dirname, basename, join, resolve } from 'node:path';
+import { createHash, randomBytes } from 'node:crypto';
+
+// The deepest existing component (the target itself when present, so a leaf
+// symlink shares its referent's lock like atomicWrite writes through it) is
+// resolved; components not created yet are appended as given.
+function canonicalLockTarget(targetPath) {
+  const resolved = resolve(targetPath);
+  const tail = [];
+  let dir = resolved;
+  for (;;) {
+    try {
+      return join(realpathSync.native(dir), ...tail.reverse());
+    } catch {
+      if (dirname(dir) === dir) return resolved;
+      tail.push(basename(dir));
+      dir = dirname(dir);
+    }
+  }
+}
+
+// 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) {
-  return join(dirname(targetPath), `.${basename(targetPath)}.mixdog-lock`);
+  const canonical = canonicalLockTarget(targetPath);
+  const key = process.platform === 'win32' ? canonical.toLowerCase() : canonical;
+  const hash = createHash('sha256').update(key).digest('hex');
+  return join(lockDirectory(), `${hash}.mixdog-lock`);
 }
 
 function isPidAlive(pid) {
@@ -87,15 +123,12 @@ function tryCreateLock(lockFile, token) {
 
 async function acquireAdvisoryLock(targetPath, { timeoutMs = 5000, pollMs = 25 } = {}) {
   const lockFile = lockFileFor(targetPath);
-  // Ensure parent directory exists before openSync('wx'); the lockfile lives
-  // next to the target, so writes to new files in missing parent dirs would
-  // otherwise fail with ENOENT here.
-  mkdirSync(dirname(lockFile), { recursive: true });
+  ensurePrivateRuntimeRoot(dirname(lockFile));
   const token = `${process.pid}.${randomBytes(8).toString('hex')}`;
   const deadline = Date.now() + timeoutMs;
   let stalePostDeadlineRetryUsed = false;
   const timeoutError = (holderPid) => {
-    const err = new Error(`advisory lock timeout: ${lockFile} held by pid ${holderPid}`);
+    const err = new Error(`advisory lock timeout: ${targetPath} (${lockFile}) held by pid ${holderPid}`);
     err.code = 'EAGAIN';
     return err;
   };

package/src/runtime/agent/orchestrator/tools/builtin/atomic-write.mjs

@@ -24,9 +24,24 @@ function expectedTargetSnapshotChanged(currentStat, expected) {
   return !sameFileVersion(currentStat, expected);
 }
 
+// Files the agent writes into a user's project are durable by default: without
+// the flush a crash can publish the renamed file with every byte NUL.
+// MIXDOG_ATOMIC_FSYNC=0|false|no|off opts out.
 function atomicWriteShouldFsync(value) {
   if (value === true || value === false) return value;
-  return /^(1|true|yes|on|sync)$/i.test(String(process.env.MIXDOG_ATOMIC_FSYNC || ''));
+  return !/^(0|false|no|off)$/i.test(String(process.env.MIXDOG_ATOMIC_FSYNC || ''));
+}
+
+// Filesystems that refuse fsync answer with one of these; durability is
+// best-effort there and must not fail the write.
+const FSYNC_TOLERATED = new Set(['EPERM', 'ENOTSUP', 'EINVAL']);
+
+async function syncHandle(fh) {
+  try {
+    await fh.sync();
+  } catch (error) {
+    if (!FSYNC_TOLERATED.has(error?.code)) throw error;
+  }
 }
 
 // 'wx' preflight creates an empty placeholder at targetPath; if the write is
@@ -104,7 +119,10 @@ async function writeTempFile(tmp, content, { mode, fsync }) {
     if (payloadByteLength(content) > STREAMING_THRESHOLD_BYTES) {
       // Streaming path: avoid buffering the entire payload through
       // fh.writeFile (which copies into a single Buffer).
-      const ws = createWriteStream(tmp, { flags: 'wx', mode });
+      // Owner-writable while we flush: the fsync reopens the file for writing,
+      // which a read-only mode would refuse; the final mode is applied after.
+      const streamMode = fsync ? mode | 0o200 : mode;
+      const ws = createWriteStream(tmp, { flags: 'wx', mode: streamMode });
       // Stream construction precedes open; only the open event proves ownership.
       ws.once('open', () => {
         ownsTemp = true;
@@ -115,15 +133,16 @@ async function writeTempFile(tmp, content, { mode, fsync }) {
       await pipeline(source, ws);
       if (fsync) {
         fh = await fsPromises.open(tmp, 'r+');
-        await fh.sync();
+        await syncHandle(fh);
         await fh.close();
         fh = null;
+        if (streamMode !== mode) await fsPromises.chmod(tmp, mode);
       }
     } else {
       fh = await fsPromises.open(tmp, 'wx', mode);
       ownsTemp = true;
       await fh.writeFile(content);
-      if (fsync) await fh.sync();
+      if (fsync) await syncHandle(fh);
       await fh.close();
       fh = null;
     }
@@ -260,7 +279,8 @@ export async function atomicWrite(
   // beside the real target, so the rename stays on one filesystem.
   const writeTarget = symlinkWriteTarget(targetPath) ?? targetPath;
   const dir = dirname(writeTarget);
-  const tmp = join(dir, `.${basename(writeTarget)}.mixdog-tmp-${randomBytes(4).toString('hex')}`);
+  // No leading dot: sync-drive folders (e.g. Naver MYBOX) refuse dot-prefixed names.
+  const tmp = join(dir, `${basename(writeTarget)}.mixdog-tmp-${randomBytes(4).toString('hex')}`);
   const existingStat = statOrNull(writeTarget);
   let effectiveMode = mode;
   if (effectiveMode === undefined && existingStat) effectiveMode = existingStat.mode & 0o777;

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

@@ -3,7 +3,7 @@ import { killShellJob, watchBackgroundShellJob } from '../shell-jobs.mjs';
 import { renderBackgroundPartialOutput } from '../shell-output.mjs';
 import { readShellTaskOutput } from '../lib/shell-task-output.mjs';
 import { normalizeOutputPath } from '../path-utils.mjs';
-import { cleanupArtifactOnTaskSettled, consumeTeeArtifact } from './transport-artifacts.mjs';
+import { cleanupArtifactAfter, cleanupArtifactOnTaskSettled, consumeTeeArtifact } from './transport-artifacts.mjs';
 import { _backgroundResultLines, _prependDestructiveWarning } from './result-format.mjs';
 
 const DEFAULT_BACKGROUND_MESSAGE =
@@ -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 */
@@ -68,8 +70,9 @@ export function renderBackgroundedResult({ result, command, cwd, options, starte
   }
   // The promoted producer is still writing into the tee file, so it cannot be
   // consumed here — but it must not survive the command either. Consume (and
-  // delete) it when the task settles.
-  if (teePlan) cleanupArtifactOnTaskSettled(teePlan.teePath, result.jobId, consumeTeeArtifact);
+  // delete) it when the task settles — for a queued command, its run.
+  if (teePlan && result.jobId) cleanupArtifactOnTaskSettled(teePlan.teePath, result.jobId, consumeTeeArtifact);
+  else if (teePlan) cleanupArtifactAfter(teePlan.teePath, result.settled, consumeTeeArtifact);
   let taskBlock = null;
   if (task) taskBlock = renderBackgroundTask(task, { ownerTool: true });
   else if (result.jobId) taskBlock = `[task_id: ${result.jobId}]`;

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

@@ -1,9 +1,9 @@
 import { renderBackgroundTask, startBackgroundTask } from '../../../../../shared/background-tasks.mjs';
 import { killShellDescendants, waitForShellDescendants } from '../../lib/shell-descendants.mjs';
 import { releaseShellJobWorkspace } from '../lib/shell-job-records.mjs';
-import { consumeFilterTeeCapture } from '../shell-analysis.mjs';
+import { readFilterTeeCapture } from '../shell-analysis.mjs';
 import { compactShellOutputLosslessly, renderShellOutputBody } from '../shell-lossless-compact.mjs';
-import { removeTransportFileNow } from './transport-artifacts.mjs';
+import { cleanupArtifactAfter, removeTransportFileNow } from './transport-artifacts.mjs';
 import { DELIVERY_FULL_CHARS, EMPTY_PIECE, fitPieces, shellTextPiece } from '../lib/shell-delivery.mjs';
 import { shellLogPiece } from '../lib/shell-task-output.mjs';
 import { shellTaskIdentity } from './backgrounded-result.mjs';
@@ -74,17 +74,16 @@ function survivingDescendantsWarning(result, taskContext) {
   return [heading, renderBackgroundTask(task, { ownerTool: true })].join('\n');
 }
 
-// Filter-swallow rescue: the tee file is ALWAYS consumed (deleted) here; its
-// tail is attached only when the run failed with an empty visible capture —
-// the exact `(no output)` shape that previously cost the model extra
-// diagnostic turns.
-function filterRescueNote(teePlan, { failed, stdout, stderr }) {
-  const rescueTail = consumeFilterTeeCapture(teePlan.teePath);
-  // consumeFilterTeeCapture unlinks best-effort and swallows the failure; on
-  // Windows a process that survived an unconfirmed kill still holds the file.
-  // Route it through the same retry + exit-hook path the settlement branch
-  // uses instead of abandoning it.
-  removeTransportFileNow(teePlan.teePath);
+// Filter-swallow rescue: the tee file is ALWAYS consumed (deleted) — once the
+// run's tree has settled when its result says it may still run; its tail is
+// attached only when the run failed with an empty visible capture — the exact
+// `(no output)` shape that previously cost the model extra diagnostic turns.
+function filterRescueNote(teePlan, { failed, stdout, stderr }, settled) {
+  const rescueTail = readFilterTeeCapture(teePlan.teePath);
+  // Removal goes through the retry + exit-hook path: on Windows a process
+  // that survived an unconfirmed kill still holds the file.
+  if (settled) cleanupArtifactAfter(teePlan.teePath, settled);
+  else removeTransportFileNow(teePlan.teePath);
   if (!failed || !rescueTail || stdout.trim() || stderr.trim()) return '';
   return `\n\n[filter-swallowed output rescue] the command failed but its trailing filter(s) matched nothing, so the visible output was empty. Unfiltered pipeline output (tail):\n${rescueTail}`;
 }
@@ -148,7 +147,7 @@ export function renderCompletedResult({
   const { signal, exitCode, completedExit, benignExit, isReallyErrored } = outcome;
   const commandExitedNonzero = completedExit && exitCode !== 0 && !benignExit;
   const rescueNote = teePlan
-    ? filterRescueNote(teePlan, { failed: isReallyErrored || commandExitedNonzero, stdout, stderr })
+    ? filterRescueNote(teePlan, { failed: isReallyErrored || commandExitedNonzero, stdout, stderr }, result.settled)
     : '';
   const descendantWarning = survivingDescendantsWarning(result, { command, cwd, options, startedAtMs });
   // rewriteNote states that the text which RAN is not the text the caller

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool/transport-artifacts.mjs

@@ -79,6 +79,15 @@ export function removeTransportFileNow(file) {
   finishTransportArtifact(file, removeTransportFile);
 }
 
+/** Remove `file` once a run's own lifetime promise settles: a queued command
+ *  has no job to subscribe to until it runs. */
+export function cleanupArtifactAfter(file, settled, remove = removeTransportFile) {
+  if (!file) return;
+  registerTransportArtifact(file);
+  const done = () => finishTransportArtifact(file, remove);
+  Promise.resolve(settled).then(done, done);
+}
+
 export function cleanupArtifactOnTaskSettled(file, jobId, remove = removeTransportFile) {
   if (!file) return;
   registerTransportArtifact(file);

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

@@ -12,7 +12,11 @@ import { recordShellCaptureTelemetry } from './shell-output.mjs';
 import { normalizeErrorMessage } from './path-diagnostics.mjs';
 import { invalidateBuiltinResultCache } from './cache-layers.mjs';
 import { formatShellToolFailure } from './bash-tool/result-format.mjs';
-import { cleanupArtifactOnTaskSettled, removeTransportFileNow } from './bash-tool/transport-artifacts.mjs';
+import {
+  cleanupArtifactAfter,
+  cleanupArtifactOnTaskSettled,
+  removeTransportFileNow,
+} from './bash-tool/transport-artifacts.mjs';
 import { combineAbortSignals, sessionAbortSignal } from './bash-tool/abort-signals.mjs';
 import { beginInterruptibleTaskWait } from '../../session/task-wait-control.mjs';
 import { prepareShellCommand } from './bash-tool/command-preflight.mjs';
@@ -39,9 +43,10 @@ export { buildShellSpawnEnv } from './bash-tool/spawn-env.mjs';
 export { executeTaskTool } from './task-tool.mjs';
 
 // Reads cached after a mutating command must not serve pre-command state. A
-// promoted command has barely started when the tool returns and a queued one
-// has not started at all, so the invalidation repeats when it settles.
-function settleMutationCaches(shellEffects, backgroundJobId, queuedSettled = null) {
+// promoted command has barely started when the tool returns, a queued one has
+// not started at all and a killed tree may still run, so the invalidation
+// repeats when it settles.
+function settleMutationCaches(shellEffects, backgroundJobId, runSettled = null) {
   const invalidate = () => {
     if (shellEffects.mutationMode === 'paths') {
       invalidateBuiltinResultCache(shellEffects.paths);
@@ -55,7 +60,7 @@ function settleMutationCaches(shellEffects, backgroundJobId, queuedSettled = nul
   if (backgroundJobId && shellEffects.mutationMode !== 'none') {
     subscribeShellJobSettled(backgroundJobId, invalidate);
   }
-  if (queuedSettled && shellEffects.mutationMode !== 'none') queuedSettled.then(invalidate).catch(() => {});
+  if (runSettled && shellEffects.mutationMode !== 'none') runSettled.then(invalidate).catch(() => {});
 }
 
 export async function executeBashTool(args, workDir, options = {}) {
@@ -89,7 +94,8 @@ export async function executeBashTool(args, workDir, options = {}) {
   const inputWake = backgroundOnTimeout ? beginInterruptibleTaskWait(options?.sessionId) : null;
   let backgrounded = false;
   let backgroundJobId = null;
-  let queuedSettled = null;
+  // A queued run, or a foreground tree that may outlive its result, settles later.
+  let runSettled = null;
   try {
     const invocation = await planShellInvocation({ command, resolvedSpec, cwd: bashWorkDir });
     if (invocation.failure) return invocation.failure;
@@ -127,7 +133,7 @@ export async function executeBashTool(args, workDir, options = {}) {
     });
     backgrounded = result.backgrounded === true;
     backgroundJobId = backgrounded ? result.jobId || null : null;
-    queuedSettled = backgrounded ? result.settled || null : null;
+    runSettled = result.settled || null;
     const stdout = stripAnsi(result.stdout || '');
     const stderr = stripAnsi(result.stderr || '');
     recordShellCaptureTelemetry(options?.resultTelemetry, result, stdout, stderr);
@@ -152,14 +158,13 @@ export async function executeBashTool(args, workDir, options = {}) {
     inputWake?.dispose();
     combinedAbort?.cleanup?.();
     if (hoisted.hoistPath) {
-      // A promoted or queued command still runs from the hoisted file; a
-      // foreground one is done with it now (an unconfirmed kill may keep it
-      // locked — retried).
-      if (queuedSettled) {
-        queuedSettled.then(() => removeTransportFileNow(hoisted.hoistPath)).catch(() => {});
-      } else if (backgrounded) cleanupArtifactOnTaskSettled(hoisted.hoistPath, backgroundJobId);
+      // A promoted or queued command still runs from the hoisted file, and so
+      // may a killed tree until it settles; a finished foreground one is done
+      // with it now (an unconfirmed kill may keep it locked — retried).
+      if (runSettled) cleanupArtifactAfter(hoisted.hoistPath, runSettled);
+      else if (backgrounded) cleanupArtifactOnTaskSettled(hoisted.hoistPath, backgroundJobId);
       else removeTransportFileNow(hoisted.hoistPath);
     }
-    settleMutationCaches(shellEffects, backgroundJobId, queuedSettled);
+    settleMutationCaches(shellEffects, backgroundJobId, runSettled);
   }
 }

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

@@ -87,7 +87,13 @@ export const BUILTIN_TOOLS = [
           type: 'integer',
           minimum: 1,
           maximum: PUBLIC_READ_WINDOW_MAX,
-          description: 'Maximum line count; default 500 per exact file, 25 per glob-expanded file; batch default.',
+          description:
+            'Maximum line count; default 500 per exact file, 25 per glob-expanded file; batch default. Lines only: PDFs use pages.',
+        },
+        pages: {
+          type: 'string',
+          description:
+            'PDF page range "N" or "N-M", 1-based, ≤20 pages per call. Text pages return text; scanned pages (no text layer) return page images, or OCR text on a text-only model. Without pages, a PDF over 10 pages returns its first 5 pages and page count.',
         },
       },
       required: ['file_path'],

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');
   }