@cydm/pie 2.6.5 → 2.6.7

package/dist/chunks/{chunk-QKSK5K5N.js → chunk-T6GMEDIE.js}

@@ -2,8 +2,9 @@ import { createRequire as __createRequire } from "node:module"; const require =
 import {
   Agent,
   getToolCallerIdentity
-} from "./chunk-AETQBDEG.js";
+} from "./chunk-PAC62XU4.js";
 import {
+  AssistantMessageEventStream,
   FileSystemGateway,
   completeSimple,
   detectPlatform,
@@ -11,7 +12,7 @@ import {
   getPlatformConfig,
   hashText,
   streamSimple
-} from "./chunk-5OXH6NUH.js";
+} from "./chunk-7B4IIBVS.js";
 import {
   Type
 } from "./chunk-XXGYUYXI.js";
@@ -1070,6 +1071,141 @@ function createPlanCapability() {
   });
 }
 
+// ../../packages/shared-headless-capabilities/src/subagent-stream.ts
+function isRetryableSubagentFailure(message) {
+  const remoteClosure = /SSE stream (?:aborted|closed before end|ended before response completed)/i.test(message);
+  const classificationText = message.replace(/econnaborted/ig, "").replace(/SSE stream aborted/ig, "remote stream closed");
+  if (/\b(?:400|401|403|404|422|429)\b|quota|weekly|monthly|limit reached|exhausted|unauthorized|authentication|invalid|protocol|stopReason=length|token limit|abort/i.test(classificationText)) return false;
+  return remoteClosure || /Request timeout/i.test(message) || /econnreset|econnaborted|etimedout|eai_again|econnrefused|socket hang up|socket disconnected|secure TLS connection|fetch failed|network error|connection reset|premature close|\b50[0234]\b|bad gateway|service unavailable/i.test(message);
+}
+function cancellableBackoff(ms, signal) {
+  return new Promise((resolve3) => {
+    const finish = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", finish);
+      resolve3();
+    };
+    const timer = setTimeout(finish, ms);
+    signal?.addEventListener("abort", finish, { once: true });
+    if (signal?.aborted) finish();
+  });
+}
+function withSubagentResponseRecovery(stream, backoffMs = 2e3) {
+  return async (model, context, options) => {
+    for (let attempt = 0; ; attempt++) {
+      if (options?.signal?.aborted) throw new Error("Subagent aborted by parent");
+      let message;
+      try {
+        const response = await stream(model, context, options);
+        let terminal;
+        const iterator = response[Symbol.asyncIterator]();
+        try {
+          while (true) {
+            const next = await iterator.next();
+            if (next.done) break;
+            if (next.value.type === "done") terminal = next.value.message;
+            if (next.value.type === "error") terminal = next.value.error;
+          }
+        } finally {
+          try {
+            await iterator.return?.();
+          } catch {
+          }
+        }
+        if (!terminal) throw new Error("Provider protocol error: response ended without a terminal event");
+        message = terminal;
+      } catch (error) {
+        if (!options?.signal?.aborted && attempt < 2 && isRetryableSubagentFailure(error instanceof Error ? error.message : String(error))) {
+          await cancellableBackoff(backoffMs * (attempt + 1), options?.signal);
+          continue;
+        }
+        throw error;
+      }
+      if (options?.signal?.aborted) throw new Error("Subagent aborted by parent");
+      if (message.stopReason === "error" && attempt < 2 && isRetryableSubagentFailure(message.errorMessage ?? "")) {
+        await cancellableBackoff(backoffMs * (attempt + 1), options?.signal);
+        continue;
+      }
+      const result = new AssistantMessageEventStream();
+      if (message.stopReason === "error" || message.stopReason === "aborted") {
+        result.push({ type: "error", reason: message.stopReason, error: { ...message, content: [] } });
+      } else {
+        result.push({ type: "done", reason: message.stopReason, message });
+      }
+      result.end();
+      return result;
+    }
+  };
+}
+
+// ../../packages/shared-headless-capabilities/src/subagent-sessions.ts
+var SUBAGENT_SESSION_RECORD_VERSION = 1;
+var DEFAULT_MAX_LIVE_SESSIONS = 8;
+var DEFAULT_SESSION_STORE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1e3;
+var DEFAULT_SESSION_STORE_MAX_RECORDS = 64;
+var SESSION_TRANSCRIPT_WARN_CHARS = 24e4;
+var SESSION_RECORD_MAX_CHARS = 4e6;
+function touchLiveSession(registry, id) {
+  const session = registry.get(id);
+  if (!session) return void 0;
+  registry.delete(id);
+  registry.set(id, session);
+  return session;
+}
+function retainLiveSession(registry, session, cap) {
+  registry.delete(session.id);
+  registry.set(session.id, session);
+  while (registry.size > Math.max(1, cap)) {
+    let evicted = false;
+    for (const [key, candidate] of registry) {
+      if (candidate.busy) continue;
+      registry.delete(key);
+      evicted = true;
+      break;
+    }
+    if (!evicted) {
+      break;
+    }
+  }
+}
+function toSessionRecord(session, messages) {
+  return {
+    version: SUBAGENT_SESSION_RECORD_VERSION,
+    id: session.id,
+    name: session.name,
+    mode: session.mode,
+    priority: session.priority,
+    originalTask: session.originalTask,
+    modelOverride: session.modelOverride,
+    thinkingLevel: session.thinkingLevel,
+    timeoutSeconds: session.timeoutSeconds,
+    createdAt: session.createdAt,
+    lastUsedAt: session.lastUsedAt,
+    runCount: session.runCount,
+    revision: session.revision,
+    messages
+  };
+}
+function estimateTranscriptChars(messages) {
+  let total = 0;
+  for (const message of messages) {
+    try {
+      total += JSON.stringify(message)?.length ?? 0;
+    } catch {
+      total += SESSION_TRANSCRIPT_WARN_CHARS;
+    }
+  }
+  return total;
+}
+function transplantMessages(target, messages) {
+  const mutable = target;
+  if (typeof mutable.replaceMessages === "function") {
+    mutable.replaceMessages(messages);
+  } else {
+    mutable.state.messages = messages;
+  }
+}
+
 // ../../packages/shared-headless-capabilities/src/bash-policy.ts
 var DESTRUCTIVE_PATTERNS = [
   { pattern: /\bgit\s+reset\s+--hard\b/, warning: "may discard uncommitted changes", commandClass: "git_destructive" },
@@ -1404,6 +1540,10 @@ function clipHeartbeatLabel(text, maxLength = 60) {
 function formatSkillsForPrompt(skills) {
   return formatSkillSummariesForPrompt(skills);
 }
+var SYNTHETIC_PROVIDER_TEXT_PREFIXES = ["[output truncated:", "[dropped "];
+function isSyntheticProviderText(text) {
+  return SYNTHETIC_PROVIDER_TEXT_PREFIXES.some((prefix) => text.startsWith(prefix));
+}
 function collectLastAssistantText(messages) {
   for (let i = messages.length - 1; i >= 0; i--) {
     const message = messages[i];
@@ -1411,17 +1551,29 @@ function collectLastAssistantText(messages) {
       continue;
     }
     if (Array.isArray(message.content)) {
-      const textContent = message.content.filter((content) => content?.type === "text" && typeof content.text === "string").map((content) => content.text).join("\n");
+      const realBlocks = message.content.filter((content) => content?.type === "text" && typeof content.text === "string").map((content) => content.text).filter((text) => !isSyntheticProviderText(text));
+      const textContent = realBlocks.join("\n");
       if (textContent.trim()) {
         return textContent;
       }
     }
-    if (typeof message.content === "string" && message.content.trim()) {
+    if (typeof message.content === "string" && message.content.trim() && !isSyntheticProviderText(message.content)) {
       return message.content;
     }
   }
   return "";
 }
+function visibleTextBlocks(message) {
+  if (!Array.isArray(message.content)) return [];
+  return message.content.filter((content) => content?.type === "text" && typeof content.text === "string").map((content) => content.text).filter((text) => text.trim().length > 0 && !isSyntheticProviderText(text));
+}
+function messageHasOwnText(message) {
+  if (!message) return false;
+  if (Array.isArray(message.content)) {
+    return visibleTextBlocks(message).length > 0;
+  }
+  return typeof message.content === "string" && message.content.trim().length > 0 && !isSyntheticProviderText(message.content);
+}
 function inferComplexity(task, priority) {
   const normalized = task.toLowerCase();
   if (priority === "thorough" || task.length > 600 || /\b(across|architecture|refactor|review|investigate|debug|failing|test|compare|multiple|race|root cause)\b/.test(normalized)) {
@@ -1539,9 +1691,31 @@ function buildSubagentPlan(deps, task, name, priority, timeoutSeconds, modelOver
 function subagentOutputBudget(model) {
   return Math.min(model.maxTokens || 8192, 16384);
 }
+function buildSubagentSystemPrompt(mode, skills) {
+  return `You are a specialized subagent focused on one bounded task.
+
+Task boundary:
+- Work only on the assigned task.
+- Use available tools to gather evidence before making claims.
+${mode === "edit" ? "- You may edit files and run tests using the inherited parent tools and permissions. This is a shared workspace, not an isolated sandbox. Preserve existing user changes. Do not commit or automatically roll back changes. Report changed files, tests actually run, and remaining work for parent review." : "- Do not edit files; if writing is needed, say what the parent agent should change."}
+- Return a concise answer with evidence and uncertainty.
+
+Output:
+- Answer
+- Evidence
+- Uncertainty: low, medium, or high
+- Parent follow-up needed, if any
+
+${formatSkillsForPrompt(skills ?? [])}`;
+}
 function createAgentInstance(deps, systemPrompt, tools, model, apiKey, thinkingLevel) {
+  const streamFn = withSubagentResponseRecovery((streamModel, context, options) => streamSimple(streamModel, context, {
+    ...options,
+    maxTokens: options?.maxTokens ?? subagentOutputBudget(streamModel)
+  }), deps.transientRetryBackoffMs);
   if (deps.createAgent) {
     return deps.createAgent({
+      streamFn,
       systemPrompt,
       model,
       tools,
@@ -1560,10 +1734,7 @@ function createAgentInstance(deps, systemPrompt, tools, model, apiKey, thinkingL
     // Subagent turns are single-purpose report generations: request an
     // explicit output budget (see subagentOutputBudget) instead of leaving
     // it to endpoint defaults that silently truncate long reports.
-    streamFn: (streamModel, context, options) => streamSimple(streamModel, context, {
-      ...options,
-      maxTokens: options?.maxTokens ?? subagentOutputBudget(streamModel)
-    })
+    streamFn
   });
 }
 function extractEvidenceFromToolArgs(toolName, args) {
@@ -1606,7 +1777,114 @@ function inferUncertainty(text, signals) {
 function isParentHandoffRequired(task) {
   return task.mode === "edit" || task.needsParentWrite || task.status === "timeout" || task.status === "failed" || task.confidenceSignals.some((signal) => signal.type === "tool_error" || signal.type === "no_tool_use" || signal.type === "no_text_report");
 }
-async function runSubagentWithProgress(deps, task, reportProgress, signal) {
+function shellFromRecord(record) {
+  return {
+    id: record.id,
+    name: record.name,
+    mode: record.mode,
+    priority: record.priority,
+    originalTask: record.originalTask,
+    modelOverride: record.modelOverride,
+    thinkingLevel: record.thinkingLevel,
+    timeoutSeconds: record.timeoutSeconds,
+    agent: null,
+    pendingMessages: record.messages,
+    createdAt: record.createdAt,
+    lastUsedAt: record.lastUsedAt,
+    runCount: record.runCount,
+    // The restored record IS our durable base line: its revision (0 for
+    // legacy records that predate the field) is both our current revision
+    // and our known-persisted revision.
+    revision: record.revision ?? 0,
+    persistedRevision: record.revision ?? 0,
+    busy: true
+  };
+}
+async function resolveRecallSession(deps, id, sessions, maxLiveSessions) {
+  let live = sessions ? touchLiveSession(sessions, id) : void 0;
+  if (live?.busy) throw new Error(`Subagent session "${id}" is busy with another task; wait for it to settle.`);
+  let record;
+  if (deps.sessionStore) {
+    try {
+      record = await deps.sessionStore.load(id);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      deps.debugLog?.("session", "session store load failed", { id, error: detail });
+      throw new Error(`Subagent session "${id}" could not be read from the session store (${detail}); refusing to recall without verifying session freshness. Retry the recall, or spawn a fresh task.`);
+    }
+  }
+  if (record && typeof record.version === "number" && record.version !== SUBAGENT_SESSION_RECORD_VERSION) {
+    throw new Error(`Subagent session "${id}" is persisted in record format version ${record.version}, which this build cannot read (supported: ${SUBAGENT_SESSION_RECORD_VERSION}); refusing to recall so the newer record is not overwritten. Use the matching Pie version, or spawn a fresh task.`);
+  }
+  if (record && (record.version !== SUBAGENT_SESSION_RECORD_VERSION || record.id !== id || !Array.isArray(record.messages))) {
+    record = void 0;
+  }
+  live = sessions ? touchLiveSession(sessions, id) : void 0;
+  if (live?.busy) throw new Error(`Subagent session "${id}" is busy with another task; wait for it to settle.`);
+  if (live) {
+    const liveTranscriptLength = live.agent?.state.messages.length ?? live.pendingMessages?.length ?? 0;
+    const recordIsNewer = record !== void 0 && (record.revision !== void 0 ? record.revision > live.revision : record.runCount > live.runCount || record.runCount === live.runCount && record.lastUsedAt > live.lastUsedAt || record.runCount === live.runCount && record.lastUsedAt === live.lastUsedAt && record.messages.length > liveTranscriptLength);
+    const forked = record?.revision !== void 0 && record.revision > (live.persistedRevision ?? 0) && live.revision > (live.persistedRevision ?? 0);
+    if (forked && record?.revision !== void 0) {
+      deps.debugLog?.("session", "live and durable sessions diverged after failed persistence", {
+        id,
+        liveRevision: live.revision,
+        persistedRevision: record.revision,
+        lastSharedRevision: live.persistedRevision
+      });
+      sessions?.delete(id);
+      throw new Error(`Subagent session "${id}" diverged across processes: this process holds unsaved work (revision ${live.revision}, last durable sync ${live.persistedRevision ?? 0}) while another process advanced the stored record (revision ${record.revision}). The diverged in-memory branch was discarded; recall again to continue from the last durable transcript, or spawn a fresh task.`);
+    }
+    if (recordIsNewer && record) {
+      deps.debugLog?.("session", "live session behind the durable record; adopting the persisted record", {
+        id,
+        liveMessages: liveTranscriptLength,
+        persistedMessages: record.messages.length,
+        liveRevision: live.revision,
+        persistedRevision: record.revision,
+        liveRunCount: live.runCount,
+        persistedRunCount: record.runCount,
+        liveLastUsedAt: live.lastUsedAt,
+        persistedLastUsedAt: record.lastUsedAt
+      });
+      const shell2 = shellFromRecord(record);
+      if (sessions) {
+        retainLiveSession(sessions, shell2, maxLiveSessions);
+      }
+      return { session: shell2, restored: true };
+    }
+    live.busy = true;
+    return { session: live, restored: false };
+  }
+  if (!record) return void 0;
+  const shell = shellFromRecord(record);
+  if (sessions) {
+    retainLiveSession(sessions, shell, maxLiveSessions);
+  }
+  return { session: shell, restored: true };
+}
+async function persistSubagentSession(deps, session, task) {
+  const messages = session.agent?.state.messages ?? session.pendingMessages ?? [];
+  const transcriptChars = estimateTranscriptChars(messages);
+  if (task.status === "completed" && task.result && transcriptChars > SESSION_TRANSCRIPT_WARN_CHARS) {
+    task.result += `
+
+[Session growth warning: session ${session.id} now carries ~${Math.round(transcriptChars / 4)} tokens of transcript; every recall pays for the whole history. For the next round, consider a fresh subagent with a compact brief instead of recalling.]`;
+  }
+  if (!deps.sessionStore) return;
+  if (transcriptChars > SESSION_RECORD_MAX_CHARS) {
+    deps.debugLog?.("session", "skipping session persist: transcript over the size cap", { id: session.id, transcriptChars });
+    return;
+  }
+  try {
+    const saved = await deps.sessionStore.save(toSessionRecord(session, messages));
+    task.sessionPersisted = saved === true;
+    if (saved === true) session.persistedRevision = session.revision;
+  } catch (error) {
+    deps.debugLog?.("session", "session persist failed", { id: session.id, error: error instanceof Error ? error.message : String(error) });
+  }
+}
+async function runSubagentWithProgress(deps, task, reportProgress, signal, sessions) {
   const startTime = Date.now();
   task.status = "running";
   let timedOut = false;
@@ -1620,6 +1898,11 @@ async function runSubagentWithProgress(deps, task, reportProgress, signal) {
   const heartbeatIntervalMs = deps.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
   deps.debugLog?.("run", "runSubagentWithProgress START", { taskName: task.name, yoloMode: deps.yoloMode });
   let heartbeat;
+  let session;
+  let runStarted = false;
+  let pendingRun;
+  let agentSettled = true;
+  let releaseLease;
   if (heartbeatIntervalMs > 0) {
     heartbeat = setInterval(() => {
       try {
@@ -1632,46 +1915,134 @@ async function runSubagentWithProgress(deps, task, reportProgress, signal) {
       }
     }, Math.max(50, Math.min(1e3, heartbeatIntervalMs / 2)));
   }
+  if (task.sessionId) task.wasRecall = true;
   try {
     report({ message: `[${task.name}] Starting...`, increment: 5 });
-    const { plan, tools, apiKey, model } = buildSubagentPlan(deps, task.task, task.name, task.priority, task.timeoutSeconds, task.modelOverride, task.thinkingLevel, task.mode);
-    task.plan = plan;
-    task.needsParentWrite = task.mode === "read" && needsParentWrite(task.task);
-    for (const excluded of plan.toolsExcluded) {
-      if (excluded.reason === "unclassified_tool") {
-        task.confidenceSignals.push({ type: "unclassified_tool", message: `${excluded.name} inherited without risk metadata` });
+    let subagent;
+    let baseline = 0;
+    let plan;
+    let runTimeoutSeconds = task.timeoutSeconds;
+    if (task.sessionId) {
+      if (sessions?.get(task.sessionId)?.busy) {
+        throw new Error(`Subagent session "${task.sessionId}" is busy with another task; wait for it to settle.`);
       }
+      releaseLease = await deps.sessionStore?.acquire?.(task.sessionId);
+      const resolved = await resolveRecallSession(deps, task.sessionId, sessions, Math.max(1, deps.maxLiveSessions ?? DEFAULT_MAX_LIVE_SESSIONS));
+      if (!resolved) {
+        throw new Error(`Unknown or expired subagent session "${task.sessionId}": it is neither live in this process nor in the session store (evicted, swept, or never persisted). Spawn a fresh task instead of recalling.`);
+      }
+      const owned = resolved.session;
+      session = owned;
+      if (task.requestedTimeoutSeconds !== void 0) {
+        session.timeoutSeconds = task.requestedTimeoutSeconds;
+      }
+      const nextMode = task.requestedMode ?? session.mode;
+      if (nextMode === "edit" && (task.batchSize ?? 1) > 1) {
+        throw new Error(`Recalling session "${session.id}" resolves to edit mode, and an edit delegation must contain exactly one task (the workspace is shared). Retry it alone.`);
+      }
+      const nextModelOverride = task.modelOverride ?? session.modelOverride;
+      const nextThinking = task.thinkingLevel ?? session.thinkingLevel;
+      const mustRebuild = session.agent === null || task.requestedMode !== void 0 || task.modelOverride !== void 0 || task.thinkingLevel !== void 0;
+      if (!mustRebuild) {
+        subagent = session.agent;
+        baseline = subagent.state.messages.length;
+      } else {
+        let built = buildSubagentPlan(deps, session.originalTask, session.name, session.priority, session.timeoutSeconds, nextModelOverride, nextThinking, nextMode);
+        let effectiveOverride = nextModelOverride;
+        if (task.modelOverride && !built.plan.modelOverrideApplied && session.modelOverride && session.modelOverride !== task.modelOverride) {
+          const missReason = built.plan.modelFallbackReason ?? `model override "${task.modelOverride}" could not be resolved`;
+          built = buildSubagentPlan(deps, session.originalTask, session.name, session.priority, session.timeoutSeconds, session.modelOverride, nextThinking, nextMode);
+          built.plan.modelFallbackReason = built.plan.modelFallbackReason ? `${missReason}; ${built.plan.modelFallbackReason}` : missReason;
+          effectiveOverride = session.modelOverride;
+        }
+        plan = built.plan;
+        task.plan = plan;
+        for (const excluded of plan.toolsExcluded) {
+          if (excluded.reason === "unclassified_tool") {
+            task.confidenceSignals.push({ type: "unclassified_tool", message: `${excluded.name} inherited without risk metadata` });
+          }
+        }
+        if (plan.modelFallbackReason) {
+          task.confidenceSignals.push({ type: "model_fallback", message: plan.modelFallbackReason });
+        }
+        if (!built.apiKey) {
+          throw new Error("No API key available for subagent execution.");
+        }
+        if (!built.model) {
+          throw new Error("No model configured for subagent execution.");
+        }
+        const priorMessages = session.agent ? session.agent.state.messages : session.pendingMessages ?? [];
+        const rebuilt = createAgentInstance(deps, buildSubagentSystemPrompt(nextMode, deps.skills), built.tools, built.model, built.apiKey, plan.thinkingLevel);
+        transplantMessages(rebuilt, priorMessages);
+        baseline = priorMessages.length;
+        subagent = rebuilt;
+        session.agent = subagent;
+        session.pendingMessages = void 0;
+        session.mode = nextMode;
+        session.modelOverride = effectiveOverride;
+        session.thinkingLevel = plan.thinkingLevel;
+      }
+      if (plan) {
+        runTimeoutSeconds = plan.timeoutSeconds;
+      } else {
+        runTimeoutSeconds = session.timeoutSeconds;
+      }
+      task.mode = session.mode;
+      task.needsParentWrite = task.mode === "read" && needsParentWrite(task.task);
+      deps.log(`[Subagent ${task.name}] Recalling session ${session.id} (run ${session.runCount + 1}, mode=${session.mode}${resolved.restored ? ", restored from disk" : ""}${mustRebuild ? ", reconfigured" : ""})`);
+    } else {
+      const built = buildSubagentPlan(deps, task.task, task.name, task.priority, task.timeoutSeconds, task.modelOverride, task.thinkingLevel, task.mode);
+      plan = built.plan;
+      task.plan = plan;
+      const { tools, apiKey, model } = built;
+      task.needsParentWrite = task.mode === "read" && needsParentWrite(task.task);
+      for (const excluded of plan.toolsExcluded) {
+        if (excluded.reason === "unclassified_tool") {
+          task.confidenceSignals.push({ type: "unclassified_tool", message: `${excluded.name} inherited without risk metadata` });
+        }
+      }
+      if (plan.modelFallbackReason) {
+        task.confidenceSignals.push({ type: "model_fallback", message: plan.modelFallbackReason });
+      }
+      if (!apiKey) {
+        throw new Error("No API key available for subagent execution.");
+      }
+      if (!model) {
+        throw new Error("No model configured for subagent execution.");
+      }
+      if (signal?.aborted) {
+        throw new Error("Subagent aborted by parent");
+      }
+      deps.log(`[Subagent ${task.name}] Plan: ${plan.complexity}/${plan.modelClass}${plan.modelOverride ? `, model=${plan.modelOverrideApplied ? plan.modelOverride : "override failed"}` : ""}, ${tools.length} tools`);
+      deps.debugLog?.("plan", "SubagentPlan", plan);
+      subagent = createAgentInstance(deps, buildSubagentSystemPrompt(task.mode, deps.skills), tools, model, apiKey, plan.thinkingLevel);
+      session = {
+        id: task.id,
+        name: task.name,
+        mode: task.mode,
+        priority: task.priority,
+        originalTask: task.task,
+        modelOverride: task.modelOverride,
+        thinkingLevel: plan.thinkingLevel,
+        timeoutSeconds: task.timeoutSeconds,
+        agent: subagent,
+        createdAt: Date.now(),
+        lastUsedAt: Date.now(),
+        runCount: 0,
+        revision: 0,
+        busy: true
+      };
+      task.sessionId = session.id;
     }
-    if (plan.modelFallbackReason) {
-      task.confidenceSignals.push({ type: "model_fallback", message: plan.modelFallbackReason });
-    }
-    if (!apiKey) {
-      throw new Error("No API key available for subagent execution.");
-    }
-    if (!model) {
-      throw new Error("No model configured for subagent execution.");
-    }
-    if (signal?.aborted) {
-      throw new Error("Subagent aborted by parent");
+    if (!task.wasRecall) {
+      try {
+        releaseLease = await deps.sessionStore?.acquire?.(session.id);
+      } catch (error) {
+        session = void 0;
+        throw error;
+      }
     }
-    deps.log(`[Subagent ${task.name}] Plan: ${plan.complexity}/${plan.modelClass}${plan.modelOverride ? `, model=${plan.modelOverrideApplied ? plan.modelOverride : "override failed"}` : ""}, ${tools.length} tools`);
-    deps.debugLog?.("plan", "SubagentPlan", plan);
-    const systemPrompt = `You are a specialized subagent focused on one bounded task.
-
-Task boundary:
-- Work only on the assigned task.
-- Use available tools to gather evidence before making claims.
-${task.mode === "edit" ? "- You may edit files and run tests using the inherited parent tools and permissions. This is a shared workspace, not an isolated sandbox. Preserve existing user changes. Do not commit or automatically roll back changes. Report changed files, tests actually run, and remaining work for parent review." : "- Do not edit files; if writing is needed, say what the parent agent should change."}
-- Return a concise answer with evidence and uncertainty.
-
-Output:
-- Answer
-- Evidence
-- Uncertainty: low, medium, or high
-- Parent follow-up needed, if any
-
-${formatSkillsForPrompt(deps.skills ?? [])}`;
-    const subagent = createAgentInstance(deps, systemPrompt, tools, model, apiKey, plan.thinkingLevel);
+    if (sessions) retainLiveSession(sessions, session, Math.max(1, deps.maxLiveSessions ?? DEFAULT_MAX_LIVE_SESSIONS));
     let assistantTurns = 0;
     let toolCalls = 0;
     let rejectTimeout = () => void 0;
@@ -1683,10 +2054,10 @@ ${formatSkillsForPrompt(deps.skills ?? [])}`;
     });
     timeout = setTimeout(() => {
       timedOut = true;
-      const timeoutMessage = `Subagent timed out after ${plan.timeoutSeconds} seconds`;
+      const timeoutMessage = `Subagent timed out after ${runTimeoutSeconds} seconds`;
       subagent.abort?.();
       rejectTimeout(new Error(timeoutMessage));
-    }, plan.timeoutSeconds * 1e3);
+    }, runTimeoutSeconds * 1e3);
     const abortPromise = new Promise((_, reject) => {
       if (!signal) return;
       const abortSubagent = () => {
@@ -1723,17 +2094,33 @@ ${formatSkillsForPrompt(deps.skills ?? [])}`;
       }
     });
     let prompt = task.task;
+    if (task.wasRecall && session) {
+      prompt = `This task CONTINUES subagent session "${session.name}" (${session.id}); your earlier transcript is retained. Build on it instead of redoing completed investigation, and re-verify anything the workspace may have changed since your last run.
+
+New instruction:
+${task.task}`;
+    }
     if (task.mode === "read") {
       prompt += "\n\nThis delegation is read mode. Do not write files. If changes are needed, describe them for the parent.";
     }
     prompt += "\n\nReturn evidence for your conclusion and state uncertainty as low, medium, or high.";
-    report({ message: `[${task.name}] Running plan ${plan.complexity}/${plan.modelClass}...`, increment: 20 });
+    const runLabel = plan ? `plan ${plan.complexity}/${plan.modelClass}` : `session ${session?.id ?? ""} (run ${(session?.runCount ?? 0) + 1})`;
+    report({ message: `[${task.name}] Running ${runLabel}...`, increment: 20 });
+    runStarted = true;
+    agentSettled = false;
+    const runPromise = (async () => {
+      try {
+        await subagent.prompt(prompt);
+        await subagent.waitForIdle?.();
+      } finally {
+        agentSettled = true;
+      }
+    })();
+    const settledRun = runPromise.catch(() => void 0);
+    pendingRun = settledRun;
     try {
       await Promise.race([
-        (async () => {
-          await subagent.prompt(prompt);
-          await subagent.waitForIdle?.();
-        })(),
+        runPromise,
         timeoutPromise,
         abortPromise
       ]);
@@ -1743,17 +2130,30 @@ ${formatSkillsForPrompt(deps.skills ?? [])}`;
       }
       removeAbortListener?.();
       unsubscribe?.();
+      if (!agentSettled) {
+        const graceMs = deps.sessionSettleGraceMs ?? 2e3;
+        if (graceMs > 0) {
+          await Promise.race([
+            settledRun,
+            new Promise((resolve3) => setTimeout(resolve3, graceMs))
+          ]);
+        }
+      }
     }
-    const messages = subagent.state.messages;
-    deps.log(`[Subagent ${task.name}] Total messages: ${messages.length}`);
+    const allMessages = subagent.state.messages;
+    const messages = allMessages.slice(baseline);
+    deps.log(`[Subagent ${task.name}] Total messages: ${allMessages.length} (${messages.length} new)`);
     const lastAssistant = [...messages].reverse().find((m) => m?.role === "assistant");
     const terminalStopReason = lastAssistant?.stopReason;
     const terminalError = typeof lastAssistant?.errorMessage === "string" ? lastAssistant.errorMessage : void 0;
     const collectedResponse = collectLastAssistantText(messages) || void 0;
-    const streamInterrupted = terminalStopReason === "error" || terminalStopReason === "aborted" || terminalError || !collectedResponse && terminalStopReason !== "stop";
+    const streamInterrupted = terminalStopReason === "error" || terminalStopReason === "aborted" || terminalError || !collectedResponse && terminalStopReason !== "stop" || terminalStopReason === "length" && !messageHasOwnText(lastAssistant);
     if (streamInterrupted) {
+      if (terminalStopReason === "length") {
+        throw new Error(`Subagent output token limit reached (stopReason=length): the provider cut the final response before the report was produced${collectedResponse ? " (earlier-turn narration discarded)" : ", no text response"}. The output/thinking budget was too small for this task at its reasoning level. Rerun with a narrower task or a lower thinkingLevel.`);
+      }
       const detail = terminalError ? `: ${terminalError.slice(0, 200)}` : "";
-      throw new Error(`Subagent stream interrupted (SSE stream aborted before the report was produced, stopReason=${terminalStopReason ?? "none"}${collectedResponse ? ", partial transcript discarded" : ", no text response"})${detail}`);
+      throw new Error(`Subagent response failed (provider/transport failure before the report was produced, stopReason=${terminalStopReason ?? "none"}${collectedResponse ? ", partial transcript discarded" : ", no text response"})${detail}`);
     }
     let response = collectedResponse ?? "[No textual report: the subagent finished normally (stopReason=stop) but produced no text \u2014 every assistant message was tool calls only. Review the task's effects directly, or rerun it with an explicit instruction to summarize findings.]";
     if (!collectedResponse) {
@@ -1802,6 +2202,29 @@ ${formatSkillsForPrompt(deps.skills ?? [])}`;
     if (heartbeat) {
       clearInterval(heartbeat);
     }
+    const finalize = async () => {
+      try {
+        if (session) {
+          if (runStarted) session.runCount++;
+          session.lastUsedAt = Date.now();
+          session.revision++;
+          task.sessionRunCount = session.runCount;
+          await persistSubagentSession(deps, session, task);
+        }
+      } finally {
+        await releaseLease?.();
+        if (session) {
+          session.busy = false;
+          if (sessions) retainLiveSession(sessions, session, Math.max(1, deps.maxLiveSessions ?? DEFAULT_MAX_LIVE_SESSIONS));
+        }
+      }
+    };
+    if (!agentSettled && pendingRun) {
+      task.sessionBusy = true;
+      void pendingRun.then(finalize).catch((error) => deps.debugLog?.("session", "late session cleanup failed", { error: String(error) }));
+    } else {
+      await finalize();
+    }
   }
 }
 function buildParallelResult(tasks, totalDuration) {
@@ -1838,6 +2261,12 @@ function buildParallelResult(tasks, totalDuration) {
       resultText += `Evidence: ${task.evidence.slice(0, 5).map((entry) => `${entry.type}:${entry.value}`).join("; ")}
 `;
     }
+    if (task.sessionId) {
+      resultText += task.sessionBusy ? `Session: ${task.sessionId} (busy \u2014 previous run is still settling; recall will fail until it settles` : `Session: ${task.sessionId} (resumable \u2014 pass as "sessionId" in a later spawn to continue this subagent with its accumulated context`;
+      if (task.sessionRunCount) resultText += `; run ${task.sessionRunCount}`;
+      if (task.sessionPersisted) resultText += "; persisted to disk, survives restarts";
+      resultText += ")\n";
+    }
     if (task.mode === "edit") {
       resultText += "Parent follow-up: review changes and validate reported tests. Partial edits are preserved on failure; no automatic rollback or task retry.\n";
     } else if (task.needsParentWrite) {
@@ -1862,7 +2291,8 @@ function normalizeTaskDefs(args) {
     return { error: "Invalid spawn_subagents_parallel arguments: tasks must be a non-empty array." };
   }
   const normalized = [];
-  const allowedFields = [...TASK_FIELD_ALIASES, "name", "priority", "timeout", "model", "thinkingLevel", "mode"];
+  const allowedFields = [...TASK_FIELD_ALIASES, "name", "priority", "timeout", "model", "thinkingLevel", "mode", "sessionId"];
+  const seenSessionIds = /* @__PURE__ */ new Set();
   for (const [index, def] of taskDefs.entries()) {
     if (!def || typeof def !== "object") {
       return { error: `Invalid task #${index + 1}: expected an object with the objective in "task" (aliases "description"/"prompt"/"objective" accepted).` };
@@ -1895,6 +2325,16 @@ function normalizeTaskDefs(args) {
     if (def.thinkingLevel !== void 0 && (typeof def.thinkingLevel !== "string" || !SUBAGENT_THINKING_LEVELS.includes(def.thinkingLevel))) {
       return { error: `Invalid task #${index + 1}: "thinkingLevel" must be one of ${SUBAGENT_THINKING_LEVELS.map((level) => `"${level}"`).join(", ")}.` };
     }
+    const sessionId = typeof def.sessionId === "string" && def.sessionId.trim() ? def.sessionId.trim() : void 0;
+    if (def.sessionId !== void 0 && !sessionId) {
+      return { error: `Invalid task #${index + 1}: "sessionId" must be a non-empty session id from an earlier result's Session line.` };
+    }
+    if (sessionId) {
+      if (seenSessionIds.has(sessionId)) {
+        return { error: `Invalid task #${index + 1}: duplicate "sessionId" "${sessionId}" \u2014 recalls to the same session must run in separate calls.` };
+      }
+      seenSessionIds.add(sessionId);
+    }
     normalized.push({
       name: typeof def.name === "string" && def.name.trim() ? def.name.trim() : void 0,
       task,
@@ -1902,7 +2342,10 @@ function normalizeTaskDefs(args) {
       mode: def.mode ?? "read",
       timeoutSeconds,
       modelOverride,
-      thinkingLevel: def.thinkingLevel
+      thinkingLevel: def.thinkingLevel,
+      sessionId,
+      requestedMode: def.mode,
+      requestedTimeoutSeconds: "timeout" in def ? timeoutSeconds : void 0
     });
   }
   if (normalized.length !== 1 && normalized.some((task) => task.mode === "edit")) {
@@ -1911,25 +2354,7 @@ function normalizeTaskDefs(args) {
   return normalized;
 }
 var DEFAULT_MAX_CONCURRENT_SUBAGENTS = 4;
-var MAX_TRANSIENT_RETRIES = 2;
-var TRANSIENT_RETRY_BACKOFF_MS = 2e3;
-var TRANSIENT_ERROR_PATTERN = /econnreset|econnaborted|etimedout|timeout|enotfound|eai_again|econnrefused|socket hang up|sse stream aborted|fetch failed|status 5\d\d|bad gateway|service unavailable|overloaded/i;
-function isTransientNetworkError(message) {
-  return TRANSIENT_ERROR_PATTERN.test(message);
-}
-function sleep(ms, signal) {
-  return new Promise((resolve3) => {
-    const timer = setTimeout(resolve3, ms);
-    signal?.addEventListener(
-      "abort",
-      () => {
-        clearTimeout(timer);
-        resolve3();
-      },
-      { once: true }
-    );
-  });
-}
+var taskIdCounter = 0;
 async function runWithConcurrencyLimit(jobs, limit) {
   let next = 0;
   const workers = Array.from({ length: Math.max(1, Math.min(limit, jobs.length)) }, async () => {
@@ -1941,6 +2366,13 @@ async function runWithConcurrencyLimit(jobs, limit) {
   await Promise.all(workers);
 }
 function createSubagentCapability(deps) {
+  const liveSessions = /* @__PURE__ */ new Map();
+  if (deps.sessionStore?.sweep) {
+    try {
+      void Promise.resolve(deps.sessionStore.sweep({ maxAgeMs: DEFAULT_SESSION_STORE_MAX_AGE_MS, maxRecords: DEFAULT_SESSION_STORE_MAX_RECORDS })).catch(() => void 0);
+    } catch {
+    }
+  }
   const spawnParallelTool = {
     name: "spawn_subagents_parallel",
     label: "Spawn Subagents",
@@ -1953,7 +2385,9 @@ Arguments shape (each tasks[] item puts the objective in "task" \u2014 "descript
 
 "model" overrides the automatic model-class selection for that task when the user explicitly asks for a specific model (e.g. "anthropic/claude-..."). Prefer "provider/model-id"; a bare model id works only when it is unambiguous across providers. When the override cannot be resolved, the task falls back to automatic selection and reports why.
 
-"thinkingLevel" defaults to "medium"; set it only when the user asks (e.g. "xhigh" for deep review) or for cheap lookup tasks ("off"). Non-reasoning models ignore it.`,
+"thinkingLevel" defaults to "medium"; set it only when the user asks (e.g. "xhigh" for deep review) or for cheap lookup tasks ("off"). Non-reasoning models ignore it.
+
+Sessions: every task that starts execution returns a Session id (persisted to disk when the host supports it). Pass "sessionId" in a later call to continue that subagent with its accumulated context \u2014 cheaper than re-briefing a fresh agent for iterative work on the same area. A recall may override "mode" (including upgrading read\u2192edit), "model", and "thinkingLevel": the session is reconfigured with freshly resolved tools and credentials. Recalls never replay on failure, and a session runs one task at a time. Prefer a FRESH task for independent reviews \u2014 accumulated context anchors judgment, and each recall carries the whole transcript.`,
     parameters: Type.Object({
       tasks: Type.Array(
         Type.Object(
@@ -1967,9 +2401,10 @@ Arguments shape (each tasks[] item puts the objective in "task" \u2014 "descript
             priority: Type.Optional(Type.Union([Type.Literal("fast"), Type.Literal("thorough")], { description: "fast uses lower-cost defaults; thorough raises model class when needed." })),
             model: Type.Optional(Type.String({ description: 'Explicit model override for this task, e.g. "provider/model-id". Only set when the user explicitly requests a specific model; otherwise Pie picks the model class automatically.' })),
             thinkingLevel: Type.Optional(Type.Union([Type.Literal("off"), Type.Literal("minimal"), Type.Literal("low"), Type.Literal("medium"), Type.Literal("high"), Type.Literal("xhigh")], { description: `Reasoning level for this task. Default: "medium". Only override when the user asks (e.g. "xhigh" for deep review tasks, "off" for cheap lookups). Ignored by non-reasoning models.` })),
-            timeout: Type.Optional(Type.Number({ description: "Timeout in seconds. Default: 1200s (20 minutes). For longer tasks, explicitly set a higher value, e.g. 3600." }))
+            timeout: Type.Optional(Type.Number({ description: "Timeout in seconds. Default: 1200s (20 minutes). For longer tasks, explicitly set a higher value, e.g. 3600." })),
+            sessionId: Type.Optional(Type.String({ description: "Resume a previous subagent session by id (from an earlier result's Session line). The session's accumulated transcript is reused \u2014 cheaper for iterative work on the same area. Optional mode/model/thinkingLevel on a recall RECONFIGURE the session with freshly resolved tools and credentials (read sessions may be upgraded to edit). Recalls never replay on failure and must target an idle session." }))
           },
-          { additionalProperties: false, description: "Objective goes in 'task' (or an accepted alias); plus optional name/priority/model/thinkingLevel/timeout." }
+          { additionalProperties: false, description: "Objective goes in 'task' (or an accepted alias); plus optional name/priority/model/thinkingLevel/timeout/sessionId." }
         ),
         { description: "Array of tasks to run in parallel; at least one of task/description/prompt/objective must be a non-empty string per item.", minItems: 1, maxItems: 10 }
       )
@@ -1996,7 +2431,9 @@ Arguments shape (each tasks[] item puts the objective in "task" \u2014 "descript
         };
       }
       const tasks = normalized.map((def, index) => ({
-        id: `subagent-${Date.now()}-${index}`,
+        // Date.now()+index alone collides when two spawn calls land in the
+        // same millisecond (ids double as session ids and store filenames).
+        id: `subagent-${Date.now().toString(36)}-${(++taskIdCounter).toString(36)}${Math.random().toString(36).slice(2, 6)}-${index}`,
         name: def.name || `Task-${index + 1}`,
         status: "pending",
         task: def.task,
@@ -2005,6 +2442,10 @@ Arguments shape (each tasks[] item puts the objective in "task" \u2014 "descript
         timeoutSeconds: def.timeoutSeconds,
         modelOverride: def.modelOverride,
         thinkingLevel: def.thinkingLevel,
+        sessionId: def.sessionId,
+        requestedMode: def.requestedMode,
+        requestedTimeoutSeconds: def.requestedTimeoutSeconds,
+        batchSize: normalized.length,
         evidence: [],
         confidenceSignals: [],
         uncertainty: "medium",
@@ -2018,24 +2459,26 @@ Arguments shape (each tasks[] item puts the objective in "task" \u2014 "descript
       toolContext.reportProgress?.({ message: `Launching ${tasks.length} parallel subagents...`, increment: 5 });
       const startTime = Date.now();
       const runTask = async (task) => {
-        for (let attempt = 0; ; attempt++) {
-          await runSubagentWithProgress(deps, task, toolContext.reportProgress, signal);
-          const canRetry = task.mode === "read" && task.status === "failed" && isTransientNetworkError(task.error ?? "") && attempt < MAX_TRANSIENT_RETRIES && !signal?.aborted;
-          if (!canRetry) return;
-          const failureReason = task.error ?? "unknown";
-          task.evidence.length = 0;
-          task.runtimeEvidence.length = 0;
-          task.reportedEvidence.length = 0;
-          task.confidenceSignals.length = 0;
-          task.status = "pending";
-          task.error = void 0;
-          task.completedAt = void 0;
-          const backoffMs = (deps.transientRetryBackoffMs ?? TRANSIENT_RETRY_BACKOFF_MS) * (attempt + 1);
-          toolContext.reportProgress?.({ message: `[${task.name}] Transient error, retrying in ${Math.round(backoffMs / 1e3)}s (attempt ${attempt + 2}/${MAX_TRANSIENT_RETRIES + 1})...` });
-          deps.log(`[subagent] ${task.name} failed with a transient error (${failureReason}); retrying`);
-          await sleep(backoffMs, signal);
-          if (signal?.aborted) return;
-        }
+        await runSubagentWithProgress(deps, task, toolContext.reportProgress, signal, liveSessions);
+        if (task.wasRecall || task.mode !== "read" || task.status !== "failed" || !task.error) return;
+        if (signal?.aborted) return;
+        if (!isRetryableSubagentFailure(task.error)) return;
+        const settleMs = Math.max(0, (deps.transientRetryBackoffMs ?? 2e3) * 10);
+        toolContext.reportProgress?.({ message: `[${task.name}] Provider/transport failure \u2014 replaying the read task once after ${Math.round(settleMs / 1e3)}s`, increment: 0 });
+        await cancellableBackoff(settleMs, signal);
+        if (signal?.aborted) return;
+        task.evidence = [];
+        task.confidenceSignals = [];
+        task.runtimeEvidence = [];
+        task.reportedEvidence = [];
+        task.error = void 0;
+        task.result = void 0;
+        task.details = void 0;
+        task.parentHandoffRequired = false;
+        task.sessionId = void 0;
+        task.requestedMode = void 0;
+        task.wasRecall = void 0;
+        await runSubagentWithProgress(deps, task, toolContext.reportProgress, signal, liveSessions);
       };
       await runWithConcurrencyLimit(
         tasks.map((task) => () => runTask(task)),
@@ -2053,6 +2496,9 @@ Arguments shape (each tasks[] item puts the objective in "task" \u2014 "descript
             name: task.name,
             status: task.status,
             mode: task.mode,
+            sessionId: task.sessionId,
+            sessionRunCount: task.sessionRunCount,
+            sessionPersisted: task.sessionPersisted,
             task: task.task,
             timeoutSeconds: task.timeoutSeconds,
             plan: task.plan,
@@ -4987,6 +5433,163 @@ function createSessionManager(options) {
   return new SessionManager(options);
 }
 
+// ../../packages/agent-framework/src/observer.ts
+function notifyObserver(listener, event) {
+  try {
+    void Promise.resolve(listener(event)).catch(() => {
+    });
+  } catch {
+  }
+}
+
+// ../../packages/agent-framework/src/session/controller/end-hook.ts
+async function runEndHook(hook, context, isCurrent, emit) {
+  if (!hook) return;
+  emit({ type: "agent_end_hook_start", hasQueuedMessages: context.hasQueuedMessages });
+  try {
+    await hook(context);
+    if (isCurrent()) emit({ type: "agent_end_hook_end" });
+  } catch (error) {
+    if (isCurrent()) emit({ type: "agent_end_hook_end", errorMessage: error instanceof Error ? error.message : String(error) });
+  }
+}
+
+// ../../packages/agent-framework/src/session/controller/convergence.ts
+var SessionConvergence = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  generation = 0;
+  active = false;
+  disposed = false;
+  operations = /* @__PURE__ */ new Set();
+  outcome;
+  monitoring = /* @__PURE__ */ new Set();
+  invalidated;
+  invalidation = new Promise((resolve3) => {
+    this.invalidated = resolve3;
+  });
+  get identity() {
+    return { sessionId: this.options.sessionId(), generation: this.generation };
+  }
+  begin() {
+    if (this.disposed || this.active) return;
+    this.active = true;
+    this.outcome = void 0;
+    this.generation++;
+    notifyObserver(this.options.emit, { type: "session_work_started", ...this.identity });
+  }
+  invalidate(reason) {
+    if (this.disposed) return;
+    if (reason === "dispose") this.disposed = true;
+    this.invalidated();
+    this.invalidation = new Promise((resolve3) => {
+      this.invalidated = resolve3;
+    });
+    this.generation++;
+    this.active = false;
+    this.operations.clear();
+    notifyObserver(this.options.emit, { type: "session_invalidated", ...this.identity, reason });
+  }
+  run(action) {
+    if (this.disposed) return Promise.reject(new Error("Controller disposed"));
+    const wasActive = this.active;
+    const preBeginGeneration = this.generation;
+    this.begin();
+    if (this.disposed) return Promise.reject(new Error("Controller disposed"));
+    if (!wasActive && (!this.active || this.generation !== preBeginGeneration + 1)) {
+      return Promise.resolve();
+    }
+    const generation = this.generation;
+    let resolve3;
+    let reject;
+    const operation = new Promise((yes, no) => {
+      resolve3 = yes;
+      reject = no;
+    });
+    this.operations.add(operation);
+    try {
+      resolve3(action());
+    } catch (error) {
+      reject(error);
+    }
+    void operation.catch(() => {
+      if (generation === this.generation) this.outcome = "failed";
+    }).finally(() => {
+      this.operations.delete(operation);
+      this.check();
+    });
+    this.check();
+    return operation;
+  }
+  observe(event) {
+    if (event.type === "agent_event" && event.event.type === "agent_start") this.begin();
+    if (event.type === "turn_failed_terminal" || event.type === "turn_policy_error" || event.type === "agent_end_hook_end" && event.errorMessage) this.outcome = "failed";
+    if (event.type === "turn_cancelled") this.outcome = "cancelled";
+    this.check();
+  }
+  async wait() {
+    const generation = this.generation;
+    const invalidation = this.invalidation;
+    while (generation === this.generation && !this.disposed) {
+      await Promise.race([Promise.allSettled([...this.operations]), invalidation]);
+      if (generation !== this.generation || this.disposed) return;
+      await Promise.race([this.options.wait(), invalidation]);
+      if (generation !== this.generation || this.disposed) return;
+      if (!this.operations.size && !this.options.busy()) return;
+    }
+  }
+  check() {
+    const generation = this.generation;
+    if (!this.active || this.disposed || this.monitoring.has(generation)) return;
+    this.monitoring.add(generation);
+    void this.wait().then(() => {
+      if (generation !== this.generation || !this.active || this.disposed) return;
+      this.active = false;
+      notifyObserver(this.options.emit, {
+        type: "session_quiescent",
+        ...this.identity,
+        outcome: this.outcome ?? (this.options.queued() ? "blocked" : "success")
+      });
+    }).catch(() => {
+      if (generation !== this.generation || !this.active || this.disposed) return;
+      this.active = false;
+      notifyObserver(this.options.emit, { type: "session_quiescent", ...this.identity, outcome: "failed" });
+    }).finally(() => this.monitoring.delete(generation));
+  }
+};
+
+// ../../packages/agent-framework/src/session/controller/pending-operations.ts
+var PendingEndOperations = class {
+  operations = /* @__PURE__ */ new Set();
+  get pending() {
+    return this.operations.size > 0;
+  }
+  clear() {
+    this.operations.clear();
+  }
+  async wait() {
+    await Promise.allSettled([...this.operations]);
+  }
+  track(action) {
+    let resolve3;
+    let reject;
+    const operation = new Promise((yes, no) => {
+      resolve3 = yes;
+      reject = no;
+    });
+    this.operations.add(operation);
+    void operation.finally(() => this.operations.delete(operation)).catch(() => {
+    });
+    try {
+      resolve3(action());
+    } catch (error) {
+      reject(error);
+    }
+  }
+};
+
 // ../../packages/agent-framework/src/session/controller/auto-compact-policy.ts
 function defaultSetTimeout(callback, delay) {
   return setTimeout(callback, delay);
@@ -5086,6 +5689,8 @@ var AgentSessionAutoContinueController = class {
   }
   options;
   autoContinueTimer;
+  generation = 0;
+  cancelExecutionWait;
   pendingAutoContinue;
   resolvePendingAutoContinue;
   get hasPendingAutoContinue() {
@@ -5101,21 +5706,30 @@ var AgentSessionAutoContinueController = class {
     this.ensurePending();
     const setTimer = this.options.retry?.setTimeout ?? defaultSetTimeout2;
     const snapshot = messages.slice();
+    const generation = this.generation;
     this.autoContinueTimer = setTimer(() => {
       this.autoContinueTimer = void 0;
-      void this.maybeScheduleAutoContinue(snapshot).finally(() => this.resolvePending());
+      void this.maybeScheduleAutoContinue(snapshot, generation).catch((error) => {
+        if (generation === this.generation && !this.options.getDisposed()) {
+          this.options.emit({ type: "turn_policy_error", message: error instanceof Error ? error.message : String(error) });
+        }
+      }).finally(() => {
+        if (generation === this.generation && this.autoContinueTimer === void 0) this.resolvePending();
+      });
     }, 0);
   }
   cancel() {
-    if (this.autoContinueTimer === void 0) {
-      return;
+    this.generation++;
+    if (this.autoContinueTimer !== void 0) {
+      const clearTimer = this.options.retry?.clearTimeout ?? defaultClearTimeout2;
+      clearTimer(this.autoContinueTimer);
+      this.autoContinueTimer = void 0;
     }
-    const clearTimer = this.options.retry?.clearTimeout ?? defaultClearTimeout2;
-    clearTimer(this.autoContinueTimer);
-    this.autoContinueTimer = void 0;
+    this.cancelExecutionWait?.();
+    this.cancelExecutionWait = void 0;
     this.resolvePending();
   }
-  async maybeScheduleAutoContinue(messages) {
+  async maybeScheduleAutoContinue(messages, generation) {
     if (!this.options.getAutoContinueMessage || this.options.getDisposed() || this.options.getRuntimeGuardTriggered() || this.options.isBlockedByRuntimePolicy() || this.options.hasQueuedMessages() || this.options.isStreaming()) {
       if (this.options.hasQueuedMessages()) {
         this.options.emit({ type: "auto_continue_skipped", reason: "queued_messages" });
@@ -5134,6 +5748,7 @@ var AgentSessionAutoContinueController = class {
       messages,
       hasQueuedMessages: this.options.hasQueuedMessages()
     });
+    if (generation !== this.generation || this.options.getDisposed() || this.options.getRuntimeGuardTriggered()) return;
     const message = result && "role" in result ? result : result?.message;
     const reason = result && "role" in result ? void 0 : result?.reason;
     if (!message) {
@@ -5148,9 +5763,11 @@ var AgentSessionAutoContinueController = class {
     this.options.agent.followUp(message);
     const setTimer = this.options.retry?.setTimeout ?? defaultSetTimeout2;
     await new Promise((resolve3) => {
+      this.cancelExecutionWait = resolve3;
       this.autoContinueTimer = setTimer(() => {
         this.autoContinueTimer = void 0;
-        if (this.options.getDisposed()) {
+        this.cancelExecutionWait = void 0;
+        if (generation !== this.generation || this.options.getDisposed()) {
           resolve3();
           return;
         }
@@ -5203,7 +5820,7 @@ async function runAgentSessionCompaction(params) {
     throw new Error("No compaction handler configured");
   }
   const abortedResult = () => ({ aborted: true });
-  const isAborted = () => params.signal?.aborted === true;
+  const isAborted = () => params.signal?.aborted === true || params.isCurrent?.() === false;
   params.emit({ type: "auto_compaction_start", reason: params.reason, willRetry: params.willRetry });
   try {
     if (isAborted()) {
@@ -5344,7 +5961,7 @@ async function runPreRequestAutoCompact(params) {
   try {
     await params.runAutoCompact();
   } catch {
-    params.setRecoveryState("none");
+    if (params.isCurrent?.() !== false) params.setRecoveryState("none");
   }
 }
 
@@ -5518,6 +6135,7 @@ var AgentSessionQueueDispatcher = class {
   }
   options;
   dispatchTimer;
+  generation = 0;
   pendingDispatch;
   resolvePendingDispatch;
   get hasPendingDispatch() {
@@ -5532,25 +6150,32 @@ var AgentSessionQueueDispatcher = class {
     }
     this.ensurePending();
     const setTimer = this.options.retry?.setTimeout ?? defaultSetTimeout3;
+    const generation = this.generation;
     this.dispatchTimer = setTimer(() => {
       this.dispatchTimer = void 0;
-      void this.dispatchNext().finally(() => this.resolvePending());
+      void this.dispatchNext().catch((error) => {
+        if (generation === this.generation) this.options.emit({ type: "turn_policy_error", message: String(error) });
+      }).finally(() => {
+        if (generation === this.generation) this.resolvePending();
+      });
     }, delayMs);
   }
   cancel() {
-    if (this.dispatchTimer === void 0) {
-      return;
+    this.generation++;
+    if (this.dispatchTimer !== void 0) {
+      const clearTimer = this.options.retry?.clearTimeout ?? defaultClearTimeout3;
+      clearTimer(this.dispatchTimer);
+      this.dispatchTimer = void 0;
     }
-    const clearTimer = this.options.retry?.clearTimeout ?? defaultClearTimeout3;
-    clearTimer(this.dispatchTimer);
-    this.dispatchTimer = void 0;
     this.resolvePending();
   }
   async dispatchNext() {
+    const generation = this.generation;
     if (this.options.getDisposed() || this.options.isStreaming() || this.options.isBlockedByRuntimePolicy()) {
       return false;
     }
     await this.options.agent.waitForIdle();
+    if (generation !== this.generation) return false;
     if (this.options.getDisposed() || this.options.isStreaming() || this.options.isBlockedByRuntimePolicy()) {
       this.schedule(100);
       return false;
@@ -5565,6 +6190,7 @@ var AgentSessionQueueDispatcher = class {
       cwd: this.options.cwd,
       queuedInput: cloneQueuedInput(queuedInput)
     });
+    if (generation !== this.generation) return false;
     const dispatchDecision = typeof decision === "boolean" ? { allowed: decision } : decision ?? { allowed: true };
     if (!dispatchDecision.allowed) {
       this.options.emit({
@@ -5578,6 +6204,7 @@ var AgentSessionQueueDispatcher = class {
       return false;
     }
     await this.options.runPreRequestAutoCompact();
+    if (generation !== this.generation) return false;
     if (this.options.getDisposed() || this.options.isStreaming() || this.options.isBlockedByRuntimePolicy()) {
       this.schedule(100);
       return false;
@@ -5601,6 +6228,7 @@ var AgentSessionQueueDispatcher = class {
         clearEditor: dispatched.clearEditor,
         visibility: dispatched.visibility
       });
+      if (generation !== this.generation) return false;
       if (!prepared.handled) {
         if (prepared.systemPrompt !== void 0) {
           this.options.agent.setSystemPrompt(prepared.systemPrompt);
@@ -5716,6 +6344,7 @@ var AgentSessionRetryController = class {
   /** Total attempts across kinds in this recovery episode, for reporting. */
   totalRetryAttempts = 0;
   retryTimer;
+  retryEpoch = 0;
   pendingRetry;
   resolvePendingRetry;
   get policy() {
@@ -5771,18 +6400,26 @@ var AgentSessionRetryController = class {
     const rawDelayMs = (this.retry.baseDelayMs ?? 2e3) * 2 ** (attempt - 1);
     const delayMs = this.retry.maxDelayMs !== void 0 ? Math.min(rawDelayMs, this.retry.maxDelayMs) : rawDelayMs;
     this.ensurePending();
+    const epoch = this.retryEpoch;
+    const pending = this.pendingRetry;
     this.setRecoveryState("retry_pending");
     this.emit({ type: "turn_recovery_pending", recovery: "retry", failure, attempt, maxRetries, delayMs });
+    if (epoch !== this.retryEpoch) return;
     this.emit({ type: "retry_scheduled", errorMessage: failure.message, attempt, maxRetries, delayMs });
+    if (epoch !== this.retryEpoch) return;
     this.cancelTimerOnly();
     const setTimer = this.retry.setTimeout ?? defaultSetTimeout4;
     this.retryTimer = setTimer(() => {
+      if (epoch !== this.retryEpoch) return;
       this.retryTimer = void 0;
       this.setRecoveryState("retrying");
       this.emit({ type: "retry_start", attempt, maxRetries });
+      if (epoch !== this.retryEpoch) return;
       this.emit({ type: "turn_retry_started", attempt, maxRetries, failure });
+      if (epoch !== this.retryEpoch) return;
       this.removeTrailingAssistantError();
       void this.continueTurn().catch((error) => {
+        if (epoch !== this.retryEpoch || pending !== this.pendingRetry) return;
         const errorMessage = error instanceof Error ? error.message : String(error);
         const terminalFailure = asTerminalFailure(failure, errorMessage);
         this.emit({
@@ -5794,7 +6431,7 @@ var AgentSessionRetryController = class {
         this.emit({ type: "turn_settled" });
         this.resetAttempts();
         this.setRecoveryState("terminal");
-        this.resolvePending();
+        this.resolvePending(pending);
       });
     }, delayMs);
   }
@@ -5826,6 +6463,7 @@ var AgentSessionRetryController = class {
     this.resolvePending();
   }
   cancel() {
+    this.retryEpoch++;
     this.cancelTimerOnly();
     this.resetAttempts();
     this.resolvePending();
@@ -5850,7 +6488,8 @@ var AgentSessionRetryController = class {
       this.resolvePendingRetry = resolve3;
     });
   }
-  resolvePending() {
+  resolvePending(expected = this.pendingRetry) {
+    if (expected !== this.pendingRetry) return;
     const resolve3 = this.resolvePendingRetry;
     this.pendingRetry = void 0;
     this.resolvePendingRetry = void 0;
@@ -6015,9 +6654,14 @@ function classifyControllerRuntimeError(params) {
   return createFailureClassification({ errorMessage, phase: params.phase }, params.retry, params.classifyFailure);
 }
 async function runAgentSessionRuntimePhase(params) {
+  const startedGeneration = params.getCurrentGeneration?.();
+  const isStale = () => params.getCurrentGeneration !== void 0 && startedGeneration !== void 0 && params.getCurrentGeneration() !== startedGeneration;
   try {
     return await params.action();
   } catch (error) {
+    if (isStale()) {
+      throw error;
+    }
     const failure = classifyControllerRuntimeError({
       error,
       phase: params.phase,
@@ -6179,6 +6823,8 @@ async function handleAgentSessionTurnEndRuntimePolicies(params) {
   if (params.disposed || params.runtimeGuardTriggered) {
     return;
   }
+  const startedGeneration = params.getCurrentGeneration?.();
+  const isStale = () => params.getCurrentGeneration !== void 0 && params.getCurrentGeneration() !== startedGeneration;
   const failure = classifyControllerTurnFailure({
     message: params.message,
     retry: params.retry,
@@ -6198,6 +6844,7 @@ async function handleAgentSessionTurnEndRuntimePolicies(params) {
     message: params.message,
     messages: params.agent.state.messages.slice()
   });
+  if (isStale()) return;
   if (failure?.compactable) {
     params.scheduleAutoCompact(compactDecision ?? { reason: "overflow", willRetry: true }, failure);
     return;
@@ -6216,14 +6863,18 @@ async function handleAgentSessionTurnEndRuntimePolicies(params) {
       return;
     }
     await params.handleRetryTurnEnd(params.message, failure);
+    if (isStale()) return;
     params.setRecoveryState("terminal");
     params.emit({ type: "turn_failed_terminal", failure: asTerminalFailure(failure), message: params.message });
+    if (isStale()) return;
     params.emit({ type: "turn_settled" });
     return;
   }
   await params.handleRetryTurnEnd(params.message);
+  if (isStale()) return;
   if (isAssistantTerminalCompletion(params.message)) {
     params.emit({ type: "turn_completed", message: params.message, toolResults: params.toolResults });
+    if (isStale()) return;
     const postTurnCompactDecision = compactDecision ?? params.getAutoCompactDecision?.({
       agent: params.agent,
       sessionManager: params.sessionManager,
@@ -6231,6 +6882,7 @@ async function handleAgentSessionTurnEndRuntimePolicies(params) {
       message: params.message,
       messages: params.agent.state.messages.slice()
     });
+    if (isStale()) return;
     if (postTurnCompactDecision?.reason === "threshold") {
       params.scheduleAutoCompact(postTurnCompactDecision);
       return;
@@ -6250,6 +6902,7 @@ async function runAgentSessionControllerAutoCompact(params) {
       reason: params.reason,
       willRetry: params.willRetry,
       signal: params.signal,
+      isCurrent: params.isCurrent,
       compaction: params.compaction,
       agent: params.agent,
       sessionManager: params.sessionManager,
@@ -6260,6 +6913,7 @@ async function runAgentSessionControllerAutoCompact(params) {
       markSyncedToAgentState: params.markSyncedToAgentState,
       continueTurn: params.continueTurn
     });
+    if (params.isCurrent?.() === false) return result;
     if (!params.willRetry || result?.aborted) {
       const alreadyCancelled = params.getRecoveryState?.() === "cancelled" || params.getDisposed?.() === true;
       params.setRecoveryState(result?.aborted && cancelOnAbort ? "cancelled" : "none");
@@ -6273,11 +6927,12 @@ async function runAgentSessionControllerAutoCompact(params) {
         params.emit({ type: "turn_settled" });
       }
       if (!result?.aborted && runAfterAgentEndHook) {
-        void params.handleAgentEndHook(params.agent.state.messages.slice());
+        await params.handleAgentEndHook(params.agent.state.messages.slice());
       }
     }
     return result;
   } catch (error) {
+    if (params.isCurrent?.() === false) return { aborted: true };
     const errorMessage = error instanceof Error ? error.message : String(error);
     if (!params.willRetry && params.reason !== "overflow") {
       params.setRecoveryState("none");
@@ -6285,7 +6940,7 @@ async function runAgentSessionControllerAutoCompact(params) {
         params.emit({ type: "turn_settled" });
       }
       if (runAfterAgentEndHook) {
-        void params.handleAgentEndHook(params.agent.state.messages.slice());
+        await params.handleAgentEndHook(params.agent.state.messages.slice());
       }
       throw error;
     }
@@ -6303,7 +6958,7 @@ async function runAgentSessionControllerAutoCompact(params) {
     params.emit({ type: "turn_settled" });
     throw error;
   } finally {
-    params.clearPendingFailure();
+    if (params.isCurrent?.() !== false) params.clearPendingFailure();
   }
 }
 
@@ -6324,8 +6979,22 @@ var AgentSessionController = class {
   unsubscribeSemantic;
   lastSyncedMessageCount = 0;
   disposed = false;
+  transitioning = false;
+  generation = 0;
+  convergence = new SessionConvergence({
+    sessionId: () => this.sessionManager.getActiveSession()?.id,
+    wait: () => this.waitForRuntimePolicies(),
+    busy: () => this.isStreaming || this.hasPendingRuntimePolicy(),
+    queued: () => this.hasQueuedMessages,
+    emit: (event) => this.emit(event)
+  });
+  get workIdentity() {
+    return this.convergence.identity;
+  }
+  pendingEndOperations = new PendingEndOperations();
   baseSystemPrompt;
   prepareTurn;
+  onExecutionEnd;
   afterAgentEnd;
   getAutoCompactDecision;
   classifyFailure;
@@ -6340,6 +7009,7 @@ var AgentSessionController = class {
     this.baseSystemPrompt = options.baseSystemPrompt ?? this.agent.state.systemPrompt;
     this.prepareTurn = options.prepareTurn;
     this.afterAgentEnd = options.afterAgentEnd;
+    this.onExecutionEnd = options.onExecutionEnd;
     this.getAutoCompactDecision = options.getAutoCompactDecision;
     this.classifyFailure = options.classifyFailure;
     if (options.onEvent) {
@@ -6417,7 +7087,7 @@ var AgentSessionController = class {
     return this.agent.state.isStreaming;
   }
   get hasQueuedMessages() {
-    return this.queue.hasQueuedMessages;
+    return this.queue.hasQueuedMessages || this.agent.hasQueuedMessages();
   }
   get pendingMessageCount() {
     return this.queue.length;
@@ -6449,18 +7119,32 @@ var AgentSessionController = class {
     };
   }
   subscribe(listener) {
+    if (this.disposed) return () => {
+    };
     this.listeners.add(listener);
     return () => this.listeners.delete(listener);
   }
   syncFromActiveSession(messages) {
-    const activeSession = this.sessionManager.getActiveSession();
-    this.agent.sessionId = activeSession?.id;
-    const sessionMessages = messages ?? this.sessionManager.getMessages();
-    const conversationMessages = getConversationMessages(sessionMessages);
-    this.agent.replaceMessages(conversationMessages);
-    this.lastSyncedMessageCount = conversationMessages.length;
-    this.queue.clear();
-    this.recordLifecycle({ type: "session_synced" });
+    if (this.disposed || this.transitioning) return;
+    this.transitioning = true;
+    try {
+      this.generation++;
+      this.cancelScheduledWork();
+      this.recoveryState = "none";
+      this.pendingCompactionFailure = void 0;
+      this.pendingEndOperations.clear();
+      const activeSession = this.sessionManager.getActiveSession();
+      this.agent.sessionId = activeSession?.id;
+      const sessionMessages = messages ?? this.sessionManager.getMessages();
+      const conversationMessages = getConversationMessages(sessionMessages);
+      this.agent.replaceMessages(conversationMessages);
+      this.lastSyncedMessageCount = conversationMessages.length;
+      this.queue.clear();
+      this.recordLifecycle({ type: "session_synced" });
+      this.convergence.invalidate("sync");
+    } finally {
+      this.transitioning = false;
+    }
   }
   markSyncedToAgentState() {
     this.lastSyncedMessageCount = this.agent.state.messages.length;
@@ -6478,7 +7162,12 @@ var AgentSessionController = class {
       this.agent.setTools(context.tools);
     }
   }
-  async prompt(input, options) {
+  prompt(input, options) {
+    if (this.disposed || this.transitioning) return Promise.reject(new Error("Controller disposed or transitioning"));
+    return this.convergence.run(() => this.promptInternal(input, options));
+  }
+  async promptInternal(input, options) {
+    const generation = this.generation;
     const messages = normalizePromptInput(input);
     if (this.isRecoveryActive()) {
       this.queue.enqueue(messages, options?.streamingBehavior ?? "followUp", {
@@ -6503,8 +7192,9 @@ var AgentSessionController = class {
       throw new Error("Agent is already processing. Specify streamingBehavior ('steer' or 'followUp') to queue the message.");
     }
     await this.runPreRequestAutoCompactIfNeeded();
+    if (generation !== this.generation || this.disposed) return;
     const prepared = await this.runRuntimePhase("prepare", () => this.preparePromptMessages(messages, options));
-    if (prepared.handled) {
+    if (generation !== this.generation || this.disposed || prepared.handled) {
       return;
     }
     this.recordLifecycle({ type: "prompt_started" });
@@ -6512,45 +7202,66 @@ var AgentSessionController = class {
       this.agent.setSystemPrompt(prepared.systemPrompt);
     }
     await this.runRuntimePhase("request", () => this.agent.prompt(prepared.messages));
+    if (generation !== this.generation || this.disposed) return;
     await this.runRuntimePhase("post_turn", () => this.syncNewAgentMessages());
   }
-  async continue() {
+  continue() {
+    return this.disposed || this.transitioning ? Promise.reject(new Error("Controller disposed or transitioning")) : this.convergence.run(() => this.continueInternal());
+  }
+  async continueInternal() {
+    const generation = this.generation;
     if (this.isStreaming) {
       throw new Error("Agent is already processing. Wait for completion before continuing.");
     }
     await this.runPreRequestAutoCompactIfNeeded();
+    if (generation !== this.generation || this.disposed) return;
     this.recordLifecycle({ type: "prompt_started" });
     await this.runRuntimePhase("request", () => this.agent.continue());
+    if (generation !== this.generation || this.disposed) return;
     await this.runRuntimePhase("post_turn", () => this.syncNewAgentMessages());
   }
   abort() {
-    this.recordLifecycle({ type: "abort" });
-    const cancelPendingRecovery = this.isRecoveryActive() && !this.isStreaming;
-    this.retryController.cancel();
-    this.autoCompact.cancel();
-    this.queueDispatcher.cancel();
-    this.autoContinue.cancel();
-    if (cancelPendingRecovery) {
-      this.recoveryState = "cancelled";
-      this.emit({ type: "turn_cancelled", reason: "user_abort" });
-      this.emit({ type: "turn_settled" });
+    if (this.disposed || this.transitioning) return;
+    this.transitioning = true;
+    try {
+      this.generation++;
+      this.pendingEndOperations.clear();
+      this.recordLifecycle({ type: "abort" });
+      const cancelPendingRecovery = this.isRecoveryActive() && !this.isStreaming;
+      this.cancelScheduledWork();
+      if (cancelPendingRecovery) {
+        this.recoveryState = "cancelled";
+        this.emit({ type: "turn_cancelled", reason: "user_abort" });
+        this.emit({ type: "turn_settled" });
+      }
+      this.agent.abort();
+      this.convergence.invalidate("abort");
+    } finally {
+      this.transitioning = false;
     }
-    this.agent.abort();
   }
   waitForIdle() {
     return this.agent.waitForIdle();
   }
-  async waitForSettled() {
-    while (true) {
+  waitForSettled() {
+    return this.convergence.wait();
+  }
+  async waitForRuntimePolicies() {
+    const generation = this.generation;
+    while (!this.disposed && generation === this.generation) {
       await this.agent.waitForIdle();
-      if (!this.hasPendingRuntimePolicy()) {
+      if (this.disposed || generation !== this.generation || !this.hasPendingRuntimePolicy()) {
         return;
       }
-      await Promise.all([this.retryController.waitForRetry(), this.autoCompact.waitForAutoCompact(), this.autoContinue.waitForAutoContinue(), this.queueDispatcher.waitForDispatch()]);
+      await Promise.all([this.pendingEndOperations.wait(), this.retryController.waitForRetry(), this.autoCompact.waitForAutoCompact(), this.autoContinue.waitForAutoContinue(), this.queueDispatcher.waitForDispatch()]);
     }
   }
   async runAutoCompact(reason, willRetry = false, options) {
-    return runAgentSessionControllerAutoCompact({
+    const generation = this.generation;
+    if (this.disposed || this.transitioning) throw new Error("Controller disposed or transitioning");
+    const isCurrent = () => generation === this.generation && !this.disposed;
+    return this.convergence.run(() => runAgentSessionControllerAutoCompact({
+      isCurrent,
       reason,
       willRetry,
       signal: options?.signal,
@@ -6559,7 +7270,9 @@ var AgentSessionController = class {
       sessionManager: this.sessionManager,
       cwd: this.cwd,
       pendingFailure: this.pendingCompactionFailure,
-      emit: (event) => this.emit(event),
+      emit: (event) => {
+        if (isCurrent()) this.emit(event);
+      },
       setRecoveryState: (state) => {
         this.recoveryState = state;
       },
@@ -6577,19 +7290,19 @@ var AgentSessionController = class {
       emitSettled: options?.emitSettled,
       runAfterAgentEndHook: options?.runAfterAgentEndHook,
       cancelOnAbort: options?.cancelOnAbort
-    });
+    }));
   }
   dispose() {
     if (this.disposed) return;
     this.disposed = true;
-    this.retryController.cancel();
-    this.autoCompact.cancel();
-    this.queueDispatcher.cancel();
-    this.autoContinue.cancel();
+    this.generation++;
+    this.pendingEndOperations.clear();
+    this.cancelScheduledWork();
     this.unsubscribeAgent?.();
     this.unsubscribeSemantic?.();
-    this.listeners.clear();
     this.queue.clear();
+    this.convergence.invalidate("dispose");
+    this.listeners.clear();
   }
   drainQueuedInputsForEditor() {
     return this.queue.drainForEditor();
@@ -6604,10 +7317,16 @@ var AgentSessionController = class {
     this.queue.replaceText(search, replacement);
   }
   requestQueueDispatch() {
-    if (this.queue.length > 0) this.queueDispatcher.schedule();
+    if (!this.disposed && !this.transitioning && this.queue.length > 0) {
+      void this.convergence.run(async () => {
+        this.queueDispatcher.schedule();
+      });
+    }
   }
   async runPreRequestAutoCompactIfNeeded() {
+    const generation = this.generation;
     return runPreRequestAutoCompact({
+      isCurrent: () => generation === this.generation && !this.disposed,
       disposed: this.disposed,
       runtimeGuardTriggered: this.runtimeGuard.triggered,
       isStreaming: this.isStreaming,
@@ -6639,24 +7358,32 @@ var AgentSessionController = class {
       this.queue.markMessageDelivered(event.message);
     }
     if (event.type === "turn_end") {
-      void this.syncNewAgentMessages().catch((error) => {
-        console.error("[AgentSessionController] Session sync failed after turn:", error);
-      });
+      this.pendingEndOperations.track(() => this.syncNewAgentMessages().catch((error) => {
+        this.emit({ type: "turn_policy_error", message: String(error) });
+      }));
       this.recordLifecycle({ type: "turn_end_success" });
-      void this.handleTurnEndRuntimePolicies(event.message, event.toolResults).catch((error) => handleTurnEndPolicyThrow((event2) => this.emit(event2), error, {
-        recoveryWasActive: this.isRecoveryActive(),
-        cancelPendingRecovery: () => {
-          this.retryController.cancel();
-          this.autoCompact.cancel();
-        },
-        markRecoveryTerminal: () => {
-          this.recoveryState = "terminal";
-        }
+      const generation = this.generation;
+      this.pendingEndOperations.track(() => this.handleTurnEndRuntimePolicies(event.message, event.toolResults).catch((error) => {
+        if (generation !== this.generation || this.disposed) return;
+        handleTurnEndPolicyThrow((event2) => this.emit(event2), error, {
+          recoveryWasActive: this.isRecoveryActive(),
+          cancelPendingRecovery: () => {
+            this.retryController.cancel();
+            this.autoCompact.cancel();
+          },
+          markRecoveryTerminal: () => {
+            this.recoveryState = "terminal";
+          }
+        });
       }));
     }
     if (event.type === "agent_end") {
       this.recordLifecycle({ type: "agent_end" });
-      void this.handleAgentEndHook(event.messages);
+      const generation = this.generation;
+      this.pendingEndOperations.track(async () => {
+        await runEndHook(this.onExecutionEnd, { messages: event.messages, agent: this.agent, sessionManager: this.sessionManager, cwd: this.cwd, hasQueuedMessages: this.hasQueuedMessages }, () => generation === this.generation && !this.disposed, (e) => this.emit(e));
+        if (generation === this.generation && !this.disposed) await this.handleAgentEndHook(event.messages);
+      });
       this.emit({ type: "streaming_changed", isStreaming: false });
     }
   }
@@ -6702,6 +7429,7 @@ var AgentSessionController = class {
       getAutoCompactDecision: this.getAutoCompactDecision,
       classifyFailure: this.classifyFailure,
       retry: this.retryController.policy,
+      getCurrentGeneration: () => this.generation,
       emit: (event) => this.emit(event),
       setRecoveryState: (state) => {
         this.recoveryState = state;
@@ -6712,27 +7440,12 @@ var AgentSessionController = class {
     });
   }
   async handleAgentEndHook(messages) {
+    const generation = this.generation;
     if (this.disposed || this.runtimeGuard.triggered || this.isBlockedByRuntimePolicy()) {
       return;
     }
-    if (this.afterAgentEnd) {
-      this.emit({ type: "agent_end_hook_start", hasQueuedMessages: this.hasQueuedMessages });
-      try {
-        await this.afterAgentEnd({
-          messages,
-          agent: this.agent,
-          sessionManager: this.sessionManager,
-          cwd: this.cwd,
-          hasQueuedMessages: this.hasQueuedMessages
-        });
-        this.emit({ type: "agent_end_hook_end" });
-      } catch (error) {
-        this.emit({
-          type: "agent_end_hook_end",
-          errorMessage: error instanceof Error ? error.message : String(error)
-        });
-      }
-    }
+    await runEndHook(this.afterAgentEnd, { messages, agent: this.agent, sessionManager: this.sessionManager, cwd: this.cwd, hasQueuedMessages: this.hasQueuedMessages }, () => generation === this.generation && !this.disposed, (event) => this.emit(event));
+    if (generation !== this.generation || this.disposed) return;
     if (this.queue.length > 0) {
       this.queueDispatcher.schedule();
     }
@@ -6753,6 +7466,7 @@ var AgentSessionController = class {
       action,
       retry: this.retryController.policy,
       classifyFailure: this.classifyFailure,
+      getCurrentGeneration: () => this.generation,
       emit: (event) => this.emit(event),
       setRecoveryState: (state) => {
         this.recoveryState = state;
@@ -6765,8 +7479,14 @@ var AgentSessionController = class {
   isBlockedByRuntimePolicy() {
     return this.recoveryState !== "none" || this.retryController.hasPendingRetry || this.autoCompact.hasPendingAutoCompact;
   }
+  cancelScheduledWork() {
+    this.retryController.cancel();
+    this.autoCompact.cancel();
+    this.queueDispatcher.cancel();
+    this.autoContinue.cancel();
+  }
   hasPendingRuntimePolicy() {
-    return this.retryController.hasPendingRetry || this.autoCompact.hasPendingAutoCompact || this.autoContinue.hasPendingAutoContinue || this.queueDispatcher.hasPendingDispatch;
+    return this.pendingEndOperations.pending || this.retryController.hasPendingRetry || this.autoCompact.hasPendingAutoCompact || this.autoContinue.hasPendingAutoContinue || this.queueDispatcher.hasPendingDispatch;
   }
   scheduleAutoCompact(decision, failure) {
     this.recordLifecycle({ type: "auto_compact_scheduled" });
@@ -6784,10 +7504,7 @@ var AgentSessionController = class {
     if (this.runtimeGuard.triggered) {
       this.runtimeGuard.markTriggered();
     }
-    this.retryController.cancel();
-    this.autoCompact.cancel();
-    this.queueDispatcher.cancel();
-    this.autoContinue.cancel();
+    this.cancelScheduledWork();
     this.recoveryState = "terminal";
     this.emit({ type: "runtime_guard_triggered", toolName, repeatCount, reason });
     this.emit({
@@ -6798,13 +7515,13 @@ var AgentSessionController = class {
     this.agent.abort();
   }
   emit(event) {
+    if (!event.type.startsWith("session_work_") && event.type !== "session_quiescent" && event.type !== "session_invalidated") this.convergence.observe(event);
     for (const listener of this.listeners) {
-      listener(event);
+      notifyObserver(listener, event);
     }
   }
   recordLifecycle(input) {
     this.lifecycleState = reduceAgentSessionLifecycle(this.lifecycleState, input);
-    void this.lifecycleState.phase;
   }
 };
 
@@ -6987,6 +7704,109 @@ async function requestInteraction(request) {
   return await currentInteractionHandler(request);
 }
 
+// ../../packages/agent-framework/src/attention.ts
+function same(a, b) {
+  return a?.sessionId === b.sessionId && a?.generation === b.generation;
+}
+var AttentionCoordinator = class {
+  constructor(policy = {}) {
+    this.policy = policy;
+  }
+  policy;
+  current;
+  requests = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  sequence = 0;
+  userWork = false;
+  consumed = false;
+  disposed = false;
+  get activeRequests() {
+    return [...this.requests.values()].map((r) => ({ ...r }));
+  }
+  subscribe(listener) {
+    if (this.disposed) return () => {
+    };
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  /** Feed controller work events only. Old turn_settled/skipped events are not outcomes. */
+  handle(event) {
+    if (this.disposed || this.current && event.generation < this.current.generation) return;
+    if (event.type === "session_invalidated") {
+      this.current = { sessionId: event.sessionId, generation: event.generation };
+      this.consumed = true;
+      this.clear();
+      return;
+    }
+    if (event.type === "session_work_started") {
+      if (same(this.current, event)) return;
+      this.current = { sessionId: event.sessionId, generation: event.generation };
+      this.consumed = false;
+      this.clear();
+      return;
+    }
+    if (!same(this.current, event) || this.consumed) return;
+    this.consumed = true;
+    const userWork = this.userWork;
+    this.userWork = false;
+    if (event.outcome === "cancelled") this.clear();
+    else if (event.outcome === "failed" || event.outcome === "blocked") this.request(event, event.outcome);
+    else if (this.policy.completion === "accepted-user-work" && userWork) this.request(event, "completed");
+  }
+  /** Call at actual accepted human delivery, including steer/retry; never infer from message role. */
+  acceptUserWork(identity) {
+    if (this.disposed || !same(this.current, identity) || this.consumed) return false;
+    this.userWork = true;
+    return true;
+  }
+  /** Producers retain the returned ID until answered/cancelled. Duplicate IDs do not broadcast twice. */
+  request(identity, reason, id = `attention-${++this.sequence}`) {
+    if (this.disposed || !same(this.current, identity)) return void 0;
+    const existing = this.requests.get(id);
+    if (existing) return { ...existing };
+    const request = { sessionId: identity.sessionId, generation: identity.generation, id, reason };
+    this.requests.set(id, request);
+    this.emit({ type: "attention_requested", ...request });
+    return { ...request };
+  }
+  /** Only the interaction owner resolves; suppressing/defering host presentation is not resolution. */
+  resolve(id, identity, resolution = "answered") {
+    const request = this.requests.get(id);
+    if (!request || !same(request, identity)) return false;
+    this.requests.delete(id);
+    this.emit({ type: "attention_resolved", ...request, resolution });
+    return true;
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.current = void 0;
+    this.consumed = true;
+    this.clear();
+    this.listeners.clear();
+  }
+  clear() {
+    const requests = [...this.requests.values()];
+    this.requests.clear();
+    this.userWork = false;
+    for (const request of requests) this.emit({ type: "attention_resolved", ...request, resolution: "invalidated" });
+  }
+  emit(event) {
+    for (const listener of this.listeners) notifyObserver(listener, event);
+  }
+};
+
+// ../../packages/agent-framework/src/interaction-attention.ts
+function interactionAttentionReason(request) {
+  return request.type === "notify" ? void 0 : "input-required";
+}
+function interactionAttentionResolution(response) {
+  if (!response || typeof response !== "object") return "cancelled";
+  const result = response;
+  if (result.timedOut || result.skipped || result.unavailable) return "cancelled";
+  return ["confirmed", "selection", "value", "answers"].some((key) => result[key] !== void 0) ? "answered" : "cancelled";
+}
+
 // ../../packages/agent-framework/src/context-files.ts
 var AGENTS_CONTEXT_FILE_NAME = "AGENTS.md";
 function normalizeContextPath(path4) {
@@ -8849,14 +9669,23 @@ function createFileObservationState(options = {}) {
   function coverageSpansFile(coveredRanges, totalLines) {
     if (totalLines <= 0) return true;
     const merged = mergeLineRanges(coveredRanges);
-    return merged.length > 0 && merged[0].startLine <= 1 && merged[merged.length - 1].endLine >= totalLines;
+    return merged.length === 1 && merged[0].startLine <= 1 && merged[0].endLine >= totalLines;
   }
   function summarize(observed) {
     const merged = mergeLineRanges(observed.coveredRanges);
     const coveredLines = merged.reduce((total, range2) => total + (range2.endLine - range2.startLine + 1), 0);
     let firstUnseenLine;
     if (observed.coveredTotalLines > 0 && coveredLines < observed.coveredTotalLines) {
-      firstUnseenLine = merged.length > 0 && merged[0].startLine <= 1 ? merged[merged.length - 1].endLine + 1 : 1;
+      firstUnseenLine = 1;
+      if (merged.length > 0 && merged[0].startLine <= 1) {
+        firstUnseenLine = merged[merged.length - 1].endLine + 1;
+        for (let index = 0; index + 1 < merged.length; index++) {
+          if (merged[index + 1].startLine > merged[index].endLine + 1) {
+            firstUnseenLine = merged[index].endLine + 1;
+            break;
+          }
+        }
+      }
     }
     let lastRange;
     for (const range2 of observed.readRanges.values()) {
@@ -8972,22 +9801,32 @@ function createReadTool(cwd, options) {
     ...rootSchema ? { root: rootSchema } : {},
     offset: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_CROSS_HOST_LINE_NUMBER, description: "Line number to start reading from, 1-indexed. Example: 201." })),
     limit: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_CROSS_HOST_LINE_NUMBER, description: "Maximum number of lines to read. Example: 120." })),
+    tail: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_CROSS_HOST_LINE_NUMBER, description: "Read the last N lines of the file, without needing to know the total line count. Useful for logs and files that grow. Mutually exclusive with offset/limit. Example: tail=50." })),
     question: Type.Optional(Type.String({ description: "Optional focused question for image, video, audio, or document understanding. Use this when asking what a media/document file contains; omit for ordinary text reads." }))
   });
   const pathResolutionDescription = buildPathResolutionDescription(cwd, options);
   return {
     name: "read",
     label: "read",
-    description: `Read a file's contents. Use this before editing, and use offset/limit for large files. Images are attached for the current model when it supports vision; otherwise a configured file-understanding service analyzes them. Video, audio, and documents require a configured understanding service. Pass question to specify what to focus on; it does not force a separate model request. Example: read_file path='Scripts/PlayerController.cs' or read_file path='Data/config.json'. ${pathResolutionDescription} For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). When you need the full file, continue with a larger offset until complete.`,
+    description: `Read a file's contents. Use this before editing, and use offset/limit for large files, or tail=N to read the last N lines when the line count is unknown. Images are attached for the current model when it supports vision; otherwise a configured file-understanding service analyzes them. Video, audio, and documents require a configured understanding service. Pass question to specify what to focus on; it does not force a separate model request. Example: read_file path='Scripts/PlayerController.cs' or read_file path='Data/config.json'. ${pathResolutionDescription} For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). When you need the full file, continue with a larger offset until complete.`,
     parameters: readSchema,
     execute: async (_toolCallId, params, signal) => {
-      const { path: path4, root, offset, limit, question } = params;
+      const { path: path4, root, question } = params;
+      const tail = params.tail;
+      let offset = params.offset;
+      let limit = params.limit;
       if (offset !== void 0 && (!Number.isSafeInteger(offset) || offset < 1 || offset > MAX_CROSS_HOST_LINE_NUMBER)) {
         return createReadErrorResult(`Invalid arguments: offset must be a positive safe integer no greater than ${MAX_CROSS_HOST_LINE_NUMBER}.`);
       }
       if (limit !== void 0 && (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_CROSS_HOST_LINE_NUMBER)) {
         return createReadErrorResult(`Invalid arguments: limit must be a positive safe integer no greater than ${MAX_CROSS_HOST_LINE_NUMBER}.`);
       }
+      if (tail !== void 0 && (!Number.isSafeInteger(tail) || tail < 1 || tail > MAX_CROSS_HOST_LINE_NUMBER)) {
+        return createReadErrorResult(`Invalid arguments: tail must be a positive safe integer no greater than ${MAX_CROSS_HOST_LINE_NUMBER}.`);
+      }
+      if (tail !== void 0 && (offset !== void 0 || limit !== void 0)) {
+        return createReadErrorResult("Invalid arguments: tail cannot be combined with offset or limit. Use tail=N to read the last N lines, or offset/limit for a window.");
+      }
       if (offset !== void 0 && limit !== void 0 && offset - 1 + limit > MAX_CROSS_HOST_LINE_NUMBER) {
         return createReadErrorResult(`Invalid arguments: offset and limit exceed the ${MAX_CROSS_HOST_LINE_NUMBER}-line cross-host range.`);
       }
@@ -9151,14 +9990,38 @@ Focus: ${question.trim()}` : ""}` },
                 });
                 return;
               }
-              const startLine = offset === void 0 ? 0 : offset - 1;
+              let translatedFromTail = false;
+              let tailWindowIncludesPhantom = false;
+              let tailEffectiveLines;
+              let startLine;
+              let range2;
+              if (tail !== void 0) {
+                const effectiveTail = Math.max(1, Math.min(tail, DEFAULT_MAX_LINES - 1));
+                translatedFromTail = true;
+                tailEffectiveLines = effectiveTail;
+                range2 = await fs2.readTextRange(absolutePath, {
+                  tailLines: effectiveTail,
+                  maxOutputLines: DEFAULT_MAX_LINES,
+                  maxOutputBytes: DEFAULT_MAX_BYTES
+                }, signal);
+                tailWindowIncludesPhantom = range2.endsWithNewline === true;
+                if (range2.selectedLines > 0) {
+                  const derivedHead = range2.totalLines - range2.selectedLines + 1;
+                  startLine = range2.outputStartLine !== void 0 && !range2.firstLineExceedsLimit ? range2.outputStartLine - 1 : derivedHead - 1;
+                  limit = range2.selectedLines;
+                } else {
+                  startLine = 0;
+                }
+              } else {
+                startLine = offset === void 0 ? 0 : offset - 1;
+                range2 = await fs2.readTextRange(absolutePath, {
+                  offsetLine: startLine,
+                  limitLines: limit,
+                  maxOutputLines: DEFAULT_MAX_LINES,
+                  maxOutputBytes: DEFAULT_MAX_BYTES
+                }, signal);
+              }
               const startLineDisplay = startLine + 1;
-              const range2 = await fs2.readTextRange(absolutePath, {
-                offsetLine: startLine,
-                limitLines: limit,
-                maxOutputLines: DEFAULT_MAX_LINES,
-                maxOutputBytes: DEFAULT_MAX_BYTES
-              }, signal);
               if (options?.allowBinary === false) {
                 const selectedLooksBinary = range2.selectedBytesLookBinary ?? (looksLikeBinaryText(range2.content) || range2.content.includes("\uFFFD"));
                 const selectedBinary = selectedLooksBinary ? { kind: "document", mimeType: "application/octet-stream" } : void 0;
@@ -9177,7 +10040,7 @@ Focus: ${question.trim()}` : ""}` },
                 contentHash: range2.contentHash
               };
               const totalFileLines = range2.totalLines;
-              if (startLine >= range2.totalLines) {
+              if (startLine >= range2.totalLines && !translatedFromTail) {
                 throw new Error(`Offset ${offset} is beyond end of file (${range2.totalLines} lines total)`);
               }
               let userLimitedLines;
@@ -9198,7 +10061,7 @@ Focus: ${question.trim()}` : ""}` },
                 maxLines: DEFAULT_MAX_LINES,
                 maxBytes: DEFAULT_MAX_BYTES
               };
-              const readStartsAtBeginning = offset === void 0 || offset === 1;
+              const readStartsAtBeginning = startLine === 0;
               const readReachedEndOfFile = startLine + range2.selectedLines >= range2.totalLines;
               const isCompleteTextKnown = readStartsAtBeginning && readReachedEndOfFile && !truncation.truncated && !truncation.firstLineExceedsLimit;
               let callerObservation = fileObservationState;
@@ -9220,13 +10083,14 @@ Focus: ${question.trim()}` : ""}` },
                 resolve3({
                   content: [{
                     type: "text",
-                    text: `File unchanged since previous read of this range (offset=${startLineDisplay}${limit === void 0 ? ", no limit" : `, limit=${limit}`}). Earlier reads still count toward write_file coverage of this file. Use a different offset/limit if you need another section.`
+                    text: translatedFromTail ? `File unchanged since previous tail=${tailEffectiveLines} read (last ${tailWindowIncludesPhantom ? range2.selectedLines - 1 : range2.selectedLines} lines, ${range2.totalLines} lines total). Earlier reads still count toward write_file coverage of this file.` : `File unchanged since previous read of this range (offset=${startLineDisplay}${limit === void 0 ? ", no limit" : `, limit=${limit}`}). Earlier reads still count toward write_file coverage of this file. Use a different offset/limit if you need another section.`
                   }],
                   details: {
                     unchangedSincePreviousRead: true,
                     path: absolutePath,
                     offset: startLineDisplay,
-                    limit
+                    limit,
+                    ...translatedFromTail ? { totalLines: range2.totalLines } : {}
                   }
                 });
                 return;
@@ -9245,7 +10109,12 @@ Base directory: ${nodePath.dirname(absolutePath)}
                 const endLineDisplay = startLineDisplay + truncation.outputLines - 1;
                 const nextOffset = endLineDisplay + 1;
                 outputText = truncation.content;
-                if (truncation.truncatedBy === "lines") {
+                if (translatedFromTail) {
+                  const endsAtLastLine = truncation.content.length > 0 ? ", and the content above ends at the file's last line" : "";
+                  outputText += `
+
+[Tail window hit the output cap: the earliest lines of the requested tail were dropped${endsAtLastLine}. Read earlier lines with offset, or request a smaller tail.]`;
+                } else if (truncation.truncatedBy === "lines") {
                   outputText += `
 
 [Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue.]`;
@@ -9271,18 +10140,38 @@ Base directory: ${nodePath.dirname(absolutePath)}
                 snapshot,
                 range2.selectedContentHash,
                 isCompleteTextKnown,
-                {
-                  // firstLineExceedsLimit yields an intentionally empty range
-                  // (start - 1): zero lines were actually shown, so it must
-                  // contribute nothing to write coverage.
-                  startLine: startLineDisplay,
-                  endLine: startLineDisplay + (truncation.firstLineExceedsLimit ? 0 : truncation.truncated ? truncation.outputLines : range2.selectedLines) - 1,
-                  totalLines: range2.totalLines
-                }
+                (() => {
+                  if (translatedFromTail && truncation.truncated && !truncation.firstLineExceedsLimit) {
+                    const outputStart = range2.outputStartLine ?? startLineDisplay + Math.max(0, range2.selectedLines - range2.outputLines);
+                    const clampedStart = Math.min(outputStart, range2.totalLines + 1);
+                    const clampedEnd = Math.min(range2.totalLines, clampedStart + range2.outputLines - 1);
+                    return {
+                      startLine: clampedStart,
+                      endLine: clampedStart > range2.totalLines ? clampedStart - 1 : clampedEnd,
+                      totalLines: range2.totalLines
+                    };
+                  }
+                  return {
+                    // firstLineExceedsLimit yields an intentionally empty range
+                    // (start - 1): zero lines were actually shown, so it must
+                    // contribute nothing to write coverage.
+                    startLine: startLineDisplay,
+                    endLine: startLineDisplay + (truncation.firstLineExceedsLimit ? 0 : truncation.truncated ? truncation.outputLines : range2.selectedLines) - 1,
+                    totalLines: range2.totalLines
+                  };
+                })()
               );
               if (callerObservation !== fileObservationState) {
                 callerObservation.recordTextRead(absolutePath, rangeKey, snapshot, range2.selectedContentHash, isCompleteTextKnown);
               }
+              if (translatedFromTail && tail !== void 0 && tailEffectiveLines !== void 0 && tailEffectiveLines < tail && startLineDisplay > 1) {
+                outputText += `
+
+[Tail clamped to ${tailEffectiveLines} lines: the per-read line cap is ${DEFAULT_MAX_LINES}, so the ${startLineDisplay - 1} earliest lines of the file are not shown. Use offset reads to walk earlier lines, or a smaller tail.]`;
+              }
+              if (translatedFromTail) {
+                details = { ...details ?? {}, totalLines: range2.totalLines };
+              }
               outputText = sourceHeader + outputText;
               const textContent = [{ type: "text", text: outputText }];
               if (aborted) return;
@@ -9661,13 +10550,15 @@ function createWriteTool(cwd, options) {
                 const observedSnapshot = fileObservationState.getCompleteTextSnapshot(absolutePath);
                 if (!observedSnapshot) {
                   const summary = fileObservationState.describeObservation(absolutePath);
-                  const coverageHint = summary && summary.totalLines > 0 ? ` Previous reads cover ${summary.coveredLines}/${summary.totalLines} lines${summary.lastRange ? ` (last read: lines ${summary.lastRange.startLine}-${summary.lastRange.endLine})` : ""}${summary.firstUnseenLine ? `; read the rest with read_file offset=${summary.firstUnseenLine}` : "; read the full file with read_file (no offset/limit)"}.` : " Read the current full file with read_file (no offset/limit) first.";
+                  const coverageHint = summary && summary.totalLines > 0 ? ` Previous reads cover ${summary.coveredLines}/${summary.totalLines} lines${summary.lastRange ? ` (last read: lines ${summary.lastRange.startLine}-${summary.lastRange.endLine})` : ""}${summary.firstUnseenLine ? `; read the rest with read_file offset=${summary.firstUnseenLine}, or a tail read spanning the whole file` : "; read the full file with read_file (no offset/limit, or a tail read spanning the whole file)"}.` : " Read the current full file with read_file (no offset/limit, or a tail read spanning the whole file) first.";
                   throw new Error(
                     usesExternalFileObservationState ? `write_file blocked: overwriting requires the file to be fully observed by read_file.${coverageHint} Alternatively, use edit_file for targeted changes.` : "Existing-file overwrite requires write_file to share a fileObservationState with read_file; use createSharedFileSystemTools or pass the same fileObservationState to both tools."
                   );
                 }
                 if (!snapshotsHaveSameContent(observedSnapshot, currentSnapshot)) {
-                  throw new Error("File changed since it was read. Read the latest file contents before overwriting it.");
+                  throw new Error(
+                    `File changed since it was read (${observedSnapshot.size} \u2192 ${currentSnapshot.size} bytes; out-of-band edits such as bash sed/redirects cause this). Re-read with the read_file tool \u2014 offset/limit/tail reads accumulate coverage; bash head/cat does not count \u2014 or use edit_file for targeted changes.`
+                  );
                 }
               }
               await fs2.writeFile(absolutePath, content, "utf-8");
@@ -9681,7 +10572,7 @@ function createWriteTool(cwd, options) {
                 signal.removeEventListener("abort", onAbort);
               }
               resolve3({
-                content: [{ type: "text", text: `Successfully wrote ${content.length} bytes to ${filePath}` }],
+                content: [{ type: "text", text: `Successfully wrote ${writtenStat.size} bytes to ${filePath}` }],
                 details: void 0
               });
             } catch (error) {
@@ -9714,6 +10605,8 @@ function restoreLineEndings(text, ending) {
   return ending === "\r\n" ? text.replace(/\n/g, "\r\n") : text;
 }
 var MAX_FUZZY_DIAGNOSTIC_CHARS = 256 * 1024;
+var MAX_CLOSEST_DIFF_REGION_LINES = 80;
+var MAX_CLOSEST_DIFF_LINES = 30;
 var RELAXED_MATCH_WORK_BUDGET = 1e6;
 function normalizeForFuzzyMatch(text) {
   return buildFuzzyIndexMap(text).normalized;
@@ -9862,6 +10755,9 @@ function leadingWhitespace(line) {
   const match2 = line.match(/^[ \t]*/);
   return match2 ? match2[0] : "";
 }
+function stripLeadingWhitespace(line) {
+  return line.replace(/^[ \t]*/, "");
+}
 var RelaxedWindow;
 ((RelaxedWindow2) => {
   RelaxedWindow2.EMPTY_MAP = /* @__PURE__ */ new Map();
@@ -9944,6 +10840,9 @@ function reindentNewText(newText, qLines, fileLines, window) {
     nIdx.push(i);
   }
   if (nIdx.length === 0) return newText;
+  if (qIdx.length === nIdx.length && qIdx.every((q, pos) => qLines[q].trim() === newLines[nIdx[pos]].trim()) && qIdx.some((q, pos) => leadingWhitespace(qLines[q]) !== leadingWhitespace(newLines[nIdx[pos]]))) {
+    return newText;
+  }
   const counterpart = /* @__PURE__ */ new Map();
   let p = 0;
   while (p < qIdx.length && p < nIdx.length && qLines[qIdx[p]].trim() === newLines[nIdx[p]].trim()) {
@@ -10002,7 +10901,7 @@ function reindentNewText(newText, qLines, fileLines, window) {
     }
     const nPos = nPosOfLine.get(i) ?? 0;
     const qPos = counterpart.get(nPos) ?? 0;
-    result.push(qIndent(qIdx[qPos] ?? qIdx[0]) + newLines[i].trim());
+    result.push(qIndent(qIdx[qPos] ?? qIdx[0]) + stripLeadingWhitespace(newLines[i]));
   }
   return result.join("\n");
 }
@@ -10061,7 +10960,8 @@ function describeClosestRegion(content, oldText) {
     let matched = 0;
     let fi = i;
     let firstDiff;
-    for (let qi = firstNonBlank; qi < qLines.length; qi++) {
+    let qi = firstNonBlank;
+    for (; qi < qLines.length; qi++) {
       budget -= 1;
       if (budget < 0) {
         return `Closest-region diagnostics were skipped because the file and the quoted block are too repetitive to compare within the relaxed-match budget \u2014 quote a larger region with distinguishing context lines and retry.`;
@@ -10070,24 +10970,102 @@ function describeClosestRegion(content, oldText) {
       if (!q) continue;
       while (fi < fileLines.length && !fileLines[fi].trim()) fi++;
       if (fi >= fileLines.length || fileLines[fi].trim() !== q) {
-        firstDiff = { fileNo: fi + 1, fileLine: fileLines[fi] ?? "<end of file>", qLine: qLines[qi] };
+        firstDiff = { fileNo: fi + 1, fileLine: fileLines[fi] ?? "<end of file>", qLine: qLines[qi], qIdx: qi };
         break;
       }
       matched++;
       fi++;
     }
-    if (!best || matched > best.matched) best = { start: i, matched, firstDiff };
+    if (!best || matched > best.matched) best = { start: i, walkEnd: fi, matched, firstDiff };
   }
   const total = qLines.filter((line) => line.trim() !== "").length;
   if (!best) {
     return `No line matching ${JSON.stringify(clip(anchor))} exists in this file \u2014 the text may live in a different file, or the file changed since it was read.`;
   }
-  const parts = [`Closest match: file lines ${best.start + 1}\u2013${best.start + total} (${best.matched}/${total} lines matched by trimmed content).`];
+  const regionStart = best.start + 1;
+  let regionEnd = Math.max(regionStart, best.walkEnd + (best.firstDiff ? 1 : 0));
+  const parts = [];
+  let alignment = "unknown";
+  let shiftDelta = 0;
   if (best.firstDiff) {
     parts.push(`First difference at line ${best.firstDiff.fileNo}: file has ${JSON.stringify(clip(best.firstDiff.fileLine.trim()))}, edit expected ${JSON.stringify(clip(best.firstDiff.qLine.trim()))}.`);
+    const suffixIdx = [];
+    for (let s = best.firstDiff.qIdx + 1; s < qLines.length && suffixIdx.length < 3; s++) {
+      if (qLines[s].trim()) suffixIdx.push(s);
+    }
+    if (suffixIdx.length === 0) {
+      alignment = "aligned";
+    } else {
+      budget -= 20;
+      const nextNonBlank = (from) => {
+        let i = from;
+        while (i < fileLines.length && !fileLines[i].trim()) i++;
+        return i;
+      };
+      const tryAlign = (fileStart) => {
+        let score = 0;
+        let fi = fileStart;
+        for (const s of suffixIdx) {
+          fi = nextNonBlank(fi);
+          if (fi >= fileLines.length || fileLines[fi].trim() !== qLines[s].trim()) break;
+          score++;
+          fi++;
+        }
+        return { score, endFileIdx: fi };
+      };
+      const atSameLength = tryAlign(best.walkEnd + 1);
+      if (atSameLength.score === suffixIdx.length) {
+        alignment = "aligned";
+        regionEnd = Math.max(regionEnd, Math.min(atSameLength.endFileIdx, best.start + MAX_CLOSEST_DIFF_REGION_LINES));
+      } else {
+        const diffQuoteLine = best.firstDiff.qLine.trim();
+        const nextFile = nextNonBlank(best.walkEnd + 1);
+        const quoteSkipsAFileLine = nextFile < fileLines.length && fileLines[nextFile].trim() === diffQuoteLine;
+        const shiftedCandidates = [best.walkEnd - 1, best.walkEnd, best.walkEnd + 2, best.walkEnd + 3];
+        const shiftedResults = shiftedCandidates.map((candidate) => tryAlign(candidate));
+        let bestShiftedIndex = 0;
+        for (let index = 1; index < shiftedResults.length; index++) {
+          if (shiftedResults[index].score > shiftedResults[bestShiftedIndex].score) bestShiftedIndex = index;
+        }
+        const bestShifted = shiftedResults[bestShiftedIndex];
+        if (quoteSkipsAFileLine) {
+          alignment = "shifted";
+          shiftDelta = nextFile - best.walkEnd;
+          const throughSuffix = tryAlign(nextFile + 1);
+          const end = throughSuffix.score > 0 ? throughSuffix.endFileIdx : nextFile + 1;
+          regionEnd = Math.max(regionEnd, Math.min(end, best.start + MAX_CLOSEST_DIFF_REGION_LINES));
+        } else if (bestShifted.score > atSameLength.score && bestShifted.score === suffixIdx.length) {
+          alignment = "shifted";
+          shiftDelta = shiftedCandidates[bestShiftedIndex] - (best.walkEnd + 1);
+          regionEnd = Math.max(regionEnd, Math.min(bestShifted.endFileIdx, best.start + MAX_CLOSEST_DIFF_REGION_LINES));
+        } else if (atSameLength.score > 0) {
+          alignment = "aligned";
+          regionEnd = Math.max(regionEnd, Math.min(atSameLength.endFileIdx, best.start + MAX_CLOSEST_DIFF_REGION_LINES));
+        }
+      }
+    }
+    if (alignment === "shifted") {
+      parts.push("The remainder of the quote re-aligns only at a SHIFTED position \u2014 an extra, missing, or duplicated line changed the line count; fixing the quoted difference line alone cannot repair the quote.");
+    } else if (alignment === "unknown") {
+      parts.push("The remainder of the quote does not re-align within a few lines of the difference \u2014 the quote is likely stale; re-read the region and re-quote it.");
+    }
+    const quoteSpanLines = qLines.length - firstNonBlank + (alignment === "shifted" ? shiftDelta : 0);
+    regionEnd = Math.max(regionEnd, Math.min(best.start + quoteSpanLines, best.start + MAX_CLOSEST_DIFF_REGION_LINES));
   } else {
     parts.push("All non-empty lines match by trimmed content \u2014 the mismatch is leading whitespace or blank-line placement.");
   }
+  parts.unshift(`Closest match: file lines ${regionStart}\u2013${regionEnd} (${best.matched}/${total} lines matched by trimmed content).`);
+  if (best.firstDiff && alignment !== "unknown" && regionEnd - regionStart + 1 <= MAX_CLOSEST_DIFF_REGION_LINES) {
+    const regionText = fileLines.slice(best.start, Math.min(regionEnd, fileLines.length)).join("\n");
+    const { diff } = generateDiffString(regionText, oldText);
+    const body = diff.split("\n").slice(3);
+    if (body.length > 0) {
+      const shown = body.slice(0, MAX_CLOSEST_DIFF_LINES);
+      const suffix = body.length > shown.length ? ["\u2026"] : [];
+      parts.push(`Diff of the region against the quote (- file, + quote):
+${[...shown, ...suffix].join("\n")}`);
+    }
+  }
   return parts.join(" ");
 }
 function generateDiffString(oldContent, newContent, contextLines = 4) {
@@ -16743,6 +17721,9 @@ export {
   registerInteractionHandler,
   hasInteractionHandler,
   requestInteraction,
+  AttentionCoordinator,
+  interactionAttentionReason,
+  interactionAttentionResolution,
   AGENTS_CONTEXT_FILE_NAME,
   buildProjectContextSection,
   attachAgentEventsToSessionTrace,
@@ -16772,6 +17753,7 @@ export {
   modalityForReadFileUnderstandingKind,
   createReadFileUnderstandingHandler,
   formatSkillSummariesForPrompt,
+  SUBAGENT_SESSION_RECORD_VERSION,
   classifyShellCommand,
   interpretShellExit,
   createSubagentCapability,