mixdog 1.4.0 → 1.4.2

package/src/runtime/agent/orchestrator/session/store-transcript-worker.mjs

@@ -8,8 +8,10 @@
  * loop each read stretched to seconds. This worker runs exactly that pipeline
  * (stat → read → stat, digest, readTopLevelLifecycleRecord →
  * projectStoredTranscript with no turn checkpoint) and hands back the
- * digest and the same projection value; only the finished window crosses
- * back.
+ * digest and one slice of the session's display history: the history itself
+ * is built once per content and kept here with its base, and only the window
+ * or page a request names (`slice`: `{ limit, skip }`) crosses back, with its
+ * serialized size measured here.
  *
  * Inside the worker, one projection base (recovery, prepared session and
  * whole-transcript context gauge) per session content is shared by every
@@ -60,8 +62,14 @@ function clientFor(sessionId) {
  * the full file stamp the bytes provably came from, or null. Rejects when the
  * worker cannot answer; callers then run the pipeline on their own thread.
  */
-export function projectStoredTranscriptOffThread({ sessionId, recordPath, itemLimit, known = null }) {
-  return clientFor(sessionId)({ sessionId, recordPath, itemLimit, known });
+export function projectStoredTranscriptOffThread({
+  sessionId,
+  recordPath,
+  known = null,
+  fingerprint = '',
+  slice = null,
+}) {
+  return clientFor(sessionId)({ sessionId, recordPath, known, fingerprint, slice });
 }
 
 /** Whether the projection worker of `sessionId` is attached (a request now
@@ -321,15 +329,108 @@ async function buildBase(sessionId, text, previousMessages, timing) {
 
 const baseBuilds = createBaseBuilds({ build: buildBase });
 
-async function project({ sessionId, recordPath, itemLimit, known }) {
+// Serialized bytes of the display histories this worker keeps for slicing:
+// one larger than the per-session bound is rebuilt per request instead, and
+// the oldest go once all of them exceed the worker's bound. The worker's idle
+// exit releases every one.
+// Measured: a history is about as large as its record (74 MB record: 75 MB
+// history) and a page of a retained one costs ~0.2 s, a rebuilt one ~1 s. 96
+// MB keeps the largest sessions seen (~78 MB records) smooth; 128 MB holds
+// one of those beside a few ordinary ones.
+export const WORKER_HISTORY_SESSION_MAX_BYTES = 96 * 1024 * 1024;
+export const WORKER_HISTORY_MAX_BYTES = 128 * 1024 * 1024;
+
+/**
+ * The display histories one worker retains (`{ value, rowBytes, bytes }`,
+ * keyed by session, Map order LRU) within `sessionMaxBytes` each and
+ * `maxBytes` together. A history of other content (`owner`, the record
+ * content it was built from, and its sidecar fingerprint) is never served.
+ */
+export function createHistoryRetention({
+  sessionMaxBytes = WORKER_HISTORY_SESSION_MAX_BYTES,
+  maxBytes = WORKER_HISTORY_MAX_BYTES,
+} = {}) {
+  const histories = new Map();
+  let retainedBytes = 0;
+  const drop = (sessionId) => {
+    const entry = histories.get(sessionId);
+    if (!entry) return;
+    histories.delete(sessionId);
+    retainedBytes -= entry.history.bytes;
+  };
+  return {
+    get(sessionId, owner, fingerprint) {
+      const entry = histories.get(sessionId);
+      if (!entry || entry.owner !== owner || entry.fingerprint !== fingerprint) return null;
+      histories.delete(sessionId);
+      histories.set(sessionId, entry);
+      return entry.history;
+    },
+    /** Keeps `history` when it fits; whether it was kept. */
+    retain(sessionId, owner, fingerprint, history) {
+      drop(sessionId);
+      if (history.bytes > sessionMaxBytes) return false;
+      histories.set(sessionId, { owner, fingerprint, history });
+      retainedBytes += history.bytes;
+      while (retainedBytes > maxBytes && histories.size > 1) drop(histories.keys().next().value);
+      return true;
+    },
+    forget: drop,
+    stats: () => ({ histories: histories.size, retainedBytes }),
+  };
+}
+
+const historyRetention = createHistoryRetention();
+/** sessionId -> { owner, fingerprint, promise }: histories being built. */
+const historyBuilds = new Map();
+
+/** The display history of `built` (one base) under sidecar `fingerprint`,
+ *  with each row's serialized bytes: retained, joined while another request
+ *  builds it, or built now. */
+async function displayHistory(sessionId, built, content, fingerprint, projection) {
+  const retained = historyRetention.get(sessionId, content, fingerprint);
+  if (retained) return { history: retained, historyBuilt: false };
+  const pending = historyBuilds.get(sessionId);
+  if (pending && pending.owner === content && pending.fingerprint === fingerprint) {
+    return { history: await pending.promise, historyBuilt: false };
+  }
+  const promise = (async () => {
+    const value = await projection.windowStoredTranscript(sessionId, built.base, {
+      history: true,
+      includeMessages: false,
+    });
+    const rowBytes = new Float64Array(value.items.length);
+    let bytes = 0;
+    for (let index = 0; index < value.items.length; index += 1) {
+      rowBytes[index] = Buffer.byteLength(JSON.stringify(value.items[index] ?? null));
+      bytes += rowBytes[index];
+    }
+    return { value, rowBytes, bytes };
+  })();
+  const record = { owner: content, fingerprint, promise };
+  historyBuilds.set(sessionId, record);
+  try {
+    const history = await promise;
+    if (historyBuilds.get(sessionId) === record) historyRetention.retain(sessionId, content, fingerprint, history);
+    return { history, historyBuilt: true };
+  } finally {
+    if (historyBuilds.get(sessionId) === record) historyBuilds.delete(sessionId);
+  }
+}
+
+async function project({ sessionId, recordPath, known, fingerprint = '', slice = null }) {
   const importStartedAt = performance.now();
-  const [{ statSessionStamp, sameSessionStamp }, { readTextFile, PROBE_PRESENT }, { transcriptTextHash }, projection] =
-    await Promise.all([
-      import('./store/canonical-reader.mjs'),
-      import('./store/fs-probe.mjs'),
-      import('./store-transcript-cache.mjs'),
-      import('./store-transcript-projection.mjs'),
-    ]);
+  const [
+    { statSessionStamp, sameSessionStamp },
+    { readTextFile, PROBE_PRESENT },
+    { transcriptTextHash, historyStampOf },
+    projection,
+  ] = await Promise.all([
+    import('./store/canonical-reader.mjs'),
+    import('./store/fs-probe.mjs'),
+    import('./store-transcript-cache.mjs'),
+    import('./store-transcript-projection.mjs'),
+  ]);
   const timing = { importMs: performance.now() - importStartedAt };
   const observe = () => {
     try {
@@ -374,12 +475,32 @@ async function project({ sessionId, recordPath, itemLimit, known }) {
       const built = await pending;
       if (built === RESTART_READ) continue;
       if (built.unreadable) return { ...digest, unreadable: true };
-      const value = await projection.windowStoredTranscript(sessionId, built.base, {
-        itemLimit,
-        includeMessages: false,
-      });
+      // The whole display history stays here (within its budgets); only the
+      // requested slice crosses back.
+      const { history, historyBuilt } = await displayHistory(
+        sessionId,
+        built,
+        `${digest.textHash}:${digest.textChars}`,
+        fingerprint,
+        projection
+      );
+      const request = slice || {};
+      const historyStamp = historyStampOf(sessionId, digest.textHash, digest.textChars, fingerprint, request.epoch);
+      const proven = Boolean(request.held) && request.baseHistory === historyStamp;
+      const value = projection.storedHistorySlice(
+        history.value,
+        { ...request, proven },
+        {
+          digestOf: request.held && !proven ? await projection.heldRowsDigester() : null,
+          rowBytes: (index) => history.rowBytes[index],
+        }
+      );
+      const { windowStamp } = value;
+      delete value.windowStamp;
+      value.projectionStamp = `${historyStamp}/${windowStamp}`;
+      const bytes = Buffer.byteLength(JSON.stringify(value));
       timing.projectMs = performance.now() - projectStartedAt;
-      return { ...digest, value, lifecycle: built.lifecycle };
+      return { ...digest, value, bytes, historyBuilt, lifecycle: built.lifecycle };
     } finally {
       if (!submitted) baseBuilds.release(ticket);
     }
@@ -388,6 +509,9 @@ async function project({ sessionId, recordPath, itemLimit, known }) {
 
 if (!isMainThread && workerData?.kind === WORKER_KIND) {
   serveWorkerRequests((payload) => {
-    return payload?.forget ? baseBuilds.forget(payload.forget) : project(payload);
+    if (!payload?.forget) return project(payload);
+    historyRetention.forget(payload.forget);
+    historyBuilds.delete(payload.forget);
+    return baseBuilds.forget(payload.forget);
   });
 }

package/src/runtime/agent/orchestrator/session/transcript-restore/restore.mjs

@@ -44,6 +44,7 @@ import {
 } from '../../../../shared/transcript-metadata.mjs';
 import { routineTriggerField } from '../../../../shared/routine-trigger.mjs';
 import { isImportedMessage } from '../imported-message.mjs';
+import { toolRunLine } from '../conversation-import/turns.mjs';
 import { isContextAckMessage } from '../compact/user-message-kind.mjs';
 import { isRoutineResultMessage, routineResultNotice } from '../routine-result.mjs';
 import { heldRequestNotice, isHeldRequestMessage } from '../human-gate/held-message.mjs';
@@ -140,7 +141,64 @@ function restoredContentText(message) {
   return typeof message?.content === 'string' ? message.content : toolResultText(message?.content);
 }
 
+// The runs of tool use an imported assistant message recorded (conversation-import
+// turns.mjs), kept only where the text still holds exactly their canonical line.
+function importedToolRuns(message) {
+  const runs = message?.meta?.importedToolRuns;
+  if (!isImportedMessage(message) || typeof message.content !== 'string' || !Array.isArray(runs)) return [];
+  let cursor = 0;
+  return runs.filter((run) => {
+    const valid =
+      Number.isInteger(run?.start) &&
+      Number.isInteger(run?.end) &&
+      run.start >= cursor &&
+      run.end > run.start &&
+      run.end <= message.content.length &&
+      Array.isArray(run.tools) &&
+      run.tools.length > 0 &&
+      run.tools.every((tool) => typeof tool?.name === 'string' && Number.isInteger(tool.count) && tool.count > 0) &&
+      message.content.slice(run.start, run.end) === toolRunLine(run.tools);
+    if (valid) cursor = run.end;
+    return valid;
+  });
+}
+
+// An imported reply with tool use: its text around each run as assistant rows,
+// each run as tool rows (one per tool, counted). The calls' results were never
+// imported; the `imported` mark lets the row say so.
+function restoredImportedAssistantItems(message, runs, nextId) {
+  const { completion: _completion, ...metadata } = restoredTranscriptMetadata(message);
+  const at = Number(message?.meta?.transcript?.at);
+  const items = [];
+  const pushText = (raw) => {
+    const text = raw.trim();
+    if (text) items.push({ kind: 'assistant', id: nextId(), text, ...metadata });
+  };
+  let cursor = 0;
+  for (const run of runs) {
+    pushText(message.content.slice(cursor, run.start));
+    for (const { name, count } of run.tools) {
+      if (isTranscriptHiddenControlToolName(name)) continue;
+      items.push({
+        kind: 'tool',
+        id: nextId(),
+        name,
+        imported: true,
+        expanded: false,
+        count,
+        completedCount: count,
+        ...(Number.isFinite(at) ? { at, startedAt: at, completedAt: at } : {}),
+      });
+    }
+    cursor = run.end;
+  }
+  pushText(message.content.slice(cursor));
+  return items;
+}
+
 function restoredAssistantTranscriptItems(message, nextId) {
+  const runs = importedToolRuns(message);
+  if (runs.length) return restoredImportedAssistantItems(message, runs, nextId);
   const text = restoredContentText(message).trim();
   if (!text) return [];
   const { completion, ...metadata } = restoredTranscriptMetadata(message);
@@ -339,7 +397,7 @@ function mergeRestoredToolItems(items) {
     // Result-dependent hiding (built-in skill loads) resolves here, after
     // every role:'tool' result has been attached to its restored call.
     if (item?.kind === 'tool' && isTranscriptHiddenToolItem(item)) continue;
-    const mergeable = item?.kind === 'tool' && item.aggregate !== true;
+    const mergeable = item?.kind === 'tool' && item.aggregate !== true && item.imported !== true;
     if (!mergeable) {
       flushRun();
       merged.push(item);
@@ -379,7 +437,8 @@ function restoredMessageItemUpperBound(message) {
   const calls = restoredMessageToolCalls(message);
   const content = message?.content;
   const hasContent = typeof content === 'string' ? content.length > 0 : Array.isArray(content) && content.length > 0;
-  return Number(hasContent) + completionCount + calls.length + boundaries;
+  const importedRows = importedToolRuns(message).reduce((total, run) => total + run.tools.length + 1, 0);
+  return Number(hasContent) + completionCount + calls.length + importedRows + boundaries;
 }
 
 // One restored tool card for a parsed notification/completion envelope.

package/src/runtime/agent/orchestrator/stall-policy.mjs

@@ -259,6 +259,29 @@ export const PROVIDER_WS_SEMANTIC_IDLE_TIMEOUT_MS = resolveTimeoutMs(
   { minMs: 10_000, maxMs: Math.max(10_000, STALL_ABORT_MS - STALL_TICK_MS) }
 );
 
+// First-OUTPUT window of one provider stream: from the stream opening until
+// the model's first semantic output (reasoning, text or a tool call). Server
+// metadata and keepalives (response.created / in_progress, an empty reasoning
+// or message item, a role-only chunk, pings) neither end this phase nor start
+// the semantic-idle clock, so a reasoning model may think silently past the
+// idle window (issue #244: 4–6 min on a large post-tool-result prompt). The
+// window sits one tick under the stall abort — the same ceiling the semantic
+// idle uses — so the provider still fails (and may retry or fall back) before
+// the agent watchdog's first-output deadline (600s default), and it is never
+// shorter than the idle window it replaces. Not separately tunable: it
+// follows STALL_TIMEOUT_S.
+export const PROVIDER_FIRST_OUTPUT_TIMEOUT_MS = Math.max(
+  PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS,
+  PROVIDER_WS_SEMANTIC_IDLE_TIMEOUT_MS,
+  STALL_ABORT_MS - STALL_TICK_MS
+);
+
+/** The first-output window of a stream whose semantic idle is `idleMs`: a
+ *  longer idle window (a provider profile) is never cut short by it. */
+export function providerFirstOutputTimeoutMs(idleMs) {
+  return Math.max(idleMs, PROVIDER_FIRST_OUTPUT_TIMEOUT_MS);
+}
+
 /**
  * The longest a provider's own first-byte handling may legitimately run
  * before it gives up, over every attempt it permits: `windowMs(n)` is the wait

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

@@ -25,6 +25,9 @@ import {
  *  when the last observed survivor exits, `cancel` terminates them. */
 function trackSurvivingDescendants(handle, { command, cwd, options, startedAtMs } = {}) {
   if (!handle?.taskId) return null;
+  // Once cancelled, every observation pass terminates survivors that ignored
+  // the first kill, so a retry is not needed to finish the job.
+  let cancelled = false;
   try {
     const task = startBackgroundTask({
       taskId: handle.taskId,
@@ -36,10 +39,10 @@ function trackSurvivingDescendants(handle, { command, cwd, options, startedAtMs
       meta: { task_id: handle.taskId, stdout: null, stderr: null, cwd, timeoutMs: 0 },
       resultType: 'shell_task_result',
       run: async () => {
-        await waitForShellDescendants(handle);
+        await waitForShellDescendants(handle, { sweep: () => cancelled });
         // The folder reservation the finished command handed to its
         // survivors ends with the last of them.
-        releaseShellJobWorkspace(handle.taskId);
+        await releaseShellJobWorkspace(handle.taskId);
         return {
           task_id: handle.taskId,
           status: 'completed',
@@ -48,6 +51,7 @@ function trackSurvivingDescendants(handle, { command, cwd, options, startedAtMs
       },
       // The kill's own re-observation is what `task cancel` reports.
       cancel: () => {
+        cancelled = true;
         task.cancelOutcome = killShellDescendants(handle);
       },
     });

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

@@ -28,9 +28,9 @@ function prefixPowerShellUtf8(command) {
 // UTF-8 prefix (+ optional filter-tee rescue), or a POSIX bash/zsh snapshot
 // wrapper delivered through the environment. Returns `{ failure }` when the
 // snapshot wrapper cannot be built.
-export async function planShellInvocation({ command, resolvedSpec, cwd }) {
+export async function planShellInvocation({ command, resolvedSpec, cwd, sessionId = null }) {
   const { shell, shellArg, shellArgs, shellType } = resolvedSpec;
-  const spawnEnv = buildShellSpawnEnv(cwd);
+  const spawnEnv = buildShellSpawnEnv(cwd, process.env, sessionId);
   const plan = {
     execShell: shell,
     execShellArg: shellArg,

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

@@ -1,3 +1,4 @@
+import { applySessionScratchEnv } from '../../../../../shared/session-scratch.mjs';
 import { withSkillLauncherPath } from '../../../../../shared/skill-script-runtime.mjs';
 import {
   applyShellEgressPolicy,
@@ -6,7 +7,8 @@ import {
   scrubRuntimeRootVars,
 } from '../../env-scrub.mjs';
 
-export function buildShellSpawnEnv(cwd, baseEnv = process.env) {
+// `sessionId` points TEMP/TMP/TMPDIR at that session's scratch directory.
+export function buildShellSpawnEnv(cwd, baseEnv = process.env, sessionId = null) {
   const spawnEnv = {
     ...baseEnv,
     LANG: 'C.UTF-8',
@@ -24,5 +26,5 @@ export function buildShellSpawnEnv(cwd, baseEnv = process.env) {
   // `mixdog-skill-node` (a skill's ${MIXDOG_SKILL_NODE}) resolves in every
   // model shell; only this env gets the entry, never the daemon's own.
   withSkillLauncherPath(spawnEnv);
-  return spawnEnv;
+  return applySessionScratchEnv(spawnEnv, sessionId);
 }

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

@@ -116,7 +116,12 @@ export async function executeBashTool(args, workDir, options = {}) {
   // A queued run, or a foreground tree that may outlive its result, settles later.
   let runSettled = null;
   try {
-    const invocation = await planShellInvocation({ command, resolvedSpec, cwd: bashWorkDir });
+    const invocation = await planShellInvocation({
+      command,
+      resolvedSpec,
+      cwd: bashWorkDir,
+      sessionId: options?.callerSessionId || options?.sessionId || null,
+    });
     if (invocation.failure) return invocation.failure;
     combinedAbort = combineAbortSignals(await sessionAbortSignal(options?.sessionId), options?.abortSignal || null);
     const startedAtMs = Date.now();

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

@@ -5,7 +5,7 @@
 // behavior, argument shapes, and the usage boundaries that only apply to that
 // tool; cross-tool policy lives in rules/shared/*.md.
 // Platform-specific command syntax belongs next to the command argument.
-import { GIT_TOOL_DEF } from './git-command-tool.mjs';
+import { GIT_AGENT_TOOL_DEF, GIT_TOOL_DEF } from './git-command-tool.mjs';
 import { PUBLIC_PATH_BATCH_LIMIT, PUBLIC_READ_WINDOW_MAX } from './arg-guard.mjs';
 import { GITHUB_TOOL_DEF } from '../../../../github/tool.mjs';
 import { envFlag } from '../../../../shared/env.mjs';
@@ -50,7 +50,7 @@ export function buildShellRoutingRules(kind = _defaultShellKind) {
 function buildShellDescription(kind) {
   const run = _shellBackgroundDisabled
     ? 'Commands run in the foreground until completion.'
-    : `Holds ${_holdS}s; then, or on input/task notification, backgrounds with task_id (command keeps running). Completion is automatic; never poll, and never sleep/poll-loop inside the shell (background:true or wait_ms instead; for an external job, background a command that exits when it ends). Result needed now: task wait. Known-long finite run: wait_ms up to ${SHELL_HOLD_MAX_MS}. Independent long runs, servers/watchers: background:true; cancel them when done.`;
+    : `Holds ${_holdS}s; then, or on input/task notification, backgrounds with task_id (command keeps running). Completion is automatic; never poll, and never sleep/poll-loop inside the shell (background:true or wait_ms instead; for an external job, background a command that exits when it ends). Result needed now: task wait. Independent long runs: background:true; cancel when done.`;
   return `Run programs, builds, tests and computation. ${buildShellRoutingRules(kind)} ${run}`;
 }
 
@@ -88,6 +88,10 @@ export function bindShellKind(tool, kind) {
   return bound;
 }
 
+function taskTimeoutDescription(defaultMs) {
+  return `Wait ceiling in ms; else current output at the ceiling. Default ${defaultMs}; clamped to ${TASK_WAIT_TIMEOUT_MIN_MS}-${TASK_WAIT_TIMEOUT_MAX_MS}.`;
+}
+
 export const BUILTIN_TOOLS = [
   {
     name: 'read',
@@ -101,7 +105,7 @@ export const BUILTIN_TOOLS = [
       compressible: false,
     },
     description:
-      "Read file windows or images. One call per read stage: {file_path, offset, limit} entries for every located site (≤10 files per call), never a whole large file. Content in context is never read again. Missing paths are reported, never replaced. Directories: list. Binaries: bounded hex. Rows carry no line numbers; `[lines a-b]` gives each block's range. Never count rows: before writing a line number, copy it from grep, code_graph or git diff output; otherwise cite path and symbol.",
+      "Read file windows or images. One call per read stage: {file_path, offset, limit} entries for every located site, never a whole large file. Content in context is never read again. Missing paths are reported, never replaced. Directories: list. Binaries: bounded hex. Rows carry no line numbers; `[lines a-b]` gives each block's range. Never count rows: before writing a line number, copy it from grep, code_graph or git diff output; otherwise cite path and symbol.",
     inputSchema: {
       type: 'object',
       properties: {
@@ -129,8 +133,7 @@ export const BUILTIN_TOOLS = [
               },
             },
           ],
-          description:
-            'Path(s) or {file_path, offset, limit} entries; overlapping windows of one file merge. A glob fans out to ≤10 newest files, 25 lines each.',
+          description: 'Overlapping windows of one file merge. A glob fans out to ≤10 newest files.',
         },
         offset: {
           type: 'integer',
@@ -167,14 +170,11 @@ export const BUILTIN_TOOLS = [
       compressibleLossless: true,
     },
     description:
-      'Replace exact text in one file. old_string must match once unless replace_all is true. Every non-overlapping edit of the stage in one response, using existing text, not text another edit creates; many files → one edit per file, all in that response. Widened replacements keep intervening lines verbatim.',
+      'Replace exact text in one file. old_string must match once unless replace_all is true. Every non-overlapping edit of the stage in one response, using existing text, not text another edit creates; many files → one edit per file. Widened replacements keep intervening lines verbatim.',
     inputSchema: {
       type: 'object',
       properties: {
-        file_path: {
-          type: 'string',
-          description: 'Path to the file to modify.',
-        },
+        file_path: { type: 'string' },
         old_string: {
           type: 'string',
           description:
@@ -187,7 +187,7 @@ export const BUILTIN_TOOLS = [
         replace_all: {
           type: 'boolean',
           default: false,
-          description: 'Replace all occurrences of old_string; default false.',
+          description: 'Replace all occurrences of old_string.',
         },
       },
       required: ['file_path', 'old_string', 'new_string'],
@@ -254,7 +254,7 @@ export const BUILTIN_TOOLS = [
       openWorldHint: false,
     },
     description:
-      'Manage shell tasks. Completion is delivered automatically; wait only when you need the result now, never poll with read. wait returns when the task finishes, or when new user input or any task notification arrives (the task keeps running). read/wait return new output, prioritizing the tail on completion. output:tail re-reads recent output without advancing the cursor; use read on the log path for omitted content.',
+      'Manage shell tasks. Completion is delivered automatically; wait only when you need the result now, never poll with read. wait returns when the task finishes, or when new user input or any task notification arrives (the task keeps running). read/wait return new output, prioritizing the tail on completion. Use read on the log path for omitted content.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -267,13 +267,13 @@ export const BUILTIN_TOOLS = [
         timeout_ms: {
           type: 'integer',
           minimum: 0,
-          description: `Wait ceiling in ms; returns on completion, new user input or a task notification, else current output at the ceiling. Default ${TASK_WAIT_TIMEOUT_DEFAULT_MS} (agents ${AGENT_TASK_WAIT_DEFAULT_MS}); clamped to ${TASK_WAIT_TIMEOUT_MIN_MS}-${TASK_WAIT_TIMEOUT_MAX_MS}.`,
+          description: taskTimeoutDescription(TASK_WAIT_TIMEOUT_DEFAULT_MS),
         },
         output: {
           type: 'string',
           enum: ['new', 'tail'],
           description:
-            'read/wait only. Default new; tail replays recent output after an interruption or context loss. Up to 8 KiB per stream while running, 12 KiB on completion or replay; original logs are preserved.',
+            'read/wait only. Default new; tail re-reads recent output without advancing the cursor, after an interruption or context loss. Up to 8 KiB per stream while running, 12 KiB on completion or replay; original logs are preserved.',
         },
       },
       required: ['action'],
@@ -324,7 +324,7 @@ export const BUILTIN_TOOLS = [
           description:
             'Requested results; default 250; 0 unlimited. Context output caps at 40 blocks; continue via the returned offset.',
         },
-        offset: { type: 'integer', minimum: 0, description: 'Result offset.' },
+        offset: { type: 'integer', minimum: 0 },
         context: {
           type: 'integer',
           minimum: 0,
@@ -356,7 +356,7 @@ export const BUILTIN_TOOLS = [
       compressible: true,
     },
     description:
-      'Wildcard file-path lookup under a known directory; directories never match. Omit path for the current Project; no preliminary listing. Unknown base: find first with a known path fragment. Gitignored paths need include_noise:true.',
+      'Wildcard file-path lookup under a known directory; directories never match. No preliminary listing. Unknown base: find first with a known path fragment.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -374,7 +374,7 @@ export const BUILTIN_TOOLS = [
           description: 'mtime default (newest first); natural = raw walk order, cheaper on huge trees.',
         },
         limit: { type: 'integer', minimum: 0, description: 'Max entries; default 100; 0 unlimited.' },
-        offset: { type: 'integer', minimum: 0, description: 'Entry offset.' },
+        offset: { type: 'integer', minimum: 0 },
         include_noise: {
           type: 'boolean',
           description: 'Also search gitignored trees.',
@@ -404,7 +404,7 @@ export const BUILTIN_TOOLS = [
           type: 'string',
           minLength: 1,
           pattern: '\\S',
-          description: 'Non-empty filename/path fragment; space-separated fragments AND-match within one path.',
+          description: 'Filename/path fragment; space-separated fragments AND-match within one path.',
         },
         path: { type: 'string', description: 'Base directory; omit for the current Project.' },
         limit: { type: 'integer', minimum: 0, description: 'Max paths; default 25; 0 unlimited.' },
@@ -445,10 +445,36 @@ export const BUILTIN_TOOLS = [
           maximum: 100,
           description: 'Max entries; default 100; 0 = no page cap (absolute cap still applies).',
         },
-        offset: { type: 'integer', minimum: 0, description: 'Entry offset.' },
+        offset: { type: 'integer', minimum: 0 },
       },
-      required: [],
       additionalProperties: false,
     },
   },
 ];
+
+// What a delegated agent's session sees of the tools whose text differs from
+// the Lead's: git (worktree operations are Lead-only) and task (the agent wait
+// default). Keyed by the shared definition, so a rebuilt list binds once.
+const _taskTool = BUILTIN_TOOLS.find((tool) => tool.name === 'task');
+const _agentTaskTool = {
+  ..._taskTool,
+  inputSchema: {
+    ..._taskTool.inputSchema,
+    properties: {
+      ..._taskTool.inputSchema.properties,
+      timeout_ms: {
+        ..._taskTool.inputSchema.properties.timeout_ms,
+        description: taskTimeoutDescription(AGENT_TASK_WAIT_DEFAULT_MS),
+      },
+    },
+  },
+};
+const _agentToolVariants = new Map([
+  [GIT_TOOL_DEF, GIT_AGENT_TOOL_DEF],
+  [_taskTool, _agentTaskTool],
+]);
+
+/** The agent-session variant of `tool`, or `tool` itself when it has none. */
+export function bindAgentOwner(tool) {
+  return _agentToolVariants.get(tool) ?? tool;
+}

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

@@ -324,7 +324,13 @@ export function rawContentCacheSet(fullPath, stat, rawBuf, now = Date.now()) {
   if (!canPublishReadCache(fullPath)) return;
   if (!fullPath || !Buffer.isBuffer(rawBuf)) return;
   const version = fileVersion(stat);
-  if (!version || !canCacheReadFile(version) || rawBuf.length !== version.size || rawBuf.length > RAW_CONTENT_CACHE_MAX_BYTES) return;
+  if (
+    !version ||
+    !canCacheReadFile(version) ||
+    rawBuf.length !== version.size ||
+    rawBuf.length > RAW_CONTENT_CACHE_MAX_BYTES
+  )
+    return;
   const key = canonicalCachePath(fullPath);
   rawContentCacheDelete(key);
   RAW_CONTENT_CACHE.set(key, {