talon-agent 5.29.0 → 5.31.0

package/src/core/agents/runner.ts

@@ -4,8 +4,8 @@
  *
  * The shape is the heartbeat / cron-job shape, because a sub-agent *is* one
  * of those: acquire a backend, resolve a model, open a run log, register a
- * task, and hand `runOneShotAgent` to `runIsolatedAgent` for the hard
- * timeout → abort → grace → eviction discipline. Nothing here is
+ * task, and hand `runOneShotAgent` to `runIsolatedAgent` for the (optional)
+ * hard timeout → abort → grace → eviction discipline. Nothing here is
  * backend-specific, which is the whole point: sub-agents work on Claude,
  * Codex, Kilo, OpenCode and any future backend with a background capability.
  *
@@ -65,6 +65,7 @@ import {
 import { openRunLog } from "../background/run-log.js";
 import { agentContextLabel } from "./context.js";
 import {
+  deliverMessage,
   deliverSettlement,
   initAgentDelivery,
   type AgentDeliveryDeps,
@@ -77,28 +78,47 @@ import {
   buildAgentSystemPrompt,
   buildRebriefPrompt,
   buildResumePrompt,
+  buildStallPing,
+  buildStallWarning,
 } from "./prompt.js";
+import { closeTrail, openTrail, type RunTrail } from "./trail.js";
+import { startWatchdog, type WatchdogHandle } from "./watchdog.js";
 import * as agentsRepo from "../../storage/agents/repo.js";
 import type { PersistedAgent } from "../../storage/agents/repo.js";
 import { agentRegistry } from "./registry.js";
+import { closeScratch, openScratch, scratchEnv } from "./scratch.js";
 import type {
   AgentCaps,
   AgentParent,
   AgentRecord,
   AgentSpawnOutcome,
   AgentSpawnSpec,
+  AgentTrail,
 } from "./types.js";
 
-/** Defaults for `config.agents`, applied when the block is absent. */
+/**
+ * Defaults for `config.agents`, applied when the block is absent. No hard
+ * timeout: the no-progress watchdog ends a run that has gone quiet, and a
+ * run that is still working is left to finish.
+ */
 export const DEFAULT_AGENT_CAPS: AgentCaps = {
   maxConcurrent: 6,
   maxDepth: 2,
-  defaultTimeoutMs: 15 * 60 * 1000,
+  stallTimeoutMs: 15 * 60 * 1000,
 };
 
-/** Floor and ceiling the tool boundary clamps a requested `timeout_s` into. */
+/** Floor the tool boundary clamps a requested `timeout_s` up to. */
 const MIN_TIMEOUT_MS = 30_000;
-const MAX_TIMEOUT_MS = 60 * 60 * 1000;
+
+/** Raised to abort a run the no-progress watchdog gave up on. */
+class AgentStalledError extends Error {
+  constructor(idleMs: number) {
+    super(
+      `stalled: no tool call or output for ${Math.round(idleMs / 60_000)} min`,
+    );
+    this.name = "AgentStalledError";
+  }
+}
 
 const capsHolder: { caps: AgentCaps } = { caps: DEFAULT_AGENT_CAPS };
 
@@ -112,7 +132,9 @@ export function initAgents(
     "agents",
     `Initialized — maxConcurrent=${capsHolder.caps.maxConcurrent} ` +
       `maxDepth=${capsHolder.caps.maxDepth} ` +
-      `timeout=${Math.round(capsHolder.caps.defaultTimeoutMs / 1000)}s` +
+      `timeout=${describeTimeout(capsHolder.caps.defaultTimeoutMs)} ` +
+      `ceiling=${describeTimeout(capsHolder.caps.maxTimeoutMs)} ` +
+      `stall=${describeTimeout(capsHolder.caps.stallTimeoutMs || undefined)}` +
       (capsHolder.caps.allowedBackends?.length
         ? ` allowedBackends=${capsHolder.caps.allowedBackends.join(",")}`
         : ""),
@@ -124,14 +146,38 @@ export function getAgentCaps(): AgentCaps {
   return capsHolder.caps;
 }
 
+/** "15m" / "90s" / "none" — for logs and tool text. */
+export function describeTimeout(ms: number | undefined): string {
+  if (ms === undefined || !(ms > 0)) return "none";
+  return ms % 60_000 === 0 ? `${ms / 60_000}m` : `${Math.round(ms / 1000)}s`;
+}
+
 /**
- * Clamp a model-supplied timeout into the supported window, or fall back to
- * the configured default. Applied at the tool boundary — `spawnAgent` itself
- * honours whatever it is handed, so the runner has one rule and not two.
+ * The hard timeout a run gets: the requested one, else
+ * `agents.defaultTimeoutMs`, either capped by `agents.maxTimeoutMs`; with
+ * none of those set, `undefined` — no hard timeout. Applied by the runner,
+ * so a resumed run follows the same rule as a fresh one.
  */
-export function clampTimeout(requestedMs: number | undefined): number {
-  if (requestedMs === undefined) return capsHolder.caps.defaultTimeoutMs;
-  return Math.min(MAX_TIMEOUT_MS, Math.max(MIN_TIMEOUT_MS, requestedMs));
+function effectiveTimeout(requestedMs: number | undefined): number | undefined {
+  const { defaultTimeoutMs, maxTimeoutMs } = capsHolder.caps;
+  const base = requestedMs ?? defaultTimeoutMs;
+  if (base === undefined) return maxTimeoutMs;
+  return maxTimeoutMs !== undefined ? Math.min(maxTimeoutMs, base) : base;
+}
+
+/**
+ * The tool boundary's rule: a model-supplied timeout is floored at 30s,
+ * then resolved like any other (`effectiveTimeout`). Returns `undefined`
+ * for "no hard timeout".
+ */
+export function clampTimeout(
+  requestedMs: number | undefined,
+): number | undefined {
+  return effectiveTimeout(
+    requestedMs !== undefined && Number.isFinite(requestedMs)
+      ? Math.max(MIN_TIMEOUT_MS, requestedMs)
+      : undefined,
+  );
 }
 
 /** The backend an agent inherits when the caller didn't pick one. */
@@ -326,7 +372,7 @@ export async function spawnAgent(
         ? { reasoningEffort: spec.reasoningEffort }
         : {}),
       ...(spec.model ? { requestedModel: spec.model } : {}),
-      timeoutMs: spec.timeoutMs ?? capsHolder.caps.defaultTimeoutMs,
+      ...(spec.timeoutMs !== undefined ? { timeoutMs: spec.timeoutMs } : {}),
       cwd: dirs.workspace,
       ...(spec.preflight ? { preflight: true } : {}),
     },
@@ -382,9 +428,11 @@ async function buildRunParams(
   model: string,
   abortController: AbortController,
   capture: { last: string },
+  trail: RunTrail,
+  scratchDir: string | undefined,
   resume?: ResumePlan,
 ): Promise<OneShotAgentParams> {
-  const appendLog = await openRunLog(
+  const writeLog = await openRunLog(
     agentLogPath(record.id),
     resume
       ? agentResumeLogHeader(
@@ -396,6 +444,10 @@ async function buildRunParams(
       : agentLogHeader(record, model),
   );
   const id = record.id;
+  const appendLog = (text: string): Promise<void> => {
+    trail.onLog(text);
+    return writeLog(text);
+  };
   return {
     prompt: resume
       ? resume.prompt
@@ -408,7 +460,9 @@ async function buildRunParams(
       parent: record.parent,
       depth: record.depth,
       maxDepth: capsHolder.caps.maxDepth,
+      ...(scratchDir ? { scratchDir } : {}),
     }),
+    ...(scratchDir ? { env: scratchEnv(scratchDir) } : {}),
     workspace: dirs.workspace,
     model,
     contextLabel: agentContextLabel(record.id),
@@ -417,6 +471,7 @@ async function buildRunParams(
     onAssistantText: (text) => {
       const trimmed = text.trim();
       if (trimmed) capture.last = trimmed;
+      trail.onAssistantText(text);
     },
     // Persisted the moment the backend reports it, so a restart at any
     // point after the first message can resume the conversation.
@@ -432,11 +487,13 @@ function settleSuccess(
   task: TaskHandle,
   lastText: string,
   usage: TaskUsage | undefined,
+  trail: AgentTrail,
 ): AgentRecord | null {
   if (agentRegistry.hasReported(id)) {
     task.succeed(usage);
     return agentRegistry.settle(id, {
       state: "done",
+      trail,
       ...(usage ? { usage } : {}),
     });
   }
@@ -445,6 +502,7 @@ function settleSuccess(
     return agentRegistry.settle(id, {
       state: "done",
       result: { summary: lastText },
+      trail,
       ...(usage ? { usage } : {}),
     });
   }
@@ -454,24 +512,82 @@ function settleSuccess(
   return agentRegistry.settle(id, {
     state: "failed",
     error,
+    trail,
     ...(usage ? { usage } : {}),
   });
 }
 
-/** Settle a run that threw: timeout, kill, or a genuine failure. */
+/**
+ * Settle a run that threw: timeout, stall, kill, or a genuine failure.
+ * `stalled` is the watchdog's own abort reason, checked first because a
+ * backend that honours the abort rejects with its own error.
+ */
 function settleFailure(
   id: string,
   task: TaskHandle,
   err: unknown,
+  trail: AgentTrail,
+  stalled?: AgentStalledError,
 ): AgentRecord | null {
   const state =
-    err instanceof IsolatedAgentTimeoutError
+    stalled || err instanceof IsolatedAgentTimeoutError
       ? "timed_out"
       : agentRegistry.killRequested(id)
         ? "killed"
         : "failed";
-  task.fail(err);
-  return agentRegistry.settle(id, { state, error: errText(err) });
+  task.fail(stalled ?? err);
+  return agentRegistry.settle(id, {
+    state,
+    error: errText(stalled ?? err),
+    trail,
+  });
+}
+
+/**
+ * Start the no-progress watchdog for one run (see `watchdog.ts`). Its kill
+ * aborts the run with an `AgentStalledError` recorded in `watch.stalled`,
+ * which the settle path reads to classify the run `timed_out`.
+ */
+function watchRun(
+  id: string,
+  trail: RunTrail,
+  abortController: AbortController,
+): { watch: { stalled?: AgentStalledError }; watchdog: WatchdogHandle } {
+  const watch: { stalled?: AgentStalledError } = {};
+  const watchdog = startWatchdog(capsHolder.caps.stallTimeoutMs, {
+    lastActivityAt: () => trail.lastActivityAt,
+    pingAgent: (idleMs) => {
+      agentRegistry.push(id, {
+        from: "watchdog",
+        text: buildStallPing(idleMs, capsHolder.caps.stallTimeoutMs),
+        at: Date.now(),
+      });
+      logWarn(
+        "agents",
+        `${id} quiet for ${Math.round(idleMs / 1000)}s — pinged`,
+      );
+    },
+    warnParent: (idleMs, killInMs) => {
+      const current = agentRegistry.get(id);
+      if (!current) return;
+      void deliverMessage(
+        current,
+        buildStallWarning(current, idleMs, killInMs),
+      ).catch((err: unknown) =>
+        logError("agents", `stall warning delivery failed for ${id}`, err),
+      );
+    },
+    kill: (idleMs) => {
+      watch.stalled = new AgentStalledError(idleMs);
+      logWarn("agents", `${id}: ${watch.stalled.message} — aborting`);
+      try {
+        abortController.abort(watch.stalled);
+      } catch {
+        /* the settle path below still runs */
+      }
+    },
+  });
+  return { watch, watchdog };
 }
 
 /**
@@ -491,7 +607,9 @@ async function runAgent(
   const id = record.id;
   const abortController = new AbortController();
   const capture = { last: "" };
-  const timeoutMs = spec.timeoutMs ?? capsHolder.caps.defaultTimeoutMs;
+  const timeoutMs = effectiveTimeout(spec.timeoutMs);
+  const trail = openTrail(id);
+  const { watch, watchdog } = watchRun(id, trail, abortController);
 
   // Registered as queued, bound, then started — so a kill arriving in the
   // gap between the task existing and the abort handle being published still
@@ -509,12 +627,15 @@ async function runAgent(
 
   let settled: AgentRecord | null = null;
   try {
+    const scratchDir = await openScratch(id);
     const params = await buildRunParams(
       record,
       spec,
       model,
       abortController,
       capture,
+      trail,
+      scratchDir,
       resume,
     );
     if (agentRegistry.isInterrupted(id)) {
@@ -528,12 +649,13 @@ async function runAgent(
         id,
         task,
         new Error("aborted before the run started"),
+        trail.snapshot(),
       );
     } else {
       const usage = await runIsolatedAgent({
         background,
         params,
-        timeoutMs,
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
         logCategory: "agents",
         // Safe to sweep: the context label is unique to this agent, so no
         // other context's subprocesses share the tag.
@@ -546,18 +668,37 @@ async function runAgent(
       if (agentRegistry.isInterrupted(id)) {
         settled = null;
       } else {
-        recordBackendRunSuccess(record.backendId);
-        settled = settleSuccess(id, task, capture.last, usage ?? undefined);
+        if (watch.stalled) {
+          // The backend swallowed the watchdog's abort and returned.
+          settled = settleFailure(
+            id,
+            task,
+            watch.stalled,
+            trail.snapshot(),
+            watch.stalled,
+          );
+        } else {
+          recordBackendRunSuccess(record.backendId);
+          settled = settleSuccess(
+            id,
+            task,
+            capture.last,
+            usage ?? undefined,
+            trail.snapshot(),
+          );
+        }
       }
     }
   } catch (err) {
     if (agentRegistry.isInterrupted(id)) {
       settled = null;
     } else {
-      recordBackendRunFailure(record.backendId, err);
-      settled = settleFailure(id, task, err);
+      if (!watch.stalled) recordBackendRunFailure(record.backendId, err);
+      settled = settleFailure(id, task, err, trail.snapshot(), watch.stalled);
     }
   } finally {
+    watchdog.stop();
+    closeTrail(id);
     await release().catch((err: unknown) =>
       logError("agents", `failed to release backend for ${id}`, err),
     );
@@ -573,10 +714,12 @@ async function runAgent(
     return;
   }
   if (!settled) return;
+  // Removed on success; kept on failure for whoever picks the work up.
+  await closeScratch(id, settled.state);
   log(
     "agents",
     `${id} "${settled.label}" → ${settled.state} ` +
-      `(${settled.backendId}/${model}, ${timeoutMs}ms cap)`,
+      `(${settled.backendId}/${model}, timeout ${describeTimeout(timeoutMs)})`,
   );
   reapChildren(settled);
   await deliverSettlement(settled).catch((err: unknown) =>
@@ -667,6 +810,7 @@ async function settleRestored(
 ): Promise<void> {
   const settled = agentRegistry.settle(record.id, patch);
   if (!settled) return;
+  await closeScratch(record.id, settled.state);
   log(
     "agents",
     `${record.id} "${record.label}" → ${settled.state} (after restart)`,
@@ -812,9 +956,12 @@ async function resumeOne(saved: PersistedAgent, now: number): Promise<void> {
         interruptedAt,
       };
 
-  const budget =
-    (saved.timeoutMs ?? capsHolder.caps.defaultTimeoutMs) - elapsedMs;
-  const timeoutMs = Math.max(AGENT_RESUME_MIN_TIMEOUT_MS, budget);
+  // An uncapped run stays uncapped; a capped one gets what it had left.
+  const cap = effectiveTimeout(saved.timeoutMs);
+  const timeoutMs =
+    cap === undefined
+      ? undefined
+      : Math.max(AGENT_RESUME_MIN_TIMEOUT_MS, cap - elapsedMs);
   const spec: AgentSpawnSpec = {
     brief: saved.brief,
     label: saved.label,
@@ -824,7 +971,7 @@ async function resumeOne(saved: PersistedAgent, now: number): Promise<void> {
     ...(record.reasoningEffort
       ? { reasoningEffort: record.reasoningEffort }
       : {}),
-    timeoutMs,
+    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
     ...(saved.preflight ? { preflight: true } : {}),
   };
   agentRegistry.markResumed(record.id);
@@ -832,7 +979,7 @@ async function resumeOne(saved: PersistedAgent, now: number): Promise<void> {
     "agents",
     `${record.id} "${record.label}" resuming after restart ` +
       `(${canResume ? `session ${saved.sessionId}` : "re-briefed"}, ` +
-      `${backendId}/${resolved.model}, ${Math.round(timeoutMs / 1000)}s left, ` +
+      `${backendId}/${resolved.model}, timeout ${describeTimeout(timeoutMs)}, ` +
       `resume #${saved.resumeCount + 1})`,
   );
   void runAgent(record, spec, resolved, acquired, plan);

package/src/core/agents/scratch.ts

@@ -0,0 +1,80 @@
+/**
+ * Scratch — a private temp directory per sub-agent.
+ *
+ * Every agent gets `/tmp/talon-agents/<id>/` (under `os.tmpdir()`), created
+ * when its run starts and exported as `TMPDIR` / `TMP` / `TEMP` to the
+ * backend run (`OneShotAgentParams.env`), so its shells and tools write
+ * their temporary files somewhere no other agent is writing. The directory
+ * is named in the agent's system prompt too, for backends that cannot take
+ * a per-run environment.
+ *
+ * Lifecycle: kept across a daemon restart (a resumed agent finds its files
+ * where it left them), removed when the agent settles `done`, and **kept**
+ * on any other terminal state so whoever picks up a failed, killed or
+ * timed-out run can inspect what it left behind.
+ */
+
+import { mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { logWarn } from "../../util/log.js";
+import type { AgentState } from "./types.js";
+
+/** Root of every agent's scratch dir. Overridable for tests. */
+const root: { dir: string } = { dir: join(tmpdir(), "talon-agents") };
+
+export function setScratchRootForTest(dir: string): void {
+  root.dir = dir;
+}
+
+/** Absolute path of an agent's scratch dir (whether or not it exists). */
+export function agentScratchDir(agentId: string): string {
+  return join(root.dir, agentId);
+}
+
+/** The env a run with this scratch dir is given. */
+export function scratchEnv(dir: string): Record<string, string> {
+  return { TMPDIR: dir, TMP: dir, TEMP: dir };
+}
+
+/**
+ * Create (or reuse, on resume) the agent's scratch dir. Returns its path,
+ * or `undefined` when it could not be created — a run is never refused for
+ * want of a temp dir; it just shares the system one.
+ */
+export async function openScratch(
+  agentId: string,
+): Promise<string | undefined> {
+  const dir = agentScratchDir(agentId);
+  try {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    return dir;
+  } catch (err) {
+    logWarn(
+      "agents",
+      `could not create scratch dir ${dir}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return undefined;
+  }
+}
+
+/**
+ * Clean up after a settled agent: removed on `done`, kept otherwise.
+ * Returns whether the directory was removed. Never throws.
+ */
+export async function closeScratch(
+  agentId: string,
+  state: AgentState,
+): Promise<boolean> {
+  if (state !== "done") return false;
+  try {
+    await rm(agentScratchDir(agentId), { recursive: true, force: true });
+    return true;
+  } catch (err) {
+    logWarn(
+      "agents",
+      `could not remove scratch dir for ${agentId}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return false;
+  }
+}

package/src/core/agents/trail.ts

@@ -0,0 +1,141 @@
+/**
+ * Trail — what a running sub-agent has been doing, kept so a run that is
+ * cut short (killed, timed out, stalled, failed) still hands its parent
+ * something to work with.
+ *
+ * Three bounded lists, all best-effort:
+ *
+ *   - **messages** — its last interim `message_parent` notes.
+ *   - **notes** — its last assistant texts (progress narration).
+ *   - **files** — paths it wrote or edited, scraped from the run log the
+ *     backend writes: Claude-style `**Tool call:** \`Write\`` blocks carrying
+ *     a `file_path` / `path` / `notebook_path`, and Codex `**File changes:**`
+ *     lists. A backend that logs neither simply contributes no files.
+ *
+ * The trail also carries the run's `lastActivityAt` clock, which the
+ * no-progress watchdog reads: any log line or assistant text counts.
+ *
+ * Trails live in memory only, keyed by agent id, for the life of the run.
+ */
+
+import type { AgentTrail } from "./types.js";
+
+const MAX_MESSAGES = 3;
+const MAX_NOTES = 3;
+const MAX_FILES = 50;
+/** One note or message is clipped to this many characters in the trail. */
+const MAX_TEXT_CHARS = 1_500;
+
+/** Tool names (bare or MCP-prefixed) that write files. */
+const WRITE_TOOL = /(?:^|__)(?:Write|Edit|MultiEdit|NotebookEdit|write|edit)$/;
+const TOOL_CALL_BLOCK =
+  /\*\*(?:MCP )?Tool call:\*\* `([^`]+)`\s*```json\n([\s\S]*?)\n```/g;
+const PATH_KEY = /"(?:file_path|notebook_path|path)":\s*"((?:[^"\\]|\\.)+)"/;
+const FILE_CHANGES_BLOCK = /\*\*File changes:\*\*[^\n]*\n((?:\s+- .*\n?)+)/g;
+
+function clip(text: string): string {
+  const t = text.trim();
+  return t.length > MAX_TEXT_CHARS ? `${t.slice(0, MAX_TEXT_CHARS)}…` : t;
+}
+
+function pushBounded(list: string[], item: string, max: number): void {
+  list.push(item);
+  if (list.length > max) list.splice(0, list.length - max);
+}
+
+/** File paths a chunk of run-log text says were written or edited. */
+export function filesFromLogChunk(chunk: string): string[] {
+  const out: string[] = [];
+  for (const m of chunk.matchAll(TOOL_CALL_BLOCK)) {
+    const tool = m[1] ?? "";
+    // MCP calls are logged as `server.tool`; normalise to the `__` form.
+    if (!WRITE_TOOL.test(tool.replace(/\./g, "__"))) continue;
+    const path = PATH_KEY.exec(m[2] ?? "")?.[1];
+    if (path) out.push(JSON.parse(`"${path}"`) as string);
+  }
+  for (const m of chunk.matchAll(FILE_CHANGES_BLOCK)) {
+    for (const line of (m[1] ?? "").split("\n")) {
+      const path = /^\s+- \S+ (.+)$/.exec(line)?.[1]?.trim();
+      if (path && path !== "?") out.push(path);
+    }
+  }
+  return out;
+}
+
+/** The live trail of one run. */
+export class RunTrail {
+  private readonly messages: string[] = [];
+  private readonly notes: string[] = [];
+  private readonly files: string[] = [];
+  lastActivityAt: number;
+
+  constructor(now: number = Date.now()) {
+    this.lastActivityAt = now;
+  }
+
+  /** Any sign of life — resets the watchdog. */
+  touch(now: number = Date.now()): void {
+    this.lastActivityAt = now;
+  }
+
+  /** A chunk the backend appended to the run log. */
+  onLog(chunk: string): void {
+    this.touch();
+    for (const file of filesFromLogChunk(chunk)) {
+      if (this.files.includes(file)) continue;
+      pushBounded(this.files, file, MAX_FILES);
+    }
+  }
+
+  onAssistantText(text: string): void {
+    this.touch();
+    const t = clip(text);
+    if (t) pushBounded(this.notes, t, MAX_NOTES);
+  }
+
+  onMessage(text: string): void {
+    this.touch();
+    const t = clip(text);
+    if (t) pushBounded(this.messages, t, MAX_MESSAGES);
+  }
+
+  snapshot(): AgentTrail {
+    return {
+      messages: [...this.messages],
+      notes: [...this.notes],
+      files: [...this.files],
+    };
+  }
+}
+
+const trails = new Map<string, RunTrail>();
+
+/** Start (or restart, on resume) the trail for a run. */
+export function openTrail(agentId: string): RunTrail {
+  const trail = new RunTrail();
+  trails.set(agentId, trail);
+  return trail;
+}
+
+export function getTrail(agentId: string): RunTrail | undefined {
+  return trails.get(agentId);
+}
+
+export function closeTrail(agentId: string): void {
+  trails.delete(agentId);
+}
+
+/** Record an interim `message_parent` note against a running agent. */
+export function recordInterimMessage(agentId: string, text: string): void {
+  trails.get(agentId)?.onMessage(text);
+}
+
+/** Whether a trail snapshot has anything worth showing. */
+export function trailIsEmpty(trail: AgentTrail | undefined): boolean {
+  return (
+    !trail ||
+    (trail.messages.length === 0 &&
+      trail.notes.length === 0 &&
+      trail.files.length === 0)
+  );
+}

package/src/core/agents/types.ts

@@ -87,6 +87,21 @@ export interface AgentRecord {
   readonly children: readonly string[];
   /** Messages waiting to be drained by `check_inbox`. */
   readonly inboxDepth: number;
+  /**
+   * What the run had been doing when it settled — set on every settlement
+   * the runner makes, shown to the parent when the run did not end `done`.
+   */
+  readonly trail?: AgentTrail;
+}
+
+/** A settled run's last interim messages, progress notes and changed files. */
+export interface AgentTrail {
+  /** Last `message_parent` notes, oldest first. */
+  readonly messages: readonly string[];
+  /** Last assistant texts, oldest first. */
+  readonly notes: readonly string[];
+  /** Files it wrote or edited (best-effort, from the run log). */
+  readonly files: readonly string[];
 }
 
 /** What `spawnAgent` is asked for. */
@@ -106,7 +121,11 @@ export interface AgentSpawnSpec {
    */
   readonly model?: string;
   readonly reasoningEffort?: ReasoningEffortLevel;
-  /** Hard wall-clock cap. Defaults to `agents.defaultTimeoutMs`. */
+  /**
+   * Hard wall-clock cap. Unset = `agents.defaultTimeoutMs`, and with that
+   * unset too, no cap at all — the no-progress watchdog is what ends a run
+   * that has gone quiet.
+   */
   readonly timeoutMs?: number;
   /**
    * Append the pre-flight lane instruction (run `npm run preflight` before
@@ -137,8 +156,15 @@ export interface AgentCaps {
   readonly maxConcurrent: number;
   /** Deepest `depth` an agent may have — 2 means chat → A → B. */
   readonly maxDepth: number;
-  /** Default hard timeout for one run. */
-  readonly defaultTimeoutMs: number;
+  /** Hard timeout for a spawn that sets none. Unset = no hard timeout. */
+  readonly defaultTimeoutMs?: number;
+  /** Ceiling on any run's hard timeout, requested or not. Unset = none. */
+  readonly maxTimeoutMs?: number;
+  /**
+   * No-progress watchdog step N: ping the agent after N ms of silence, warn
+   * its parent after 2N, kill it after 3N. 0 disables the watchdog.
+   */
+  readonly stallTimeoutMs: number;
   /**
    * Backends a sub-agent may run on. Unset or empty = any backend with a
    * background capability. Enforced by `spawnAgent` on the final choice.