mixdog 1.2.5 → 1.2.6

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

@@ -1,67 +1,393 @@
 /**
- * Off-thread parse + projection of a large stored transcript.
+ * Off-thread read + parse + projection of a stored transcript.
  *
- * The strict record parse and the transcript projection of a multi-megabyte
- * session took 0.4-3s of daemon event-loop time (`slow stored projection`).
- * This module runs exactly that pure pipeline (readTopLevelLifecycleRecord →
- * projectStoredTranscript with no turn checkpoint) on a lazily started worker
- * thread and hands back the same projection value. The worker loads its own
- * module graph; only the finished projection crosses back.
+ * A cold pane read used to cost the daemon event loop the whole pipeline: a
+ * chunked async read whose every 512 KB chunk waited for a loop turn, a
+ * SHA-256 of the text, the strict record parse and a projection that meters
+ * every message of the transcript (`slow stored projection`). Under a busy
+ * 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.
+ *
+ * Inside the worker, one projection base (recovery, prepared session and
+ * whole-transcript context gauge) per session content is shared by every
+ * window and every concurrent request of it, and a new version of a session
+ * reuses the parsed messages its previous version already metered wherever
+ * they are unchanged, so an appended turn re-meters only the new tail.
+ * Bodies read but not yet built are bounded (`createBaseBuilds`): room is
+ * reserved before a record is read, and a newer version of a session
+ * replaces its queued older build.
  *
  * Client (main thread): `projectStoredTranscriptOffThread`. Worker side is
  * active only when this file is loaded as a worker of that client.
  */
+import { availableParallelism } from 'node:os';
 import { isMainThread, workerData } from 'node:worker_threads';
 import { createWorkerRequestClient, serveWorkerRequests } from '../../../shared/worker-requests.mjs';
 
-/** Records at least this many characters go to the worker; smaller ones cost
- *  less on the main thread than the round trip. */
-export const OFFLOAD_MIN_CHARS = 1_000_000;
+/** Records of at least this many bytes go to the worker. Smaller ones cost
+ *  only a few ms here, and their parse can then be handed to the resume that
+ *  follows a pane read. */
+export const OFFLOAD_MIN_CHARS = 256 * 1024;
 const WORKER_KIND = 'stored-transcript-projection';
 const IDLE_EXIT_MS = 120_000;
+// A restore burst projects every pane at once; two threads halve its tail.
+// A session always goes to the same worker, which holds its base.
+const POOL_SIZE = Math.max(1, Math.min(2, availableParallelism() - 1));
 
-let client = null;
+const clients = [];
 
