mixdog 1.1.2 → 1.2.1

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

@@ -0,0 +1,137 @@
+/**
+ * Keep coalesced child observations private until the caller's exact windows
+ * have been restored. A fresh child may outlive the batch's original cache
+ * generation; retain that child's lease, never renew the whole batch.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { canPublishReadCache, runReadCachePublication } from '../cache-layers.mjs';
+import { fileVersion, sameFileVersion } from '../file-version.mjs';
+import { mergeReadRanges } from '../read-ranges.mjs';
+
+// Streamed reads have numbered rows but no total-line footer. Prefer the
+// rows themselves so smart-elided gaps never become delivered evidence.
+export function renderedBatchReadRanges(body) {
+  if (typeof body !== 'string') return [];
+  const rows = [...body.matchAll(/^(\d+)[\t│→]/gm)]
+    .map((match) => Number(match[1]))
+    .filter((line) => Number.isSafeInteger(line) && line > 0)
+    .map((line) => ({ startLine: line, endLine: line }));
+  if (rows.length) return mergeReadRanges(rows);
+  const footer = /\[lines\s+(\d+)-(\d+)\s+of\s+\d+/.exec(body);
+  return footer ? mergeReadRanges([{ startLine: Number(footer[1]), endLine: Number(footer[2]) }]) : [];
+}
+
+function hasRenderedLines(body) {
+  return renderedBatchReadRanges(body).length > 0;
+}
+
+export async function runBatchReadSnapshotPublication(executeChildBuiltinTool, helpers, run) {
+  const tasks = [];
+  const records = [];
+  const corrections = new Map();
+  let closed = false;
+
+  function capture(task, fullPath, st, scope, meta) {
+    if (closed) return;
+    const identity = fileVersion(st);
+    const record = {
+      fullPath,
+      scope: scope ?? null,
+      identity,
+      ranges: mergeReadRanges(meta?.ranges),
+      isCurrent: () => false,
+      publish: () => {},
+      release: () => {},
+      done: Promise.resolve(),
+    };
+    task.records.push(record);
+    records.push(record);
+    // Acquiring a new lease must not rehabilitate an already stale producer.
+    if (!identity || !canPublishReadCache(fullPath)) return;
+    const decision = Promise.withResolvers();
+    record.publish = (replacement = meta) => decision.resolve(replacement);
+    record.release = () => decision.resolve(null);
+    record.done = runReadCachePublication(fullPath, async () => {
+      record.isCurrent = AsyncLocalStorage.bind(() => canPublishReadCache(fullPath));
+      const selected = await decision.promise;
+      if (selected) helpers._recordReadSnapshot(fullPath, identity, scope, selected);
+    });
+  }
+
+  const executeChild = async (name, args, workDir, options = {}) => {
+    if (name !== 'read' || (args.mode && args.mode !== 'full')) {
+      return executeChildBuiltinTool(name, args, workDir, options);
+    }
+    const task = {
+      entry: args,
+      fullPath: helpers.resolveAgainstCwd(args.path, workDir),
+      records: [],
+      body: null,
+    };
+    tasks.push(task);
+    task.body = await executeChildBuiltinTool(name, args, workDir, {
+      ...options,
+      _readSnapshotRecorder: (...snapshot) => capture(task, ...snapshot),
+    });
+    return task.body;
+  };
+  const snapshotHelpers = {
+    ...helpers,
+    _filterReadSnapshotRanges: (entry, fullPath, scope, ranges) => {
+      const task = tasks.find((task) => task.entry === entry);
+      const observation = task?.records.findLast(
+        (record) => record.fullPath === fullPath && record.scope === (scope ?? null)
+      );
+      // 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),
+      }))));
+    },
+    _recordReadSnapshot: (fullPath, _st, scope, meta) => {
+      corrections.set(fullPath, { scope: scope ?? null, meta });
+    },
+  };
+
+  try {
+    const result = await run(executeChild, snapshotHelpers);
+    // reject_partial refuses the entire payload: staged bodies were not
+    // delivered, so none of their snapshots may become session evidence.
+    if (result?.isError === true || (typeof result === 'string' && helpers.classifyResultKind(result) === 'error')) {
+      return result;
+    }
+    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
+      ));
+      // 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)
+      )) {
+        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;
+      for (const record of task.records) {
+        if (!corrections.has(record.fullPath)) record.publish();
+      }
+    }
+    for (const record of records) record.release();
+    await Promise.all(records.map((record) => record.done));
+    return result;
+  } finally {
+    // Promise.all in the dispatcher may reject while other children remain
+    // active. Late captures then become no-ops and cannot leak a held lease.
+    closed = true;
+    for (const record of records) record.release();
+    await Promise.allSettled(records.map((record) => record.done));
+  }
+}

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

@@ -6,6 +6,7 @@
  */
 import { readFile } from 'node:fs/promises';
 import { rangeTextOf } from '../snapshot-helpers.mjs';
