@cydm/pie 2.6.5 → 2.6.6

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

@@ -2,8 +2,9 @@ import { createRequire as __createRequire } from "node:module"; const require =
 import {
   Agent,
   getToolCallerIdentity
-} from "./chunk-AETQBDEG.js";
+} from "./chunk-KEARZX6F.js";
 import {
+  AssistantMessageEventStream,
   FileSystemGateway,
   completeSimple,
   detectPlatform,
@@ -11,7 +12,7 @@ import {
   getPlatformConfig,
   hashText,
   streamSimple
-} from "./chunk-5OXH6NUH.js";
+} from "./chunk-G5B6D35K.js";
 import {
   Type
 } from "./chunk-XXGYUYXI.js";
@@ -1070,6 +1071,73 @@ 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/bash-policy.ts
 var DESTRUCTIVE_PATTERNS = [
   { pattern: /\bgit\s+reset\s+--hard\b/, warning: "may discard uncommitted changes", commandClass: "git_destructive" },
@@ -1404,6 +1472,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 +1483,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)) {
@@ -1540,8 +1624,13 @@ function subagentOutputBudget(model) {
   return Math.min(model.maxTokens || 8192, 16384);
 }
 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 +1649,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) {
@@ -1750,10 +1836,13 @@ ${formatSkillsForPrompt(deps.skills ?? [])}`;
     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) {
@@ -1911,25 +2000,6 @@ 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 }
-    );
-  });
-}
 async function runWithConcurrencyLimit(jobs, limit) {
   let next = 0;
   const workers = Array.from({ length: Math.max(1, Math.min(limit, jobs.length)) }, async () => {
@@ -2018,24 +2088,23 @@ 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);
+        if (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;
+        await runSubagentWithProgress(deps, task, toolContext.reportProgress, signal);
       };
       await runWithConcurrencyLimit(
         tasks.map((task) => () => runTask(task)),
@@ -4987,6 +5056,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 +5312,8 @@ var AgentSessionAutoContinueController = class {
   }
   options;
   autoContinueTimer;
+  generation = 0;
+  cancelExecutionWait;
   pendingAutoContinue;
   resolvePendingAutoContinue;
   get hasPendingAutoContinue() {
@@ -5101,21 +5329,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 +5371,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 +5386,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 +5443,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 +5584,7 @@ async function runPreRequestAutoCompact(params) {
   try {
     await params.runAutoCompact();
   } catch {
-    params.setRecoveryState("none");
+    if (params.isCurrent?.() !== false) params.setRecoveryState("none");
   }
 }
 
@@ -5518,6 +5758,7 @@ var AgentSessionQueueDispatcher = class {
   }
   options;
   dispatchTimer;
+  generation = 0;
   pendingDispatch;
   resolvePendingDispatch;
   get hasPendingDispatch() {
@@ -5532,25 +5773,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 +5813,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 +5827,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 +5851,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);
@@ -6015,9 +6266,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,
@@ -6250,6 +6506,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 +6517,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 +6531,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 +6544,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 +6562,7 @@ async function runAgentSessionControllerAutoCompact(params) {
     params.emit({ type: "turn_settled" });
     throw error;
   } finally {
-    params.clearPendingFailure();
+    if (params.isCurrent?.() !== false) params.clearPendingFailure();
   }
 }
 
@@ -6324,8 +6583,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 +6613,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 +6691,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 +6723,30 @@ 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.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 +6764,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 +6794,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 +6804,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 +6872,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 +6892,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 +6919,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,11 +6960,11 @@ 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, {
+      this.pendingEndOperations.track(() => this.handleTurnEndRuntimePolicies(event.message, event.toolResults).catch((error) => handleTurnEndPolicyThrow((event2) => this.emit(event2), error, {
         recoveryWasActive: this.isRecoveryActive(),
         cancelPendingRecovery: () => {
           this.retryController.cancel();
@@ -6652,11 +6973,15 @@ var AgentSessionController = class {
         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 });
     }
   }
@@ -6712,27 +7037,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 +7063,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 +7076,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 +7101,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 +7112,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 +7301,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 +9266,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 +9398,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 +9587,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 +9637,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 +9658,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 +9680,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 +9706,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 +9737,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 +10147,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 +10169,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 +10202,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;
@@ -9944,6 +10434,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()) {
@@ -10061,7 +10554,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 +10564,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 +17315,9 @@ export {
   registerInteractionHandler,
   hasInteractionHandler,
   requestInteraction,
+  AttentionCoordinator,
+  interactionAttentionReason,
+  interactionAttentionResolution,
   AGENTS_CONTEXT_FILE_NAME,
   buildProjectContextSection,
   attachAgentEventsToSessionTrace,