mixdog 1.4.0 → 1.4.2

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

@@ -9,11 +9,12 @@ 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 { tryAdmitWorkspaceActivityAsync } 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 { startGit } from '../../../../shared/git-launch.mjs';
 import { sleep } from '../../../../shared/sleep.mjs';
 import { capMarker } from '../../../../shared/tool-output-marker.mjs';
 import { drainCodeGraphCache } from '../code-graph-state.mjs';
@@ -83,6 +84,9 @@ const SERVER_OPERATIONS = new Set(['daemon', 'instaweb']);
 // probe into `git rev-parse exited 128` inside a plain directory.
 const REPO_FREE_OPERATIONS = new Set(['version', 'help']);
 
+const GIT_DESCRIPTION_HEAD =
+  'Run Git here, never through shell. An array 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.';
+
 export const GIT_TOOL_DEF = {
   name: 'git',
   title: 'Git',
@@ -94,8 +98,7 @@ export const GIT_TOOL_DEF = {
     openWorldHint: true,
     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. 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.',
+  description: `${GIT_DESCRIPTION_HEAD} Worktrees are managed only: action:worktree; 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.`,
   inputSchema: {
     type: 'object',
     properties: {
@@ -118,14 +121,14 @@ export const GIT_TOOL_DEF = {
         minimum: 1,
         maximum: GIT_OUTPUT_LIMIT_MAX,
         description:
-          'Body line cap, max 1000; staging IDs are not capped. Default 500; git log defaults to 100. A cut ends with [output capped …] naming how to continue.',
+          'Body line cap; staging IDs are not capped. Default 500; git log defaults to 100. A cut ends with [output capped …] naming how to continue.',
       },
       include_stage_ids: {
         type: 'boolean',
         description:
           'Include staging IDs outside the body cap for git diff or git diff -- <paths> only. Default false.',
       },
-      diff_id: { type: 'string', description: 'stage: exact diff_id from git diff with include_stage_ids:true.' },
+      diff_id: { type: 'string', description: 'stage: exact diff_id from git diff.' },
       change_ids: {
         anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 50 }],
         description: 'stage: exact change ID or IDs to stage, including new files.',
@@ -158,6 +161,29 @@ export const GIT_TOOL_DEF = {
   },
 };
 
+// Only the Lead host runs enter/return/merge/remove/prune (git-worktree-tool.mjs
+// leadHost); an agent keeps `list`, so its schema omits every field the other
+// operations take.
+const LEAD_ONLY_WORKTREE_FIELDS = ['session_id', 'name', 'branch', 'create', 'carry', 'confirm_large', 'force'];
+
+function buildGitAgentToolDef(base) {
+  const properties = { ...base.inputSchema.properties };
+  for (const field of LEAD_ONLY_WORKTREE_FIELDS) delete properties[field];
+  properties.action = {
+    ...properties.action,
+    description: 'Default command. stage uses diff_id/change_ids instead of command. worktree uses worktree_action.',
+  };
+  properties.worktree_action = { type: 'string', enum: ['list'], description: 'list only.' };
+  return {
+    ...base,
+    description: `${GIT_DESCRIPTION_HEAD} Worktrees are Lead-managed: only worktree_action:list and git worktree list work; every other worktree operation is refused.`,
+    inputSchema: { ...base.inputSchema, properties },
+  };
+}
+
+/** The git tool as a delegated agent sees it (see bindAgentOwner). */
+export const GIT_AGENT_TOOL_DEF = buildGitAgentToolDef(GIT_TOOL_DEF);
+
 function cleanText(value) {
   return String(value || '')
     .replace(/\r\n/g, '\n')
@@ -412,7 +438,24 @@ function parseCommand(rawCommand, workDir) {
   return { command: String(command), cwd, globalArgs, operation, args };
 }
 
-async function runProcess(program, argv, { cwd, signal, maxBytes = MAX_CAPTURE_BYTES, optionalLocks = true } = {}) {
+function gitToolEnvironment(optionalLocks) {
+  return {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_PAGER: 'cat',
+    GIT_EDITOR: 'true',
+    GIT_SEQUENCE_EDITOR: 'true',
+    LC_ALL: 'C',
+    // Reads run beside writes without a lock (git-repo-rw-lock.mjs).
+    // With optional locks off `git status` never takes index.lock to
+    // write back a refreshed index, so it cannot fail a concurrent
+    // write on that lock. (`git diff` ignores the setting and may still
+    // refresh the index briefly; the write retry absorbs that.)
+    ...(optionalLocks ? {} : { GIT_OPTIONAL_LOCKS: '0' }),
+  };
+}
+
+async function runProcess(program, argv, { cwd, signal, maxBytes = MAX_CAPTURE_BYTES, env } = {}) {
   let child;
   try {
     await ensureNativeSpawnServer();
@@ -421,20 +464,7 @@ async function runProcess(program, argv, { cwd, signal, maxBytes = MAX_CAPTURE_B
       argv,
       spawnOptions: {
         cwd,
-        env: {
-          ...process.env,
-          GIT_TERMINAL_PROMPT: '0',
-          GIT_PAGER: 'cat',
-          GIT_EDITOR: 'true',
-          GIT_SEQUENCE_EDITOR: 'true',
-          LC_ALL: 'C',
-          // Reads run beside writes without a lock (git-repo-rw-lock.mjs).
-          // With optional locks off `git status` never takes index.lock to
-          // write back a refreshed index, so it cannot fail a concurrent
-          // write on that lock. (`git diff` ignores the setting and may still
-          // refresh the index briefly; the write retry absorbs that.)
-          ...(optionalLocks ? {} : { GIT_OPTIONAL_LOCKS: '0' }),
-        },
+        env,
         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.
@@ -548,11 +578,11 @@ function commandFailure(plan, result, limit = GIT_OUTPUT_LINES_DEFAULT) {
 }
 
 function runGit(plan, argv, options = {}) {
-  return runProcess('git', [...plan.globalArgs, ...argv], {
-    cwd: plan.cwd,
-    signal: options.signal,
-    optionalLocks: !options.readOnly,
-  });
+  return startGit(
+    gitToolEnvironment(!options.readOnly),
+    (command, env) => runProcess(command, [...plan.globalArgs, ...argv], { cwd: plan.cwd, signal: options.signal, env }),
+    (result) => result.error
+  );
 }
 
 // Another process (an editor, a terminal, an IDE) holding one of git's lock
@@ -560,6 +590,10 @@ function runGit(plan, argv, options = {}) {
 // config.lock. Commands take that lock before changing anything, so a brief
 // retry with backoff turns the collision into a short wait; a command that had
 // already done part of its work reports its own state on the retry.
+// Git reports lock contention only as text: lockfile.c's "Unable to create
+// '<path>.lock': File exists" (and config.c's "could not lock config file"),
+// stable English because runProcess pins LC_ALL=C. The delays are a bounded
+// backoff (3.1 s in all), a policy choice rather than anything git reports.
 const GIT_LOCK_CONTENTION_RE =
   /Unable to create '[^'\n]*\.lock': File exists|could not lock config file [^\n]*: File exists/;
 const GIT_LOCK_RETRY_DELAYS_MS = [100, 200, 400, 800, 1600];
@@ -849,7 +883,8 @@ function snapshotContaining(repo) {
   }
   return (
     Object.values(entries).find(
-      (record) => record?.kind === WORKTREE_SNAPSHOT_KIND && typeof record.path === 'string' && isWithin(record.path, repo)
+      (record) =>
+        record?.kind === WORKTREE_SNAPSHOT_KIND && typeof record.path === 'string' && isWithin(record.path, repo)
     ) ?? null
   );
 }
@@ -858,12 +893,13 @@ function snapshotContaining(repo) {
 // 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) {
+async function admitSnapshotCommand(repo, sessionId) {
   const snapshot = snapshotContaining(repo);
   if (!snapshot) return () => {};
-  const leave = tryAdmitWorkspaceActivity(sessionId || 'git-tool', repo, { kind: 'command' });
+  const leave = await tryAdmitWorkspaceActivityAsync(sessionId || 'git-tool', repo, { kind: 'command' });
   if (!leave) throw new Error(`the snapshot worktree ${snapshot.path} is being removed; nothing ran`);
-  return leave;
+  // Fails only when workspace admission stopped (reported there), which keeps the snapshot held.
+  return () => leave().catch(() => {});
 }
 
 function invalidateAfterGitMutation() {
@@ -1031,14 +1067,14 @@ async function executeSingleGitTool(input, workDir, options = {}) {
   // under it, and a snapshot being removed refuses it.
   let leaveSnapshot;
   try {
-    leaveSnapshot = admitSnapshotCommand(repo, options.sessionId);
+    leaveSnapshot = await admitSnapshotCommand(repo, options.sessionId);
   } catch (error) {
     return rejected(error.message);
   }
   try {
     return await runInRepository(input, plan, { repo, lockKey, limit, signal, workDir });
   } finally {
-    leaveSnapshot();
+    await leaveSnapshot();
   }
 }
 

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

@@ -101,6 +101,8 @@ function worktreeFailureText(code, message, details) {
       return typeof details.path === 'string' && details.path
         ? `This branch is already checked out in ${details.path}.`
         : 'This branch is already checked out in another worktree.';
+    case 'WORKTREE_DEFAULT_BRANCH':
+      return "The repository's default branch can't be opened in a worktree: the project folder could not switch to it while the worktree exists. Check it out in the project folder, or create a new branch for the worktree.";
     case 'WORKTREE_REMOVAL_INCOMPLETE':
       return 'The worktree could not be removed completely because a file is still in use. Close it and remove the worktree again.';
     case 'WORKTREE_PATH_UNSAFE':
@@ -162,6 +164,8 @@ function nextStep(code, details, { raw }) {
       return 'The workspace changed meanwhile; call again (the workspace is read afresh).';
     case 'WORKTREE_BUSY_JOBS':
       return 'Nothing was changed; try again once the session and its workers are idle.';
+    case 'WORKTREE_DEFAULT_BRANCH':
+      return 'Nothing was created. Work on a new branch instead (worktree_action:"enter" with branch and create:true), or ask the user to check the default branch out in the project folder.';
     case 'MERGE_CONFLICT':
       return 'Nothing was merged or forced. Resolve the conflict in the worktree (merge the target branch into it there), or ask the user.';
     case 'WORKTREE_DIRTY':
@@ -316,7 +320,8 @@ async function rawAdd(plan, input, options) {
       throw new Error(`git worktree add: ${value} is not supported for managed worktrees`);
     }
     if (ADD_BARE_FLAGS.has(value)) continue;
-    if (value.startsWith('-')) throw new Error(`git worktree add: option ${value} is not supported for managed worktrees`);
+    if (value.startsWith('-'))
+      throw new Error(`git worktree add: option ${value} is not supported for managed worktrees`);
     positional.push(value);
   }
   const [path, commitish = null] = positional;
@@ -329,11 +334,9 @@ async function rawAdd(plan, input, options) {
   const txId = txIdOf(options, plan.command);
   const mapped = { mapped: plan.command, requestedPath: resolve(plan.cwd, path) };
   // A detached checkout, or a commit-ish that names no local branch: a snapshot.
-  const snapshotCommit = detach
-    ? (commitish ?? 'HEAD')
-    : !branch && commitish && !(await localBranchExists(plan.cwd, commitish))
-      ? commitish
-      : null;
+  let snapshotCommit = null;
+  if (detach) snapshotCommit = commitish ?? 'HEAD';
+  else if (!branch && commitish && !(await localBranchExists(plan.cwd, commitish))) snapshotCommit = commitish;
   if (snapshotCommit) {
     const commit = await commitIn(plan.cwd, snapshotCommit);
     if (!commit) throw new Error(`git worktree add: ${snapshotCommit} is not a commit`);
@@ -436,8 +439,9 @@ async function rawPrune(plan, options) {
 const WORKTREE_HELP = Object.freeze({
   add: 'git worktree add [-b <branch>] [--detach] <path> [<commit-ish>]: a managed worktree for the branch (the session stays put), or a read-only snapshot for a detached commit.',
   remove: 'git worktree remove [-f] <path>: the managed removal of that worktree.',
-  list: 'git worktree list [-v]: managed worktrees plus the repository\'s other worktrees. --porcelain stays raw git.',
-  prune: 'git worktree prune [-n|--dry-run] [-v]: the managed prune of this repository (clean, merged worktrees no session retains); -n only lists what it would remove.',
+  list: "git worktree list [-v]: managed worktrees plus the repository's other worktrees. --porcelain stays raw git.",
+  prune:
+    'git worktree prune [-n|--dry-run] [-v]: the managed prune of this repository (clean, merged worktrees no session retains); -n only lists what it would remove.',
 });
 
 /** -h/--help before any `--` (the help answers instead of the operation running). */
@@ -450,7 +454,9 @@ function wantsHelp(args) {
 function checkListArgs(args) {
   for (const value of args) {
     if (value === '-v' || value === '--verbose') continue;
-    throw new Error(`git worktree list: ${value.startsWith('-') ? `option ${value} is not supported` : `unexpected argument ${value}`}`);
+    throw new Error(
+      `git worktree list: ${value.startsWith('-') ? `option ${value} is not supported` : `unexpected argument ${value}`}`
+    );
   }
 }
 
@@ -466,7 +472,8 @@ export async function executeRawWorktree(plan, input, options = {}) {
   if (sub === 'list' && plan.args.includes('--porcelain')) return null;
   try {
     if (sub === 'list') checkListArgs(plan.args.slice(1));
-    if (sub === 'list') return { text: okJson({ mapped: plan.command, ...(await listRows(options, plan.cwd)) }), failed: false };
+    if (sub === 'list')
+      return { text: okJson({ mapped: plan.command, ...(await listRows(options, plan.cwd)) }), failed: false };
     if (sub === 'add') return { text: await rawAdd(plan, input, options), failed: false };
     if (sub === 'remove') return { text: await rawRemove(plan, options), failed: false };
     if (sub === 'prune') return { text: await rawPrune(plan, options), failed: false };
@@ -479,7 +486,9 @@ export async function executeRawWorktree(plan, input, options = {}) {
       };
     }
     return {
-      text: fail(`git worktree ${sub || '(no subcommand)'} is not supported; use add, remove, list, prune or action:"worktree"`),
+      text: fail(
+        `git worktree ${sub || '(no subcommand)'} is not supported; use add, remove, list, prune or action:"worktree"`
+      ),
       failed: true,
     };
   } catch (error) {
@@ -529,7 +538,8 @@ export async function executeWorktreeAction(input, workDir, options = {}) {
   if (problem) return fail(problem);
   const action = input.worktree_action;
   try {
-    if (action === 'list') return okJson({ worktree_action: action, ...(await listRows(options, resolve(workDir || process.cwd()))) });
+    if (action === 'list')
+      return okJson({ worktree_action: action, ...(await listRows(options, resolve(workDir || process.cwd()))) });
     const host = leadHost(options, `git worktree_action ${action}`);
     const sessionId = input.session_id?.trim() || null;
     const request = {
@@ -545,7 +555,9 @@ export async function executeWorktreeAction(input, workDir, options = {}) {
           }
         : {}),
       ...(action === 'remove' ? { force: input.force === true } : {}),
-      ...(action === 'prune' ? { repoCommonDir: (await repositoryAt(resolve(workDir || process.cwd())))?.repoCommonDir ?? null } : {}),
+      ...(action === 'prune'
+        ? { repoCommonDir: (await repositoryAt(resolve(workDir || process.cwd())))?.repoCommonDir ?? null }
+        : {}),
       txId: txIdOf(options, action),
     };
     const result = await runOn(host, request, options);

package/src/runtime/agent/orchestrator/tools/builtin/lib/scoped-search-flight.mjs

@@ -8,11 +8,15 @@ import {
 // A shared scan's outcome belongs to every subscriber, not only the caller
 // whose computation won admission. Persisted cache hits contain safe text.
 export async function runScopedSearchInFlight(key, compute, options, outcome) {
-  const settled = await runResultCacheInFlight(key, async ({ signal }) => {
-    const scopedCacheOutcome = createScopedCacheOutcome();
-    const result = await compute({ signal, scopedCacheOutcome });
-    return { result, scopedCacheOutcome };
-  }, options);
+  const settled = await runResultCacheInFlight(
+    key,
+    async ({ signal }) => {
+      const scopedCacheOutcome = createScopedCacheOutcome();
+      const result = await compute({ signal, scopedCacheOutcome });
+      return { result, scopedCacheOutcome };
+    },
+    options
+  );
   if (typeof settled === 'string') return settled;
   if (settled.scopedCacheOutcome.complete === false) markScopedCacheIncomplete(outcome);
   if (settled.scopedCacheOutcome.cacheSafe === false) markScopedCacheUnsafe(outcome);

package/src/runtime/agent/orchestrator/tools/builtin/lib/shell-job-records.mjs

@@ -27,24 +27,40 @@ import { join } from 'node:path';
 import { holdsNoData, writeJsonAtomicAsync } from '../../../../../shared/atomic-file.mjs';
 import { isPidAlive } from '../../../../../shared/pid-liveness.mjs';
 import { displayShellCommand } from '../../../../../shared/shell-display.mjs';
-import { tryAdmitWorkspaceActivity } from '../../../../../shared/worktrees/activity-gate.mjs';
+import { tryAdmitWorkspaceActivityAsync } from '../../../../../shared/worktrees/activity-gate.mjs';
 import { worktreeError } from '../../../../../shared/worktrees/contract.mjs';
 import { workspaceSees } from '../../../../../shared/worktrees/workspace-visibility.mjs';
 
 const workspaceLeases = new Map();
 
+/**
+ * Calls both releases in order; settles once both did. Never goes unhandled
+ * (an asynchronous release rejects only when workspace admission stopped).
+ */
+export function bothReleased(first, second) {
+  const both = Promise.all([first(), second()]);
+  both.catch(() => {});
+  return both;
+}
+
+/**
+ * A workspace grant requested now, for a release handle needed before it is
+ * answered: the release, whenever called, follows the grant (and releases
+ * nothing if it was refused or failed).
+ */
+export function pendingWorkspaceAdmission(granting) {
+  granting.catch(() => {});
+  return () =>
+    granting.then(
+      (leave) => leave?.(),
+      () => {}
+    );
+}
+
 /** Transfer a foreground reader to a surviving-descendant task without a lease gap. */
 export function adoptShellWorkspaceAdmission(jobId, leave) {
   const prior = workspaceLeases.get(jobId);
-  workspaceLeases.set(
-    jobId,
-    prior
-      ? () => {
-          prior();
-          leave();
-        }
-      : leave
-  );
+  workspaceLeases.set(jobId, prior ? () => bothReleased(prior, leave) : leave);
 }
 
 // A record whose owner process is gone is garbage. Age alone never deletes a
@@ -88,8 +104,13 @@ function validJobId(jobId) {
 
 function terminalRecord(base, detail) {
   const finishedAt = detail?.finishedAt || new Date().toISOString();
+  // A completed record no longer claims an unconfirmed termination: it is
+  // written once the processes are confirmed gone, or explicitly released.
+  // A completed record no longer claims an unconfirmed termination: it is
+  // written once the processes are confirmed gone, or explicitly released.
+  const { terminationUnconfirmed: _held, ...open } = base || {};
   return {
-    ...(base || {}),
+    ...open,
     jobId: String(detail?.jobId || base?.jobId || ''),
     kind: 'bash',
     status: String(detail?.status || 'failed'),
@@ -172,7 +193,14 @@ async function sweepOrphanRecords(dir) {
   }
 }
 
-/** Publish the record for a job that has just started or been promoted. */
+/**
+ * Publish the record for a job that has just started or been promoted. Its
+ * workspace lease (under the job's pid) is requested at the call and adopted
+ * under the job id at once, so a later release of the job — or of a
+ * predecessor's lease — is ordered after it. Resolves once the lease is in
+ * both ledger copies; rejects (and writes no record) when it is refused or
+ * cannot be written. The returned promise never goes unhandled.
+ */
 export function publishShellJobRecord(
   task,
   {
@@ -184,16 +212,20 @@ export function publishShellJobRecord(
   } = {}
 ) {
   const jobId = String(task?.jobId || '').trim();
-  if (!jobId) return;
+  if (!jobId) return Promise.resolve();
+  let admitted = Promise.resolve();
   if (task?.cwd) {
-    const leave = tryAdmitWorkspaceActivity(ownerSessionId || jobId, task.cwd, {
+    const granting = tryAdmitWorkspaceActivityAsync(ownerSessionId || jobId, task.cwd, {
       pid: Number(task.pid) || process.pid,
       kind: 'command',
     });
-    if (!leave) throw worktreeError('WORKTREE_BUSY_JOBS', 'The command folder is being managed.');
+    admitted = granting.then((leave) => {
+      if (!leave) throw worktreeError('WORKTREE_BUSY_JOBS', 'The command folder is being managed.');
+    });
+    admitted.catch(() => {});
     // A descendant handoff can reuse the job id with a different live pid.
-    // Acquire its reader before releasing any predecessor's admission.
-    adoptShellWorkspaceAdmission(jobId, leave);
+    // Its reader is requested before any predecessor's admission is released.
+    adoptShellWorkspaceAdmission(jobId, pendingWorkspaceAdmission(granting));
   }
   const ownerPid = Number(clientHostPid ?? task?.clientHostPid) || process.pid;
   const dir = jobsDir();
@@ -202,6 +234,8 @@ export function publishShellJobRecord(
   paths.set(jobId, [jsonPath, ownerPath]);
   void enqueue(jobId, async () => {
     try {
+      // No record for a job whose workspace lease was not granted.
+      await admitted;
       await mkdir(dir, { recursive: true });
       if (!sweepStarted) {
         sweepStarted = true;
@@ -244,6 +278,7 @@ export function publishShellJobRecord(
       /* the record is presentation only; never fail a job for it */
     }
   });
+  return admitted;
 }
 
 /** Preserve a bounded terminal snapshot for manual recovery after restart. */
@@ -335,8 +370,9 @@ export function releaseShellJobWorkspace(jobId) {
   const key = String(jobId || '').trim();
   const leave = workspaceLeases.get(key);
   if (!leave) return;
-  leave();
+  const released = leave();
   if (workspaceLeases.get(key) === leave) workspaceLeases.delete(key);
+  return released;
 }
 
 /** Flag a still-open job record as "termination unconfirmed" for the readouts. */
@@ -390,8 +426,10 @@ export function completeShellJobRecord(jobId, detail) {
       // Callers complete a record only once its processes are confirmed gone
       // (or explicitly released): the workspace admission follows that, not
       // the record write, so a failed write cannot strand it with no handle.
-      leaveWorkspace?.();
+      const released = leaveWorkspace?.();
       if (workspaceLeases.get(key) === leaveWorkspace) workspaceLeases.delete(key);
+      // Fails only when workspace admission stopped (reported there), which keeps the folder held.
+      await Promise.resolve(released).catch(() => {});
     }
     await removePaths(ownerPaths);
     paths.set(key, [jsonPath, donePath]);
@@ -486,6 +524,6 @@ export function retireShellJobRecord(jobId) {
     records.delete(key);
     incarnations.delete(key);
     await removePaths(list);
-    leaveWorkspace?.();
+    await leaveWorkspace?.();
   });
 }

package/src/runtime/agent/orchestrator/tools/builtin/read-single-stream.mjs

@@ -53,7 +53,13 @@ export async function streamRangeResult(ctx, { source, fileHandle, prefixBuffer
       res.firstEmitted && res.lastEmitted ? [{ startLine: res.firstEmitted, endLine: res.lastEmitted }] : [];
     const snapshotMeta = { source, ranges, rangeHashes: _rangeHashesFromRenderedReadText(res.text, ranges) };
     if (!res.readSnapshotStat) return res.text;
-    return await commitStreamResult({ ...ctx, st: res.readSnapshotStat }, res.text, snapshotMeta, res.prefixHash, helpers);
+    return await commitStreamResult(
+      { ...ctx, st: res.readSnapshotStat },
+      res.text,
+      snapshotMeta,
+      res.prefixHash,
+      helpers
+    );
   } catch (err) {
     return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
   }

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

@@ -137,9 +137,12 @@ async function readRangeFromHandle(fh, fullPath, offset, limit, stHint, hooks) {
   }
   if (!stop) lines.finishTail();
   let readSnapshotStat = null;
-  if (!(await publishReadRangeIndex(rangeIndex, fh, null, checkDeadline, (version) => {
-    readSnapshotStat = version;
-  }))) checkDeadline();
+  if (
+    !(await publishReadRangeIndex(rangeIndex, fh, null, checkDeadline, (version) => {
+      readSnapshotStat = version;
+    }))
+  )
+    checkDeadline();
 
   ioTraceDone('read_range_stream', traceStart, {
     pathHash: hashText(fullPath).slice(0, 12),

package/src/runtime/agent/orchestrator/tools/builtin/read-tool/batch-dispatch.mjs

@@ -41,7 +41,7 @@ async function estimateTaskBytes(entry, workDir) {
   const st = await stat(resolvePath(workDir || '.', String(entry?.path || ''))).catch(() => null);
   if (!st?.isFile()) return Infinity;
   const lines = Math.max(1, st.size / AVG_LINE_BYTES);
-  let need = st.size + st.size / MIN_LINE_BYTES * LINE_PREFIX_BYTES;
+  let need = st.size + (st.size / MIN_LINE_BYTES) * LINE_PREFIX_BYTES;
   // A coalesced entry reads its whole union window, not only its own slot.
   const limit = Number(readEntryCoalescedDiskWindow(entry)?.limit ?? entry?.limit);
   if (Number.isFinite(limit) && limit > 0) need *= Math.min(1, limit / lines);

package/src/runtime/agent/orchestrator/tools/builtin/read-tool/batch-publication.mjs

@@ -85,10 +85,14 @@ export async function runBatchReadSnapshotPublication(executeChildBuiltinTool, h
       // A numbered row may end halfway through its content at the byte cap.
       // Only this slot's producer can certify complete lines; another read of
       // the same path must not authorize hashing this slot's partial text.
-      return mergeReadRanges(ranges.flatMap((range) => (observation?.ranges ?? []).map((complete) => ({
-        startLine: Math.max(range.startLine, complete.startLine),
-        endLine: Math.min(range.endLine, complete.endLine),
-      }))));
+      return mergeReadRanges(
+        ranges.flatMap((range) =>
+          (observation?.ranges ?? []).map((complete) => ({
+            startLine: Math.max(range.startLine, complete.startLine),
+            endLine: Math.min(range.endLine, complete.endLine),
+          }))
+        )
+      );
     },
     _recordReadSnapshot: (fullPath, _st, scope, meta) => {
       corrections.set(fullPath, { scope: scope ?? null, meta });
@@ -104,22 +108,29 @@ export async function runBatchReadSnapshotPublication(executeChildBuiltinTool, h
     }
     for (const [fullPath, correction] of corrections) {
       const delivered = tasks.filter((task) => task.fullPath === fullPath && hasRenderedLines(task.body));
-      const observations = delivered.map((task) => task.records.findLast(
-        (record) => record.fullPath === fullPath && record.scope === correction.scope
-      ));
+      const observations = delivered.map((task) =>
+        task.records.findLast((record) => record.fullPath === fullPath && record.scope === correction.scope)
+      );
       // Never combine different versions or bless stale/missing observations.
       // The eventual recorder rechecks the retained lease after all awaits.
-      if (observations.length && observations.every((record) =>
-        record?.isCurrent() && sameFileVersion(record.identity, observations[0].identity)
-      )) {
+      if (
+        observations.length &&
+        observations.every(
+          (record) => record?.isCurrent() && sameFileVersion(record.identity, observations[0].identity)
+        )
+      ) {
         observations[0].publish(correction.meta);
       }
     }
     // Rich media/binary results have no line slices. Preserve their original
     // evidence, still under the producer's lease rather than the batch's.
     for (const task of tasks) {
-      if (hasRenderedLines(task.body) || task.body?.isError === true ||
-          (typeof task.body === 'string' && helpers.classifyResultKind(task.body) === 'error')) continue;
+      if (
+        hasRenderedLines(task.body) ||
+        task.body?.isError === true ||
+        (typeof task.body === 'string' && helpers.classifyResultKind(task.body) === 'error')
+      )
+        continue;
       for (const record of task.records) {
         if (!corrections.has(record.fullPath)) record.publish();
       }

package/src/runtime/agent/orchestrator/tools/builtin/read-tool/batch-snapshot.mjs

@@ -69,7 +69,12 @@ async function rawRangeHashes(fullPath, mergedRanges, { _hashText }) {
 
 export async function recordSlicedBatchSnapshots(orderedResults, workDir, readStateScope, helpers) {
   const { _mergeReadRanges, _recordReadSnapshot } = helpers;
-  const { exactRangesByPath, rangeHashesByPath } = deliveredRangesByPath(orderedResults, workDir, readStateScope, helpers);
+  const { exactRangesByPath, rangeHashesByPath } = deliveredRangesByPath(
+    orderedResults,
+    workDir,
+    readStateScope,
+    helpers
+  );
   for (const [fullPath, ranges] of exactRangesByPath) {
     const mergedRanges = _mergeReadRanges(ranges);
     let rangeHashes = rangeHashesByPath.get(fullPath) || [];

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

@@ -112,14 +112,7 @@ export async function executeReadTool(args, ...rest) {
   return `${out}\n[skipped ${skipped.length} more file(s) over the per-call limit: ${skipped.join(', ')} — read them in another call]`;
 }
 
-async function executeReadToolBody(
-  args,
-  workDir,
-  readStateScope,
-  executeChildBuiltinTool,
-  options = {},
-  helpers = {}
-) {
+async function executeReadToolBody(args, workDir, readStateScope, executeChildBuiltinTool, options = {}, helpers = {}) {
   const { normalizeInputPath, normaliseReadLineWindowArgs } = helpers;
   applyFilePathAlias(args);
   args.path = coerceReadFamilyPathArg(args.path);