-/**
- * Parse and project `text` for `sessionId`. Resolves `{ unreadable: true }`
- * when the record is not a strict, identity-matching session record, else
- * `{ value, lifecycle }` where `lifecycle` is `{ id, closed, generation }`.
- * Rejects when the worker cannot answer; callers fall back to the main thread.
- */
-export function projectStoredTranscriptOffThread({ sessionId, text, itemLimit }) {
-  client ||= createWorkerRequestClient(new URL(import.meta.url), {
+function clientFor(sessionId) {
+  let hash = 0;
+  for (let index = 0; index < sessionId.length; index += 1) hash = (hash * 31 + sessionId.charCodeAt(index)) >>> 0;
+  const slot = hash % POOL_SIZE;
+  clients[slot] ||= createWorkerRequestClient(new URL(import.meta.url), {
     idleExitMs: IDLE_EXIT_MS,
     workerData: { kind: WORKER_KIND },
   });
-  return client({ sessionId, text, itemLimit });
+  return clients[slot];
 }
 
-/** Whether a projection worker is attached (a request now skips its start). */
-export function storedTranscriptWorkerRunning() {
-  return client?.running() === true;
+/**
+ * Read, digest and project the record at `recordPath` for `sessionId`.
+ * Resolves `{ state, timing }` with state absent/unreadable when the file
+ * cannot be read; otherwise `{ state, textChars, textHash, stamp, timing }`
+ * plus `same: true` when the content is `known` ({ textChars, textHash }),
+ * `unreadable: true` when it is not a strict, identity-matching session
+ * record, or `{ value, lifecycle }` (`{ id, closed, generation }`). `stamp` is
+ * 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 });
 }
 
-async function project({ sessionId, text, itemLimit }) {
-  const importStartedAt = performance.now();
-  const [{ readTopLevelLifecycleRecord, isLifecycleUnreadable }, { projectStoredTranscript }] = await Promise.all([
+/** Whether the projection worker of `sessionId` is attached (a request now
+ *  skips its start). */
+export function storedTranscriptWorkerRunning(sessionId) {
+  return clientFor(sessionId).running() === true;
+}
+
+/** Drop this session's projection base and queued builds in its worker (it
+ *  went live). Never starts a worker just to forget. */
+export function forgetStoredTranscriptOffThread(sessionId) {
+  const request = clientFor(sessionId);
+  if (request.running() === true) request({ forget: sessionId }).catch(() => {});
+}
+
+// ── Worker side ─────────────────────────────────────────────────────────────
+
+/** The answer a superseded or forgotten queued build gives its waiters: read
+ *  the record again (it now holds that newer content, or none). */
+export const RESTART_READ = Symbol('restart-read');
+
+// Source characters of records read but not yet built: reserved from the
+// file size BEFORE a record is read and held until its build settles, it
+// joins another build, or it is dropped. A record alone larger than this is
+// admitted only when nothing else is reserved.
+const BUILD_CHARS_LIMIT = 16 * 1024 * 1024;
+// Source characters of the retained bases (their parsed records and memos
+// stay alive with them). The newest base is kept even when it alone exceeds
+// this; the worker's idle exit releases everything.
+const BASE_CHARS_LIMIT = 16 * 1024 * 1024;
+
+/**
+ * Admission, build queue and retained bases of one worker.
+ * `build(sessionId, text, previousMessages, timing)` builds a base; it runs
+ * one at a time, in arrival order (metering yields between slices, so
+ * concurrent builds would share the thread round-robin and every pane of a
+ * restore burst would get its answer only at the end).
+ *
+ * A caller `admit`s the record's size before reading it, then `submit`s the
+ * text with its ticket (or `release`s it): retained or in-progress builds of
+ * the same content are shared; a newer version of a session replaces its
+ * queued older build, whose waiters get RESTART_READ. The previous version's
+ * messages are looked up when a build starts, so no queued build keeps an
+ * evicted or replaced base alive.
+ */
+export function createBaseBuilds({ build, buildCharsLimit = BUILD_CHARS_LIMIT, baseCharsLimit = BASE_CHARS_LIMIT }) {
+  /** sessionId -> { textHash, chars, built } (Map order is LRU). */
+  const bases = new Map();
+  let baseChars = 0;
+  /** Unstarted builds: { sessionId, text, textHash, chars, ticket, timing, waiters, retain }. */
+  const queue = [];
+  let running = null;
+  let draining = false;
+  /** Waiting for room: { chars, resolve } in arrival order. */
+  const admissions = [];
+  let reservedChars = 0;
+  let peakReservedChars = 0;
+  let builds = 0;
+
+  const dropBase = (sessionId) => {
+    const entry = bases.get(sessionId);
+    if (!entry) return;
+    bases.delete(sessionId);
+    baseChars -= entry.chars;
+  };
+
+  const retainBase = (sessionId, entry) => {
+    dropBase(sessionId);
+    bases.set(sessionId, entry);
+    baseChars += entry.chars;
+    while (baseChars > baseCharsLimit && bases.size > 1) dropBase(bases.keys().next().value);
+  };
+
+  const reserve = (ticket, chars) => {
+    reservedChars += chars - ticket.chars;
+    ticket.chars = chars;
+    peakReservedChars = Math.max(peakReservedChars, reservedChars);
+  };
+
+  const pump = () => {
+    while (admissions.length > 0 && (reservedChars === 0 || reservedChars + admissions[0].chars <= buildCharsLimit)) {
+      const { chars, resolve } = admissions.shift();
+      const ticket = { chars: 0, released: false };
+      reserve(ticket, chars);
+      resolve(ticket);
+    }
+  };
+
+  const release = (ticket) => {
+    if (!ticket || ticket.released) return;
+    ticket.released = true;
+    reservedChars -= ticket.chars;
+    ticket.chars = 0;
+    pump();
+  };
+
+  // An unstarted build nobody needs any more: its body and reservation go,
+  // its waiters read again.
+  const drop = (job) => {
+    queue.splice(queue.indexOf(job), 1);
+    job.text = null;
+    release(job.ticket);
+    for (const waiter of job.waiters.splice(0)) waiter.resolve(RESTART_READ);
+  };
+
+  async function drain() {
+    if (draining) return;
+    draining = true;
+    try {
+      while (queue.length > 0) {
+        const job = queue.shift();
+        running = job;
+        let outcome;
+        try {
+          const previous = bases.get(job.sessionId)?.built.messages ?? null;
+          outcome = { value: await build(job.sessionId, job.text, previous, job.timing) };
+        } catch (error) {
+          outcome = { error };
+        }
+        running = null;
+        job.text = null;
+        release(job.ticket);
+        builds += 1;
+        const { value, error } = outcome;
+        if (job.retain && value && !value.unreadable) {
+          retainBase(job.sessionId, { textHash: job.textHash, chars: job.chars, built: value });
+        }
+        for (const waiter of job.waiters.splice(0)) {
+          if (error) waiter.reject(error);
+          else waiter.resolve(value);
+        }
+      }
+    } finally {
+      draining = false;
+    }
+  }
+
+  return {
+    /** Resolves a ticket reserving `chars` once they fit the budget. */
+    admit(chars) {
+      const admitted = new Promise((resolve) => admissions.push({ chars: Math.max(0, chars || 0), resolve }));
+      pump();
+      return admitted;
+    },
+    /** The record read is `chars` long (its size was only an estimate). */
+    resize(ticket, chars) {
+      if (!ticket.released) reserve(ticket, chars);
+    },
+    release,
+    /** The base of this exact content (the ticket passes to the build or is
+     *  released), or RESTART_READ. */
+    submit(sessionId, text, textHash, ticket, timing) {
+      const chars = text.length;
+      const retained = bases.get(sessionId);
+      if (retained && retained.textHash === textHash && retained.chars === chars) {
+        release(ticket);
+        retainBase(sessionId, retained);
+        timing.base = 'shared';
+        return Promise.resolve(retained.built);
+      }
+      const sameContent = (job) =>
+        !!job && job.sessionId === sessionId && job.textHash === textHash && job.chars === chars;
+      let job = sameContent(running) ? running : queue.find(sameContent);
+      if (job) {
+        release(ticket);
+        timing.base = 'shared';
+      } else {
+        for (const older of queue.filter((queued) => queued.sessionId === sessionId)) drop(older);
+        job = { sessionId, text, textHash, chars, ticket, timing, waiters: [], retain: true };
+        queue.push(job);
+      }
+      const answer = new Promise((resolve, reject) => job.waiters.push({ resolve, reject }));
+      void drain();
+      return answer;
+    },
+    /** The session went live: drop its base and queued builds; one already
+     *  running answers its waiters but is not retained. */
+    forget(sessionId) {
+      dropBase(sessionId);
+      for (const queued of queue.filter((job) => job.sessionId === sessionId)) drop(queued);
+      if (running?.sessionId === sessionId) running.retain = false;
+    },
+    stats() {
+      return {
+        reservedChars,
+        peakReservedChars,
+        queuedBuilds: queue.length,
+        queuedChars: queue.reduce((sum, job) => sum + job.chars, 0),
+        waitingAdmissions: admissions.length,
+        builds,
+        retainedBases: bases.size,
+        baseChars,
+      };
+    },
+  };
+}
+
+/** Whether two JSON.parse results are the same value, key order included
+ *  (estimators serialize them). */
+export function sameJsonValue(left, right) {
+  if (left === right) return typeof left !== 'number' || Object.is(left, right);
+  if (!left || !right || typeof left !== 'object' || typeof right !== 'object') return false;
+  if (Array.isArray(left)) {
+    if (!Array.isArray(right) || left.length !== right.length) return false;
+    for (let index = 0; index < left.length; index += 1) {
+      if (!sameJsonValue(left[index], right[index])) return false;
+    }
+    return true;
+  }
+  if (Array.isArray(right)) return false;
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  if (leftKeys.length !== rightKeys.length) return false;
+  for (let index = 0; index < leftKeys.length; index += 1) {
+    const key = leftKeys[index];
+    if (rightKeys[index] !== key || !sameJsonValue(left[key], right[key])) return false;
+  }
+  return true;
+}
+
+/**
+ * Replace the leading messages of `next` that are the same value as those of
+ * `previous` with the previous objects, whose per-message meter memos the
+ * projection then reads instead of re-metering. Returns how many were reused.
+ * Projections never mutate messages, and the comparison is against each
+ * previous object as it is now, so the result is the projection of `next`.
+ */
+export function reuseParsedPrefix(next, previous) {
+  if (!Array.isArray(next) || !Array.isArray(previous)) return 0;
+  const shared = Math.min(next.length, previous.length);
+  let index = 0;
+  while (index < shared && sameJsonValue(next[index], previous[index])) {
+    next[index] = previous[index];
+    index += 1;
+  }
+  return index;
+}
+
+async function buildBase(sessionId, text, previousMessages, timing) {
+  const [{ readTopLevelLifecycleRecord, isLifecycleUnreadable }, { prepareStoredTranscriptBase }] = await Promise.all([
     import('./lifecycle-scan.mjs'),
     import('./store-transcript-projection.mjs'),
   ]);
   const parseStartedAt = performance.now();
   const record = readTopLevelLifecycleRecord(text);
   if (isLifecycleUnreadable(record) || record.id !== sessionId) return { unreadable: true };
-  const projectStartedAt = performance.now();
-  const value = await projectStoredTranscript(sessionId, record.doc, {
-    itemLimit,
-    includeMessages: false,
-    checkpointAbsent: true,
-  });
-  const timing = {
-    importMs: parseStartedAt - importStartedAt,
-    parseMs: projectStartedAt - parseStartedAt,
-    projectMs: performance.now() - projectStartedAt,
+  const messages = record.doc.messages;
+  timing.reusedMessages = reuseParsedPrefix(messages, previousMessages);
+  timing.parseMs = performance.now() - parseStartedAt;
+  const base = await prepareStoredTranscriptBase(sessionId, record.doc, { checkpointAbsent: true });
+  return {
+    base,
+    messages,
+    lifecycle: { id: record.id, closed: record.closed, generation: record.generation },
   };
-  return { value, lifecycle: { id: record.id, closed: record.closed, generation: record.generation }, timing };
 }
 
-if (!isMainThread && workerData?.kind === WORKER_KIND) serveWorkerRequests(project);
+const baseBuilds = createBaseBuilds({ build: buildBase });
+
+async function project({ sessionId, recordPath, itemLimit, known }) {
+  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 timing = { importMs: performance.now() - importStartedAt };
+  const observe = () => {
+    try {
+      return statSessionStamp(recordPath);
+    } catch {
+      return null;
+    }
+  };
+  for (let restarts = 0; ; restarts += 1) {
+    if (restarts > 0) timing.restarts = restarts;
+    // Room for the body is reserved before it is read (bytes bound chars).
+    const sized = observe();
+    const admitStartedAt = performance.now();
+    const ticket = await baseBuilds.admit(sized ? Number(sized.size) : 0);
+    timing.admitMs = performance.now() - admitStartedAt;
+    let submitted = false;
+    try {
+      const readStartedAt = performance.now();
+      const before = observe();
+      let body = readTextFile(recordPath);
+      if (body.state !== PROBE_PRESENT) return { state: body.state, timing };
+      const stamp = before && sameSessionStamp(before, observe()) ? before : null;
+      let text = body.text;
+      body = null;
+      baseBuilds.resize(ticket, text.length);
+      const digest = {
+        state: PROBE_PRESENT,
+        textChars: text.length,
+        textHash: transcriptTextHash(text),
+        stamp,
+        timing,
+      };
+      timing.readMs = performance.now() - readStartedAt;
+      if (known && known.textHash === digest.textHash && known.textChars === digest.textChars) {
+        return { ...digest, same: true };
+      }
+      const projectStartedAt = performance.now();
+      submitted = true;
+      const pending = baseBuilds.submit(sessionId, text, digest.textHash, ticket, timing);
+      // Only the build may keep the body; a joined read lets go of its copy.
+      text = null;
+      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,
+      });
+      timing.projectMs = performance.now() - projectStartedAt;
+      return { ...digest, value, lifecycle: built.lifecycle };
+    } finally {
+      if (!submitted) baseBuilds.release(ticket);
+    }
+  }
+}
+
+if (!isMainThread && workerData?.kind === WORKER_KIND) {
+  serveWorkerRequests((payload) => {
+    return payload?.forget ? baseBuilds.forget(payload.forget) : project(payload);
+  });
+}

package/src/runtime/agent/orchestrator/session/store.mjs

@@ -701,9 +701,16 @@ async function _doSave(payload) {
 // Durable lifecycle barriers (tombstone plant + detach generation bump) live
 // in store/lifecycle-barriers.mjs; re-exported so prior importers of
 // store.mjs stay unchanged.
-export { markSessionClosed, bumpSessionGeneration } from './store/lifecycle-barriers.mjs';
+export {
+  markSessionClosed,
+  bumpSessionGeneration,
+  markSessionClosedAsync,
+  markSessionClosedAttempt,
+  bumpSessionGenerationAttempt,
+  isLifecycleRetry,
+} from './store/lifecycle-barriers.mjs';
 // Session reads live in store/load-session.mjs, same facade contract.
-export { loadSession } from './store/load-session.mjs';
+export { loadSession, loadSessionStatus } from './store/load-session.mjs';
 
 // Hard delete + owned-agent enumeration live in store/session-delete.mjs;
 // re-exported here so prior importers of store.mjs stay unchanged.

package/src/runtime/agent/orchestrator/session/task-wait-control.mjs

@@ -1,14 +1,21 @@
-// Per-session wake control for `task wait`.
+// Per-session wake control for `task wait` and the foreground shell hold.
 //
 // This is intentionally separate from the turn AbortController: new user input
-// should release only the passive wait, let the tool return a running snapshot,
-// and then flow through the normal post-tool steering boundary. The background
-// task itself keeps running.
+// or a queued task notification releases only the passive wait, lets the tool
+// return a running snapshot, and then flows through the normal post-tool
+// steering boundary. The background task itself keeps running.
 const waitersBySession = new Map();
 const steeringChecks = new Set();
 
+// Why a wait was released early: user input/steering, or a deliverable task
+// notification queued for the session.
+export const TASK_WAIT_WAKE_USER = 'user-message';
+export const TASK_WAIT_WAKE_NOTIFICATION = 'notification';
+
 // Scoped to an active turn. Read the live queue at wait entry rather than
 // retaining a wake signal that could outlive a consumed or reclaimed prompt.
+// A check returns a wake reason (or true for user input) when something
+// deliverable is already queued for the session, else a falsy value.
 export function registerTaskWaitSteeringCheck(check) {
   steeringChecks.add(check);
   return () => steeringChecks.delete(check);
@@ -32,6 +39,8 @@ export function beginInterruptibleTaskWait(sessionId, parentSignal = null) {
   const waiter = {
     controller,
     interruptedByUser: false,
+    wakeReason: null,
+    wakeDetail: null,
   };
   let waiters = waitersBySession.get(key);
   if (!waiters) {
@@ -53,9 +62,18 @@ export function beginInterruptibleTaskWait(sessionId, parentSignal = null) {
     }
   }
 
-  if (!controller.signal.aborted && [...steeringChecks].some((check) => check(key))) {
-    waiter.interruptedByUser = true;
-    controller.abort('user-message');
+  if (!controller.signal.aborted) {
+    let queued = null;
+    for (const check of steeringChecks) {
+      const found = check(key);
+      if (!found) continue;
+      const reason = found === true ? TASK_WAIT_WAKE_USER : String(found);
+      // User input outranks a notification: its result text asks the model
+      // to handle the new message first.
+      if (!queued || reason === TASK_WAIT_WAKE_USER) queued = reason;
+      if (queued === TASK_WAIT_WAKE_USER) break;
+    }
+    if (queued) wakeWaiter(waiter, queued, null);
   }
 
   return {
@@ -63,6 +81,12 @@ export function beginInterruptibleTaskWait(sessionId, parentSignal = null) {
     get interruptedByUser() {
       return waiter.interruptedByUser;
     },
+    get wakeReason() {
+      return waiter.wakeReason;
+    },
+    get wakeDetail() {
+      return waiter.wakeDetail;
+    },
     dispose() {
       if (disposed) return;
       disposed = true;
@@ -77,17 +101,24 @@ export function beginInterruptibleTaskWait(sessionId, parentSignal = null) {
   };
 }
 
-export function interruptTaskWaitForSession(sessionId, reason = 'user-message') {
+function wakeWaiter(waiter, reason, detail) {
+  waiter.interruptedByUser = reason !== TASK_WAIT_WAKE_NOTIFICATION;
+  waiter.wakeReason = reason;
+  waiter.wakeDetail = detail || null;
+  try {
+    waiter.controller.abort(reason);
+  } catch {}
+}
+
+// `detail` names what woke the wait (the notified task id) for its result text.
+export function interruptTaskWaitForSession(sessionId, reason = TASK_WAIT_WAKE_USER, detail = null) {
   const waiters = waitersBySession.get(sessionKey(sessionId));
   if (!waiters?.size) return 0;
   let interrupted = 0;
   for (const waiter of [...waiters]) {
     if (waiter.controller.signal.aborted) continue;
-    waiter.interruptedByUser = true;
     interrupted += 1;
-    try {
-      waiter.controller.abort(reason);
-    } catch {}
+    wakeWaiter(waiter, reason, detail);
   }
   return interrupted;
 }

package/src/runtime/agent/orchestrator/session/tool-result-offload.mjs

@@ -19,11 +19,12 @@ import { getPluginData } from '../config.mjs';
 import { countSplitLines, normalizeOutputPath } from '../tools/builtin/path-utils.mjs';
 import { classifyResultKind } from './result-classification.mjs';
 import { registerSessionPurgeHook } from './store.mjs';
-import { SETUP_OUTPUT_MAX_BYTES } from '../../../shared/tool-output-limit.mjs';
+import { SETUP_OUTPUT_MAX_BYTES, capMarker } from '../../../shared/tool-output-limit.mjs';
 
 const TOOL_RESULT_OFFLOAD_THRESHOLD_CHARS = 50_000;
 const TOOL_RESULT_SETUP_THRESHOLD_CHARS = SETUP_OUTPUT_MAX_BYTES;
 const TOOL_RESULT_PREVIEW_CHARS = 512;
+const TOOL_RESULT_GIT_PREVIEW_CHARS = 8_000;
 const TOOL_RESULT_SHELL_THRESHOLD_CHARS = 30_000;
 const TOOL_RESULT_SEARCH_THRESHOLD_CHARS = 50_000;
 const TOOL_RESULT_GREP_THRESHOLD_CHARS = 20_000;
@@ -38,7 +39,8 @@ const ARTIFACT_READ_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (
 // Per-tool persistence limits are per-tool maxResultSizeChars values rather
 // than a single global value: grep persists at 20k, glob and list/find_* at
 // the 50k system default (deliberately tighter than the common 100k), and
-// shell/bash_session/task at 30k. Read/head/tail/diff stay inline
+// bash_session/terminal at 30k. shell/task stay inline: the shell delivery
+// helper already capped them, with the full log on disk. Read/head/tail/diff stay inline
 // (Infinity) — they are self-bound by FileRead semantics and the upstream
 // READ_MAX_SIZE_BYTES cap, so persisting to a sidecar to be re-read would be
 // circular. These values keep context-rich IO tools from turning into "read
@@ -59,10 +61,13 @@ const INLINE_THRESHOLD_BY_TOOL = new Map([
   ['tree', TOOL_RESULT_SEARCH_THRESHOLD_CHARS],
   ['find_files', TOOL_RESULT_SEARCH_THRESHOLD_CHARS],
   ['code_graph', TOOL_RESULT_SEARCH_THRESHOLD_CHARS],
-  ['shell', TOOL_RESULT_SHELL_THRESHOLD_CHARS],
+  // shell and task results are already capped by the shared shell delivery
+  // (tools/builtin/lib/shell-delivery.mjs) and name their full log on disk;
+  // offloading them again would cut a capped result down to a preview.
+  ['shell', Infinity],
   ['bash_session', TOOL_RESULT_SHELL_THRESHOLD_CHARS],
   ['terminal', TOOL_RESULT_SHELL_THRESHOLD_CHARS],
-  ['task', TOOL_RESULT_SHELL_THRESHOLD_CHARS],
+  ['task', Infinity],
   ['setup', TOOL_RESULT_SETUP_THRESHOLD_CHARS],
 ]);
 
@@ -110,6 +115,8 @@ function offloadableTextLength(result) {
 }
 
 const AGGREGATE_OFFLOAD_EXCLUDED_TOOLS = new Set([
+  'shell',
+  'task',
   'read',
   'head',
   'tail',
@@ -321,11 +328,21 @@ async function offloadText(sessionId, toolCallId, toolName, text, channel) {
   });
   if (!artifact) return text;
 
-  const { preview, truncated } = buildPreview(text);
+  // git offloads were fetched 95% of the time from a 512-char preview, so git
+  // keeps a head+tail large enough to answer from directly.
+  const previewChars = String(toolName || '').toLowerCase() === 'git' ? TOOL_RESULT_GIT_PREVIEW_CHARS : undefined;
+  const { preview, truncated } = buildPreview(text, previewChars);
   const sizeKb = Math.max(1, Math.round(text.length / 1024));
   const displayPath = normalizeOutputPath(artifact.path);
   const header = `${TOOL_RESULT_OFFLOAD_PREFIX} ${toolName} → ${displayPath} (${sizeKb} KB, ${artifact.lines} lines)]`;
-  const suffix = truncated ? '\n[preview truncated; full output preserved at the artifact path above]' : '';
+  // The header already names the path; git repeats it after its long preview,
+  // where the header is far above the cut.
+  let suffix = '';
+  if (truncated) {
+    suffix = previewChars
+      ? `\n${capMarker({ limit: `${previewChars} chars`, narrow: 'read it with offset/limit', fullPath: displayPath })}`
+      : '\n[preview truncated; full output preserved at the artifact path above]';
+  }
   return `${header}\n\n${preview}${suffix}`;
 }
 

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

@@ -12,6 +12,7 @@
 import { coerceReadFamilyPathArg, coerceShapeFlex, hasGlobMagic, normalizeGrepArgs } from './path-utils.mjs';
 import { hasOwn } from '../../../../shared/object.mjs';
 import { CODE_GRAPH_FILE_MODES, CODE_GRAPH_MODES } from '../code-graph-tool-defs.mjs';
+import { SHELL_HOLD_MAX_MS, SHELL_HOLD_MIN_MS } from './wait-budgets.mjs';
 
 const MAX_INT = 100000;
 export const PUBLIC_PATH_BATCH_LIMIT = 10;
@@ -737,7 +738,7 @@ function guardRead(a) {
       if (err) return err;
       for (const ek of ['offset', 'limit']) {
         const eErr = checkIntInRange(entry, ek, 0, ek === 'offset' ? READ_OFFSET_MAX : MAX_INT);
-        if (eErr) return eErr.replace(`"${ek}"`, `"path[${i}].${ek}"`);
+        if (eErr) return eErr.replace(`"${ek}"`, () => `"path[${i}].${ek}"`);
       }
     }
   }
@@ -779,16 +780,21 @@ function guardRead(a) {
 }
 
 function guardShell(a) {
-  const allowed = new Set(['command', 'timeout_ms', 'wait_ms']);
+  const allowed = new Set(['command', 'timeout_ms', 'wait_ms', 'background']);
   const unsupported = Object.keys(a).find((key) => !allowed.has(key));
   if (unsupported) {
-    return `Error: shell arg "${unsupported}" is unsupported; use only command, timeout_ms, and wait_ms`;
+    return `Error: shell arg "${unsupported}" is unsupported; use only command, timeout_ms, wait_ms, and background`;
+  }
+  if (hasOwn(a, 'background') && typeof a.background !== 'boolean') {
+    return `Error: shell arg "background" must be a boolean (got ${describeType(a.background)})`;
   }
   // Over-max is an unambiguous "wait as long as allowed"; clamp like the other
   // saturating integer args instead of failing the call.
-  if (hasOwn(a, 'wait_ms') && Number.isInteger(a.wait_ms) && a.wait_ms > 30000) a.wait_ms = 30000;
-  if (hasOwn(a, 'wait_ms') && (!Number.isInteger(a.wait_ms) || a.wait_ms < 1000)) {
-    return `Error: shell arg "wait_ms" must be an integer from 10000 to 30000, e.g. wait_ms:20000 (got ${JSON.stringify(a.wait_ms)})`;
+  if (hasOwn(a, 'wait_ms') && Number.isInteger(a.wait_ms) && a.wait_ms > SHELL_HOLD_MAX_MS) {
+    a.wait_ms = SHELL_HOLD_MAX_MS;
+  }
+  if (hasOwn(a, 'wait_ms') && (!Number.isInteger(a.wait_ms) || a.wait_ms < SHELL_HOLD_MIN_MS)) {
+    return `Error: shell arg "wait_ms" must be an integer from ${SHELL_HOLD_MIN_MS} to ${SHELL_HOLD_MAX_MS}, e.g. wait_ms:120000 (got ${JSON.stringify(a.wait_ms)})`;
   }
   if (!hasOwn(a, 'command')) {
     return 'Error: shell requires "command"';