mixdog 1.2.5 → 1.3.0

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

@@ -9,10 +9,13 @@ import {
   shellJobPublicTaskResult,
   shellJobTaskStatus,
   waitForShellJob,
+  waitShellJobTerminated,
 } from './shell-jobs.mjs';
+import { beginSessionTaskWait } from '../../session/manager/runtime-liveness.mjs';
 import { TASK_WAIT_TIMEOUT_DEFAULT_MS, TASK_WAIT_TIMEOUT_MAX_MS, TASK_WAIT_TIMEOUT_MIN_MS } from './builtin-tools.mjs';
+import { AGENT_TASK_WAIT_DEFAULT_MS } from './wait-budgets.mjs';
 import { getAbortSignalForSession } from '../../session/abort-lookup.mjs';
-import { beginInterruptibleTaskWait } from '../../session/task-wait-control.mjs';
+import { TASK_WAIT_WAKE_NOTIFICATION, beginInterruptibleTaskWait } from '../../session/task-wait-control.mjs';
 import {
   acknowledgeBackgroundTaskCompletion,
   cancelBackgroundTask,
@@ -31,6 +34,18 @@ import { readShellTaskOutput } from './lib/shell-task-output.mjs';
 // wait returns the moment the native task settles, so this only bounds a
 // process that ignores the kill.
 const TASK_CANCEL_CONFIRM_MS = 5_000;
+// Ceiling for confirming that every process the task started is gone once its
+// root exited: a sweep is a table read, the kill and a second read (each read
+// ~1-2 s on Windows).
+const TASK_CANCEL_TREE_CONFIRM_MS = 15_000;
+
+function cancelPendingText(taskId) {
+  return [
+    'status: cancel-pending',
+    `task_id: ${taskId}`,
+    'the kill was sent and the command itself exited, but processes it started are still alive. They keep being terminated and stay tracked (the folder stays held) until they are gone; re-run task cancel or task read to check again.',
+  ].join('\n');
+}
 
 function recoveredTaskMatches(record, options = {}) {
   const context =
@@ -84,12 +99,22 @@ function renderTaskCancelSuccess(taskId, task) {
 
 // Clamp lives next to the caller; the bounds themselves are published by the
 // tool schema, so an out-of-range request is corrected rather than rejected.
-function resolveTaskWaitTimeoutMs(value) {
+function resolveTaskWaitTimeoutMs(value, defaultMs = TASK_WAIT_TIMEOUT_DEFAULT_MS) {
   const raw = Number(value);
-  if (!Number.isFinite(raw) || raw <= 0) return TASK_WAIT_TIMEOUT_DEFAULT_MS;
+  if (!Number.isFinite(raw) || raw <= 0) return defaultMs;
   return Math.min(TASK_WAIT_TIMEOUT_MAX_MS, Math.max(TASK_WAIT_TIMEOUT_MIN_MS, Math.floor(raw)));
 }
 
+// Agents run on the 5 m prompt cache, so their default wakes before it lapses;
+// the Lead keeps the 1 h cache and the longer default.
+async function defaultTaskWaitMs(sessionId) {
+  if (!sessionId) return TASK_WAIT_TIMEOUT_DEFAULT_MS;
+  const { getSession } = await import('../../session/manager.mjs');
+  const session = getSession(String(sessionId));
+  const agentOwned = session?.owner === 'agent' || session?.visibility === 'agent-only';
+  return agentOwned ? AGENT_TASK_WAIT_DEFAULT_MS : TASK_WAIT_TIMEOUT_DEFAULT_MS;
+}
+
 // Read-only counts of this runtime's shell work owned by OTHER sessions.
 // Admission is runtime-wide while task list/cancel are session-scoped, so
 // without this those holders are invisible. Counts only: another session's
@@ -128,8 +153,15 @@ async function listTasks(options) {
   return sections.join('\n');
 }
 
-// Blocks until the shell task settles, the timeout elapses, or the turn/user
-// interrupts; returns whether new user input cut the wait short.
+// Ceiling hits per still-running task, so a wait that keeps timing out on the
+// same job can suggest a different move. Keyed by the task object, so the count
+// goes with the task however it settles or is removed.
+const waitCeilingHits = new WeakMap();
+
+// Blocks until the shell task settles, the timeout elapses, the turn is
+// cancelled, or anything deliverable is queued for this session (user input,
+// steering, or any task notification: an agent or another shell job
+// finishing). Returns what cut the wait short.
 async function waitForShellTask(task, taskId, args, options) {
   // The turn's abort signal must cut the wait short; a cancelled turn
   // cannot sit out the remaining ceiling.
@@ -140,9 +172,12 @@ async function waitForShellTask(task, taskId, args, options) {
     turnSignal = null;
   }
   const waitControl = beginInterruptibleTaskWait(options?.sessionId, turnSignal);
+  const releaseWaitState = beginSessionTaskWait(options?.sessionId);
   const waitSignal = waitControl.signal;
-  const waitTimeoutMs = resolveTaskWaitTimeoutMs(args.timeout_ms);
+  const waitTimeoutMs = resolveTaskWaitTimeoutMs(args.timeout_ms, await defaultTaskWaitMs(options?.sessionId));
   let interruptedByUser = false;
+  let notified = false;
+  let notifiedTaskId = null;
   try {
     // A shell task whose descendants outlived the shell process has no
     // native job to subscribe to — the process it belonged to is gone.
@@ -175,9 +210,12 @@ async function waitForShellTask(task, taskId, args, options) {
     }
   } finally {
     interruptedByUser = waitControl.interruptedByUser;
+    notified = waitControl.wakeReason === TASK_WAIT_WAKE_NOTIFICATION;
+    notifiedTaskId = waitControl.wakeDetail;
     waitControl.dispose();
+    releaseWaitState();
   }
-  return interruptedByUser;
+  return { interruptedByUser, notified, notifiedTaskId };
 }
 
 // Outcome of a shell cancel: `outcome` is 'cancelled' only when the process is
@@ -208,6 +246,11 @@ async function cancelShellTaskOutcome(task, taskId, options) {
         ].join('\n'),
       };
     }
+    // The root exited; what it started outside its process group is swept
+    // by the job's termination watch. Cancelled means all of it is gone.
+    if (confirmed && !(await waitShellJobTerminated(taskId, TASK_CANCEL_TREE_CONFIRM_MS))) {
+      return { outcome: 'unconfirmed', text: cancelPendingText(taskId) };
+    }
     if (!confirmed) {
       // No terminal event and no observable task: absence of
       // state is not proof of termination. Stop tracking it so it
@@ -228,6 +271,10 @@ async function cancelShellTaskOutcome(task, taskId, options) {
   cancelBackgroundShellJobWatch(taskId);
   clearShellJobNotifyCtx(taskId);
   cancelBackgroundTask(taskId, 'cancelled by task control');
+  // A task whose own cancel hook kills (what a finished command left running)
+  // reports what that kill confirmed.
+  const hookKill = job ? null : await task.cancelOutcome;
+  if (hookKill && hookKill.terminated !== true) return { outcome: 'unconfirmed', text: cancelPendingText(taskId) };
   return job || wasRunning
     ? {
         outcome: 'cancelled',
@@ -323,27 +370,59 @@ export async function executeTaskTool(args, options = {}) {
 
   if (action === 'read' || action === 'wait') {
     let waitInterruptedByUser = false;
+    let waitNotified = false;
+    let notifiedTaskId = null;
     if (action === 'wait') {
       if (!isShellTask) return `Error: task wait is only available for shell tasks: ${taskId}`;
-      waitInterruptedByUser = await waitForShellTask(task, taskId, args, options);
+      ({
+        interruptedByUser: waitInterruptedByUser,
+        notified: waitNotified,
+        notifiedTaskId,
+      } = await waitForShellTask(task, taskId, args, options));
     }
     if (isShellTask) refreshShellTask(taskId, { includeRunning: true });
     const latest = getBackgroundTask(taskId, { context: options }) || task;
+    // A finished task whose completion notice is still unconsumed returns that
+    // notice's output (the unseen remainder) once; everything else reads the
+    // cursor. A wait that leaves the job running carries the progress digest.
+    const pendingCompletionOutput =
+      isShellTask &&
+      latest.status !== 'running' &&
+      latest.completionAcknowledged !== true &&
+      args.output !== 'tail' &&
+      typeof latest.completionOutput === 'string'
+        ? latest.completionOutput
+        : null;
     const visible =
       isShellTask && latest.result && typeof latest.result === 'object'
-        ? { ...latest, resultText: readShellTaskOutput(latest, latest.result, { output: args.output }) }
+        ? {
+            ...latest,
+            resultText:
+              pendingCompletionOutput ??
+              readShellTaskOutput(latest, latest.result, {
+                output: args.output,
+                digest: action === 'wait' && latest.status === 'running',
+              }),
+          }
         : latest;
     let rendered = renderBackgroundTask(visible, { includeResult: true });
     if (action === 'wait' && latest.status === 'running') {
       if (waitInterruptedByUser) {
         rendered +=
-          '\n\nWait interrupted by new user input; task still running. Handle the new message now and reply to it before waiting on this task again.';
+          '\n\nWait ended by new user input; task still running in the background. Handle the new message first.';
+      } else if (waitNotified) {
+        const from = notifiedTaskId && notifiedTaskId !== taskId ? ` (task_id: ${notifiedTaskId})` : '';
+        rendered += `\n\nWait ended because a notification arrived${from}; it is delivered to you now. This task (${taskId}) is still running in the background.`;
       } else {
+        const hits = (waitCeilingHits.get(latest) || 0) + 1;
+        waitCeilingHits.set(latest, hits);
         // In-band report cue: the static "periodic reports" rule does not
         // survive a long tool loop, so a ceiling-hit wait carries the
         // protocol reminder itself.
         rendered +=
-          '\n\nWait ceiling reached; task still running. If periodic reports were requested, write the user-facing report now, then call task wait for the next interval; otherwise continue independent work or end the turn.';
+          hits > 1
+            ? `\n\nWait ceiling reached again (${hits} times); task still running. Check whether it is progressing (task read output:tail, or the log file) and cancel it if it is stuck; otherwise continue other work — its result is delivered automatically.`
+            : '\n\nWait ceiling reached; task still running and its result is delivered automatically. If periodic reports were requested, write the user-facing report now; otherwise continue independent work or end the turn.';
       }
     }
     if (acknowledgeBackgroundTaskCompletion(taskId, { context: options })) {

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

@@ -0,0 +1,23 @@
+// The one place the shell hold and the task wait budgets are set. Every
+// schema, clamp, description and result text reads them from here.
+//
+// Shell hold: how long a foreground command may hold the tool call before it
+// moves to the background (it keeps running; completion is delivered
+// automatically). New user input ends the hold early. `wait_ms` picks a
+// different hold for one call, clamped to MIN..MAX.
+export const SHELL_HOLD_DEFAULT_MS = 60_000;
+export const SHELL_HOLD_MIN_MS = 1_000;
+export const SHELL_HOLD_MAX_MS = 600_000;
+
+// `task wait` ceiling. The wait returns the moment the task settles or new
+// user input arrives, so the ceiling only bounds a still-running task. The
+// floor stops a caller from turning wait into a busy poll. An agent's default
+// stays under the 5 m prompt-cache TTL with room for the turn's own generation
+// time, so a wait that runs to the ceiling wakes to a warm cache.
+export const TASK_WAIT_DEFAULT_MS = 300_000;
+export const AGENT_TASK_WAIT_DEFAULT_MS = 240_000;
+export const TASK_WAIT_MIN_MS = 10_000;
+export const TASK_WAIT_MAX_MS = 3_600_000;
+
+/** Whole seconds for descriptions and result text. */
+export const budgetSeconds = (ms) => Math.round(ms / 1000);

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

@@ -58,6 +58,7 @@ import {
   GREP_OUTPUT_MAX_BYTES,
   LOCATOR_OUTPUT_MAX_BYTES,
   capLineOrientedToolOutput,
+  capMarker,
 } from './builtin/tool-output-limit.mjs';
 import {
   isBlockedDevicePath,
@@ -340,6 +341,46 @@ function _locatorTargets(toolName, args) {
   return [toolName === 'find' ? '' : '.'];
 }
 
+const _GREP_MATCH_ROW_RE = /^(?:\d+|.+?:\d+):/;
+
+// Match rows the byte cap left visible, in the units grep's `offset` counts.
+function _grepShownEntries(keptLines, mode) {
+  // A context block counts only when its header and every source line survived.
+  let blocks = 0;
+  let sawHeader = false;
+  keptLines.forEach((line, index) => {
+    const header = /^# .+:\d+ \[lines (\d+)-(\d+)\]$/.exec(line);
+    if (!header) return;
+    sawHeader = true;
+    if (index + Number(header[2]) - Number(header[1]) + 1 < keptLines.length) blocks += 1;
+  });
+  if (sawHeader) return blocks;
+  const rows = keptLines.filter((line) => line && !/^(?:#|--$|\[|\.\.\.|…|\()/.test(line));
+  return mode === 'content' ? rows.filter((line) => _GREP_MATCH_ROW_RE.test(line)).length : rows.length;
+}
+
+// Byte-cap marker for grep: the continuation is the offset of the first match
+// row not shown. A pattern/path fan-out has per-target offsets, so it gets
+// narrowing advice instead of a misleading global offset.
+function _grepBudgetFooter(args, keptLines, capBytes) {
+  const fanout = keptLines.some((line) => line.startsWith('# grep '));
+  const baseOffset =
+    Number.isFinite(Number(args?.offset)) && Number(args.offset) > 0 ? Math.floor(Number(args.offset)) : 0;
+  const shown = _grepShownEntries(keptLines, args?.mode);
+  // Every mode orders the whole result set before `offset` slices it (files
+  // and count pages are sorted first, then cut), so the rows kept here are a
+  // prefix of the offset order and offset resumes right after them.
+  let narrow = '';
+  if (fanout) narrow = 'run one pattern/path per call, or add path/glob/type to cut the match set';
+  else if (shown === 0) narrow = 'one match row exceeds the cap; read that file window or use a tighter pattern';
+  return capMarker({
+    limit: capBytes,
+    shown: `${shown} match row(s) shown`,
+    nextOffset: fanout || shown === 0 ? null : baseOffset + shown,
+    narrow,
+  });
+}
+
 function _locatorBudgetFooter(toolName, args, keptLines, capBytes) {
   const targets = _locatorTargets(toolName, args);
   const header = new RegExp(`^# ${toolName} (.+)$`);
@@ -358,17 +399,24 @@ function _locatorBudgetFooter(toolName, args, keptLines, capBytes) {
   }
   const target = targets[targetIndex] || targets[0] || '';
   const remaining = targets.length - targetIndex - 1;
-  const capKb = Math.round((Number(capBytes) > 0 ? Number(capBytes) : LOCATOR_OUTPUT_MAX_BYTES) / 1024);
-  // Factual continuation only — no retry imperatives: the marker states
-  // what was cut, never instructs another call.
+  const limit = Number(capBytes) > 0 ? Number(capBytes) : LOCATOR_OUTPUT_MAX_BYTES;
   const nextTarget =
     remaining > 0 ? `; ${remaining} target(s) not shown, next=${JSON.stringify(targets[targetIndex + 1])}` : '';
   if (toolName === 'find') {
-    return `... [find output capped at ${capKb} KB; remaining matches for query=${JSON.stringify(target)} omitted${nextTarget}]`;
+    // find has no offset: the rest of the ranked matches needs a tighter query.
+    return capMarker({
+      limit,
+      shown: `matches for query=${JSON.stringify(target)} cut${nextTarget}`,
+      narrow: 'use a more specific query or add path',
+    });
   }
   const baseOffset =
     Number.isFinite(Number(args?.offset)) && Number(args.offset) > 0 ? Math.floor(Number(args.offset)) : 0;
-  return `... [${toolName} output capped at ${capKb} KB; rows above are complete; continue path=${JSON.stringify(target)} offset:${baseOffset + visibleEntries}${nextTarget}]`;
+  return capMarker({
+    limit,
+    shown: `${visibleEntries} complete row(s) shown for path=${JSON.stringify(target)}${nextTarget}`,
+    nextOffset: baseOffset + visibleEntries,
+  });
 }
 
 export async function executeBuiltinTool(name, args, cwd, options = {}) {
@@ -489,11 +537,7 @@ function _budgetBuiltinOutput(toolName, args, result, options) {
   const explicitCap = Number(options?.toolOutputMaxBytes) > 0 ? Math.trunc(Number(options.toolOutputMaxBytes)) : null;
   if (toolName === 'grep') {
     const grepCap = explicitCap ? Math.min(explicitCap, GREP_OUTPUT_MAX_BYTES) : GREP_OUTPUT_MAX_BYTES;
-    return capLineOrientedToolOutput(
-      result,
-      grepCap,
-      (kept) => `[grep output capped at ${grepCap} bytes; ${kept.length} line(s) shown, remainder omitted]`
-    );
+    return capLineOrientedToolOutput(result, grepCap, (kept) => _grepBudgetFooter(args, kept, grepCap));
   }
   if (_LOCATOR_BUDGET_TOOLS.has(toolName)) {
     const locatorCap = explicitCap ? Math.min(explicitCap, LOCATOR_OUTPUT_MAX_BYTES) : LOCATOR_OUTPUT_MAX_BYTES;

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

@@ -172,9 +172,10 @@ async function _validateDiskCodeGraphHit({
   return { graph, manifest, signature };
 }
 
-// Owns a pre-acquired slot until a validated miss hands it to spawnWorker.
-// Keeping this seam dependency-injectable makes slot/abort behavior testable
-// without spawning native processes or Worker threads.
+// Validates the disk graph under a read-only query slot; a miss releases it
+// and spawnWorker queues for a build slot, so queries never wait behind
+// builds. Keeping this seam dependency-injectable makes slot/abort behavior
+// testable without spawning native processes or Worker threads.
 export async function _runDiskCodeGraphFastPath({
   graphCwd,
   diskProbe,
@@ -182,36 +183,31 @@ export async function _runDiskCodeGraphFastPath({
   signal = null,
   loadDiskEntry,
   consumeDirty = () => {},
-  // Long-lived code-graph lane so a cold graph build never blocks short rg
-  // processes in the independent search lane.
-  acquireSlot = (signal) => acquireChildSpawnSlot(signal, 'code-graph'),
+  acquireSlot = (signal) => acquireChildSpawnSlot(signal, 'code-graph-query'),
   validateDiskHit = _validateDiskCodeGraphHit,
   spawnWorker,
   maxFiles = CODE_GRAPH_MAX_FILES,
 }) {
   if (!diskProbe?.isFastPathEligible || diskProbe.maxFiles !== maxFiles) {
-    return spawnWorker(null, null, null);
+    return spawnWorker(null, null);
   }
   const diskEntry = loadDiskEntry();
   if (!_isCompatibleDiskCodeGraphEntry(diskEntry, maxFiles)) {
-    return spawnWorker(null, null, null);
+    return spawnWorker(null, null);
   }
   consumeDirty();
   const release = await acquireSlot(signal || null);
-  let handedToWorker = false;
+  let hit;
   try {
     _throwIfAborted(signal);
-    const hit = await validateDiskHit({ graphCwd, diskEntry, genAtStart, signal });
-    _throwIfAborted(signal);
-    if (hit?.invalidated) throw codeGraphBuildInvalidatedError(hit.graph);
-    if (hit?.graph) return hit.graph;
-    _throwIfAborted(signal);
-    const workerPromise = spawnWorker(release, hit?.manifest || null, hit?.signature || null);
-    handedToWorker = true;
-    return workerPromise;
+    hit = await validateDiskHit({ graphCwd, diskEntry, genAtStart, signal });
   } finally {
-    if (!handedToWorker) release();
+    release();
   }
+  _throwIfAborted(signal);
+  if (hit?.invalidated) throw codeGraphBuildInvalidatedError(hit.graph);
+  if (hit?.graph) return hit.graph;
+  return spawnWorker(hit?.manifest || null, hit?.signature || null);
 }
 
 function _prepareDiskCodeGraphFastPath({
@@ -306,8 +302,10 @@ export async function buildCodeGraphAsync(
   const existing = _inflightAsyncBuilds.get(inflightKey);
   if (existing) return raceAbort(existing, signal);
   // Non-competing prewarm: the signature-validation manifest also needs a
-  // child-spawn slot, so warmers skip before either it or a Worker can queue.
-  if (bestEffort && !childSpawnHasSpareCapacity('code-graph')) return null;
+  // query slot and a miss a build slot, so warmers skip before either queues.
+  if (bestEffort && !(childSpawnHasSpareCapacity('code-graph-query') && childSpawnHasSpareCapacity('code-graph'))) {
+    return null;
+  }
   const promise = _retryCodeGraphBuildAfterInvalidation(
     async () => {
       const genAtStart = _getCodeGraphGen(graphCwd);
@@ -315,7 +313,7 @@ export async function buildCodeGraphAsync(
       // bounded I/O. Do not run a manifest at all when no disk candidate exists:
       // cold/dirty misses remain entirely on the existing Worker path.
       if (scoped) {
-        return _spawnCodeGraphWorker(cwd, graphCwd, genAtStart, signal, null, null, null, {
+        return _spawnCodeGraphWorker(cwd, graphCwd, genAtStart, signal, null, null, {
           buildOptions: scopeOptions,
           cacheResult: false,
         });
@@ -330,8 +328,8 @@ export async function buildCodeGraphAsync(
             signal,
             loadDiskEntry: () => getDiskCodeGraphEntry(graphCwd),
             consumeDirty: () => _consumeCodeGraphDirtyPaths(graphCwd),
-            spawnWorker: (preAcquiredRelease, manifest, signature) =>
-              _spawnCodeGraphWorker(cwd, graphCwd, genAtStart, signal, preAcquiredRelease, manifest, signature),
+            spawnWorker: (manifest, signature) =>
+              _spawnCodeGraphWorker(cwd, graphCwd, genAtStart, signal, manifest, signature),
           }),
       });
     },
@@ -350,7 +348,6 @@ export function _spawnCodeGraphWorker(
   graphCwd,
   genAtStart,
   signal,
-  preAcquiredRelease = null,
   manifest = null,
   signature = null,
   {
@@ -416,10 +413,7 @@ export function _spawnCodeGraphWorker(
         /* best-effort */
       }
     };
-    (preAcquiredRelease
-      ? Promise.resolve(preAcquiredRelease)
-      : acquireChildSpawnSlot(signal || null, 'code-graph')
-    ).then((release) => {
+    acquireChildSpawnSlot(signal || null, 'code-graph').then((release) => {
       _releaseSlot = release;
       if (settled) {
         release();

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

@@ -14,7 +14,7 @@ import { resolve as pathResolve, isAbsolute, relative as pathRelative, dirname a
 import { normalizeInputPath } from '../builtin/path-utils.mjs';
 import { markScopedCacheIncomplete, recordScopedCacheDependency } from '../../session/cache/scoped-cache-outcome.mjs';
 import { CODE_GRAPH_TOOL_DEFS } from '../code-graph-tool-defs.mjs';
-import { CODE_GRAPH_OUTPUT_MAX_BYTES, capLineOrientedToolOutput } from '../builtin/tool-output-limit.mjs';
+import { CODE_GRAPH_OUTPUT_MAX_BYTES, capLineOrientedToolOutput, capMarker } from '../builtin/tool-output-limit.mjs';
 import { _graphRel, _appendSameBasenameHint, _isExistingFile } from './source-access.mjs';
 import {
   _capGraphList,
@@ -375,7 +375,6 @@ async function executeCodeGraphToolRaw(name, rawArgs, cwd, signal = null, option
 
 function _codeGraphBudgetFooter(args, keptLines) {
   const rawMode = String(args?.mode || '').trim();
-  const capKb = Math.round(CODE_GRAPH_OUTPUT_MAX_BYTES / 1024);
   const targets = collectGraphSymbolList(args);
   const files = _collectGraphFileList(args);
   const batchTargets = targets.length ? targets : files;
@@ -389,13 +388,18 @@ function _codeGraphBudgetFooter(args, keptLines) {
       const index = batchTargets.indexOf(match[1]);
       if (index >= 0) currentIndex = index;
     }
-    return `... [code_graph output capped at ${capKb} KB; not fully shown: ${label}=${JSON.stringify(batchTargets.slice(currentIndex))}]`;
+    return capMarker({
+      limit: CODE_GRAPH_OUTPUT_MAX_BYTES,
+      shown: `${label} from index ${currentIndex} not fully shown`,
+      narrow: `re-query ${label}=${JSON.stringify(batchTargets.slice(currentIndex))} separately`,
+    });
   }
   const target = batchTargets[0];
-  const targetTail = target
-    ? `; remainder for ${label.slice(0, -1)}=${JSON.stringify(target)} omitted`
-    : '; remainder omitted';
-  return `... [code_graph output capped at ${capKb} KB${targetTail}]`;
+  return capMarker({
+    limit: CODE_GRAPH_OUTPUT_MAX_BYTES,
+    shown: target ? `remainder for ${label.slice(0, -1)}=${JSON.stringify(target)} omitted` : 'remainder omitted',
+    narrow: 'add file/path scope, a narrower mode, or a smaller depth/limit',
+  });
 }
 
 export async function executeCodeGraphTool(name, args, cwd, signal = null, options = {}) {

package/src/runtime/agent/orchestrator/tools/destructive-warning.mjs

@@ -9,12 +9,111 @@
 import { SHELL_NAMES as _SHELL_NAMES, WRAPPER_NAMES as _WRAPPER_NAMES } from './shell-policy.mjs';
 import { extractPowerShellCommandInner } from './shell-powershell.mjs';
 
+// A `#` (or PowerShell `<#`) starts a comment only at the start of a word:
+// line start, after whitespace, or after a command operator. Inside a word or
+// URL (`a#b`, `http://x/#y`, `$#`, `${#v}`) it is an ordinary character.
+function _isCommentStart(text, i) {
+  return i === 0 || /[\s;&|(]/.test(text[i - 1]);
+}
+
+const _PS_HERE_SQ = /@'[ \t]*\r?\n[\s\S]*?\r?\n'@/y;
+const _PS_HERE_DQ = /@"[ \t]*\r?\n[\s\S]*?\r?\n"@/y;
+const _HEREDOC_START = /<<-?\s*['"]?(\w+)['"]?/y;
+
+function _closingQuote(text, from, quote, escapes) {
+  let j = from;
+  while (j < text.length && text[j] !== quote) j += escapes && text[j] === '\\' ? 2 : 1;
+  return j < text.length ? j : -1;
+}
+
+// Single left-to-right scan so each construct is recognised by what the shell
+// would see at that position (a `'` inside a comment, a `#` inside a word or a
+// quote inside a here-string never mis-pair later delimiters). Any construct
+// that cannot be closed (unterminated quote, `<#` without `#>`, heredoc without
+// terminator) is left in the output verbatim, so uncertain text stays visible
+// to the policy checks instead of being dropped.
 export function stripQuotedAndHeredoc(s) {
-  return String(s || '')
-    .replace(/<<-?\s*['"]?(\w+)['"]?[\s\S]*?\n\1\b/g, '<<HEREDOC>>')
-    .replace(/'[^']*'/g, "''")
-    .replace(/"(?:[^"\\]|\\.)*"/g, '""')
-    .replace(/#[^\n]*/g, '');
+  const text = String(s || '');
+  const n = text.length;
+  const pendingHeredocs = [];
+  let out = '';
+  let i = 0;
+  while (i < n) {
+    const ch = text[i];
+    if (ch === '\\') {
+      out += text.slice(i, i + 2);
+      i += 2;
+      continue;
+    }
+    if (ch === '@' && (text[i + 1] === "'" || text[i + 1] === '"')) {
+      const re = text[i + 1] === "'" ? _PS_HERE_SQ : _PS_HERE_DQ;
+      re.lastIndex = i;
+      const m = re.exec(text);
+      if (m) {
+        out += text[i + 1] === "'" ? "''" : '""';
+        i += m[0].length;
+        continue;
+      }
+    }
+    if (ch === '<' && text[i + 1] === '<' && text[i - 1] !== '<') {
+      _HEREDOC_START.lastIndex = i;
+      const m = _HEREDOC_START.exec(text);
+      if (m && new RegExp(`\\n${m[1]}\\b`).test(text.slice(i + m[0].length))) {
+        // The rest of the opening line stays visible; the body is skipped at
+        // the next newline.
+        pendingHeredocs.push(m[1]);
+        out += '<<HEREDOC>>';
+        i += m[0].length;
+        continue;
+      }
+    }
+    if (ch === '<' && text[i + 1] === '#' && _isCommentStart(text, i)) {
+      const end = text.indexOf('#>', i + 2);
+      if (end >= 0) {
+        out += ' ';
+        i = end + 2;
+        continue;
+      }
+    }
+    if (ch === '#' && _isCommentStart(text, i)) {
+      const nl = text.indexOf('\n', i);
+      i = nl < 0 ? n : nl;
+      continue;
+    }
+    if (ch === "'" || ch === '"' || (ch === '$' && text[i + 1] === "'")) {
+      const ansiC = ch === '$';
+      const quote = ansiC ? "'" : ch;
+      const open = ansiC ? i + 2 : i + 1;
+      const close = _closingQuote(text, open, quote, ch !== "'");
+      if (close >= 0) {
+        out += (ansiC ? '$' : '') + quote + quote;
+        i = close + 1;
+        continue;
+      }
+    }
+    if (ch === '\n' && pendingHeredocs.length) {
+      let at = i;
+      let found = true;
+      for (const delimiter of pendingHeredocs) {
+        const re = new RegExp(`\\n${delimiter}\\b`, 'g');
+        re.lastIndex = at;
+        const m = re.exec(text);
+        if (!m) {
+          found = false;
+          break;
+        }
+        at = m.index + m[0].length;
+      }
+      pendingHeredocs.length = 0;
+      if (found) {
+        i = at;
+        continue;
+      }
+    }
+    out += ch;
+    i++;
+  }
+  return out;
 }
 
 // Heredoc bodies (shell-exec contexts route the body through scanning).
@@ -37,8 +136,11 @@ function _tokenize(s) {
     if (c === "'") {
       const e = src.indexOf("'", i + 1);
       if (e === -1) {
-        cur += src.slice(i);
-        break;
+        // Unterminated: an apostrophe inside a PowerShell word is literal, so
+        // keep tokenizing instead of swallowing the rest of the command.
+        cur += c;
+        i++;
+        continue;
       }
       cur += src.slice(i, e + 1);
       i = e + 1;
@@ -55,8 +157,9 @@ function _tokenize(s) {
         j++;
       }
       if (j >= src.length) {
-        cur += src.slice(i);
-        break;
+        cur += c;
+        i++;
+        continue;
       }
       cur += src.slice(i, j + 1);
       i = j + 1;
@@ -67,6 +170,20 @@ function _tokenize(s) {
       i += 2;
       continue;
     }
+    // `cur` is empty exactly at a word start (after whitespace or an operator),
+    // the only place `#` / PowerShell `<#` begins a comment.
+    if (!cur && c === '#') {
+      const nl = src.indexOf('\n', i);
+      i = nl < 0 ? src.length : nl;
+      continue;
+    }
+    if (!cur && c === '<' && src[i + 1] === '#') {
+      const end = src.indexOf('#>', i + 2);
+      if (end >= 0) {
+        i = end + 2;
+        continue;
+      }
+    }
     if (c === ' ' || c === '\t') {
       if (cur) {
         t.push(cur);