+import { renderedBatchReadRanges } from './batch-publication.mjs';
 
 // Coalesced batch reads fetch the union window from disk; every caller slot
 // must be sliced back to its original request window (_orig*), not the
@@ -32,22 +33,22 @@ export function restoreCallerSlots(results, origEntries, entryMap, options, { sl
 function deliveredRangesByPath(
   orderedResults,
   workDir,
-  { classifyResultKind, resolveAgainstCwd, _rangeHashesFromRenderedReadText }
+  readStateScope,
+  { classifyResultKind, resolveAgainstCwd, _rangeHashesFromRenderedReadText, _filterReadSnapshotRanges }
 ) {
   const exactRangesByPath = new Map();
   const rangeHashesByPath = new Map();
   for (const r of orderedResults) {
     if (r?.mode !== 'full' || classifyResultKind(String(r.body || '')) === 'error') continue;
-    const m = String(r.body || '').match(/\[lines\s+(\d+)-(\d+)\s+of\s+(\d+)/);
-    if (!m) continue;
-    const startLine = Number(m[1]);
-    const endLine = Number(m[2]);
-    if (!Number.isFinite(startLine) || !Number.isFinite(endLine)) continue;
     const fullPath = resolveAgainstCwd(r.path, workDir);
+    const renderedRanges = renderedBatchReadRanges(r.body);
+    const ranges = _filterReadSnapshotRanges
+      ? _filterReadSnapshotRanges(r.readEntry, fullPath, readStateScope, renderedRanges)
+      : renderedRanges;
+    if (ranges.length === 0) continue;
     if (!exactRangesByPath.has(fullPath)) exactRangesByPath.set(fullPath, []);
-    const range = { startLine, endLine };
-    exactRangesByPath.get(fullPath).push(range);
-    const renderedHashes = _rangeHashesFromRenderedReadText(r.body, [range]);
+    exactRangesByPath.get(fullPath).push(...ranges);
+    const renderedHashes = _rangeHashesFromRenderedReadText(r.body, ranges);
     if (renderedHashes.length > 0) {
       if (!rangeHashesByPath.has(fullPath)) rangeHashesByPath.set(fullPath, []);
       rangeHashesByPath.get(fullPath).push(...renderedHashes);
@@ -68,7 +69,7 @@ async function rawRangeHashes(fullPath, mergedRanges, { _hashText }) {
 
 export async function recordSlicedBatchSnapshots(orderedResults, workDir, readStateScope, helpers) {
   const { _mergeReadRanges, _recordReadSnapshot } = helpers;
-  const { exactRangesByPath, rangeHashesByPath } = deliveredRangesByPath(orderedResults, workDir, 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

@@ -18,6 +18,8 @@ import { normalizeObjectBatchArgs, batchEntriesFromArgs, primaryReadIndexes } fr
 import { dispatchBatchReads } from './read-tool/batch-dispatch.mjs';
 import { restoreCallerSlots, recordSlicedBatchSnapshots } from './read-tool/batch-snapshot.mjs';
 import { renderBatchResults } from './read-tool/batch-render.mjs';
+import { runBatchReadSnapshotPublication } from './read-tool/batch-publication.mjs';
+import { runReadCachePublication } from './cache-layers.mjs';
 
 function hasLineCoordinate(path) {
   return typeof path === 'string' && /(?:#L\d+|:\d+(?:-\d+)?(?::|$))/i.test(path);
@@ -54,17 +56,25 @@ async function executeBatchRead(args, workDir, readStateScope, executeChildBuilt
   const origEntries = Array.isArray(args._readsOrigEntries) ? args._readsOrigEntries : null;
   const entryMap = Array.isArray(args._readsEntryToDeduped) ? args._readsEntryToDeduped : null;
   const readIndexFor = primaryReadIndexes(entries, overrides, (p) => helpers.resolveAgainstCwd(p, workDir));
-  const results = await dispatchBatchReads({
-    entries,
-    readIndexFor,
-    workDir,
-    options,
-    helpers,
-    executeChildBuiltinTool,
-  });
-  const orderedResults = origEntries ? restoreCallerSlots(results, origEntries, entryMap, options, helpers) : results;
-  if (origEntries) await recordSlicedBatchSnapshots(orderedResults, workDir, readStateScope, helpers);
-  return renderBatchResults(orderedResults, args, helpers);
+  const run = async (executeChild = executeChildBuiltinTool, snapshotHelpers = helpers) => {
+    const results = await dispatchBatchReads({
+      entries,
+      readIndexFor,
+      workDir,
+      options,
+      helpers,
+      executeChildBuiltinTool: executeChild,
+    });
+    const orderedResults = origEntries ? restoreCallerSlots(results, origEntries, entryMap, options, helpers) : results;
+    if (origEntries) await recordSlicedBatchSnapshots(orderedResults, workDir, readStateScope, snapshotHelpers);
+    return renderBatchResults(orderedResults, args, helpers);
+  };
+  if (!origEntries) return run();
+  // Keep the original batch lease for glance/media paths outside the scalar
+  // pipeline. Sliced evidence uses the producing child's retained lease, so
+  // a hash rejection never requires renewing this potentially stale parent.
+  const paths = entries.filter((entry) => entry?.path).map((entry) => helpers.resolveAgainstCwd(entry.path, workDir));
+  return runReadCachePublication(paths, () => runBatchReadSnapshotPublication(executeChildBuiltinTool, helpers, run));
 }
 
 // Glance modes served by their own child tool: the tool name and the args it

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

@@ -102,7 +102,7 @@ function findRepositoryRoot(startDirectory, { maxDepth = 64 } = {}) {
     const marker = pathJoin(current, '.git');
     try {
       const stats = statSync(marker);
-      return { root: current, gitDirectory: stats.isDirectory() ? marker : null };
+      return { root: current, gitDirectory: stats.isDirectory() ? marker : _linkedGitDirectory(marker, current) };
     } catch {}
     const parent = pathDirname(current);
     if (parent === current) break;
@@ -111,6 +111,17 @@ function findRepositoryRoot(startDirectory, { maxDepth = 64 } = {}) {
   return null;
 }
 
+// A linked worktree's `.git` file names its own git directory (`gitdir: …`),
+// which holds that worktree's HEAD.
+function _linkedGitDirectory(markerFile, root) {
+  try {
+    const target = /^gitdir:\s*(.+)$/m.exec(readFileSync(markerFile, 'utf8'))?.[1]?.trim();
+    return target ? pathResolveAbsolute(root, target) : null;
+  } catch {
+    return null;
+  }
+}
+
 function _headBranch(gitDirectory) {
   if (!gitDirectory) return null;
   try {

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

@@ -254,8 +254,8 @@ function absolutePaths(lines, rgCwd) {
   return lines.map((line) => (isAbsolute(line) ? line : resolveAgainstCwd(line, rgCwd)));
 }
 
-function missingGlobRoot(scan, root, rgCwd, err) {
-  const hint = buildNotFoundHint(scan.workDir, rgCwd, 'Search', err?.code);
+async function missingGlobRoot(scan, root, rgCwd, err) {
+  const hint = await buildNotFoundHint(scan.workDir, rgCwd, 'Search', err?.code);
   return {
     error: `path does not exist: ${normalizeOutputPath(rgCwd)} (${err?.code || 'ENOENT'})${finalizeReadFamilyEnoentTail(hint, root, err?.code)}`,
     paths: [],
@@ -422,14 +422,14 @@ function globMoreSuffix({ rgWindowIncomplete, remaining, totalBeforeOffset, next
   return '';
 }
 
-function globEmptyDiagnostic(scan, { totalBeforeOffset }) {
+async function globEmptyDiagnostic(scan, { totalBeforeOffset }) {
   const { patterns, basePath, baseEntries, workDir, statCache, offset } = scan;
   const patternStr = patterns.length === 1 ? JSON.stringify(patterns[0]) : JSON.stringify(patterns);
   const baseLabel = normalizeOutputPath(basePath);
   if (totalBeforeOffset > 0 && offset >= totalBeforeOffset) {
     return `(no entries after offset=${offset}; total=${totalBeforeOffset}) pattern=${patternStr} path=${baseLabel}`;
   }
-  const diagnostic = basePathDiagnostic(
+  const diagnostic = await basePathDiagnostic(
     baseEntries.map((e) => e.root),
     workDir,
     statCache
@@ -473,7 +473,7 @@ async function scanGlobGroups(scan) {
     const shown = await directAbsoluteMatches({ patterns, headLimit, offset });
     if (shown.length > 0) return patternCapNote + shown.join('\n');
   }
-  const out = patternCapNote + renderGlobPage(scan, merged, { capped, remaining, totalBeforeOffset, miss });
+  const out = patternCapNote + (await renderGlobPage(scan, merged, { capped, remaining, totalBeforeOffset, miss }));
   settleGlobScanCache(scan, merged, out, remaining);
   reportToolProgress(options, `found ${totalBeforeOffset} files`);
   return out;
@@ -482,7 +482,7 @@ async function scanGlobGroups(scan) {
 // The page body with its more/integrity suffixes. Empty partials are not
 // proof of absence: diagnostics are preserved even when there is no path
 // body, rather than silently dropping the integrity suffix.
-function renderGlobPage(scan, merged, { capped, remaining, totalBeforeOffset, miss }) {
+async function renderGlobPage(scan, merged, { capped, remaining, totalBeforeOffset, miss }) {
   const { offset } = scan;
   const errSuffix = globIntegritySuffix(merged);
   const moreSuffix = globMoreSuffix({
@@ -492,7 +492,7 @@ function renderGlobPage(scan, merged, { capped, remaining, totalBeforeOffset, mi
     nextOffset: offset + capped.length,
   });
   if (capped.length > 0) return `${capped.join('\n')}${moreSuffix}${errSuffix}`;
-  const emptyDiag = miss ? globEmptyDiagnostic(scan, { totalBeforeOffset }) : '';
+  const emptyDiag = miss ? await globEmptyDiagnostic(scan, { totalBeforeOffset }) : '';
   const emptyBody = (emptyDiag || '(no files found)').replace(
     '(no files found)',
     merged.rgStdoutPartial || merged.rgWindowIncomplete ? '(no files found yet)' : '(no files found)'
@@ -608,9 +608,12 @@ export async function executeGlobTool(args, workDir, options = {}) {
   };
   return await runScopedSearchInFlight(
     cacheKey,
-    ({ signal: sharedSignal, scopedCacheOutcome }) => scanGlobGroups({
-      ...scan, sharedSignal, options: { ...options, scopedCacheOutcome },
-    }),
+    ({ signal: sharedSignal, scopedCacheOutcome }) =>
+      scanGlobGroups({
+        ...scan,
+        sharedSignal,
+        options: { ...options, scopedCacheOutcome },
+      }),
     { signal: options?.signal || options?.abortSignal || null, scopes },
     options?.scopedCacheOutcome
   );

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

@@ -211,7 +211,7 @@ async function runGrepSearch(request, sharedSignal) {
 
 async function grepMissingPathResult({ workDir, grepResolvedPath, searchPath, executeChildBuiltinTool }, err) {
   const msg = `Error: path does not exist: ${normalizeOutputPath(grepResolvedPath)} (${err?.code || 'ENOENT'})`;
-  let hint = buildNotFoundHintBody(workDir, grepResolvedPath, 'Search', err?.code, {});
+  let hint = await buildNotFoundHintBody(workDir, grepResolvedPath, 'Search', err?.code, {});
   if (!hint) hint = await _suggestIndexedPaths(grepResolvedPath, executeChildBuiltinTool, workDir);
   return msg + finalizeReadFamilyEnoentTail(appendNotFoundCwdNote(hint, workDir, err?.code), searchPath, err?.code);
 }

package/src/runtime/agent/orchestrator/tools/builtin/search-path-diagnostics.mjs

@@ -65,10 +65,10 @@ const ENOENT_ABSENT =
 
 // Share diagnostic lookup results within one invocation without changing
 // the requested operand or executing a replacement operation.
-function cachedFileByBasename(workDir, missingPath, cache) {
+async function cachedFileByBasename(workDir, missingPath, cache) {
   if (!cache) return findFileByBasename(workDir, missingPath);
   if (!('fileHits' in cache)) cache.fileHits = findFileByBasename(workDir, missingPath);
-  return cache.fileHits;
+  return await cache.fileHits;
 }
 
 // A missing ABSOLUTE path that resolves outside the project cannot be
@@ -180,15 +180,15 @@ export function appendNotFoundCwdNote(hint, workDir, errCode = 'ENOENT') {
   return `${hint} (relative paths resolve from ${normalizeOutputPath(workDir)})`;
 }
 
-export function buildNotFoundHint(workDir, missingPath, actionVerb, errCode = 'ENOENT', cache = null) {
+export async function buildNotFoundHint(workDir, missingPath, actionVerb, errCode = 'ENOENT', cache = null) {
   return appendNotFoundCwdNote(
-    buildNotFoundHintBody(workDir, missingPath, actionVerb, errCode, cache),
+    await buildNotFoundHintBody(workDir, missingPath, actionVerb, errCode, cache),
     workDir,
     errCode
   );
 }
 
-export function buildNotFoundHintBody(workDir, missingPath, actionVerb, errCode = 'ENOENT', cache = null) {
+export async function buildNotFoundHintBody(workDir, missingPath, actionVerb, errCode = 'ENOENT', cache = null) {
   if (!NOT_FOUND_CODES.has(String(errCode || 'ENOENT'))) return '';
   // `C:tmpsmp` shape: a Windows path whose separators were eaten by JSON
   // escaping (`"C:\\tmp\\smp"` written as `"C:\tmp\smp"`). Name the cause —
@@ -200,12 +200,12 @@ export function buildNotFoundHintBody(workDir, missingPath, actionVerb, errCode
   if (missingPathIsOutsideProject(workDir, missingPath)) {
     return outsideProjectNotFoundHint(missingPath, actionVerb);
   }
-  const elsewhere = cachedFileByBasename(workDir, missingPath, cache);
+  const elsewhere = await cachedFileByBasename(workDir, missingPath, cache);
   if (elsewhere.length) {
     return ` Not found at this path; the same filename exists at: ${elsewhere.map((p) => `"${normalizeOutputPath(p)}"`).join(', ')}. ${actionVerb} that path directly.`;
   }
   if (isDirectoryPathGuess(missingPath)) {
-    const dirHits = findDirectoryByBasename(workDir, missingPath, { limit: 5 });
+    const dirHits = await findDirectoryByBasename(workDir, missingPath, { limit: 5 });
     if (dirHits.length > 1) {
       return ` Not found at this path; same-named directories exist at: ${dirHits
         .slice(0, 5)
@@ -268,9 +268,9 @@ export function uncRefusalMessage(toolName, original, resolved) {
   return `Error: ${toolName} refuses UNC/SMB path ${JSON.stringify(shown)}; remote share access is blocked to prevent NTLM credential leaks`;
 }
 
-export function basePathDiagnostic(basePaths, workDir, statCache = null) {
-  return basePaths
-    .map((basePath) => {
+export async function basePathDiagnostic(basePaths, workDir, statCache = null) {
+  const parts = await Promise.all(
+    basePaths.map(async (basePath) => {
       const resolved = resolveSearchScope(basePath, workDir);
       // Reuse the caller's call-scoped stat cache (glob preflight + per-group
       // rg runs already stat'd this same resolved root) instead of re-stating.
@@ -291,8 +291,13 @@ export function basePathDiagnostic(basePaths, workDir, statCache = null) {
       }
       return (
         `${normalizeOutputPath(basePath)}: path does not exist (${err?.code || 'ENOENT'})` +
-        finalizeReadFamilyEnoentTail(buildNotFoundHint(workDir, resolved, 'Search', err?.code), basePath, err?.code)
+        finalizeReadFamilyEnoentTail(
+          await buildNotFoundHint(workDir, resolved, 'Search', err?.code),
+          basePath,
+          err?.code
+        )
       );
     })
-    .join('; ');
+  );
+  return parts.join('; ');
 }

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

@@ -180,7 +180,10 @@ async function waitForShellTask(task, taskId, args, options) {
   return interruptedByUser;
 }
 
-async function cancelShellTask(task, taskId, options) {
+// Outcome of a shell cancel: `outcome` is 'cancelled' only when the process is
+// confirmed gone (or never had one), 'unconfirmed' when the kill was delivered
+// but the exit could not be confirmed, 'not-found' for an unknown task.
+async function cancelShellTaskOutcome(task, taskId, options) {
   // A tracked task with no native job is still cancellable: the
   // registry's own cancel hook owns it (descendants that outlived
   // their shell). Remember that it WAS live so the outcome is
@@ -196,11 +199,14 @@ async function cancelShellTask(task, taskId, options) {
     if (confirmed && confirmed.status === 'running') {
       // Watcher and notify context stay armed: the eventual exit
       // must still reach the owner.
-      return [
-        'status: cancel-unconfirmed',
-        `task_id: ${taskId}`,
-        'the cancellation was delivered but the process has not exited yet. It stays tracked and its completion is still delivered; re-run task cancel or task read to check again.',
-      ].join('\n');
+      return {
+        outcome: 'unconfirmed',
+        text: [
+          'status: cancel-unconfirmed',
+          `task_id: ${taskId}`,
+          'the cancellation was delivered but the process has not exited yet. It stays tracked and its completion is still delivered; re-run task cancel or task read to check again.',
+        ].join('\n'),
+      };
     }
     if (!confirmed) {
       // No terminal event and no observable task: absence of
@@ -209,19 +215,56 @@ async function cancelShellTask(task, taskId, options) {
       cancelBackgroundShellJobWatch(taskId);
       clearShellJobNotifyCtx(taskId);
       cancelBackgroundTask(taskId, 'cancelled by task control; termination unconfirmed');
-      return [
-        'status: cancel-unconfirmed',
-        `task_id: ${taskId}`,
-        'the cancellation was delivered but this task is no longer observable, so its termination could not be confirmed. Verify the process directly if it must be gone.',
-      ].join('\n');
+      return {
+        outcome: 'unconfirmed',
+        text: [
+          'status: cancel-unconfirmed',
+          `task_id: ${taskId}`,
+          'the cancellation was delivered but this task is no longer observable, so its termination could not be confirmed. Verify the process directly if it must be gone.',
+        ].join('\n'),
+      };
     }
   }
   cancelBackgroundShellJobWatch(taskId);
   clearShellJobNotifyCtx(taskId);
   cancelBackgroundTask(taskId, 'cancelled by task control');
   return job || wasRunning
-    ? renderTaskCancelSuccess(taskId, getBackgroundTask(taskId, { context: options }) || task)
-    : buildJobNotFoundMessage(taskId);
+    ? {
+        outcome: 'cancelled',
+        text: renderTaskCancelSuccess(taskId, getBackgroundTask(taskId, { context: options }) || task),
+      }
+    : { outcome: 'not-found', text: buildJobNotFoundMessage(taskId) };
+}
+
+async function cancelShellTask(task, taskId, options) {
+  return (await cancelShellTaskOutcome(task, taskId, options)).text;
+}
+
+/**
+ * Stop one BACKGROUND shell job of the caller's session (desktop stop button).
+ * The same cancel the `task` tool runs, with a structured answer: `stopped` is
+ * true only when the job was actually cancelled. Only promoted/async jobs hold
+ * a background task, so a foreground command can never match; the session
+ * scope is the caller's, so another session's job reads as unknown.
+ */
+export async function stopBackgroundShellJob(taskId, options = {}) {
+  const id = typeof taskId === 'string' ? taskId.trim() : '';
+  if (!id) return { stopped: false, error: 'task_id is required' };
+  const task = getBackgroundTask(id, { context: options });
+  if (!task || task.surface !== 'shell') return { stopped: false, error: `task not found: ${id}` };
+  const job = peekShellJob(id);
+  const status = job ? job.status : task.status;
+  if (status !== 'running') return { stopped: false, error: `task already ${status}: ${id}` };
+  try {
+    const { outcome, text } = await cancelShellTaskOutcome(task, id, options);
+    if (outcome === 'cancelled') return { stopped: true };
+    return {
+      stopped: false,
+      error: outcome === 'unconfirmed' ? `cancellation not confirmed: ${id}` : text.replace(/^Error:\s*/, ''),
+    };
+  } catch (error) {
+    return { stopped: false, error: error instanceof Error ? error.message : String(error) };
+  }
 }
 
 export async function executeTaskTool(args, options = {}) {

package/src/runtime/agent/orchestrator/tools/code-graph/disk-cache.mjs

@@ -573,6 +573,64 @@ export function listCachedCodeGraphRoots() {
   }
 }
 
+// Remove one root (exact canonical match) from the disk cache: its resident
+// entry, its staged call-site sidecar, its manifest row and its <hash>.json /
+// <hash>.calls.json files. The resident drop is synchronous and happens first,
+// so a flush already scheduled for other roots can no longer write this one
+// back; the manifest is edited under the same cross-process lock the persist
+// path takes, so a concurrent writer merges the result instead of restoring
+// the row. Never creates the cache directory. Returns { removed, kept }; kept
+// are cache files that matched but could not be deleted.
+export function forgetDiskCodeGraphRoot(root) {
+  const key = _canonicalGraphCwd(root);
+  const removed = [];
+  const kept = [];
+  if (_diskCodeGraphCache.has(key)) removed.push(`resident:${key}`);
+  _dropDiskEntry(key);
+  if (_pendingCallsSidecars.delete(key)) removed.push(`pending-calls-sidecar:${key}`);
+  const dir = _codeGraphDiskDir();
+  if (!existsSync(dir)) return { removed, kept };
+  withFileLockSync(
+    join(dir, '.persist.lock'),
+    () => {
+      const manifest = _readPreservedManifest(dir);
+      const hashes = new Set([_hashCwd(key)]);
+      let changed = false;
+      for (const [cwd, meta] of Object.entries(manifest)) {
+        let same = false;
+        try {
+          same = _canonicalGraphCwd(cwd) === key;
+        } catch {
+          /* a malformed key is not this root */
+        }
+        if (!same) continue;
+        if (_isCodeGraphCacheHash(meta?.hash)) hashes.add(meta.hash);
+        delete manifest[cwd];
+        changed = true;
+        removed.push(`manifest:${cwd}`);
+      }
+      for (const hash of hashes) {
+        for (const file of [join(dir, `${hash}.json`), callsSidecarPath(dir, hash)]) {
+          if (!existsSync(file)) continue;
+          try {
+            unlinkSync(file);
+            removed.push(file);
+          } catch {
+            kept.push(file);
+          }
+        }
+      }
+      if (changed) writeJsonAtomicSync(join(dir, 'manifest.json'), manifest, { compact: true, lock: false });
+      if (_diskManifest) {
+        delete _diskManifest[key];
+        if (changed) _diskManifest = manifest;
+      }
+    },
+    { timeoutMs: 10_000 }
+  );
+  return { removed, kept };
+}
+
 // ── call-site sidecar ───────────────────────────────────────────────────────
 // Resolve the sidecar file of a canonical cwd. The manifest hash wins when the
 // entry is known (it is what the persist loop wrote); otherwise the hash is

package/src/runtime/agent/orchestrator/tools/code-graph/dispatch/root-resolution.mjs

@@ -79,10 +79,10 @@ export function resolveAggregateAnchorRoot(name, args, baseCwd, { explicitCwdArg
  * One `file` anchor: an error string when it does not exist, otherwise the
  * root it re-homes the call to (null keeps the current cwd).
  */
-export function resolveFileAnchorRoot(name, args, fileArg, baseCwd) {
+export async function resolveFileAnchorRoot(name, args, fileArg, baseCwd) {
   const abs = _absFrom(baseCwd, fileArg);
   if (!existsSync(abs)) {
-    const elsewhere = findFileByBasename(pathResolve(baseCwd), abs);
+    const elsewhere = await findFileByBasename(pathResolve(baseCwd), abs);
     const hint = elsewhere.length
       ? ` Same filename exists at: ${elsewhere.map((p) => `"${toDisplayPath(p, baseCwd).replace(/\\/g, '/')}"`).join(', ')}. Use that path.`
       : '';

package/src/runtime/agent/orchestrator/tools/code-graph/dispatch.mjs

@@ -345,7 +345,7 @@ async function executeCodeGraphToolRaw(name, rawArgs, cwd, signal = null, option
     args = resolved.args;
   }
   if (fileArg && !hasAggregateFileArgs) {
-    const anchor = resolveFileAnchorRoot(name, args, fileArg, baseCwd);
+    const anchor = await resolveFileAnchorRoot(name, args, fileArg, baseCwd);
     if (anchor.error) return anchor.error;
     if (anchor.root) effectiveCwd = anchor.root;
   }

package/src/runtime/agent/orchestrator/tools/code-graph/trusted-roots.mjs

@@ -1,6 +1,6 @@
 import { statSync } from 'node:fs';
 import { basename, dirname, isAbsolute, relative, resolve } from 'node:path';
-import { listProjects } from '../../../../shared/projects.mjs';
+import { listProjects, removeProject } from '../../../../shared/projects.mjs';
 import { explicitSessionCwd, readLastSessionCwd } from '../../../../shared/user-cwd.mjs';
 import { canonicalGraphPath } from '../code-graph-state.mjs';
 import { listCachedCodeGraphRoots } from './disk-cache.mjs';
@@ -85,6 +85,30 @@ export function collectTrustedCodeGraphRoots(
   return [...found.values()].sort((a, b) => a.localeCompare(b));
 }
 
+/**
+ * Stop trusting one root as a federation target. Trust is derived from the
+ * Project registry, the session's selected cwd and the cache manifest; the
+ * manifest row goes with forgetDiskCodeGraphRoot() and a selected cwd is
+ * dropped by the directory check once the folder is gone, so the registry is
+ * the only stored source left. Only the exact root is removed (nested Projects
+ * stay). Returns { removed, kept }; kept are registered paths that matched but
+ * could not be unregistered.
+ */
+export function forgetTrustedCodeGraphRoot(
+  root,
+  { registered = () => listProjects().map((entry) => entry.path), unregister = removeProject } = {}
+) {
+  const removed = [];
+  const kept = [];
+  const key = canonicalGraphPath(root);
+  for (const path of registered()) {
+    if (!path || canonicalGraphPath(path) !== key) continue;
+    if (unregister(path)) removed.push(path);
+    else kept.push(path);
+  }
+  return { removed, kept };
+}
+
 export function owningTrustedCodeGraphRoot(file, roots) {
   const matches = (roots || []).filter((root) => _pathIsWithin(root, file));
   matches.sort((a, b) => resolve(b).length - resolve(a).length);