Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

160 KB
Raw Blame
/**
 * Session — 单次 agent 会话的上层包装。
 *
 * 职责:
 * - 统一暴露能力(capabilities)+ runtime 切换接口
 * - 把 BaseAgent 的事件流转发给订阅者
 * - 提供 UI 友好的事件订阅 API(不强迫 UI 自己消费 AsyncIterable)
 * - 管理 InteractionResolver 注入(permission / ask_user_question / plan_review 三合一)
 *
 * 不持有 LLM client、不做决策、不存任何业务记忆 —— 这些是未来 MetaAgent 的事。
 */

import { appendAutoReviewUserIntent, type AutoReviewUserIntent } from './agents/shared/auto-review-decision.js';
import { randomUUID } from 'node:crypto';
import { ToolLoopGuard } from './agents/shared/loop-guard.js';
import { AsyncUserQuestions } from './agents/shared/async-user-questions.js';
import {
  ToolLoopMonitor,
  type HardToolLoopVerdict,
  type ToolLoopReviewer,
} from './agents/shared/tool-loop-review.js';
import type { ReviewableAction } from './agents/shared/auto-review.js';
import type { AutoReviewDecision } from './agents/shared/auto-review-decision.js';

import {
  extractNonSecretErrorSignals,
  redactSensitiveText,
} from '@cindy/maker-shared/error-redaction';
import type { SessionGracefulStopState } from '@cindy/maker-shared/session-activity';
export type { SessionGracefulStopState } from '@cindy/maker-shared/session-activity';
import type {
  Effort,
  PermissionMode,
  AgentKind,
  UserMessage,
} from './types/common.js';
import type {
  Capabilities,
  ManualCompactResult,
  NavigateSessionTreeOptions,
  NavigateSessionTreeResult,
  SessionTreeSnapshot,
} from './types/capabilities.js';
import { NotSupportedError } from './types/capabilities.js';
import type { VisionBridgeHook } from './types/vision-bridge.js';
import type {
  AgentEvent,
  AskUserQuestionItem,
  InteractionRequest,
  InteractionDecision,
  RewindCommitOptions,
  RewindCommitResult,
  UsageSnapshot,
  RewindFilesResult,
  SendOrigin,
} from './types/events.js';
import { isTerminalAgentErrorEvent, parseToolLoopErrorDetails, isTurnWatchdogLivenessEvent } from './types/events.js';
import type { ContextUsageData } from './types/context-usage.js';
import type { PiRuntimeCapabilityManifest } from './types/pi-runtime-capabilities.js';
import type {
  AgentMcpServerToolsReport,
  AgentSessionHandle,
  PiModelSwitchPreview,
  AgentSessionTeardownOptions,
  BackgroundTaskSnapshot,
  SendOptions,
  StartSessionOptions,
  TurnContinuationState,
} from './agents/base-agent.js';
import {
  AUTO_REVIEW_SOURCE_CONTENT,
  ASYNC_QUESTION_ANSWER,
  AUTO_REVIEW_USER_INTENT,
  TurnDispatchRejectedError,
  TurnDispatchUnconfirmedError,
} from './agents/base-agent.js';
import { formatManagedImageReferences } from './agents/shared/managed-image-reference.js';
import type { Logger } from './interfaces/logger.js';

export type SessionStatus = 'active' | 'aborting' | 'closed' | 'error';

export interface PermissionModeState {
  mode: PermissionMode | null;
  generation: number;
}

export type SessionEventListener = (event: AgentEvent) => void;
export type SessionStatusListener = (status: SessionStatus) => void;
export type InteractionRequestListener = (req: InteractionRequest, signal?: AbortSignal) => Promise<InteractionDecision>;

/**
 * turn 零事件看门狗阈值(ms)。turn 在跑、却连续这么久**没有产品进展**,视为整条
 * 链路已死,中断本轮而不是永远转圈。env `XDT_SESSION_TURN_STALL_MS` 覆盖,0 关闭。
 *
 * 与 agent 层 watchdog 的分工:各 agent 内部的 upstream-idle watchdog 只盯"球在上游
 * 却不回话"(claude-code 30min / codex 30min),它们在**工具执行期间刻意不计时** ——
 * 因此工具自己 hang(MCP 卡住、SDK↔子进程 stdio 通道 wedge)时没有任何机制兜底,
 * turn 可以永久挂着。这一层就是兜那个洞:不区分球在谁手里,只看有没有产品进展。
 * `status` / `account_usage` 是传输层或用量心跳,不算进展(见 isTurnWatchdogLivenessEvent)。
 *
 * 45min 刻意大于 agent 层的 30min,保证正常情况下 agent 自己先自愈、不被抢跑;
 * 只有 agent 层也失灵才轮到这里。
 *
 * 误杀防护(见 armTurnStallWatchdog):等用户回应交互(权限询问 / AskUserQuestion /
 * plan review)期间、以及有后台任务在跑期间都不计时 —— 那些场景没有事件是正常的。
 */
const DEFAULT_TURN_STALL_MS = 45 * 60_000;

/**
 * 看门狗 abort 之后复核"turn 真的停了吗"的宽限(ms)。
 *
 * 为什么必须复核:各 agent 的 abort 在中断失败时都只记日志、**不改** turn-in-flight
 * 状态(claude-code 的 `q.interrupt()` 抛错、codex 的 app-server 两次 ack 超时都是
 * 这样)。此时 handle.isTurnRunning() 恒 true,而终态 error 已经推给上层收口 ——
 * 之后每一条 send 都被 in-flight guard 拒掉,会话彻底不可用,看门狗等于"报告已恢复
 * 但什么都没恢复"(review #944 第三轮)。
 *
 * 复核发现 turn 仍在跑就关闭会话:下一次 send 由 Maker 的 lazy create 重建 handle
 * (与 handle 自然死亡后的路径一致,见 runEventLoop 尾部注释),这是唯一不依赖各 agent
 * 自己实现重建的通用出路。
 *
 * 10s 是给 abort 的正常收口留的余量:interrupt 成功后 turn 的终态事件要经 SDK drain
 * → translator → 事件流才让 isTurnRunning 翻 false,abort() resolve 的那一刻通常还没到。
 */
export const STALL_ABORT_RECOVERY_GRACE_MS = 10_000;

/**
 * 手动 abort(用户按 Stop)之后的复核宽限。
 *
 * agent 层的 abort() 已自带 interrupt 超时(10s) + turnInFlight 即刻清除;
 * 超时后走 q.close() → U2 兜底收口。本宽限是最后的保险:只保 agent 层 timeout
 * 和 q.close() 都失败(极度罕见)的极端情况。从 60s 缩到 15s, 与 agent 层互不叠加,
 * 端到端最长不超过 15s(review #944 第十一轮末尾调优)。
 */
export const MANUAL_ABORT_RECOVERY_GRACE_MS = 15_000;
/**
 * The same Codex tool call starting again sooner than this cannot be a new model
 * response (one sampling takes seconds): it is a script repeating it in a burst.
 */
const CODEX_BURST_REPEAT_GAP_MS = 2_000;

/** Shared confirmation budget for provider interrupt ACK and send acceptance. */
const GRACEFUL_STOP_CONFIRMATION_TIMEOUT_MS = 5_000;

/**
 * Terminal error message when this host closes a session while its turn is still running.
 * Hosts match it to tell a local close apart from the agent dying on its own.
 */
export const SESSION_CLOSED_MID_TURN_MESSAGE = 'Session closed before the current turn delivered a terminal event';

/**
 * turn 零事件看门狗的计时分片长度。额度按片累加,片尾核对真实经过时间,
 * 借此把系统挂起(合盖睡眠)的那段排除掉 —— 见 armTurnStallSlice。
 */
const TURN_STALL_SLICE_MS = 60_000;

/**
 * 一个计时分片的实际耗时超出片长这么多 → 判为进程被系统挂起过,该片不计入额度。
 * 与 maker-scheduler 的 SUSPEND_GAP_MS 同量级:远大于正常的事件循环抖动。
 */
const TURN_STALL_SUSPEND_GAP_MS = 30_000;
/** Terminal error 的尾部 drain 宽限;超时后关闭句柄,下一次 send 由 Maker 重建。 */
const TERMINAL_ERROR_DRAIN_GRACE_MS = 250;

function parseTurnStallMs(raw: string | undefined): number {
  if (raw === undefined || raw === '') return DEFAULT_TURN_STALL_MS;
  const n = Number(raw);
  if (!Number.isFinite(n) || n < 0) return DEFAULT_TURN_STALL_MS;
  return Math.floor(n);
}

/** Launch-only caller preferences. Live controls and grants have separate authorities. */
export type SessionStartupPreferences = Readonly<Pick<StartSessionOptions,
  'userPrompt' | 'makerMemoryEnabled' | 'displayReasoning'>>;

export interface SessionOptions {
  hostStartupPreferences?: SessionStartupPreferences;
  id: string;
  /** 与 Agent MCP context 同源的本次内存实例代号;省略时由 Session 自铸。 */
  sessionInstanceId?: string;
  agentKind: AgentKind;
  workDir: string;
  handle: AgentSessionHandle;
  capabilities: Capabilities;
  logger: Logger;
  /** Runtime permission mode used to create/resume the underlying handle. */
  permissionMode?: PermissionMode;
  /**
   * 远端 SSH 主机的 alias (来自 `@cindy/maker-remote-ssh` ConnectionPool)。
   * 非空 → 这个 session 实际跑在远端机器上, workDir 是远端机器上的路径。
   * 主进程的 send 路径用它判断 "local fs guard 应不应该跑" — 远端 workdir
   * 是不可能存在于本地 fs 的, 没必要也不该 stat。
   */
  remoteHostId?: string | null;
  /**
   * 同账号另一台电脑(或 `share:` 分享来源)上运行 Agent 时的设备 id,与 remoteHostId 互斥。
   * 主进程的发送边界用它判断供应商目录在对端:本机目录不能裁决这类会话的显式来源。
   */
  agentDeviceId?: string | null;
  /**
   * turn 零事件看门狗阈值(ms)。省略 = env / DEFAULT_TURN_STALL_MS;0 = 关闭。
   * 主要供测试注入短阈值,宿主正常不传。
   */
  turnStallMs?: number;
  /**
   * 可选:视觉桥钩子(层 B)。host 注入后,session.send 在组装 UserMessage、交给
   * handle 前调用一次,把用户贴图替换为视觉描述。host 不注入 = 完全跳过,字节级零干扰
   * (见 docs/vision-bridge-design.md 层 B)。
   */
  visionBridge?: VisionBridgeHook;
  /**
   * 可选:工具循环疑似命中时的辅助模型复核入口(host 注入)。缺省 = 疑似即中断,
   * 与未接入复核前一致。
   */
  toolLoopReviewer?: ToolLoopReviewer;
}

function redactEventForListeners(event: AgentEvent): AgentEvent {
  if (!event.data || typeof event.data !== 'object') return event;

  const data = event.data as Record<string, unknown>;
  const safeData = { ...data };
  let changed = false;
  if (event.type === 'error' && typeof safeData.message === 'string') {
    const signals = extractNonSecretErrorSignals(safeData.message);
    if (safeData.errorStatus == null && signals.errorStatus !== undefined) {
      safeData.errorStatus = signals.errorStatus;
      changed = true;
    }
    if (safeData.usageLimit == null && signals.usageLimit) {
      safeData.usageLimit = true;
      changed = true;
    }
  }
  const stringKeys = ['message', 'sdkError', 'summary'];
  if (event.type === 'tool_result_full' && safeData.isError === true) {
    stringKeys.push('fullText');
  }
  for (const key of stringKeys) {
    if (typeof safeData[key] === 'string') {
      const redacted = redactSensitiveText(safeData[key]);
      if (redacted !== safeData[key]) {
        safeData[key] = redacted;
        changed = true;
      }
    }
  }

  if (
    event.type === 'agent_task_update' &&
    safeData.status === 'failed' &&
    safeData.raw &&
    typeof safeData.raw === 'object'
  ) {
    safeData.raw = redactNestedStrings(safeData.raw, () => {
      changed = true;
    });
  }

  if (event.type === 'done' && safeData.raw && typeof safeData.raw === 'object') {
    const raw = { ...(safeData.raw as Record<string, unknown>) };
    if (raw.error && typeof raw.error === 'object') {
      raw.error = redactNestedStrings(raw.error, () => {
        changed = true;
      });
    }
    if (raw.status === 'failed' && Array.isArray(raw.items)) {
      raw.items = redactNestedStrings(raw.items, () => {
        changed = true;
      });
    }
    safeData.raw = raw;
  }

  return changed ? ({ ...event, data: safeData } as AgentEvent) : event;
}

function redactNestedStrings(value: unknown, onChange: () => void): unknown {
  if (typeof value === 'string') {
    const redacted = redactSensitiveText(value);
    if (redacted !== value) onChange();
    return redacted;
  }
  if (Array.isArray(value)) {
    return value.map((item) => redactNestedStrings(item, onChange));
  }
  if (!value || typeof value !== 'object') return value;

  const copy: Record<string, unknown> = {};
  for (const [key, child] of Object.entries(value)) {
    copy[key] = redactNestedStrings(child, onChange);
  }
  return copy;
}

/**
 * Vision bridging replaces image blocks before the provider adapter sees them.
 * Preserve the Host-managed attachment identities as ordinary per-turn text,
 * without exposing them to the external vision backend or changing image bytes.
 */
function appendManagedImageReferences(
  source: UserMessage,
  bridged: UserMessage,
): UserMessage {
  const references = formatManagedImageReferences(source.content);
  if (!references) return bridged;
  if (typeof bridged.content === 'string') {
    return {
      ...bridged,
      content: bridged.content ? `${bridged.content}\n${references}` : references,
    };
  }
  return {
    ...bridged,
    content: [...bridged.content, { type: 'text', text: references }],
  };
}

export interface SessionSendOptions extends SendOptions {
  /**
   * Host-owned authorization refresh after all preparation, before vendor dispatch.
   * Returning undefined preserves the existing intent; an empty intent still clears it.
   */
  resolveAutoReviewUserIntent?: () => Promise<AutoReviewUserIntent | undefined>;
  /**
   * Turn reservation 建立后的原子准备钩子。
   *
   * Session 在 active/running 守卫通过并占住本轮之后、provider option preflight
   * 之前调用。仅用于让 host 临时收紧 preflight 本身依赖的 live session 状态;
   * 后续校验或派发仍可能失败,因此调用方必须在自己的终态路径恢复该状态。
   */
  afterTurnReserved?: () => void | Promise<void>;
  /**
   * Provider 启动前的安全屏障。
   *
   * Session 在 active/running 守卫通过、turn reservation 建立后调用;只有该
   * hook 成功完成,才会继续执行产品层 onAccepted 与 vendor handle.send。
   * 适合 durable queue 用 CAS 把任务从 dispatching 标成 accepted_running:
   * hook 失败时 provider/model/tool 均不会启动。
   */
  beforeProviderStart?: () => void | Promise<void>;
  /**
   * 产品层 accepted hook。
   * Session 在 active/running 守卫通过、turn reservation 建立后调用;
   * hook 完成后才启动 vendor handle。
   */
  // Reservation cancellation reaches host preparation (for example Git
  // snapshots); returning from a cancelled hook never authorizes dispatch.
  onAccepted?: (signal?: AbortSignal) => void | Promise<void>;
  /** Reservation 建立后立刻回调本轮 turn generation;host 必须用它绑定 leftover,不能等 send 返回后再读最新 generation。 */
  onTurnReserved?: (turnGeneration: number) => void;
  /**
   * vendor dispatch 前最后一个同步边界。用于让 host 在底层可能产生新 turn
   * callback 之前,精确切换自己的 turn-scoped 状态。
   */
  onDispatching?: () => void;
}

export interface SessionTurnLifecycleObserver {
  /** Last synchronous authorization check; no asynchronous work may follow before handle.send. */
  onDispatching?(): void;
  /** Awaited after option validation and before any provider-owned start hook or send. */
  beforeProviderStart(turnGeneration: number): void | Promise<void>;
  /** Called when a prepared generation never crosses the provider dispatch boundary. */
  onUndispatched(turnGeneration: number): void | Promise<void>;
  /** Called before event listeners for a foreground unclaimed done or terminal error. */
  onTerminal(input: {
    turnGeneration: number;
    event: AgentEvent;
    isCurrentGeneration: boolean;
  }): void | Promise<void>;
  /**
   * Called synchronously, before event listeners see its first event, when the provider starts a
   * turn on its own: top-level output after this generation's product terminal, with no
   * `Session.send` reserved and no `Session.steer` carried over (e.g. Claude Code waking itself on a
   * background task notification). The turn reuses the previous generation and has no turnOrigin.
   * Claimed continuations never reach here: their `done` is not a product terminal.
   */
  onProviderInitiatedTurn?(turnGeneration: number): void;
}

/**
 * Session.send 的产品层结果。
 * accepted=true 表示 vendor handle.send 已经跨过 dispatch 边界;onAccepted 只表示
 * 产品层持久化 hook 执行过,不能单独当作 turn 已启动。
 */
export type SessionSendResult =
  | { accepted: true }
  | {
      accepted: false;
      reason: 'cancelled-before-dispatch' | 'provider-rejected-before-dispatch';
    };

export interface SessionTurnControlSnapshot {
  active: boolean;
  turnGeneration: number | null;
  activeToolCount: number;
  pendingInteractionCount: number;
  gracefulStopState: SessionGracefulStopState;
}

export type SessionGracefulStopResult =
  | { status: 'no-active-turn' }
  | { status: 'unsupported'; reason: 'provider-not-supported' }
  | { status: 'waiting-for-safe-point'; turnGeneration: number }
  | { status: 'requested'; turnGeneration: number }
  | { status: 'unconfirmed'; turnGeneration: number; reason: string };

type TurnControlState = {
  generation: number;
  toolLoopMonitor: ToolLoopMonitor | null;
  pendingToolLoop: { toolUseId: string; verdict: HardToolLoopVerdict } | null;
  /** 已送达完整结果、尚未送达结果摘要的工具;终态错误必须排在它们的摘要之后。 */
  awaitingToolResultSummaries: Set<string>;
  activeToolIds: Set<string>;
  anonymousActiveTools: number;
  pendingInteractionToolIds: Map<string, number>;
  gracefulStopState: SessionGracefulStopState;
  gracefulStopPromise: Promise<SessionGracefulStopResult> | null;
};

type SendReservation = {
  generation: number;
  phase: 'accepting' | 'dispatching';
  /** handle.send() has resolved as accepted. Until then, late N terminals stay off N+1. */
  accepted: boolean;
  cancelled: boolean;
  abortController: AbortController;
  settled: Promise<SendReservationOutcome>;
  settle(outcome: SendReservationOutcome): void;
  gracefulStopPromise: Promise<SessionGracefulStopResult> | null;
};

type SendReservationOutcome = 'accepted' | 'undispatched' | 'unconfirmed';

function createSendReservation(generation: number): SendReservation {
  let resolveSettled!: (outcome: SendReservationOutcome) => void;
  const settled = new Promise<SendReservationOutcome>((resolve) => {
    resolveSettled = resolve;
  });
  return {
    generation,
    phase: 'accepting',
    accepted: false,
    cancelled: false,
    abortController: new AbortController(),
    settled,
    settle: resolveSettled,
    gracefulStopPromise: null,
  };
}

export class Session {
  /** Caller preferences before generated context; memory-only recovery input. */
  readonly hostStartupPreferences?: SessionStartupPreferences;
  readonly id: string;
  /** business id 可复用;instanceId 精确标识本次内存 Session incarnation。 */
  readonly instanceId: string;
  readonly agentKind: AgentKind;
  readonly workDir: string;
  readonly capabilities: Capabilities;
  /** 见 SessionOptions.remoteHostId。 */
  readonly remoteHostId: string | null;
  /** 见 SessionOptions.agentDeviceId。 */
  readonly agentDeviceId: string | null;

  private readonly handle: AgentSessionHandle;
  private readonly logger: Logger;
  /** 视觉桥钩子(层 B)。缺省 = 未启用,send 完全跳过。 */
  private readonly visionBridge: VisionBridgeHook | undefined;
  private readonly toolLoopReviewer: ToolLoopReviewer | undefined;
  private toolLoopUserIntent: AutoReviewUserIntent | undefined;
  private permissionModeStateValue: PermissionModeState;
  private permissionModeChangeChain: Promise<void> = Promise.resolve();
  private permissionModeChangesInFlight = 0;
  /** Invalidation only; the provider remains the sole owner of the live Plan flag. */
  private planModeGeneration = 0;
  private planModeChangesInFlight = 0;
  /** User/API permission changes, serialized separately so host restores cannot deadlock. */
  private externalPermissionModeChangeChain: Promise<void> = Promise.resolve();
  private externalPermissionModeChangesInFlight = 0;
  /** Host-owned logical turn leases that outlive a vendor's transient idle edge. */
  private readonly hostTurnLeases = new Set<Promise<void>>();
  private readonly eventListeners = new Set<SessionEventListener>();
  private readonly runtimeRecoveryListeners = new Set<SessionEventListener>();
  private readonly statusListeners = new Set<SessionStatusListener>();
  private interactionListener: InteractionRequestListener | null = null;
  private turnLifecycleObserver: SessionTurnLifecycleObserver | null = null;
  /** Generation whose turn after the product terminal (no send) is currently open. */
  private unsolicitedTurnGeneration: number | null = null;
  /**
   * Generation that accepted a steer. Claude may run a steer that missed the ending turn as a new
   * SDK turn without a send; that turn belongs to the steering input, not to the provider.
   */
  private steerAcceptedGeneration: number | null = null;
  private status: SessionStatus = 'active';
  /**
   * 同一 Session 的并发 close 共享一次底层关闭过程。renderer 与 main 生命周期钩子可能
   * 同时请求关闭;所有调用方都必须等到 transport / 子进程真正释放后才能继续回收 worktree。
   */
  private closePromise: Promise<void> | null = null;
  /** close/detach 一进入同步入口就置位,早于底层 handle 的异步关闭完成。 */
  private terminationStarted = false;
  /**
   * The runtime itself began this teardown (dead handle, crashed loop, failed
   * dispatch, abort / terminal-error recovery). External close()/closeIfIdle()/
   * detach() callers never set it, so a direct product close is not mistaken
   * for a self-close even when no Maker close reason was recorded.
   */
  private runtimeInitiatedClose = false;
  private eventLoopStarted = false;
  /**
   * 最近一次已观察到的终态事件属于哪个 turn generation;事件迭代器可能在上一轮
   * 开始等待、下一轮 dispatch 后才返回旧事件,不能用一个 bool 判断是否已收口。
   */
  private terminalEventObservedGeneration: number | null = null;
  /** 与 terminalEventObservedGeneration 成对;同 generation 的 error 不被后续 done 尾巴改写。 */
  private terminalEventObservedKind: 'done' | 'error' | null = null;
  private terminalEventObservedErrorMessage: string | null = null;
  private terminalEventObservedErrorSignals: {
    reason?: string;
    sdkError?: string;
    errorStatus?: number;
    toolLoop?: import('./types/events.js').ToolLoopErrorDetails;
    /** Codex app-server 的结构化错误 tag(如 badRequest / cyberPolicy)。 */
    codexErrorInfo?: string;
  } | null = null;
  /** Survives N+1 reservation clearing the current snapshot; leftover done must not adopt. */
  private lastObservedTerminalGeneration: number | null = null;
  private lastObservedTerminalKind: 'done' | 'error' | null = null;
  /**
   * N+1 reservation 窗口内观察到的前一轮前台终态。lost-callback 时 turn N 的
   * done/error 可能在直接 N+1 `handle.send()` 待处理期间才 fan-out;当时
   * `turnGeneration` 已是 N+1,不能写入当前 generation 快照。拒绝回滚时再提升
   * 到 N,避免 leftover `activeTurn` 永久失去回收证据。
   */
  private terminalObservedDuringReservation: {
    kind: 'done' | 'error';
    message: string | null;
    signals: {
      reason?: string;
      sdkError?: string;
      errorStatus?: number;
    } | null;
  } | null = null;
  /** 终态 error 后等待 provider 尾部 done;避免旧尾事件冒领下一轮。 */
  private terminalErrorDrainGeneration: number | null = null;
  private terminalErrorDrainTimer: ReturnType<typeof setTimeout> | null = null;
  private sendReservation: SendReservation | null = null;
  /**
   * N+1 send that has reserved a generation but not yet accepted.
   * Survives `releaseSendReservationIfObserved()` clearing the reservation
   * after the handle flips running; leftover N tails must not adopt as N+1.
   */
  private unacceptedSendGeneration: number | null = null;
  /** True while runEventLoop is blocked in iterator.next(). */
  private eventLoopAwaiting = false;
  /** The blocked next() that was pending when the current send entered handle.send. */
  private inFlightSendOwnsBlockedWait = false;
  /** Last resolve() returned the in-flight send generation. */
  private lastResolvedInFlightSend = false;
  /** True from handle.send() start until that send settles. */
  private insideProviderSendSync = false;
  /** Keep a leftover status/done tail on the generation that started it. */
  private staleTerminalQueuedGeneration: number | null = null;
  /** Previous turn generation, kept until leftover tail or new-turn progress. */
  private pendingPriorGeneration: number | null = null;
  /** Generation that already emitted foreground running. */
  private sawCurrentTurnRunningGeneration: number | null = null;
  /**
   * 当前进行中 turn 的发起来源(来自 send 的 opts.origin)。事件 fan-out 前打到
   * AgentEvent.turnOrigin 上,turn 终止(isTerminalTurnEvent)后清空 — 共享
   * session(心跳 + 远程控制)下区分 per-turn 归属。null = 未标记来源(默认)。
   */
  private currentTurnOrigin: SendOrigin | null = null;
  /** Host-owned per-turn correlation, kept beside origin and cleared at the terminal boundary. */
  private currentTurnAttemptToken: number | null = null;
  // ── turn 零事件看门狗(见 DEFAULT_TURN_STALL_MS)────────────────────────
  private readonly turnStallMs: number;
  private turnStallTimer: ReturnType<typeof setTimeout> | null = null;
  private turnStallDiagnosticState = 'idle';
  private turnStallLastDiagnosticAt = 0;
  /** 还需要"清醒地"静默多久才判卡死;按分片递减(见 armTurnStallSlice)。 */
  private turnStallRemainingMs = 0;
  /** 当前分片的起始壁钟时刻;片尾据此识别系统挂起。 */
  private turnStallSliceStartedAt = 0;
  /** 正在等用户回应的交互数;>0 期间不计 stall 额度(没事件是正常的)。 */
  private pendingInteractions = 0;
  /** Blocking question cards take precedence over optional async cards. */
  private pendingUserQuestions = 0;
  /** 最近一次 fan-out 事件的时刻,仅用于日志诊断。 */
  private lastEventAt = 0;
  /**
   * turn 代号:每次 send 建立 reservation 时 +1。看门狗的善后动作(尤其
   * recoverIfTurnStillRunning 的"关掉会话")必须绑定到超时的那一个 turn,否则宽限期内
   * 新起的健康 turn 会被误杀 —— `isTurnRunning()` 只回答"有 turn 在跑",不回答"是不是
   * 那一个"(review #944 第七轮 P1)。
   *
   * 只在 reservation 创建处自增就够:send 入口有 `isTurnRunning()` 守卫,卡死的 turn
   * 还在跑时新 send 会被 SESSION_RUNNING 拒掉、拿不到 reservation。换句话说代号变了
   * 就一定意味着"卡死那个 turn 已经停了、这是新活儿"。
   */
  private turnGeneration = 0;
  /** 已为哪个 turn 代号排过 abort 复核;同一 turn 上重复 abort 不重复排。 */
  private abortRecoveryScheduledFor: number | null = null;
  private lastEventType: string | null = null;
  /** 优雅停止所需的 turn 控制事实;不承担 UI/MCP 会话状态投影。 */
  private turnControlState: TurnControlState | null = null;
  private readonly asyncUserQuestions: AsyncUserQuestions;

  constructor(opts: SessionOptions) {
    this.hostStartupPreferences = opts.hostStartupPreferences
      ? Object.freeze({ ...opts.hostStartupPreferences }) : undefined;
    this.id = opts.id;
    this.instanceId = opts.sessionInstanceId ?? generateSessionId();
    this.agentKind = opts.agentKind;
    this.workDir = opts.workDir;
    this.handle = opts.handle;
    this.capabilities = opts.capabilities;
    this.remoteHostId = opts.remoteHostId ?? null;
    this.agentDeviceId = opts.agentDeviceId ?? null;
    this.logger = opts.logger.child(`s:${this.id}`);
    this.permissionModeStateValue = {
      mode: opts.permissionMode ?? null,
      generation: 0,
    };
    this.turnStallMs =
      opts.turnStallMs ?? parseTurnStallMs(process.env.XDT_SESSION_TURN_STALL_MS);
    this.visionBridge = opts.visionBridge;
    this.toolLoopReviewer = opts.toolLoopReviewer;
    this.asyncUserQuestions = new AsyncUserQuestions({
      isActive: (generation) => this.status === 'active' && !this.terminationStarted
        && generation === this.turnGeneration && this.handle.isTurnRunning?.() === true,
      resolve: (request) => this.interactionListener!(request),
      deliver: (text, signal) => this.steer(text, { signal, [ASYNC_QUESTION_ANSWER]: true }),
      dismiss: (requestId, reason) => this.fanOutEvent({
        type: 'interaction_dismissed', data: { requestId, reason, resolvedAs: 'deny' }, source: this.agentKind,
      }),
      reportError: () => this.fanOutEvent({ type: 'error', source: this.agentKind,
        data: { message: 'Async question answer delivery failed.', isTerminal: false } }),
    });

    // 注入 InteractionResolver 到底层 handle, 转发到 host 维护的 listener。
    // 没接 listener 时按 kind 给出安全默认: 都视作 deny(host 必须接 listener 才能交互)。
    this.handle.setInteractionResolver((req, signal) => this.runHostInteraction(req, async () => {
      if (!this.interactionListener) {
        this.logger.warn('interaction request received but no listener attached, denying', { kind: req.kind, requestId: req.requestId });
        if (req.kind === 'ask_user_question') {
          return { kind: 'ask_user_question', answers: {} };
        }
        if (req.kind === 'plan_review') {
          return { kind: 'plan_review', behavior: 'deny', reason: 'no_listener_attached', dismissed: true };
        }
        return { kind: req.kind, behavior: 'deny', reason: 'no_listener_attached' } as InteractionDecision;
      }
      return await (signal ? this.interactionListener(req, signal) : this.interactionListener(req));
    }));
  }

  // ── 公开 API ─────────────────────────────────────────────────────────────

  /** 当前/最近一次已建立 reservation 的 turn 代号;只用于跨 await 识别是否仍是同一轮。 */
  getTurnGeneration(): number {
    return this.turnGeneration;
  }

  /**
   * 当前 turn generation 已 fan-out 的产品终态类型。
   * none:PI prompt accepted → agent_start 空窗、continuation claim 挡住的 SDK done、
   * 或尚无当前 generation 终态。Host 回收残留 activeTurn 必须认类型:done 才能当
   * 成功结算,error 必须走 recovery,不能靠 live idle + tracker idle 的超时猜测。
   */
  getObservedCurrentTurnTerminal(): {
    kind: 'none' | 'done' | 'error';
    generation?: number;
    message?: string;
    reason?: string;
    sdkError?: string;
    errorStatus?: number;
    toolLoop?: import('./types/events.js').ToolLoopErrorDetails;
    codexErrorInfo?: string;
  } {
    if (
      this.turnGeneration <= 0 ||
      this.terminalEventObservedGeneration !== this.turnGeneration ||
      this.terminalEventObservedKind == null
    ) {
      return { kind: 'none' };
    }
    if (this.terminalEventObservedKind === 'error') {
      return {
        kind: 'error',
        generation: this.turnGeneration,
        ...(this.terminalEventObservedErrorMessage
          ? { message: redactSensitiveText(this.terminalEventObservedErrorMessage) }
          : {}),
        ...(this.terminalEventObservedErrorSignals?.reason
          ? { reason: this.terminalEventObservedErrorSignals.reason }
          : {}),
        ...(this.terminalEventObservedErrorSignals?.sdkError
          ? { sdkError: redactSensitiveText(this.terminalEventObservedErrorSignals.sdkError) }
          : {}),
        ...(typeof this.terminalEventObservedErrorSignals?.errorStatus === 'number'
          ? { errorStatus: this.terminalEventObservedErrorSignals.errorStatus }
          : {}),
        ...(this.terminalEventObservedErrorSignals?.toolLoop
          ? { toolLoop: this.terminalEventObservedErrorSignals.toolLoop }
          : {}),
        ...(this.terminalEventObservedErrorSignals?.codexErrorInfo
          ? { codexErrorInfo: this.terminalEventObservedErrorSignals.codexErrorInfo }
          : {}),
      };
    }
    return { kind: 'done', generation: this.turnGeneration };
  }

  private readRedactedTerminalErrorSnapshot(listenerEvent: AgentEvent): {
    message: string | null;
    signals: {
      reason?: string;
      sdkError?: string;
      errorStatus?: number;
      toolLoop?: import('./types/events.js').ToolLoopErrorDetails;
      codexErrorInfo?: string;
    } | null;
  } {
    const errorData = (listenerEvent.data ?? null) as {
      message?: unknown;
      reason?: unknown;
      sdkError?: unknown;
      errorStatus?: unknown;
      toolLoop?: unknown;
      codexErrorInfo?: unknown;
    } | null;
    const errorMessage = errorData?.message;
    const signals: {
      reason?: string;
      sdkError?: string;
      errorStatus?: number;
      toolLoop?: import('./types/events.js').ToolLoopErrorDetails;
      codexErrorInfo?: string;
    } = {};
    if (typeof errorData?.reason === 'string' && errorData.reason.length > 0) {
      signals.reason = errorData.reason;
    }
    if (typeof errorData?.sdkError === 'string' && errorData.sdkError.length > 0) {
      signals.sdkError = redactSensitiveText(errorData.sdkError);
    }
    if (typeof errorData?.errorStatus === 'number' && Number.isFinite(errorData.errorStatus)) {
      signals.errorStatus = errorData.errorStatus;
    }
    const toolLoop = parseToolLoopErrorDetails(errorData?.toolLoop);
    if (toolLoop) signals.toolLoop = toolLoop;
    // Codex 的结构化 tag 是有界枚举名(translator 只取 tag,不带原文),不需要脱敏。
    if (typeof errorData?.codexErrorInfo === 'string' && /^[A-Za-z][A-Za-z0-9_]{0,63}$/u.test(errorData.codexErrorInfo)) {
      signals.codexErrorInfo = errorData.codexErrorInfo;
    }
    return {
      message: typeof errorMessage === 'string' && errorMessage.length > 0 ? errorMessage : null,
      signals:
        signals.reason ||
        signals.sdkError ||
        signals.errorStatus !== undefined ||
        signals.toolLoop ||
        signals.codexErrorInfo
          ? signals
          : null,
    };
  }

  private rememberReservationWindowPriorTerminal(
    event: AgentEvent,
    listenerEvent: AgentEvent,
  ): void {
    if (event.type === 'error') {
      const snapshot = this.readRedactedTerminalErrorSnapshot(listenerEvent);
      this.terminalObservedDuringReservation = {
        kind: 'error',
        message: snapshot.message,
        signals: snapshot.signals,
      };
      return;
    }
    if (event.type !== 'done') return;
    if (this.terminalObservedDuringReservation?.kind === 'error') return;
    this.terminalObservedDuringReservation = {
      kind: 'done',
      message: null,
      signals: null,
    };
  }

  private consumeReservationWindowPriorTerminal(): {
    kind: 'done' | 'error';
    message: string | null;
    signals: {
      reason?: string;
      sdkError?: string;
      errorStatus?: number;
      toolLoop?: import('./types/events.js').ToolLoopErrorDetails;
    } | null;
  } | null {
    const snapshot = this.terminalObservedDuringReservation;
    this.terminalObservedDuringReservation = null;
    return snapshot;
  }

  async send(message: UserMessage | string, opts?: SessionSendOptions): Promise<SessionSendResult> {
    return this.dispatchSend(message, opts, false);
  }

  /**
   * Host-owned silent-stop continuation. This is the only send admitted while a
   * retiring runtime has claimed the current generation; ordinary `send()` stays
   * rejected so queued/user work cannot run on the snapshot being retired.
   */
  async sendHostTurnContinuation(
    message: UserMessage | string,
    opts?: SessionSendOptions,
  ): Promise<SessionSendResult> {
    return this.dispatchSend(message, opts, true);
  }

  private async dispatchSend(
    message: UserMessage | string,
    opts: SessionSendOptions | undefined,
    allowRetirementContinuation: boolean,
  ): Promise<SessionSendResult> {
    const {
      afterTurnReserved,
      beforeProviderStart,
      onAccepted,
      onDispatching,
      onTurnReserved,
      resolveAutoReviewUserIntent,
      ...handleOpts
    } = opts ?? {};
    const cancelledBeforeReservation = (): SessionSendResult | null =>
      handleOpts.signal?.aborted === true
        ? { accepted: false, reason: 'cancelled-before-dispatch' }
        : null;
    const alreadyCancelled = cancelledBeforeReservation();
    if (alreadyCancelled !== null) return alreadyCancelled;
    // A host may need to keep a logical turn exclusive while the vendor briefly
    // reports idle between a foreground result and background-task continuation.
    // Wait instead of racing that continuation with a new Desktop turn.
    while (this.hostTurnLeases.size > 0) {
      if (await this.waitForGateOrAbort(Promise.all([...this.hostTurnLeases]), handleOpts.signal)) {
        return { accepted: false, reason: 'cancelled-before-dispatch' };
      }
    }
    // Preserve user/API permission change ordering before admitting the next turn.
    while (this.externalPermissionModeChangesInFlight > 0) {
      if (await this.waitForGateOrAbort(this.externalPermissionModeChangeChain, handleOpts.signal)) {
        return { accepted: false, reason: 'cancelled-before-dispatch' };
      }
    }
    // A temporary host permission lease may be restoring immediately after a
    // terminal event. Do not let the next turn reserve the session until that
    // live provider state is settled.
    while (this.permissionModeChangesInFlight > 0) {
      if (await this.waitForGateOrAbort(this.permissionModeChangeChain, handleOpts.signal)) {
        return { accepted: false, reason: 'cancelled-before-dispatch' };
      }
    }
    let msg: UserMessage = typeof message === 'string'
      ? { type: 'user', content: message }
      : message;
    this.logger.debug('send', summarizeUserMessage(msg));
    this.ensureActive();
    // A silent-stop claim keeps this generation alive for Host continuation only.
    // Any other sender (user, queue, Goal, IM) must not start new work on a
    // runtime that is already marked to retire after the current product turn.
    if (this.retirementRequested
      && (this.retirementContinuationGeneration !== this.turnGeneration
        || !allowRetirementContinuation)) {
      throw new Error(`Session ${this.id} is closing`);
    }
    if (this.terminalErrorDrainGeneration !== null) {
      throw this.createSessionRunningError();
    }
    // An auto-resume token remains owned until its terminal event has been fanned out. A vendor
    // may report idle one tick before that event; do not admit a new turn into that gap, or a late
    // old event could be attributed to the new attempt.
    if (this.currentTurnAttemptToken !== null && !this.isTurnRunning()) {
      throw this.createSessionRunningError();
    }
    if (this.isTurnRunning()) {
      throw this.createSessionRunningError();
    }
    // 并发 send 守卫:已有一个 pre-dispatch reservation 在飞(视觉桥 await 阶段,
    // handle 尚未 send → isTurnRunning 仍 false)时,拒绝新 send。否则并发 send 会覆盖
    // this.sendReservation,让先进入视觉桥的 turn 白调外部视觉后端后才发现被取消。
    if (this.sendReservation !== null) {
      throw this.createSessionRunningError();
    }
    // 新一轮 turn 的代号(见 turnGeneration):看门狗的善后动作据此判断"还是不是那个
    // 卡死的 turn",避免误杀宽限期内新起的健康 turn。
    const previousTurnGeneration = this.turnGeneration;
    const previousTerminalObservation = {
      generation: this.terminalEventObservedGeneration,
      kind: this.terminalEventObservedKind,
      message: this.terminalEventObservedErrorMessage,
      signals: this.terminalEventObservedErrorSignals
        ? { ...this.terminalEventObservedErrorSignals }
        : null,
    };
    this.turnGeneration += 1;
    if (
      previousTurnGeneration > 0 &&
      this.terminalEventObservedGeneration !== previousTurnGeneration
    ) {
      this.pendingPriorGeneration = previousTurnGeneration;
    } else {
      this.pendingPriorGeneration = null;
    }
    const reservedTurnGeneration = this.turnGeneration;
    const reservation = createSendReservation(reservedTurnGeneration);
    this.sendReservation = reservation;
    this.unacceptedSendGeneration = reservedTurnGeneration;
    this.terminalObservedDuringReservation = null;
    onTurnReserved?.(reservedTurnGeneration);
    const cleanupExternalAbort = this.attachExternalCancellation(reservation, handleOpts.signal);
    // originInstalled:已越过 dispatch 边界、把本次 origin 装进 currentTurnOrigin。
    // turnDispatched:handle.send 成功、本次 send 真正成为运行中的 turn。
    let originInstalled = false;
    let turnDispatched = false;
    let dispatchConfirmedUndispatched = false;
    let dispatchUnconfirmed = false;
    let previousTurnOrigin: SendOrigin | null = null;
    let previousTurnAttemptToken: number | null = null;
    const turnLifecycleObserver = this.turnLifecycleObserver;
    let turnLifecyclePrepared = false;
    const finishCancelledBeforeDispatch = (): SessionSendResult | null => {
      if (!reservation.cancelled && this.sendReservation === reservation) return null;
      if (this.sendReservation === reservation) this.sendReservation = null;
      if (this.unacceptedSendGeneration === reservedTurnGeneration) {
        this.unacceptedSendGeneration = null;
      }
      return { accepted: false, reason: 'cancelled-before-dispatch' };
    };
    try {
      const cancelledBeforePreparation = finishCancelledBeforeDispatch();
      if (cancelledBeforePreparation !== null) return cancelledBeforePreparation;
      if (afterTurnReserved) await afterTurnReserved();
      const cancelledAfterReservation = finishCancelledBeforeDispatch();
      if (cancelledAfterReservation !== null) return cancelledAfterReservation;
      this.handle.validateSendOptions?.(handleOpts);
      if (turnLifecycleObserver) {
        await turnLifecycleObserver.beforeProviderStart(reservedTurnGeneration);
        turnLifecyclePrepared = true;
      }
      if (beforeProviderStart) await beforeProviderStart();
      const cancelledBeforeAcceptance = finishCancelledBeforeDispatch();
      if (cancelledBeforeAcceptance !== null) return cancelledBeforeAcceptance;
      await onAccepted?.(reservation.abortController.signal);
      this.ensureActive();
      const cancelledAfterAcceptance = finishCancelledBeforeDispatch();
      if (cancelledAfterAcceptance !== null) return cancelledAfterAcceptance;
      // 层 B:用户贴图主动调视觉(视觉桥钩子)。此时 turn guard 已通过、reservation 已
      // 建立——并发 send 已被 isTurnRunning 挡住,不会在 guard 前浪费视觉调用;取消时
      // reservation.abortController.signal 可中止视觉请求。钩子失败/未生效 → 原样透传。
      const autoReviewSourceContent = handleOpts[AUTO_REVIEW_SOURCE_CONTENT] ?? msg.content;
      if (this.visionBridge) {
        // 传入 reservation abort signal:用户 Stop / 外部取消时中止视觉请求,避免浪费
        // 外部视觉调用(多图最坏 图片数×timeout 才返回)。
        msg = await this.bridgedVisionMessage(msg, reservation.abortController.signal);
        // 视觉调用期间可能被外部取消,恢复后必须复查,避免越过取消边界发消息。
        const cancelledAfterVision = finishCancelledBeforeDispatch();
        if (cancelledAfterVision !== null) {
          // 视觉桥对取消静默(不 warn 不 note),此处补一条低噪声 debug 让排障能区分
          //「用户取消/拆离」与「配置没开/模型不命中」——取消类场景唯一留痕点。
          this.logger.debug('vision bridge cancelled before dispatch', {
            sessionId: this.id,
            reason: 'cancelled-before-dispatch',
            model: this.handle.model,
          });
          return cancelledAfterVision;
        }
      }
      if (resolveAutoReviewUserIntent) {
        const intent = await resolveAutoReviewUserIntent();
        if (intent !== undefined) handleOpts[AUTO_REVIEW_USER_INTENT] = intent;
        const cancelledAfterAuthorization = finishCancelledBeforeDispatch();
        if (cancelledAfterAuthorization !== null) return cancelledAfterAuthorization;
      }
      reservation.phase = 'dispatching';
      // 越过 dispatch 边界才记 origin — cancelled-before-dispatch 早返回不会到这,
      // 不会污染下一个无 origin 的 turn。先存下当前值,handle.send 失败时**还原**而非
      // 清 null(见下方 finally 注释)。
      //
      // 已知局限(PR #129 review Thread G,经产品确认接受):currentTurnOrigin 是单一
      // session 级槽位,无法完美区分**重叠的 turn**。窄 race:turn1 在 handle 层已 idle
      // (isTurnRunning 翻 false)但其终止 done 尚未 fan-out 时,turn2 的 send **成功**会
      // 在此覆盖槽位、且 turnDispatched=true 不触发 finally 还原 → turn1 的 done 带上
      // turn2 的 origin/null,attached IM 转播卡可能不 finalize / 误归属。触发窗口仅事件
      // 队列 drain 的 ms 级延迟,后果有界(转播 UI 边角,非数据丢失)。彻底修需要把 origin
      // 关联到具体 turn 事件而非单槽位(maker-core 热路径重构,规则 10),留作独立后续。
      previousTurnOrigin = this.currentTurnOrigin;
      this.currentTurnOrigin = handleOpts.origin ?? null;
      if (this.terminalErrorDrainGeneration === null) {
        this.terminalEventObservedGeneration = null;
        this.terminalEventObservedKind = null;
        this.terminalEventObservedErrorMessage = null;
        this.terminalEventObservedErrorSignals = null;
      }
      previousTurnAttemptToken = this.currentTurnAttemptToken;
      this.currentTurnAttemptToken =
        typeof handleOpts.turnAttemptToken === 'number' ? handleOpts.turnAttemptToken : null;
      originInstalled = true;
      this.startEventLoopIfNeeded();
      try {
        this.beginTurnControl(reservedTurnGeneration);
        onDispatching?.();
        try {
          turnLifecycleObserver?.onDispatching?.();
        } catch (error) {
          // Host authorization rejected synchronously, before handle.send could
          // create work. Do not fence a later valid send for a nonexistent tail.
          dispatchConfirmedUndispatched = true;
          throw error;
        }
        this.insideProviderSendSync = true;
        const previousLoopIntent = this.toolLoopUserIntent;
        const loopIntent = appendAutoReviewUserIntent(previousLoopIntent, autoReviewSourceContent, handleOpts);
        try {
          this.toolLoopUserIntent = loopIntent;
          await this.handle.send(msg, {
            ...handleOpts,
            [AUTO_REVIEW_SOURCE_CONTENT]: autoReviewSourceContent,
            signal: reservation.abortController.signal,
          });
        } catch (error) {
          if (this.toolLoopUserIntent === loopIntent) this.toolLoopUserIntent = previousLoopIntent;
          throw error;
        } finally {
          this.insideProviderSendSync = false;
        }
      } catch (e) {
        if (e instanceof TurnDispatchRejectedError) {
          // The provider returned a trustworthy rejection before accepting any
          // work. This path is safe to reschedule and must not arm the
          // ambiguous-tail drain used for unknown dispatch failures.
          dispatchConfirmedUndispatched = true;
          return { accepted: false, reason: 'provider-rejected-before-dispatch' };
        }
        // Cancellation cannot downgrade an explicitly ambiguous provider result
        // into "cancelled before dispatch"; that would skip the mandatory
        // transport fence and could leave accepted work running invisibly.
        if (e instanceof TurnDispatchUnconfirmedError) throw e;
        if (reservation.cancelled) {
          return { accepted: false, reason: 'cancelled-before-dispatch' };
        }
        throw e;
      }
      if (reservation.cancelled && (this.terminationStarted || this.closePromise)) {
        throw new TurnDispatchUnconfirmedError(
          `Session ${this.id} terminated before provider acceptance could be reconciled`,
        );
      }
      // A resolved handle.send is the provider-acceptance boundary. A signal
      // racing after that point may request abort, but cannot rewrite history
      // and report the turn as undispatched.
      turnDispatched = true;
      reservation.accepted = true;
      this.unacceptedSendGeneration = null;
      // turn 真正开始跑 → 起 stall 看门狗。后续产品进展事件会重置它;status /
      // account_usage 心跳不算。done / 终态 error 会清掉它(见 armTurnStallWatchdog)。
      this.armTurnStallWatchdog();
      return { accepted: true };
    } catch (e) {
      if (this.sendReservation === reservation) {
        this.sendReservation = null;
      }
      if (this.unacceptedSendGeneration === reservedTurnGeneration) {
        this.unacceptedSendGeneration = null;
      }
      if (e instanceof TurnDispatchUnconfirmedError) {
        dispatchUnconfirmed = true;
        // Reserve Session shutdown before closing the handle. This suppresses
        // a synthetic terminal event from transport teardown and fences any
        // late provider activity before the orchestrator reports blocked.
        if (originInstalled && !turnDispatched) {
          this.currentTurnOrigin = previousTurnOrigin;
          this.currentTurnAttemptToken = previousTurnAttemptToken;
          this.turnGeneration = previousTurnGeneration;
          this.pendingPriorGeneration = null;
          originInstalled = false;
        }
        await this.closeFromRuntime();
      }
      throw e;
    } finally {
      cleanupExternalAbort();
      if (this.sendReservation === reservation) {
        this.sendReservation = null;
      }
      if (this.unacceptedSendGeneration === reservedTurnGeneration) {
        this.unacceptedSendGeneration = null;
      }
      // 装了 origin 但本次 send 没真正成为运行中的 turn(handle.send 抛错 / dispatch
      // 后被取消)→ **还原**到 dispatch 前的 origin(而非强制清 null)。
      // SESSION_RUNNING race:137 行 isTurnRunning 检查通过、但 handle.send 因底层已有
      // turn 在跑而 reject。两种子情形:
      //   - dispatch 前无 turn 在跑(previousTurnOrigin=null):还原为 null,本次 stale
      //     origin 不会污染后续事件;
      //   - dispatch 前有别的 turn 正在跑(previousTurnOrigin=它的 origin):还原后那个
      //     turn 的剩余事件(含 done)继续带正确 origin。若这里强行清 null,正在跑的
      //     turn 的 done 会丢 origin → IM 转播收不到 done → 转播卡永不 finalize、残留
      //     state 污染下一轮(见 PR #129 review)。
      if (!turnDispatched) {
        if (originInstalled) {
          this.currentTurnOrigin = previousTurnOrigin;
          this.currentTurnAttemptToken = previousTurnAttemptToken;
          originInstalled = false;
          // Confirmed provider rejection cannot produce a turn tail, so it may
          // immediately reuse the rolled-back generation. Other failures retain
          // the bounded tail fence before another turn can enter.
          if (!dispatchConfirmedUndispatched) {
            this.armTerminalErrorDrain(previousTurnGeneration);
          }
        }
        this.turnGeneration = previousTurnGeneration;
        const reservationWindowTerminal = this.consumeReservationWindowPriorTerminal();
        if (
          !dispatchUnconfirmed &&
          reservationWindowTerminal &&
          previousTurnGeneration > 0
        ) {
          this.terminalEventObservedGeneration = previousTurnGeneration;
          this.terminalEventObservedKind = reservationWindowTerminal.kind;
          this.terminalEventObservedErrorMessage = reservationWindowTerminal.message;
          this.terminalEventObservedErrorSignals = reservationWindowTerminal.signals;
        } else {
          this.terminalEventObservedGeneration = previousTerminalObservation.generation;
          this.terminalEventObservedKind = previousTerminalObservation.kind;
          this.terminalEventObservedErrorMessage = previousTerminalObservation.message;
          this.terminalEventObservedErrorSignals = previousTerminalObservation.signals;
        }
        this.lastObservedTerminalGeneration = this.terminalEventObservedGeneration;
        this.lastObservedTerminalKind = this.terminalEventObservedKind;
        // Confirmed rejection skips the generic tail fence above, but a
        // promoted/restored error still needs the same drain as a live error.
        if (
          this.terminalEventObservedKind === 'error' &&
          typeof this.terminalEventObservedGeneration === 'number' &&
          this.terminalEventObservedGeneration > 0
        ) {
          this.armTerminalErrorDrain(this.terminalEventObservedGeneration);
        }
        if (
          previousTurnGeneration > 0 &&
          this.terminalEventObservedGeneration !== previousTurnGeneration
        ) {
          this.pendingPriorGeneration = previousTurnGeneration;
        } else {
          this.pendingPriorGeneration = null;
        }
      } else {
        this.terminalObservedDuringReservation = null;
      }
      if (turnLifecyclePrepared && !turnDispatched) {
        try {
          await turnLifecycleObserver?.onUndispatched(reservedTurnGeneration);
        } catch (error) {
          this.logger.warn('turn lifecycle undispatched cleanup failed', {
            turnGeneration: reservedTurnGeneration,
            error: String(error),
          });
        }
      }
      if (!turnDispatched) this.clearTurnControl(reservedTurnGeneration);
      reservation.settle(
        turnDispatched ? 'accepted' : dispatchUnconfirmed ? 'unconfirmed' : 'undispatched',
      );
      this.finishRetirementIfSettled();
    }
  }

  /**
   * 层 B:若配置了视觉桥,把消息里的图片转成文字描述(send 与 steer 共用)。
   * 钩子失败/未生效 → 原样透传(零干扰)。signal 可中止视觉请求(steer 通常无 signal)。
   */
  private async bridgedVisionMessage(msg: UserMessage, signal?: AbortSignal): Promise<UserMessage> {
    if (!this.visionBridge) return msg;
    try {
      const bridged = await this.visionBridge(msg, {
        model: this.handle.model,
        signal,
        sessionId: this.id,
      });
      if (bridged.applied) return appendManagedImageReferences(msg, bridged.message);
      if (bridged.note) {
        // 无论 applied 与否,note(fallback 生效 / 视觉桥不可用)都上报,避免静默。
        this.logger.info('vision bridge note', { sessionId: this.id, note: bridged.note });
      }
    } catch (err) {
      // 防御性兜底:视觉桥抛错绝不阻塞本轮,按未启用处理(host 实现应自吞,这里兜底)。
      this.logger.warn('vision bridge threw, falling back to passthrough', {
        sessionId: this.id,
        error: err instanceof Error ? err.message : String(err),
      });
    }
    return msg;
  }

  async steer(
    message: UserMessage | string,
    opts?: SendOptions & Pick<SessionSendOptions, 'beforeProviderStart'>,
  ): Promise<void> {
    let msg: UserMessage = typeof message === 'string'
      ? { type: 'user', content: message }
      : message;
    this.logger.debug('steer', summarizeUserMessage(msg));
    this.ensureActive();
    if (!this.capabilities.sameTurnSteer.supported) {
      throw new NotSupportedError('sameTurnSteer', this.capabilities.sameTurnSteer);
    }
    if (!this.handle.isTurnRunning?.()) {
      throw new Error(`Session ${this.id} has no active turn to steer`);
    }
    // 记录发起时的 turn generation:异步视觉转换期间原 turn 可能结束、同 Session
    // 又启动新 turn。单看 isTurnRunning 会因新 turn 而通过,把迟到 steer 投给错误
    // 的 turn(跨 turn 串线)。记录发起时代号,转换后必须「同一 generation 且仍
    // 在跑」才投递。
    const steerTurnGeneration = this.getTurnGeneration();
    const autoReviewSourceContent = opts?.[AUTO_REVIEW_SOURCE_CONTENT] ?? msg.content;
    // 层 B:steer 追加图片同样走视觉桥(与 send 一致),否则纯文本模型收到的
    // 原始 image block 会被后端忽略或拒绝(Greptile P1)。
    msg = await this.bridgedVisionMessage(msg, opts?.signal);
    const { beforeProviderStart, ...handleOpts } = opts ?? {};
    // Host grants must survive all asynchronous preparation, including steer.
    // Keep the private authorization hook out of provider options.
    if (beforeProviderStart) {
      await beforeProviderStart();
      this.ensureActive();
    }
    // 异步视觉转换期间 turn 可能已完成/被中止(视觉后端慢、用户已切任务等):
    // 转换结果此时已无人接收,必须先复查原 turn 生命周期再调用 handle.steer,
    // 否则底层以「No active turn to steer」拒绝或 Pi 把迟到消息交给已结束的 turn。
    if (this.getTurnGeneration() !== steerTurnGeneration || !this.handle.isTurnRunning?.()) {
      throw new Error(`Session ${this.id} has no active turn to steer`);
    }
    this.startEventLoopIfNeeded();
    // Mark before dispatch: the provider may start the steer's own turn as soon as it accepts it.
    const previousSteerGeneration = this.steerAcceptedGeneration;
    this.steerAcceptedGeneration = steerTurnGeneration;
    const previousLoopIntent = this.toolLoopUserIntent;
    const loopIntent = appendAutoReviewUserIntent(previousLoopIntent, autoReviewSourceContent, handleOpts);
    try {
      this.toolLoopUserIntent = loopIntent;
      await this.handle.steer(msg, { ...handleOpts, [AUTO_REVIEW_SOURCE_CONTENT]: autoReviewSourceContent });
    } catch (error) {
      if (this.getTurnGeneration() === steerTurnGeneration && this.toolLoopUserIntent === loopIntent) {
        this.toolLoopUserIntent = previousLoopIntent;
      }
      if (this.steerAcceptedGeneration === steerTurnGeneration) {
        this.steerAcceptedGeneration = previousSteerGeneration;
      }
      throw error;
    }
  }

  /**
   * Cancel a send that is still in the pre-dispatch (`accepting`) phase without
   * turning the whole session into `aborting`. Hosts that withdraw one queued
   * routine send use this instead of abort(): abort is user-Stop semantics and
   * arms the manual-abort recovery watchdog.
   *
   * Returns true when a pre-dispatch reservation was cancelled. False means there
   * is no such reservation (the turn already crossed the vendor boundary, was
   * accepted, or no send is pending), so callers that need to stop a running turn
   * should use abort().
   */
  cancelPendingSend(): boolean {
    const reservation = this.sendReservation;
    if (!reservation || reservation.accepted || reservation.phase !== 'accepting') return false;
    this.cancelSendReservation(reservation);
    return true;
  }

  async abort(): Promise<void> {
    if (this.status === 'closed') return;
    if (this.status === 'error') return;
    this.asyncUserQuestions.expire('session_aborted');
    const abortGeneration = this.turnGeneration;
    this.cancelSendReservation(this.sendReservation);
    // 中断已在进行:不再计 stall 额度(下一个 turn 的 send 会重新起表)。
    this.clearTurnStallWatchdog();
    // 但**不能就这么放手**:用户按 Stop 时若 transport 已经不响应,codex 的
    // turn/interrupt 可能永久悬挂、claude 的 q.interrupt() 可能失败且不清 turn-in-flight
    // 标记。这一行刚把 Session 层唯一的复核定时器关掉,agent 层的 idle watchdog 也随
    // turn 中断一起收表 —— 没人再管的话 isTurnRunning() 恒 true,之后每一条 send 都被拒,
    // 会话永久不可用(review #944 第十一轮 P1)。
    //
    // 所以这里也排一次与 turn 绑定的复核,且**不挂在 abort 的 promise 上**(它自己就可能
    // 永不 settle,理由同 onTurnStallTimeout)。宽限比看门狗那条长得多:手动 Stop 背后
    // 没有别的兜底,而健康的 interrupt 往返远不需要这么久,宁可多等也不误关正常会话。
    this.scheduleAbortRecoveryCheck(MANUAL_ABORT_RECOVERY_GRACE_MS, 'manual-abort');
    this.setStatus('aborting');
    try {
      const aborting = this.handle.abort();
      // Stop revokes Host continuation immediately. The RPC may never settle;
      // do not let its acknowledgement own an already-settled turn's retirement.
      this.settleHostTurnContinuation(abortGeneration);
      await aborting;
    } finally {
      this.releaseSendReservationIfObserved();
      if (this.status === 'aborting') {
        this.setStatus('active');
      }
      this.settleHostTurnContinuation(abortGeneration);
    }
  }

  getTurnControlSnapshot(): SessionTurnControlSnapshot {
    const control = this.turnControlState;
    if (!control) {
      return {
        active: false,
        turnGeneration: null,
        activeToolCount: 0,
        pendingInteractionCount: 0,
        gracefulStopState: 'none',
      };
    }
    return {
      active: true,
      turnGeneration: control.generation,
      activeToolCount: control.activeToolIds.size + control.anonymousActiveTools,
      pendingInteractionCount: [...control.pendingInteractionToolIds.values()]
        .reduce((sum, count) => sum + count, 0),
      gracefulStopState: control.gracefulStopState,
    };
  }

  async requestGracefulStop(): Promise<SessionGracefulStopResult> {
    this.asyncUserQuestions.expire('session_stopping');
    const reservation = this.sendReservation;
    if (reservation) return this.requestGracefulStopForReservation(reservation);
    const control = this.turnControlState;
    if (!control || control.generation !== this.turnGeneration || !this.isHandleTurnRunning()) {
      return { status: 'no-active-turn' };
    }
    if (!this.handle.requestGracefulStop) {
      return { status: 'unsupported', reason: 'provider-not-supported' };
    }
    if (control.gracefulStopPromise) return control.gracefulStopPromise;
    if (control.gracefulStopState === 'requested') {
      return { status: 'requested', turnGeneration: control.generation };
    }
    if (control.gracefulStopState === 'unconfirmed') {
      return {
        status: 'unconfirmed',
        turnGeneration: control.generation,
        reason: 'provider-did-not-confirm',
      };
    }
    if (!this.isGracefulStopSafePoint(control)) {
      control.gracefulStopState = 'waiting-for-safe-point';
      return { status: 'waiting-for-safe-point', turnGeneration: control.generation };
    }
    return this.issueGracefulStop(control);
  }

  /** Fence a graceful stop against input that the provider has not accepted yet. */
  private requestGracefulStopForReservation(
    reservation: SendReservation,
  ): Promise<SessionGracefulStopResult> {
    if (reservation.gracefulStopPromise) return reservation.gracefulStopPromise;
    this.cancelSendReservation(reservation);
    const control = this.turnControlState;
    if (control?.generation === reservation.generation) control.gracefulStopState = 'requesting';

    const result = this.waitForSendReservationSettlement(reservation).then(async (outcome) => {
      const currentControl = this.turnControlState;
      if (outcome === 'undispatched') {
        if (currentControl?.generation === reservation.generation) {
          currentControl.gracefulStopState = 'requested';
        }
        return { status: 'requested', turnGeneration: reservation.generation } as const;
      }
      if (outcome === 'unconfirmed' || outcome === 'timeout') {
        if (currentControl?.generation === reservation.generation) {
          currentControl.gracefulStopState = 'unconfirmed';
        }
        return {
          status: 'unconfirmed',
          turnGeneration: reservation.generation,
          reason: outcome === 'timeout'
            ? 'provider-acceptance-timeout'
            : 'provider-acceptance-unconfirmed',
        } as const;
      }

      // The provider accepted while cancellation raced; only its own soft-interrupt ACK can
      // confirm the stop from this point onward.
      if (
        !currentControl ||
        currentControl.generation !== reservation.generation ||
        !this.isHandleTurnRunning()
      ) {
        return { status: 'requested', turnGeneration: reservation.generation } as const;
      }
      if (!this.handle.requestGracefulStop) {
        return { status: 'unsupported', reason: 'provider-not-supported' } as const;
      }
      if (!this.isGracefulStopSafePoint(currentControl)) {
        currentControl.gracefulStopState = 'waiting-for-safe-point';
        return {
          status: 'waiting-for-safe-point',
          turnGeneration: currentControl.generation,
        } as const;
      }
      return this.issueGracefulStop(currentControl);
    });
    reservation.gracefulStopPromise = result;
    return result;
  }

  private waitForSendReservationSettlement(
    reservation: SendReservation,
  ): Promise<SendReservationOutcome | 'timeout'> {
    return new Promise((resolve) => {
      let settled = false;
      const timeout = setTimeout(() => {
        if (settled) return;
        settled = true;
        resolve('timeout');
      }, GRACEFUL_STOP_CONFIRMATION_TIMEOUT_MS);
      (timeout as unknown as { unref?: () => void }).unref?.();
      void reservation.settled.then((outcome) => {
        if (settled) return;
        settled = true;
        clearTimeout(timeout);
        resolve(outcome);
      });
    });
  }

  /**
   * 停止本会话内单个后台任务(run_in_background 的 Bash / 后台 subagent 等)。
   * 与 abort() 不同:不中断当前 turn,只停指定 taskId;任务已到终态时幂等成功。
   * 会话已关闭 / 出错时静默返回 —— 此时子进程已死,后台任务必然随之终止。
   */
  async stopBackgroundTask(taskId: string): Promise<void> {
    if (this.status === 'closed' || this.status === 'error') return;
    if (!this.handle.stopBackgroundTask) {
      throw new NotSupportedError('stopBackgroundTask', { supported: false, reason: 'not-implemented' });
    }
    await this.handle.stopBackgroundTask(taskId);
  }

  async resumeBackgroundTask(taskId: string, message: string, childId?: string): Promise<void> {
    if (this.status === 'closed' || this.status === 'error') {
      throw new NotSupportedError('resumeBackgroundTask', { supported: false, reason: 'not-implemented' });
    }
    if (!this.handle.resumeBackgroundTask) {
      throw new NotSupportedError('resumeBackgroundTask', { supported: false, reason: 'not-implemented' });
    }
    await this.handle.resumeBackgroundTask(taskId, message, childId);
  }

  /**
   * 当前仍在运行的后台任务快照。不支持的 agent / 已关闭会话 → 空数组(此时
   * 子进程不存在,后台任务必然已死,空数组即事实)。
   */
  listBackgroundTasks(): BackgroundTaskSnapshot[] {
    if (this.status === 'closed' || this.status === 'error') return [];
    return this.handle.listBackgroundTasks?.() ?? [];
  }

  /**
   * 宿主发起的独占 RPC 操作(手动压缩 / rewind / 切模等)在途。这类操作不预约
   * turn,关闭会把它们拦腰截断;空闲回收据此拒绝关闭。会话已关闭 → false。
   */
  hasPendingHostOperation(): boolean {
    if (this.status === 'closed' || this.status === 'error') return false;
    return this.handle.hasPendingHostOperation?.() ?? false;
  }

  /**
   * 「任务已终态、wake turn 尚未启动或仍在跑」的 continuation claim 数。
   * 会话已关闭 / agent 不支持 → 0(此时不会再有 wake turn,0 即事实)。
   */
  countPendingWakeContinuations(): number {
    if (this.status === 'closed' || this.status === 'error') return 0;
    return this.handle.countPendingWakeContinuations?.() ?? 0;
  }

  /**
   * Resolve the provider-owned continuation claim already attached to this
   * exact `done`. Host observers must never infer this from the current task
   * list: task state can change after the event was queued but before it is
   * consumed.
   */
  beginTurnContinuationWait(continuationId?: number): TurnContinuationState | null {
    if (this.status === 'closed' || this.status === 'error') return null;
    if (continuationId === undefined) return null;
    return this.handle.beginTurnContinuationWait?.(continuationId) ?? null;
  }

  /** Subscribe to provider-owned continuation lifecycle transitions. */
  onTurnContinuationChange(
    listener: (continuationId: number, state: TurnContinuationState) => void,
  ): () => void {
    return this.handle.onTurnContinuationChange?.(listener) ?? (() => undefined);
  }

  /** True once teardown has started, including an unconfirmed failed close. */
  hasStartedClosing(): boolean {
    return this.terminationStarted;
  }

  /** True when this runtime, not an external caller, started its own teardown. */
  wasClosedByRuntime(): boolean {
    return this.runtimeInitiatedClose;
  }

  /** Self-close: only claims the cause when no teardown has started yet. */
  private closeFromRuntime(): Promise<void> {
    if (!this.terminationStarted && this.status !== 'closed') this.runtimeInitiatedClose = true;
    return this.close();
  }

  /**
   * Ordinary close. Without an explicit reason this is navigation: the account
   * and its database are unchanged, so an adapter's detached work survives.
   * Account boundaries go through `detach({ reason: 'account-boundary' })`.
   */
  close(opts?: AgentSessionTeardownOptions): Promise<void> {
    if (this.closePromise) return this.closePromise;
    if (this.status === 'closed') return Promise.resolve();

    this.terminationStarted = true;
    this.asyncUserQuestions.expire('session_closed');
    // 拆除开始即作废进行中的工具循环复核,迟到结论不得再中断。
    this.turnControlState?.toolLoopMonitor?.dispose();
    // Reserve before synchronous terminal listeners run, but begin transport
    // shutdown now: a pending send must see its cancellation in this tick.
    let resolve!: () => void;
    let reject!: (error: unknown) => void;
    const closing = new Promise<void>((onResolve, onReject) => {
      resolve = onResolve;
      reject = onReject;
    });
    this.closePromise = closing;
    void this.performClose(opts ?? { reason: 'navigation' }).then(resolve, reject);
    return closing;
  }

  /** Retire this runtime at its product terminal boundary, without replaying work. */
  async closeAfterCurrentTurn(opts?: { failureEvent?: () => AgentEvent }): Promise<'closed' | 'deferred'> {
    this.retirementRequested = true;
    if (!this.retirementFailureEvent && opts?.failureEvent) {
      const createEvent = opts.failureEvent;
      const generation = this.turnGeneration;
      this.retirementFailureEvent = () => ({
        ...createEvent(),
        runtimeRecovery: true,
        sessionInstanceId: this.instanceId,
        sessionTurnGeneration: generation,
      });
    }
    if (this.hasUnsettledTurn() || this.sendReservation !== null
      || this.hostTurnLeases.size > 0
      || this.retirementContinuationGeneration === this.turnGeneration) {
      return 'deferred';
    }
    await this.close();
    return 'closed';
  }

  private retirementRequested = false;
  private retirementContinuationGeneration: number | null = null;
  private retirementFailureEvent: (() => AgentEvent) | undefined;

  /** The Host has actually scheduled bounded continuation for this terminal. */
  claimHostTurnContinuation(generation: number): void {
    if (this.terminationStarted || generation !== this.turnGeneration
      || this.terminalEventObservedGeneration !== generation) return;
    this.retirementContinuationGeneration = generation;
  }

  /** The Host declined/exhausted continuation or released its observer ownership. */
  settleHostTurnContinuation(generation: number): void {
    if (generation !== this.turnGeneration || this.retirementContinuationGeneration !== generation) return;
    this.retirementContinuationGeneration = null;
    this.finishRetirementIfSettled();
  }

  /** Provider idle/exit is not evidence that the product terminal was delivered. */
  private hasUnsettledTurn(): boolean {
    return this.turnControlState?.generation === this.turnGeneration
      && this.terminalEventObservedGeneration !== this.turnGeneration;
  }

  private finishRetirementIfSettled(): void {
    if (this.terminationStarted || !this.retirementRequested || this.hasUnsettledTurn()
      || this.sendReservation !== null || this.hostTurnLeases.size > 0
      || this.retirementContinuationGeneration === this.turnGeneration) return;
    void this.close().catch((error) => {
      this.logger.warn('runtime retirement close failed', { error: String(error) });
    });
  }

  /**
   * Close only when no send reservation, agent turn, or host-initiated exclusive
   * RPC operation (manual compact / rewind / model switch) is active. The check
   * and close reservation are synchronous, so a concurrent send either wins
   * first and keeps the session open, or observes closePromise and is rejected.
   */
  closeIfIdle(): Promise<boolean> {
    if (this.status !== 'active' || this.closePromise || this.isTurnRunning() || this.hasUnsettledTurn()
      || this.retirementContinuationGeneration === this.turnGeneration
      || this.hasPendingHostOperation()) {
      return Promise.resolve(false);
    }
    return this.close().then(() => true);
  }

  private async performClose(teardown: AgentSessionTeardownOptions): Promise<void> {
    let closeSucceeded = false;
    try {
      // close() fences late provider events before entering here. Settle the
      // owned product turn ourselves before listeners and its claim are lost.
      // Never retry: tools may already have performed external side effects.
      this.settleUnfinishedTurn(SESSION_CLOSED_MID_TURN_MESSAGE);
      this.clearTurnStallWatchdog();
      this.clearTerminalErrorDrain();
      this.cancelSendReservation(this.sendReservation);
      await this.handle.close(teardown);
      closeSucceeded = true;
    } catch (error) {
      const failureEvent = this.retirementFailureEvent;
      this.retirementFailureEvent = undefined;
      if (failureEvent) {
        // The provider queue is already fenced. Dispatch the Host's recovery
        // receipt on the dedicated channel before clearing listeners, without
        // changing a successful turn or re-entering product listeners.
        try { this.dispatchRuntimeRecovery(failureEvent()); } catch (notificationError) {
          this.logger.warn('runtime retirement recovery receipt failed', { error: String(notificationError) });
        }
      }
      throw error;
    } finally {
      this.sendReservation = null;
      this.unacceptedSendGeneration = null;
      this.currentTurnOrigin = null;
      this.currentTurnAttemptToken = null;
      this.turnControlState?.toolLoopMonitor?.dispose();
      this.turnControlState = null;
      this.eventListeners.clear();
      this.runtimeRecoveryListeners.clear();
      this.interactionListener = null;
      if (closeSucceeded) {
        this.setStatus('closed');
        this.statusListeners.clear();
      } else {
        // 底层仍可能存活时不能发布 closed;保留 status listener,让 Maker 后续重试
        // close 时仍能从 activeSessions 移除,避免错误句柄永久占槽。
        this.closePromise = null;
        this.setStatus('error');
      }
    }
  }

  private settleUnfinishedTurn(message: string): void {
    if (!this.hasUnsettledTurn()) return;
    if (this.abortRecoveryScheduledFor === this.turnGeneration) {
      this.fanOutEvent({ type: 'done', data: { status: 'cancelled' }, source: this.agentKind });
    } else {
      this.fanOutEvent({ type: 'error', data: {
        message, isTerminal: true, reason: 'session_event_loop_crashed',
      }, source: this.agentKind });
    }
  }

  /**
   * Shutdown-path teardown. The reason is *not* optional in practice: Maker
   * fails closed to `account-boundary` when its caller did not identify the
   * boundary, so an unlabelled logout can never leave detached work running
   * against the next owner's credentials.
   */
  async detach(opts?: AgentSessionTeardownOptions): Promise<void> {
    const teardown: AgentSessionTeardownOptions = opts ?? { reason: 'account-boundary' };
    if (this.status === 'closed') return;
    this.terminationStarted = true;
    this.asyncUserQuestions.expire('session_closed');
    // 拆除开始即作废进行中的工具循环复核,迟到结论不得再中断。
    this.turnControlState?.toolLoopMonitor?.dispose();
    // 与 performClose() 对齐:进入拆离立即 abort 未完成的 pre-dispatch reservation
    // (vision bridge 等前置 hook 的 fetch),而不是等 handle.detach()/视觉通道超时——
    // 否则 handle.detach() 慢/挂起时,in-flight 视觉请求会继续拖住退出链。
    this.cancelSendReservation(this.sendReservation);
    let detachSucceeded = false;
    try {
      if (this.handle.detach) {
        await this.handle.detach(teardown);
      } else {
        await this.handle.close(teardown);
      }
      detachSucceeded = true;
    } finally {
      this.sendReservation = null;
      this.unacceptedSendGeneration = null;
      this.currentTurnOrigin = null;
      this.currentTurnAttemptToken = null;
      this.turnControlState?.toolLoopMonitor?.dispose();
      this.turnControlState = null;
      this.clearTerminalErrorDrain();
      this.eventListeners.clear();
      this.runtimeRecoveryListeners.clear();
      this.interactionListener = null;
      if (detachSucceeded) {
        this.setStatus('closed');
        this.statusListeners.clear();
      } else {
        // Shutdown must retain Maker's status listener and active-session owner
        // until a later detach/close attempt confirms the process is gone.
        this.setStatus('error');
      }
    }
  }

  async getCodexContextWindowInfo() {
    return this.handle.getCodexContextWindowInfo?.() ?? null;
  }

  getUsageSnapshot(): UsageSnapshot {
    return this.handle.getUsageSnapshot();
  }

  /** Return the current per-session Pi runtime capability snapshot, if exposed. */
  getRuntimeCapabilities(): PiRuntimeCapabilityManifest | undefined {
    return this.handle.getRuntimeCapabilities?.();
  }

  getDisabledSkillPaths(): readonly string[] | undefined {
    return this.handle.disabledSkillPaths;
  }

  /** Subscribe to replacement of the current per-session Pi runtime catalog. */
  onRuntimeCapabilitiesChange(
    listener: (manifest: PiRuntimeCapabilityManifest | undefined) => void,
  ): () => void {
    return this.handle.onRuntimeCapabilitiesChange?.(listener) ?? (() => undefined);
  }

  async getContextUsage(): Promise<ContextUsageData> {
    this.ensureActive();
    if (!this.handle.getContextUsage) {
      throw new NotSupportedError('contextUsage', { supported: false, reason: 'not-implemented' });
    }
    return this.handle.getContextUsage();
  }

  /**
   * The engine's own view of one MCP server in this session. Null when the
   * engine has no per-session MCP status entry; never starts or calls a server.
   */
  async readMcpServerTools(serverName: string): Promise<AgentMcpServerToolsReport | null> {
    this.ensureActive();
    return await this.handle.readMcpServerTools?.(serverName) ?? null;
  }

  /**
   * 当前 session 生命周期状态 ('active' / 'aborting' / 'closed' / 'error')。
   * 这是内存里的 SDK 子进程视角, 不持久化。区分:
   *   - 'active'      : 子进程存活, 可正常 send / 切配置
   *   - 'aborting'    : 正在 abort 当前 turn, 短暂瞬态
   *   - 'closed'      : 子进程已关闭, 不可用
   *   - 'error'       : 异常退出
   * 注意: 这跟 desktop DB 的 status 列 ('active'|'archived'|'deleted') 是两个独立维度,
   * 后者是产品归档语义, 跟 SDK 是否在跑无关。
   */
  getStatus(): SessionStatus {
    return this.status;
  }

  /**
   * Native identity safe to persist for resume. An unaccepted fork retains its source.
   * Request routing uses requestSessionId, which may already identify the destination.
   */
  get sdkSessionId(): string {
    return this.handle.id;
  }

  /** Live request identity, which may precede a fork's durable resume identity. */
  get requestSessionId(): string {
    return this.handle.requestSessionId ?? this.handle.id;
  }

  /** 当前运行时模型。底层 handle 的 getter 会随 setModel 成功更新。 */
  get model(): string {
    return this.handle.model;
  }

  /** Codex-only: 当前会话实际绑定的本地 host 身份。 */
  get codexHostKey(): string | undefined {
    return this.handle.codexHostKey;
  }

  /** Codex-only: 当前会话绑定的 app-server host 是否经 loopback proxy 出口。 */
  get codexProxyActive(): boolean | undefined {
    return this.handle.codexProxyActive;
  }

  /** Codex-only: app-server 确认的 thread 级 model provider 身份。 */
  get codexThreadModelProviderId(): string | undefined {
    return this.handle.codexThreadModelProviderId;
  }

  /** Codex-only: exact provider-owned rollout/turn acceptance evidence. */
  get codexThreadMayHaveRollout(): boolean | undefined {
    return this.handle.codexThreadMayHaveRollout;
  }

  /** Codex-only: 当前 host 的独立 Subagent 路由是否兼容 Cindy Codex 远程压缩。 */
  get codexCindyRemoteCompactionCompatible(): boolean | undefined {
    return this.handle.codexCindyRemoteCompactionCompatible;
  }

  /** Snapshot used by temporary host overrides to avoid undoing a newer user change. */
  get permissionModeState(): PermissionModeState {
    return { ...this.permissionModeStateValue };
  }

  /**
   * 只在本 Session 仍活跃、未开始关闭、且没有权限切换在途时返回稳定快照。
   * 权限边界读取方必须用本 getter,不能直接用 permissionModeState:底层切换
   * 完成前旧 mode 仍会保留,而收紧操作一开始就应 fail closed。
   */
  get stablePermissionModeState(): PermissionModeState | null {
    if (this.status !== 'active' || this.terminationStarted) return null;
    if (
      this.permissionModeChangesInFlight > 0 ||
      this.externalPermissionModeChangesInFlight > 0
    ) {
      return null;
    }
    return this.permissionModeState;
  }

  /** Host side effects must not use an unknown or in-flight Plan state. */
  get stablePlanModeState(): { enabled: boolean; generation: number } | null {
    if (this.status !== 'active' || this.terminationStarted || this.planModeChangesInFlight > 0) return null;
    const enabled = this.capabilities.planMode?.supported
      ? (this.handle.getExecutionPlanMode ? this.handle.getExecutionPlanMode() : this.getPlanMode())
      : false;
    return enabled === null ? null : { enabled, generation: this.planModeGeneration };
  }

  /** Native ownership covers harness tool calls, never independently initiated Host work. */
  get autoReviewOwner(): 'native' | 'cindy' {
    return this.stablePermissionModeState?.mode === 'auto'
      && this.stablePlanModeState?.enabled === false
      ? this.handle.getAutoReviewOwner?.() ?? 'cindy'
      : 'cindy';
  }

  /** Review a Host-side tool step without reconstructing or persisting another copy of user intent. */
  async reviewHostPermissionAction(action: ReviewableAction): Promise<AutoReviewDecision> {
    const permission = this.stablePermissionModeState;
    if (!permission) return { verdict: 'block', reason: 'Session permissions are changing or the task has closed.' };
    const plan = this.stablePlanModeState;
    if (!plan || plan.enabled || permission.mode === 'plan') {
      return { verdict: 'block', reason: 'Plan mode is active or changing; Host side effects are not allowed.' };
    }
    if (permission.mode === 'bypassPermissions') return { verdict: 'allow' };
    if (permission.mode !== 'auto') return { verdict: 'ask' };
    // Host steps can belong to a still-active descendant after the foreground
    // turn finishes. Guard Session authority here; root-turn generation is not
    // the lifetime of that call. The harness checks changing user intent, and
    // callers retain their own invocation-validity checks.
    const turnControl = this.turnControlState;
    const gracefulStop = turnControl?.gracefulStopState ?? 'none';
    let invalidated = false;
    const unsubscribe = this.onStatusChange((status) => { if (status !== 'active') invalidated = true; });
    let decision: AutoReviewDecision;
    try {
      decision = await this.handle.reviewAutoPermissionAction?.(action)
        ?? { verdict: 'ask', unavailable: true };
    } catch {
      decision = { verdict: 'ask', unavailable: true };
    } finally {
      unsubscribe();
    }
    const current = this.stablePermissionModeState;
    const currentPlan = this.stablePlanModeState;
    if (invalidated || !current || current.generation !== permission.generation
      || !currentPlan || currentPlan.enabled || currentPlan.generation !== plan.generation
      || (turnControl?.gracefulStopState ?? 'none') !== gracefulStop
      || (this.turnControlState?.gracefulStopState ?? 'none') !== gracefulStop) {
      return { verdict: 'block', reason: 'Task or permissions changed; retry with the current scope.' };
    }
    return decision;
  }

  /**
   * Keep this Session logically occupied beyond the provider's own turn flag.
   * The caller must release the returned lease on every terminal path.
   */
  acquireTurnLease(): () => void {
    let resolveGate!: () => void;
    const gate = new Promise<void>((resolve) => {
      resolveGate = resolve;
    });
    this.hostTurnLeases.add(gate);
    let released = false;
    return () => {
      if (released) return;
      released = true;
      this.hostTurnLeases.delete(gate);
      resolveGate();
      this.finishRetirementIfSettled();
    };
  }

  // ── 运行时切换 ─────────────────────────────────────────────────────────────

  async setModel(
    model: string,
    opts?: { providerId?: string | null; effort?: Effort; contextWindowBudget?: number | null; thinkingEnabled?: boolean },
  ): Promise<void> {
    if (!this.capabilities.switchModel.supported) {
      throw new NotSupportedError('switchModel', this.capabilities.switchModel);
    }
    if (!this.handle.setModel) {
      throw new NotSupportedError('switchModel', { supported: false, reason: 'not-implemented' });
    }
    await this.handle.setModel(model, opts);
  }

  async previewModelSwitch(
    model: string,
    opts?: { providerId?: string | null; contextWindowBudget?: number | null },
  ): Promise<PiModelSwitchPreview | undefined> {
    return this.handle.previewModelSwitch?.(model, opts);
  }

  async requiresModelSwitchRebuild(
    model: string,
    opts?: { providerId?: string | null },
  ): Promise<boolean> {
    return await this.handle.requiresModelSwitchRebuild?.(model, opts) ?? false;
  }

  async setEffort(effort: Effort): Promise<void> {
    if (!this.capabilities.effort.supported) {
      throw new NotSupportedError('effort', this.capabilities.effort);
    }
    if (!this.handle.setEffort) {
      throw new NotSupportedError('effort', { supported: false, reason: 'not-implemented' });
    }
    await this.handle.setEffort(effort);
  }

  async setPermissionMode(mode: PermissionMode): Promise<void> {
    this.assertPermissionModeSupported(mode);
    this.externalPermissionModeChangesInFlight += 1;
    const operation = this.externalPermissionModeChangeChain.catch(() => undefined).then(async () => {
      // The owner's live permission choice applies equally to IM and Desktop
      // turns. Host leases fence new sends/retirement, not permission changes.
      await this.setPermissionModeTracked(mode);
    });
    const tracked = operation.finally(() => {
      this.externalPermissionModeChangesInFlight -= 1;
    });
    this.externalPermissionModeChangeChain = tracked.then(
      () => undefined,
      () => undefined,
    );
    await tracked;
  }

  async setPermissionModeTracked(mode: PermissionMode): Promise<PermissionModeState> {
    this.assertPermissionModeSupported(mode);
    this.permissionModeChangesInFlight += 1;
    const operation = this.permissionModeChangeChain.catch(() => undefined).then(async () => {
      // The request may have queued before close() but reached the transport only after
      // shutdown started. Re-check at the serialized side-effect boundary.
      this.ensureActive();
      const fromMode = this.permissionModeStateValue.mode;
      await this.handle.setPermissionMode!(mode);
      this.permissionModeStateValue = {
        mode,
        generation: this.permissionModeStateValue.generation + 1,
      };
      // 轮 40-w4-t8 HIGH:权限档切换(尤其放宽到 Full access)是安全边界变更,
      // 成功提交后必须审计 —— 事后能复盘谁/何时/从哪切到哪。
      this.logger.info('audit: session permission mode changed', {
        operation: 'session_permission_mode_change',
        sessionId: this.id,
        agentKind: this.agentKind,
        fromMode,
        toMode: mode,
        generation: this.permissionModeStateValue.generation,
        widenedToBypass: mode === 'bypassPermissions' && fromMode !== 'bypassPermissions',
      });
      return this.permissionModeState;
    });
    const tracked = operation.finally(() => {
      this.permissionModeChangesInFlight -= 1;
    });
    this.permissionModeChangeChain = tracked.then(
      () => undefined,
      () => undefined,
    );
    return tracked;
  }

  async setPermissionModeIfUnchanged(
    expected: PermissionModeState,
    mode: PermissionMode,
  ): Promise<boolean> {
    this.assertPermissionModeSupported(mode);
    // An external request is newer user intent, including while its runtime
    // update is still in flight. Never restore over it.
    if (this.externalPermissionModeChangesInFlight > 0) return false;
    this.permissionModeChangesInFlight += 1;
    const operation = this.permissionModeChangeChain.catch(() => undefined).then(async () => {
      // A matching restore can wait behind another mode change. Never apply it after
      // close() has reserved transport shutdown.
      this.ensureActive();
      const current = this.permissionModeStateValue;
      if (current.mode !== expected.mode || current.generation !== expected.generation) {
        return false;
      }
      await this.handle.setPermissionMode!(mode);
      this.permissionModeStateValue = { mode, generation: current.generation + 1 };
      return true;
    });
    const tracked = operation.finally(() => {
      this.permissionModeChangesInFlight -= 1;
    });
    this.permissionModeChangeChain = tracked.then(
      () => undefined,
      () => undefined,
    );
    return tracked;
  }

  private assertPermissionModeSupported(mode: PermissionMode): void {
    this.ensureActive();
    if (!this.capabilities.permissionModes.some((m) => m.id === mode)) {
      throw new NotSupportedError(
        `permissionMode='${mode}'`,
        {
          supported: false,
          reason: 'sdk-missing',
          message: `Available: ${this.capabilities.permissionModes.map((m) => m.id).join(', ')}`,
        },
      );
    }
    if (!this.capabilities.setPermissionModeMidSession.supported) {
      throw new NotSupportedError('setPermissionModeMidSession', this.capabilities.setPermissionModeMidSession);
    }
    if (!this.handle.setPermissionMode) {
      throw new NotSupportedError('setPermissionMode', { supported: false, reason: 'not-implemented' });
    }
  }

  async setFastMode(enabled: boolean | 'ultrafast'): Promise<void> {
    this.ensureActive();
    if (!this.handle.setFastMode) {
      throw new NotSupportedError('fastMode', { supported: false, reason: 'not-implemented' });
    }
    await this.handle.setFastMode(enabled);
  }

  async setThinkingEnabled(enabled: boolean): Promise<void> {
    this.ensureActive();
    if (!this.handle.setThinkingEnabled) return;
    await this.handle.setThinkingEnabled(enabled);
  }

  /** 运行时开关计划模式(capability 见 Capabilities.planMode)。 */
  async setPlanMode(enabled: boolean): Promise<void> {
    this.ensureActive();
    if (!this.capabilities.planMode?.supported) {
      throw new NotSupportedError('planMode', this.capabilities.planMode ?? { supported: false, reason: 'not-implemented' });
    }
    if (!this.handle.setPlanMode) {
      throw new NotSupportedError('planMode', { supported: false, reason: 'not-implemented' });
    }
    if (this.planModeChangesInFlight === 0 && this.getPlanMode() === enabled) return;
    // Invalidate before awaiting the provider (Pi may queue its RPC). A switch
    // back, or a failed switch, must not revive an earlier Host approval.
    this.planModeGeneration += 1;
    this.planModeChangesInFlight += 1;
    try {
      await this.handle.setPlanMode(enabled);
    } finally {
      this.planModeChangesInFlight -= 1;
    }
  }

  getPlanMode(): boolean | null {
    return this.handle.getPlanMode?.() ?? null;
  }

  /** 导出当前会话为 HTML,返回写入路径(capability 见 Capabilities.sessionHtmlExport)。 */
  async exportSessionHtml(outputPath?: string): Promise<string> {
    this.ensureActive();
    if (!this.capabilities.sessionHtmlExport?.supported) {
      throw new NotSupportedError(
        'sessionHtmlExport',
        this.capabilities.sessionHtmlExport ?? { supported: false, reason: 'not-implemented' },
      );
    }
    if (!this.handle.exportSessionHtml) {
      throw new NotSupportedError('sessionHtmlExport', { supported: false, reason: 'not-implemented' });
    }
    return this.handle.exportSessionHtml(outputPath);
  }

  /** 手动压缩会话上下文(capability 见 Capabilities.manualCompact)。 */
  async compactSession(instructions?: string): Promise<ManualCompactResult> {
    this.ensureActive();
    if (!this.capabilities.manualCompact?.supported) {
      throw new NotSupportedError(
        'manualCompact',
        this.capabilities.manualCompact ?? { supported: false, reason: 'not-implemented' },
      );
    }
    if (!this.handle.compactSession) {
      throw new NotSupportedError('manualCompact', { supported: false, reason: 'not-implemented' });
    }
    return this.handle.compactSession(instructions);
  }

  async getSessionTree(): Promise<SessionTreeSnapshot> {
    this.ensureActive();
    const status = this.capabilities.sessionTree ?? { supported: false as const, reason: 'not-implemented' as const };
    if (!status.supported) throw new NotSupportedError('sessionTree', status);
    if (!this.handle.getSessionTree) {
      throw new NotSupportedError('sessionTree', { supported: false, reason: 'not-implemented' });
    }
    return this.handle.getSessionTree();
  }

  async navigateSessionTree(
    entryId: string,
    options?: NavigateSessionTreeOptions,
  ): Promise<NavigateSessionTreeResult> {
    this.ensureActive();
    const status = this.capabilities.sessionTree ?? { supported: false as const, reason: 'not-implemented' as const };
    if (!status.supported) throw new NotSupportedError('sessionTree', status);
    if (!this.handle.navigateSessionTree) {
      throw new NotSupportedError('sessionTree', { supported: false, reason: 'not-implemented' });
    }
    if (this.isTurnRunning()) {
      const err = new Error('SESSION_RUNNING: 会话进行中,无法切换分支');
      (err as { code?: string }).code = 'SESSION_RUNNING';
      throw err;
    }
    return this.handle.navigateSessionTree(entryId, options);
  }

  getFastMode(): boolean | 'ultrafast' | null {
    return this.handle.getFastMode?.() ?? null;
  }

  getEffort(): Effort | null {
    return this.handle.getEffort?.() ?? null;
  }

  /**
   * 运行时合并 vendorOptions (浅合并到内部 closure)。
   * 用于 host 中途切换 session-specific 配置(典型场景:Orca 协同模式 toggle,
   * 传 { orcaRole, orcaWorkflowId, orcaLeadSessionId } 让 MCP provider 的
   * isEnabled(ctx) 在下一 turn 立即返回 true / false)。
   * - Claude Code: 即时生效(下一 turn buildMcpServers 读最新 vo)。
   * - Codex: in-place 合并后重新注册 thread context;HTTP MCP bridge 在
   *          tool-call 时恢复该 context,控制类工具可读到最新 vendorOptions。
   * 不写 DB,持久化由调用方负责(orca_workflows / sessions.orca_role 等)。
   */
  async setVendorOptions(patch: Record<string, unknown>): Promise<void> {
    this.ensureActive();
    if (!this.handle.setVendorOptions) {
      throw new NotSupportedError('vendorOptions', { supported: false, reason: 'not-implemented' });
    }
    await this.handle.setVendorOptions(patch);
  }

  /**
   * 运行时覆盖 extraDirs (附加只读引用目录)。Claude 与 Codex 都在下一 turn 生效。
   * 不写 DB —— 持久化由调用方 (main IPC 协调 local-db:sessions:update) 负责,
   * 跟 setModel/setEffort 双 IPC 协调先例一致。
   */
  async setExtraDirs(dirs: string[], libraryRoot?: string | null): Promise<void> {
    this.ensureActive();
    if (!this.capabilities.extraDirs.supported) {
      throw new NotSupportedError('extraDirs', this.capabilities.extraDirs);
    }
    if (!this.handle.setExtraDirs) {
      throw new NotSupportedError('extraDirs', { supported: false, reason: 'not-implemented' });
    }
    await this.handle.setExtraDirs(dirs, libraryRoot);
  }

  /**
   * 运行时覆盖附加可读写目录。不写 DB;持久化由 host 与 setExtraDirs 相同地协调。
   */
  async setWritableDirs(dirs: string[]): Promise<void> {
    this.ensureActive();
    const capability = this.capabilities.writableDirs;
    if (!capability?.supported) {
      throw new NotSupportedError('writableDirs', capability ?? {
        supported: false,
        reason: 'not-implemented',
      });
    }
    if (!this.handle.setWritableDirs) {
      throw new NotSupportedError('writableDirs', { supported: false, reason: 'not-implemented' });
    }
    await this.handle.setWritableDirs(dirs);
  }

  // ── Rewind (Stage 2 C2) ────────────────────────────────────────────────────
  // Claude 走 SDK checkpoint;Codex 走 thread/rollback 裁剪对话。
  // 业务层 (desktop agentRewind.ts) 通过这个委托对外暴露。

  /**
   * 当前是否有 turn 在跑 (rewind preview/commit 业务前置守卫用)。
   * 默认 false (handle.isTurnRunning 不实现的 agent 永远算 idle)。
   */
  isTurnRunning(): boolean {
    return (
      this.sendReservation !== null ||
      this.hostTurnLeases.size > 0 ||
      this.permissionModeChangesInFlight > 0 ||
      this.isHandleTurnRunning()
    );
  }

  getCurrentTurnId(): string | null {
    return this.handle.getCurrentTurnId?.() ?? null;
  }

  /** Product origin of the dispatched turn; Host owner-only actions refuse automated turns. */
  getCurrentTurnOrigin(): SendOrigin | null {
    return this.currentTurnOrigin;
  }

  /**
   * dryRun: 问 SDK 这次 rewind 会动哪些文件。返回 RewindFilesResult 给 UI 显示 diff。
   * SDK 软拒绝 (老 session 无 checkpointing) 包成 {canRewind:false, error}, 业务可继续。
   */
  async previewRewindFiles(userUuid: string): Promise<RewindFilesResult> {
    if (!this.capabilities.rewind.supported) {
      throw new NotSupportedError('rewind', this.capabilities.rewind);
    }
    if (!this.handle.previewRewindFiles) {
      throw new NotSupportedError('previewRewindFiles', { supported: false, reason: 'not-implemented' });
    }
    this.ensureActive();
    return this.handle.previewRewindFiles(userUuid);
  }

  /**
   * 真执行 rewind: 文件回滚 + close 当前 SDK Query + 标记 pendingRewindTo。
   * 下一次 send 时 agent 内部会自动用三件套 (resume + resumeSessionAt + forkSession) 重启 SDK Query,
   * 对调用方完全透明。
   *
   * 守卫:
   * - capabilities.rewind 不支持 → NotSupportedError
   * - session 已 closed → ensureActive 抛
   * - turn 在跑 → SESSION_RUNNING (业务层应在调本方法前提示用户等结束)
   */
  async commitRewindFiles(
    userUuid: string,
    priorAssistantUuid: string,
    opts?: RewindCommitOptions,
  ): Promise<undefined | RewindCommitResult> {
    if (!this.capabilities.rewind.supported) {
      throw new NotSupportedError('rewind', this.capabilities.rewind);
    }
    if (!this.handle.commitRewindFiles) {
      throw new NotSupportedError('commitRewindFiles', { supported: false, reason: 'not-implemented' });
    }
    this.ensureActive();
    if (this.isTurnRunning()) {
      const err = new Error('SESSION_RUNNING: 会话进行中, 无法 rewind');
      (err as { code?: string }).code = 'SESSION_RUNNING';
      throw err;
    }
    return this.handle.commitRewindFiles(userUuid, priorAssistantUuid, opts);
  }

  // ── 订阅 ─────────────────────────────────────────────────────────────────

  onEvent(listener: SessionEventListener): () => void {
    this.eventListeners.add(listener);
    this.startEventLoopIfNeeded();
    return () => this.eventListeners.delete(listener);
  }

  /**
   * Host-only post-terminal recovery. Persistent product listeners (Orca, Learn,
   * Goal, IM turn text) must not observe these as a new turn.
   */
  onRuntimeRecovery(listener: SessionEventListener): () => void {
    this.runtimeRecoveryListeners.add(listener);
    return () => this.runtimeRecoveryListeners.delete(listener);
  }

  onStatusChange(listener: SessionStatusListener): () => void {
    this.statusListeners.add(listener);
    return () => this.statusListeners.delete(listener);
  }

  /** Host-owned permissions share the same waiting lifecycle as provider interactions. */
  async runHostInteraction(
    request: InteractionRequest,
    resolve: () => Promise<InteractionDecision>,
  ): Promise<InteractionDecision> {
    // Native async questions use the same card resolver, but never suspend turn
    // protection or register a waiting interaction with the lifecycle observer.
    if (request.kind === 'ask_user_question' && request.delivery === 'async') return resolve();
    const isQuestion = request.kind === 'ask_user_question';
    if (isQuestion) {
      this.pendingUserQuestions += 1;
      this.asyncUserQuestions.expire('superseded');
    }
    this.pendingInteractions += 1;
    const runtime = this.observeInteractionStarted(request);
    this.armTurnStallWatchdog();
    try {
      return await resolve();
    } finally {
      if (isQuestion) this.pendingUserQuestions -= 1;
      this.pendingInteractions = Math.max(0, this.pendingInteractions - 1);
      this.observeInteractionSettled(runtime);
      this.armTurnStallWatchdog();
    }
  }

  setInteractionListener(listener: InteractionRequestListener | null): void {
    this.interactionListener = listener;
  }

  /** Display an optional question and return immediately; answers steer only this execution. */
  askUserQuestionAsync(questions: AskUserQuestionItem[]): string {
    // Use the live Session identity, even if a stale MCP context claims another
    // harness. Codex's native adapter is its sole async question owner.
    if (this.agentKind === 'codex') throw new Error('Codex uses native async questions');
    this.ensureActive();
    if (!this.interactionListener) throw new Error('Question UI is unavailable');
    if (this.pendingUserQuestions > 0) throw new Error('A blocking user question is already pending');
    if (!this.capabilities.sameTurnSteer.supported) {
      throw new NotSupportedError('sameTurnSteer', this.capabilities.sameTurnSteer);
    }
    return this.asyncUserQuestions.ask(questions, this.turnGeneration);
  }

  setTurnLifecycleObserver(observer: SessionTurnLifecycleObserver | null): void {
    if (this.turnLifecycleObserver !== observer) this.settleHostTurnContinuation(this.turnGeneration);
    this.turnLifecycleObserver = observer;
  }

  // ── 内部 ──────────────────────────────────────────────────────────────────

  private ensureActive(): void {
    if (this.status === 'closed') {
      throw new Error(`Session ${this.id} is closed`);
    }
    if (this.closePromise || this.terminationStarted) {
      throw new Error(`Session ${this.id} is closing`);
    }
    if (this.status === 'error') {
      throw new Error(`Session ${this.id} is in error state`);
    }
  }

  private setStatus(s: SessionStatus): void {
    if (this.status === s) return;
    this.status = s;
    this.statusListeners.forEach((cb) => {
      try { cb(s); } catch (e) { this.logger.error('status listener threw', { error: String(e) }); }
    });
  }

  private startEventLoopIfNeeded(): void {
    if (this.eventLoopStarted) return;
    this.eventLoopStarted = true;
    void this.runEventLoop();
  }

  private beginTurnControl(generation: number): void {
    this.asyncUserQuestions.expire('superseded');
    this.turnControlState?.toolLoopMonitor?.dispose();
    this.turnControlState = {
      generation,
      // Claude owns per-sidechain guards before translation. Pi/Codex share
      // the same detector here, paired with this product turn's lifecycle.
      toolLoopMonitor: this.agentKind === 'claude-code' ? null : new ToolLoopMonitor(new ToolLoopGuard({
        // These normalized events do not identify model-response batches.
        // Distinct malformed calls can belong to one parallel attempt, so do
        // not enable the retry-count rule without that evidence. Claude also
        // disables category-only retries; repetition rules stay active.
        contractConsecutiveLimit: Number.POSITIVE_INFINITY,
        // Codex code mode: a background script's calls carry no ownership marker;
        // see ToolLoopGuardOptions.burstRepeatGapMs.
        ...(this.agentKind === 'codex' ? { burstRepeatGapMs: CODEX_BURST_REPEAT_GAP_MS } : {}),
      }), {
        reviewer: this.toolLoopReviewer,
        context: () => ({
          sessionId: this.id, agentKind: this.agentKind, model: this.handle.model,
          userIntent: this.toolLoopUserIntent,
        }),
        onReviewedStop: (verdict) => this.interruptReviewedToolLoop(verdict, generation),
        logger: this.logger,
      }),
      pendingToolLoop: null,
      awaitingToolResultSummaries: new Set(),
      activeToolIds: new Set(),
      anonymousActiveTools: 0,
      pendingInteractionToolIds: new Map(),
      gracefulStopState: 'none',
      gracefulStopPromise: null,
    };
    this.inFlightSendOwnsBlockedWait = this.eventLoopAwaiting;
  }

  private clearTurnControl(generation: number): void {
    if (this.turnControlState?.generation !== generation) return;
    this.turnControlState.toolLoopMonitor?.dispose();
    this.turnControlState = null;
  }

  /**
   * Provider 的权限/提问/计划确认会直接经过 InteractionResolver,不保证另发
   * interaction_request event。这里从权威入口更新探针,并把“尚未执行、正在等用户”
   * 视为优雅停止安全点,避免 stop 永久等不到该工具的 result。
   */
  private observeInteractionStarted(
    request: InteractionRequest,
  ): { control: TurnControlState; toolUseId: string | null } | null {
    const control = this.turnControlState;
    if (!control || control.generation !== this.turnGeneration) return null;
    const toolUseId = request.toolUseId?.trim() || null;
    if (toolUseId) {
      control.pendingInteractionToolIds.set(
        toolUseId,
        (control.pendingInteractionToolIds.get(toolUseId) ?? 0) + 1,
      );
    }
    if (
      control.gracefulStopState === 'waiting-for-safe-point' &&
      this.isGracefulStopSafePoint(control)
    ) {
      void this.issueGracefulStop(control);
    }
    return { control, toolUseId };
  }

  private observeInteractionSettled(
    observation: { control: TurnControlState; toolUseId: string | null } | null,
  ): void {
    if (!observation || this.turnControlState !== observation.control) return;
    const { control, toolUseId } = observation;
    if (toolUseId) {
      const remaining = (control.pendingInteractionToolIds.get(toolUseId) ?? 0) - 1;
      if (remaining > 0) control.pendingInteractionToolIds.set(toolUseId, remaining);
      else control.pendingInteractionToolIds.delete(toolUseId);
    }
  }

  private isGracefulStopSafePoint(control: TurnControlState): boolean {
    if (control.anonymousActiveTools > 0) return false;
    return (
      control.activeToolIds.size === 0 ||
      [...control.activeToolIds].every((id) => control.pendingInteractionToolIds.has(id))
    );
  }

  private issueGracefulStop(control: TurnControlState): Promise<SessionGracefulStopResult> {
    if (control.gracefulStopPromise) return control.gracefulStopPromise;
    control.gracefulStopState = 'requesting';
    const abortController = new AbortController();
    const request = Promise.resolve().then(() =>
      this.handle.requestGracefulStop!({ signal: abortController.signal }),
    );
    const result = new Promise<SessionGracefulStopResult>((resolve) => {
      let settled = false;
      const timeout = setTimeout(() => {
        settled = true;
        abortController.abort();
        if (this.turnControlState === control) control.gracefulStopState = 'unconfirmed';
        resolve({
          status: 'unconfirmed',
          turnGeneration: control.generation,
          reason: 'provider-confirmation-timeout',
        });
      }, GRACEFUL_STOP_CONFIRMATION_TIMEOUT_MS);
      (timeout as unknown as { unref?: () => void }).unref?.();
      void request.then(
        () => {
          clearTimeout(timeout);
          if (settled) return;
          settled = true;
          if (this.turnControlState === control) control.gracefulStopState = 'requested';
          resolve({ status: 'requested', turnGeneration: control.generation });
        },
        (error) => {
          clearTimeout(timeout);
          if (settled) return;
          settled = true;
          if (this.turnControlState === control) control.gracefulStopState = 'unconfirmed';
          this.logger.warn('graceful stop request failed', {
            turnGeneration: control.generation,
            error: String(error),
          });
          resolve({
            status: 'unconfirmed',
            turnGeneration: control.generation,
            reason: 'provider-request-failed',
          });
        },
      );
    });
    control.gracefulStopPromise = result;
    return result;
  }

  private observeTurnControl(event: AgentEvent, observedGeneration: number): void {
    const control = this.turnControlState;
    if (!control || control.generation !== observedGeneration || event.turnScope === 'background') return;
    const data = event.data && typeof event.data === 'object'
      ? event.data as Record<string, unknown>
      : {};
    if (event.type === 'tool_use') {
      const toolUseId = typeof data.toolUseId === 'string' ? data.toolUseId : null;
      // Some providers expose display-only tool-shaped snapshots (for example,
      // Codex native plan updates). They have no matching tool_result and must
      // not occupy the graceful-stop safe-point lifecycle.
      if (data.runtimeActivity === 'snapshot') {
        return;
      }
      if (toolUseId) control.activeToolIds.add(toolUseId);
      else control.anonymousActiveTools += 1;
      return;
    }
    if (event.type === 'tool_result_full' || event.type === 'tool_result') {
      const ids = [
        ...(typeof data.toolUseId === 'string' ? [data.toolUseId] : []),
        ...(Array.isArray(data.toolUseIds)
          ? data.toolUseIds.filter((id): id is string => typeof id === 'string')
          : []),
      ];
      for (const id of ids) control.activeToolIds.delete(id);
      if (ids.length === 0 && control.anonymousActiveTools > 0) {
        control.anonymousActiveTools -= 1;
      }
      if (
        this.isGracefulStopSafePoint(control) &&
        control.gracefulStopState === 'waiting-for-safe-point'
      ) {
        void this.issueGracefulStop(control);
      }
    }
  }

  /**
   * 事件 fan-out 的唯一出口(真实事件与看门狗合成的事件共用)。三件事都收在这里,
   * 保证两条来路语义一致 —— origin 打标、订阅者分发、stall 看门狗记账。
   *
   * origin 处理刻意放在这里而不是只放在 runEventLoop:看门狗合成的终态 error 若不
   * 带 turnOrigin,消费方会把它当成"无来源"事件 —— goal-host 归类成 origin:'other'
   * 并像用户插话一样暂停 goal,scheduler 的 IM 转播则直接忽略,卡片永不 finalize
   * (review #944 第二轮)。
   */
  private isIdleStatusEvent(event: AgentEvent): boolean {
    if (event.type !== 'status') return false;
    const data = event.data as { isRunning?: unknown } | null | undefined;
    return data?.isRunning === false;
  }

  private isSilentStopDoneEvent(event: AgentEvent): boolean {
    if (event.type !== 'done') return false;
    const data = event.data as { silentStop?: unknown } | null | undefined;
    return data?.silentStop === true;
  }

  private isLeftoverTailEvent(event: AgentEvent): boolean {
    return (
      (event.type === 'done' && !this.isSilentStopDoneEvent(event)) ||
      this.isIdleStatusEvent(event) ||
      (isTerminalAgentErrorEvent(event) && (
        this.staleTerminalQueuedGeneration !== null ||
        this.pendingPriorGeneration !== null
      ))
    );
  }

  private isNewTurnProgressEvent(event: AgentEvent): boolean {
    if (event.turnScope === 'background') return false;
    return (
      event.type === 'text' ||
      event.type === 'thinking' ||
      event.type === 'image' ||
      event.type === 'tool_use' ||
      event.type === 'tool_result' ||
      event.type === 'tool_result_full'
    );
  }

  /**
   * First top-level output after this generation's product terminal while no send is reserved:
   * the provider started a turn by itself. Subagent output (live `agentMeta.parentUuid`) is the
   * background work, not the wake-up. A steer carried over from the ended turn owns the first
   * such turn instead. Returns true only for the opening event of a provider-initiated turn.
   */
  private isProviderInitiatedTurnStart(
    event: AgentEvent,
    isBackgroundEvent: boolean,
    isCurrentGeneration: boolean,
  ): boolean {
    if (isBackgroundEvent || !isCurrentGeneration || !this.isNewTurnProgressEvent(event)) return false;
    const parentUuid = event.agentMeta?.parentUuid;
    if (typeof parentUuid === 'string' && parentUuid.length > 0) return false;
    const generation = this.turnGeneration;
    if (
      generation <= 0 ||
      this.terminalEventObservedGeneration !== generation ||
      this.sendReservation !== null ||
      this.isUnacceptedCurrentSend() ||
      this.retirementContinuationGeneration === generation ||
      this.unsolicitedTurnGeneration === generation
    ) {
      return false;
    }
    this.unsolicitedTurnGeneration = generation;
    const carriedSteer = this.steerAcceptedGeneration === generation;
    this.steerAcceptedGeneration = null;
    return !carriedSteer;
  }

  private resolveSessionTurnGeneration(
    waitStartGeneration: number,
    observedGeneration: number,
    event: AgentEvent,
  ): number {
    const attributed = (generation: number): number => {
      if (this.isForegroundRunningStatus(event)) {
        this.sawCurrentTurnRunningGeneration = generation;
        if (generation === this.turnGeneration) {
          this.pendingPriorGeneration = null;
          this.staleTerminalQueuedGeneration = null;
        }
      }
      return generation;
    };
    const inFlightGeneration =
      this.sendReservation?.generation ??
      (this.isUnacceptedCurrentSend() ? this.unacceptedSendGeneration : null);
    this.lastResolvedInFlightSend = false;
    const belongsToInFlightSend =
      this.insideProviderSendSync &&
      this.inFlightSendOwnsBlockedWait &&
      typeof inFlightGeneration === 'number' &&
      inFlightGeneration === this.turnGeneration &&
      this.turnControlState?.generation === inFlightGeneration;
    if (observedGeneration > waitStartGeneration) {
      // A wait that started on N can adopt N+1 progress, but a queued N
      // error must not ride that adoption into N+1. Errors emitted by the
      // active handle.send() stay on the in-flight generation.
      if (
        isTerminalAgentErrorEvent(event) &&
        this.pendingPriorGeneration !== null &&
        this.pendingPriorGeneration < this.turnGeneration &&
        this.lastObservedTerminalKind !== 'error' &&
        this.sawCurrentTurnRunningGeneration !== this.turnGeneration &&
        this.isUnacceptedCurrentSend() &&
        !belongsToInFlightSend
      ) {
        const prior = this.pendingPriorGeneration;
        this.pendingPriorGeneration = null;
        this.staleTerminalQueuedGeneration = null;
        return attributed(prior);
      }
      this.staleTerminalQueuedGeneration = null;
      if (
        this.isNewTurnProgressEvent(event) ||
        this.isForegroundRunningStatus(event) ||
        belongsToInFlightSend
      ) {
        this.pendingPriorGeneration = null;
      }
      return attributed(observedGeneration);
    }
    const prior = this.pendingPriorGeneration;
    const leftoverDoneOrIdle =
      (event.type === 'done' && !this.isSilentStopDoneEvent(event)) ||
      this.isIdleStatusEvent(event);
    const leftoverUnobservedPriorError =
      isTerminalAgentErrorEvent(event) &&
      prior !== null &&
      this.sawCurrentTurnRunningGeneration !== this.turnGeneration &&
      this.isUnacceptedCurrentSend() &&
      (
        !belongsToInFlightSend ||
        this.sawCurrentTurnRunningGeneration === prior
      ) &&
      (event.data as { reason?: string } | undefined)?.reason !== 'session_event_loop_crashed';
    if (prior !== null && (leftoverDoneOrIdle || leftoverUnobservedPriorError) && waitStartGeneration !== 0) {
      if (event.type === 'done' || leftoverUnobservedPriorError) {
        this.pendingPriorGeneration = null;
        this.staleTerminalQueuedGeneration = null;
      } else {
        this.staleTerminalQueuedGeneration = prior;
      }
      return attributed(prior);
    }
    const leftoverTail =
      this.isLeftoverTailEvent(event) &&
      !(
        belongsToInFlightSend &&
        isTerminalAgentErrorEvent(event) &&
        this.staleTerminalQueuedGeneration === null
      );
    if (
      leftoverTail &&
      this.staleTerminalQueuedGeneration !== null &&
      this.isUnacceptedCurrentSend()
    ) {
      const stamped = this.staleTerminalQueuedGeneration;
      if (event.type === 'done' || isTerminalAgentErrorEvent(event)) {
        this.staleTerminalQueuedGeneration = null;
      }
      return attributed(stamped);
    }
    if (leftoverTail && waitStartGeneration > 0 && waitStartGeneration < this.turnGeneration) {
      if (event.type === 'done' || isTerminalAgentErrorEvent(event)) {
        this.staleTerminalQueuedGeneration = null;
      } else {
        this.staleTerminalQueuedGeneration = waitStartGeneration;
      }
      return attributed(waitStartGeneration);
    }
    // N already observed a terminal error. A later error/done in the N+1
    // unaccepted send window is leftover N, not an in-flight N+1 start-failure.
    if (
      !belongsToInFlightSend &&
      waitStartGeneration > 0 &&
      waitStartGeneration < this.turnGeneration &&
      this.lastObservedTerminalGeneration === waitStartGeneration &&
      this.lastObservedTerminalKind === 'error' &&
      (event.type === 'done' || isTerminalAgentErrorEvent(event))
    ) {
      this.staleTerminalQueuedGeneration = null;
      return attributed(waitStartGeneration);
    }
    if (belongsToInFlightSend) {
      this.inFlightSendOwnsBlockedWait = false;
      this.staleTerminalQueuedGeneration = null;
      this.lastResolvedInFlightSend = true;
      if (
        this.isNewTurnProgressEvent(event) ||
        event.type === 'done' ||
        isTerminalAgentErrorEvent(event)
      ) {
        this.pendingPriorGeneration = null;
      }
      return attributed(inFlightGeneration);
    }
    if (waitStartGeneration === 0 && this.turnGeneration > 0) {
      this.staleTerminalQueuedGeneration = null;
      return attributed(this.turnGeneration);
    }
    if (this.isNewTurnProgressEvent(event)) {
      // New-turn tokens prove this generation owns later product terminals.
      // Drop a leftover idle-only tail too: if that old done is lost, the
      // live done must not inherit staleQueued and get fenced.
      this.pendingPriorGeneration = null;
      this.staleTerminalQueuedGeneration = null;
    }
    return attributed(waitStartGeneration);
  }

  private dispatchRuntimeRecovery(event: AgentEvent): void {
    if (event.sessionInstanceId === undefined) {
      event.sessionInstanceId = this.instanceId;
    }
    if (event.sessionTurnGeneration === undefined) {
      event.sessionTurnGeneration = this.turnGeneration;
    }
    const listenerEvent = redactEventForListeners(event);
    for (const listener of this.runtimeRecoveryListeners) {
      try { listener(listenerEvent); } catch (e) {
        this.logger.error('runtime recovery listener threw', { error: String(e) });
      }
    }
  }

  private fanOutEvent(
    event: AgentEvent,
    observedGeneration = this.turnGeneration,
    queuedGeneration = observedGeneration,
  ): void {
    if (event.runtimeRecovery) {
      this.dispatchRuntimeRecovery(event);
      return;
    }
    const isBackgroundEvent = event.turnScope === 'background';
    this.lastEventType = event.type;
    if (event.sessionInstanceId === undefined) {
      event.sessionInstanceId = this.instanceId;
    }
    this.lastResolvedInFlightSend = false;
    if (event.sessionTurnGeneration === undefined) {
      event.sessionTurnGeneration = this.resolveSessionTurnGeneration(
        queuedGeneration,
        observedGeneration,
        event,
      );
    }
    const resolvedGeneration = event.sessionTurnGeneration ?? observedGeneration;
    // Both the source stamp and the dequeued wait must name this turn.
    // A leftover tail can be stamped N while next() recaptures N+1, or the
    // reverse when an in-flight start-failure adopts the new generation from
    // an older wait. Current-turn cleanup requires agreement.
    const isCurrentGeneration =
      resolvedGeneration === this.turnGeneration &&
      observedGeneration === this.turnGeneration;
    // leftover / 旧 generation 的产品事件不能把当前 turn 的 stall 日志时钟往前拨。
    // 心跳与非产品事件同样不算(见 isTurnWatchdogLivenessEvent)。
    if (!isBackgroundEvent && isCurrentGeneration && isTurnWatchdogLivenessEvent(event)) {
      this.lastEventAt = Date.now();
    }
    // In-flight start-failure is stamped N+1 from an older wait. Snapshot and
    // probe must still settle the current send even when observed stays on N.
    const settleAsCurrentGeneration =
      isCurrentGeneration ||
      (
        this.lastResolvedInFlightSend &&
        resolvedGeneration === this.turnGeneration &&
        (this.agentKind === 'codex' || this.agentKind === 'pi')
      );
    this.observeTurnControl(event, resolvedGeneration);
    // fan-out 前打 turn origin(所有 listener 拿到同一份);事件对象由 translator
    // 每次新建、看门狗每次合成,不会串台。=== undefined 守卫:不覆盖 agent 自带的。
    if (!isBackgroundEvent && isCurrentGeneration && this.currentTurnOrigin && event.turnOrigin === undefined) {
      event.turnOrigin = this.currentTurnOrigin;
    }
    if (
      !isBackgroundEvent &&
      isCurrentGeneration &&
      this.currentTurnAttemptToken !== null &&
      event.turnAttemptToken === undefined
    ) {
      event.turnAttemptToken = this.currentTurnAttemptToken;
    }
    // A provider continuation claim turns this `done` into an SDK-turn
    // boundary, not a product-turn terminal. Keep the same origin/token and
    // stall watchdog across the automatic continuation; only its later done
    // (or a terminal error / explicit cancellation) ends the product turn.
    const continuationState =
      event.type === 'done' && event.turnContinuationId !== undefined
        ? this.beginTurnContinuationWait(event.turnContinuationId)
        : null;
    // Any matching claim proves this event is the provider's first SDK-turn
    // boundary, including a claim that was cancelled before the queue reached
    // us. Claude appends a separate, unclaimed done after the stopped task
    // event; that ordered boundary is what closes the Session generation.
    const hasPendingContinuation = continuationState !== null;
    const isTerminal =
      (event.type === 'done' && !hasPendingContinuation) || isTerminalAgentErrorEvent(event);
    if (isTerminal && !isBackgroundEvent) {
      this.asyncUserQuestions.expire(event.type === 'error' ? 'turn_failed' : 'turn_completed', resolvedGeneration);
    }
    // A dispatching send is not enough evidence that a terminal event belongs
    // to it: Codex can enqueue the previous turn's terminal error after flipping
    // its handle idle. Only runEventLoop's generation adoption may transfer
    // ownership to the new attempt.
    const preDispatchReservation = this.isPreDispatchReservation();
    const sameGenerationError =
      this.terminalEventObservedGeneration === this.turnGeneration &&
      this.terminalEventObservedKind === 'error';
    const sameGenerationDone =
      this.terminalEventObservedGeneration === this.turnGeneration &&
      this.terminalEventObservedKind === 'done';
    // A late leftover error must not replace N+1's result-only success,
    // nor fan-out as a current-generation failure to lifecycle / IPC listeners.
    // A provider-initiated turn reuses the generation whose done was already
    // seen: its own terminal error is not a leftover of that done.
    const lateErrorAfterDoneSnapshot =
      event.type === 'error' && sameGenerationDone && this.unsolicitedTurnGeneration !== this.turnGeneration;
    const reservationWindowLeftover =
      isTerminal &&
      !isBackgroundEvent &&
      this.isUnacceptedCurrentSend() &&
      resolvedGeneration !== this.turnGeneration &&
      (
        (
          this.lastObservedTerminalKind === 'error' &&
          this.lastObservedTerminalGeneration !== null &&
          this.lastObservedTerminalGeneration < this.turnGeneration
        ) ||
        (
          this.pendingPriorGeneration !== null &&
          this.pendingPriorGeneration < this.turnGeneration &&
          isTerminalAgentErrorEvent(event) &&
          this.sawCurrentTurnRunningGeneration !== this.turnGeneration &&
          resolvedGeneration !== this.turnGeneration
        )
      );
    const terminalBoundaryObserved =
      settleAsCurrentGeneration && isTerminal && !isBackgroundEvent && !preDispatchReservation;
    if (terminalBoundaryObserved && !lateErrorAfterDoneSnapshot && !reservationWindowLeftover) {
      this.terminalEventObservedGeneration = this.turnGeneration;
      this.lastObservedTerminalGeneration = this.turnGeneration;
      this.lastObservedTerminalKind = event.type === 'error' ? 'error' : 'done';
      if (event.type === 'error') {
        this.terminalEventObservedKind = 'error';
        this.armTerminalErrorDrain(this.turnGeneration);
      } else {
        // Codex 失败收尾是 terminal error 后再补 done。同 generation 的成功尾巴
        // 不得把已记录的 error 改写成 done,否则 Host 会把失败当成功结算。
        if (!sameGenerationError) {
          this.terminalEventObservedKind = 'done';
          this.terminalEventObservedErrorMessage = null;
          this.terminalEventObservedErrorSignals = null;
        }
        this.clearTerminalErrorDrain();
      }
    } else if (
      this.agentKind === 'codex' &&
      isCurrentGeneration &&
      event.type === 'status' &&
      (event.data as { isRunning?: unknown } | null | undefined)?.isRunning === false &&
      this.terminalErrorDrainGeneration === this.turnGeneration
    ) {
      // Codex closes a terminal error with an idle status rather than a done
      // event. That status drains the provider tail, but it is not itself a
      // generation boundary for ordinary status events.
      this.clearTerminalErrorDrain();
    } else if (
      event.type === 'done' &&
      !isBackgroundEvent &&
      this.terminalErrorDrainGeneration !== null &&
      this.lastObservedTerminalKind === 'error' &&
      this.terminalErrorDrainGeneration === this.lastObservedTerminalGeneration
    ) {
      // Rolled-back / leftover paired done still belongs to the promoted error.
      this.clearTerminalErrorDrain();
    }
    if (this.isProviderInitiatedTurnStart(event, isBackgroundEvent, isCurrentGeneration)) {
      try {
        this.turnLifecycleObserver?.onProviderInitiatedTurn?.(resolvedGeneration);
      } catch (error) {
        this.logger.warn('provider-initiated turn observer failed', {
          turnGeneration: resolvedGeneration,
          error: String(error),
        });
      }
    }
    const listenerEvent = redactEventForListeners(event);
    if (
      terminalBoundaryObserved &&
      event.type === 'error' &&
      this.terminalEventObservedKind === 'error'
    ) {
      const snapshot = this.readRedactedTerminalErrorSnapshot(listenerEvent);
      this.terminalEventObservedErrorMessage = snapshot.message;
      this.terminalEventObservedErrorSignals = snapshot.signals;
    } else if (
      isTerminal &&
      !isBackgroundEvent &&
      this.isUnacceptedCurrentSend() &&
      (!settleAsCurrentGeneration || preDispatchReservation)
    ) {
      // N 的终态在 N+1 reservation / handle.send 窗口到达:先记在窗口快照里,
      // 等拒绝回滚再提升。成功派发的 N+1 不得继承这份证据。
      // Reservation 可能已因 handle running 被释放,仍按未接受 generation 记。
      this.rememberReservationWindowPriorTerminal(event, listenerEvent);
    }
    if (isCurrentGeneration && isTerminal && !isBackgroundEvent && !lateErrorAfterDoneSnapshot && !reservationWindowLeftover) {
      if (!this.isSilentStopDoneEvent(event)) this.retirementContinuationGeneration = null;
      this.unsolicitedTurnGeneration = null;
      this.clearTurnControl(resolvedGeneration);
    }
    const isLeftoverProductTerminal =
      !isBackgroundEvent &&
      (
        resolvedGeneration < this.turnGeneration ||
        lateErrorAfterDoneSnapshot ||
        reservationWindowLeftover
      ) &&
      (isTerminal || this.isIdleStatusEvent(event));
    if (isTerminal && !isBackgroundEvent && !isLeftoverProductTerminal) {
      try {
        const pending = this.turnLifecycleObserver?.onTerminal({
          turnGeneration: resolvedGeneration,
          event: listenerEvent,
          isCurrentGeneration,
        });
        if (pending) {
          void Promise.resolve(pending).catch((error) => {
            this.logger.warn('turn lifecycle terminal cleanup failed', {
              turnGeneration: resolvedGeneration,
              error: String(error),
            });
          });
        }
      } catch (error) {
        this.logger.warn('turn lifecycle terminal cleanup failed', {
          turnGeneration: resolvedGeneration,
          error: String(error),
        });
      }
    }
    if (!isLeftoverProductTerminal) {
      for (const listener of this.eventListeners) {
        try { listener(listenerEvent); } catch (e) { this.logger.error('event listener threw', { error: String(e) }); }
      }
    }
    // A late child update belongs to the completed parent turn. It remains
    // visible to listeners, but must not clear/adopt the current turn or keep
    // its zero-event watchdog alive.
    if (isBackgroundEvent) return;
    // turn 真正结束后清 origin,下一轮无 origin 的 turn 不被污染。
    // 关键:**只**在 done / 终止型 error 上清,**不要**在 status(isRunning=false)
    // 上清 —— translator 收尾是先 push end-status(isRunning=false)、紧接着 push
    // done(claude translator.ts / codex 同序)。若在 end-status 上清,后随的 done
    // 就拿不到 origin,而 IM 转播(turnRunner)正是按 scheduler-origin 的 done 收口
    // 卡片;done 丢了 origin → 卡片永不 finalize,残留 ticker/state 污染下一轮转播。
    // done / 终止型 error 自身已在上面打过 origin,清在它们之后安全。
    //
    // Bridge /compact 这类 agent 内部排队 turn 的边界应在 agent 层 suppress,
    // 不应透传到 Session。provider 明确附 continuation claim 的 done 是唯一例外:
    // 它只结束当前 SDK turn,产品层 Agent 仍在执行;其余到达 Session 的 done /
    // 终止型 error 才代表产品 turn 已结束,必须清 origin,避免后续 standalone
    // auto-compact 等后台 turn 继承 goal/scheduler origin。
    if (isCurrentGeneration && isTerminal && !isLeftoverProductTerminal) {
      this.currentTurnOrigin = null;
      this.currentTurnAttemptToken = null;
      // 终态之后不再计 stall 额度。
      this.clearTurnStallWatchdog();
      // Only an actual Host claim keeps the executor available for bounded
      // silent-stop continuation; an unowned terminal can retire normally.
      this.finishRetirementIfSettled();
    } else if (isCurrentGeneration && isTurnWatchdogLivenessEvent(event)) {
      this.armTurnStallWatchdog();
    }
    // Deliver the completed tool result before the loop error; never discard
    // evidence or count both full and summary projections of the same result.
    if (isCurrentGeneration) this.observeToolLoop(event, resolvedGeneration);
  }

  /**
   * 工具循环检测与中断的唯一会话级前提:同步观察与后台复核结论共用,避免两处判据分叉。
   * 同一 turn、会话仍活跃且未进入拆除、没有等人确认、没有优雅停止。
   */
  private toolLoopControlFor(generation: number): TurnControlState | null {
    const control = this.turnControlState;
    if (!control?.toolLoopMonitor || control.generation !== generation ||
      generation !== this.turnGeneration || this.status !== 'active' || this.closePromise ||
      this.terminationStarted || this.pendingInteractions > 0 ||
      control.gracefulStopState !== 'none') return null;
    return control;
  }

  private observeToolLoop(event: AgentEvent, generation: number): void {
    if (event.type !== 'text' && event.type !== 'tool_use' && event.type !== 'tool_result_full' && event.type !== 'tool_result') return;
    if (event.turnScope === 'background' || event.sessionInstanceId !== this.instanceId) return;
    const data = event.data && typeof event.data === 'object'
      ? event.data as Record<string, unknown> : {};
    if (data.runtimeActivity === 'snapshot') return;
    // 摘要配对记账不受检测暂停(等人确认等)影响,否则复核终态可能等一个早已送达的摘要。
    this.trackToolResultSummaries(event, data, generation);
    const control = this.toolLoopControlFor(generation);
    if (!control?.toolLoopMonitor) return;
    if (event.type === 'text') {
      if (typeof data.text === 'string') control.toolLoopMonitor.onAssistantText(data.text, data.isFinal === true);
      return;
    }
    if (event.type === 'tool_result') {
      const pending = control.pendingToolLoop;
      if (!pending || !Array.isArray(data.toolUseIds) || !data.toolUseIds.includes(pending.toolUseId)) return;
      control.pendingToolLoop = null;
      this.interruptToolLoop(pending.verdict, generation);
      return;
    }
    if (typeof data.toolUseId !== 'string' || control.pendingToolLoop) return;
    if (event.type === 'tool_use') {
      control.toolLoopMonitor.onToolUse(data.toolUseId, data.toolName, data.input);
      return;
    }
    if (event.type !== 'tool_result_full' || typeof data.fullText !== 'string') return;
    const verdict = control.toolLoopMonitor.onToolResult(data.toolUseId, data.fullText, data.isError === true);
    if (verdict.kind !== 'hard') return;
    // Both translators enqueue full text before its summary. Let listeners
    // consume both projections before terminal cleanup clears their pairing.
    // This belongs to TurnControlState so termination/takeover discards it.
    control.pendingToolLoop = { toolUseId: data.toolUseId, verdict };
  }

  private trackToolResultSummaries(event: AgentEvent, data: Record<string, unknown>, generation: number): void {
    const control = this.turnControlState;
    if (!control || control.generation !== generation) return;
    if (event.type === 'tool_result_full' && typeof data.toolUseId === 'string') {
      control.awaitingToolResultSummaries.add(data.toolUseId);
    } else if (event.type === 'tool_result' && Array.isArray(data.toolUseIds)) {
      for (const id of data.toolUseIds) if (typeof id === 'string') control.awaitingToolResultSummaries.delete(id);
    }
  }

  /**
   * 后台复核判定 stop 时,结果可能晚于 turn 结束、接管或关闭到达。只有同一 turn
   * 仍满足 observeToolLoop 的全部前提时才中断;否则丢弃。
   */
  private interruptReviewedToolLoop(verdict: HardToolLoopVerdict, generation: number): void {
    const control = this.toolLoopControlFor(generation);
    if (!control || control.pendingToolLoop) return;
    // 与同步判定同一顺序约束:还有完整结果未配上摘要时,等最后一个摘要送达再发终态。
    const awaiting = [...control.awaitingToolResultSummaries].at(-1);
    if (awaiting !== undefined) {
      control.pendingToolLoop = { toolUseId: awaiting, verdict };
      return;
    }
    this.interruptToolLoop(verdict, generation);
  }

  private interruptToolLoop(verdict: HardToolLoopVerdict, generation: number): void {
    this.fanOutEvent({
      type: 'error',
      data: {
        message: `Repeated tool calls (${verdict.count}) indicate a tool loop; this turn was interrupted. You can send the next message to continue.`,
        isTerminal: true,
        reason: 'tool_use_loop_detected',
        toolLoop: { kind: verdict.reason, count: verdict.count },
      },
      source: this.agentKind,
    });
    // A listener can synchronously take over. Never interrupt its replacement.
    if (generation !== this.turnGeneration) return;
    // abort() already owns confirmation/rebuild fallback; no second watchdog.
    void this.abort().catch((error) => {
      this.logger.warn('tool loop interrupt failed', { error: String(error) });
    });
  }

  private clearTurnStallWatchdog(refresh = false): void {
    if (this.turnStallTimer) {
      clearTimeout(this.turnStallTimer);
      this.turnStallTimer = null;
    }
    this.turnStallRemainingMs = 0;
    this.turnStallSliceStartedAt = 0;
    if (!refresh && this.turnStallDiagnosticState === 'armed') {
      this.logger.info('turn stall watchdog disarmed', { status: this.status });
      this.turnStallDiagnosticState = 'idle';
    }
  }

  private clearTerminalErrorDrain(): void {
    if (this.terminalErrorDrainTimer) {
      clearTimeout(this.terminalErrorDrainTimer);
      this.terminalErrorDrainTimer = null;
    }
    this.terminalErrorDrainGeneration = null;
  }

  private armTerminalErrorDrain(generation: number): void {
    this.clearTerminalErrorDrain();
    this.terminalErrorDrainGeneration = generation;
    const timer = setTimeout(() => {
      this.terminalErrorDrainTimer = null;
      if (this.terminalErrorDrainGeneration !== generation) return;
      this.logger.warn('terminal error drain timed out; closing session for rebuild', {
        generation,
        graceMs: TERMINAL_ERROR_DRAIN_GRACE_MS,
      });
      void this.closeFromRuntime().catch((error) => {
        this.logger.warn('terminal error drain close failed', { error: String(error) });
      });
    }, TERMINAL_ERROR_DRAIN_GRACE_MS);
    this.terminalErrorDrainTimer = timer;
    (timer as unknown as { unref?: () => void }).unref?.();
  }

  /**
   * (重新)起 turn 零事件看门狗。以下情形不起表:
   *   - 阈值被关掉(0)
   *   - 会话已不活跃(closed / error / aborting)
   *   - 没有 turn 在跑 —— 空闲会话本来就没有事件
   *   - 正在等用户回应交互 —— 权限询问 / AskUserQuestion / plan review 可能挂很久
   *   - 有后台任务在跑 —— run_in_background 的 Bash、后台 subagent 期间安静是正常的
   * 后两条是误杀防护(见 DEFAULT_TURN_STALL_MS)。
   */
  private armTurnStallWatchdog(): void {
    this.clearTurnStallWatchdog(true);
    const reason = this.turnStallMs <= 0 ? 'disabled'
      : this.status !== 'active' ? this.status
      : this.closePromise ? 'closing'
      : !this.isTurnRunning() && !this.hasUnsettledTurn() ? 'no-active-turn'
      : this.pendingInteractions > 0 ? 'pending-interaction'
      : this.hasRunningBackgroundTasks() ? 'background-task' : null;
    if (reason) {
      if (this.turnStallDiagnosticState !== reason) {
        this.logger.info('turn stall watchdog suspended', { reason });
        this.turnStallDiagnosticState = reason;
      }
      return;
    }
    this.turnStallRemainingMs = this.turnStallMs;
    const now = Date.now();
    // Bound refresh diagnostics to once per minute, independent of token volume.
    if (this.turnStallDiagnosticState !== 'armed' || now - this.turnStallLastDiagnosticAt >= 60_000) {
      this.logger.info(this.turnStallDiagnosticState !== 'armed'
        ? 'turn stall watchdog armed' : 'turn stall watchdog refreshed', {
        timeoutMs: this.turnStallMs,
        lastActivityAt: now,
        deadlineWithoutSuspendAt: now + this.turnStallMs,
      });
      this.turnStallLastDiagnosticAt = now;
    }
    this.turnStallDiagnosticState = 'armed';
    this.armTurnStallSlice();
  }

  /**
   * 分片计时:每片最多 TURN_STALL_SLICE_MS,片尾核对"这一片真实走了多久"。
   *
   * 不能用一个 45 分钟的长定时器直接判定 —— Electron 被系统挂起(合盖睡眠)期间没有任何
   * 事件,而定时器一旦在唤醒后到期就立刻开火:一次午休就足以让看门狗给一条完全健康的
   * turn 推终态 error 并中断它(review #944 第十二轮 P1)。
   *
   * 片尾若发现壁钟走得远超本片时长,说明进程被冻结过 —— 这段不计入额度,重新起片。
   * 只有"清醒地"连续静默满 turnStallMs 才判卡死。与 scheduler 侧
   * absorbSuspendGap / tick 的挂起处理,以及 codex(armUpstreamIdleSlice)、
   * claude-code(armUpstreamResponseIdleSlice)两个 upstream-idle 看门狗同源。
   */
  private armTurnStallSlice(): void {
    const slice = Math.min(this.turnStallRemainingMs, TURN_STALL_SLICE_MS);
    this.turnStallSliceStartedAt = Date.now();
    this.turnStallTimer = setTimeout(() => {
      this.turnStallTimer = null;
      const elapsed = Date.now() - this.turnStallSliceStartedAt;
      if (elapsed > slice + TURN_STALL_SUSPEND_GAP_MS) {
        // 系统挂起过:这一片不算数,原地重开(额度不扣)。
        this.logger.info('turn stall watchdog skipped a suspended slice', {
          sliceMs: slice,
          elapsedMs: elapsed,
        });
        // 唤醒后的状态可能已经变了(turn 结束 / 冒出交互 / 起了后台任务),走完整重判。
        this.armTurnStallWatchdog();
        return;
      }
      this.turnStallRemainingMs -= Math.max(0, elapsed);
      if (this.turnStallRemainingMs > 0) {
        this.armTurnStallSlice();
        return;
      }
      this.onTurnStallTimeout();
    }, slice);
    // 不让看门狗拖住进程退出(Electron main 常驻无感,vitest / CLI 宿主有感)。
    (this.turnStallTimer as unknown as { unref?: () => void }).unref?.();
  }

  private hasRunningBackgroundTasks(): boolean {
    try {
      return (this.handle.listBackgroundTasks?.() ?? []).length > 0;
    } catch (e) {
      // 查询失败按"没有后台任务"处理:看门狗宁可起表(仍有 45min 缓冲 + 其余排除项),
      // 也不要因为一个诊断查询抛错就永久失效。
      this.logger.warn('listBackgroundTasks threw while arming stall watchdog', { error: String(e) });
      return false;
    }
  }

  /**
   * turn 零事件超时:整条链路(上游 / 工具 / 子进程 stdio)已经没有任何动静。
   * 先合成一条终态 error 事件让所有消费方收口(renderer 停转圈、scheduler 把 run 记
   * failed、IM 转播 finalize 卡片),再中断 turn。
   *
   * 顺序与 claude-code 的 upstream-idle watchdog 一致:先推事件再中断 —— 中断本身
   * 可能只 drain 出一个空 done(会被上游当成静默收尾),不足以让消费方知道发生了什么。
   *
   * 用 abort() 而不是 close():abort 在各 agent 里都是"只 interrupt 当前 turn"的安全
   * 语义(见 claude-code handle.abort 注释),会话保持可用,用户可以直接发下一条继续。
   */
  private onTurnStallTimeout(): void {
    // 触发前复核:定时器排上队之后可能已经收到事件 / turn 已结束 / 冒出交互等待。
    if (this.status !== 'active' || this.closePromise) return;
    if (!this.isTurnRunning() && !this.hasUnsettledTurn()) return;
    if (this.pendingInteractions > 0) return;
    if (this.hasRunningBackgroundTasks()) return;
    const now = Date.now();
    const msSinceLastEvent = this.lastEventAt > 0 ? now - this.lastEventAt : null;
    this.logger.warn('turn stall watchdog tripped — no product activity, interrupting turn', {
      turnStallMs: this.turnStallMs,
      lastEventType: this.lastEventType,
      msSinceLastEvent,
    });
    const minutes = Math.round(this.turnStallMs / 60_000);
    this.fanOutEvent({
      type: 'error',
      data: {
        // reason 是 renderer i18n 的稳定 key(ERROR_REASON_I18N_KEYS,规则 18);
        // message 仅作非 renderer 消费方(IM / orca / 日志)的英文兜底。
        message:
          `This turn produced no activity at all for ${minutes} minutes ` +
          '(upstream, tools and the agent subprocess were all silent); ' +
          'it was interrupted automatically. You can send the next message to continue.',
        isTerminal: true,
        reason: this.handle.isPreparingUserTurn?.()
          ? 'bridge_turn_no_event_timeout'
          : 'turn_no_event_timeout',
        turnStallMs: this.turnStallMs,
        lastEventType: this.lastEventType,
        msSinceLastEvent,
      },
      source: this.agentKind,
    } as AgentEvent);
    // 复核定时器**先于** abort 排定,且不挂在 abort 的 promise 上。
    // 曾经写在 .finally() 里,但 abort 走的正是"已经哑火"的那条链路:agent 的
    // handle.abort() 若自己也悬挂(如 turn/interrupt RPC 永不返回),promise 永不 settle
    // → finally 永不执行 → 复核永不发生 → 会话永久不可用,恰好是本看门狗要救的场景
    // (review #944 第五轮 Copilot)。recoverIfTurnStillRunning 自己会复核 isTurnRunning,
    // abort 正常生效时它是 no-op,所以无条件排定是安全的。
    // 复核由 abort() 内部统一排(见 scheduleAbortRecoveryCheck),这里只需要用看门狗
    // 自己的短宽限覆盖它:本路径已经确诊卡死,不必再等手动 Stop 那样长的时间。
    this.scheduleAbortRecoveryCheck(STALL_ABORT_RECOVERY_GRACE_MS, 'stall-watchdog');
    void this.abort().catch((e) => {
      this.logger.warn('turn stall watchdog abort failed', { error: String(e) });
    });
  }

  /**
   * 排一次"abort 到底生效了吗"的复核。中断请求本身可能永不 settle(codex 的
   * turn/interrupt 悬挂),所以定时器**不挂在 abort 的 promise 上**;也必须绑定当时的
   * turn 代号,否则宽限期内新起的健康 turn 会被误杀(见 turnGeneration)。
   * 幂等:同一 turn 上重复 abort 只保留最早排定的那次复核。
   */
  private scheduleAbortRecoveryCheck(graceMs: number, trigger: 'stall-watchdog' | 'manual-abort'): void {
    const generation = this.turnGeneration;
    if (this.abortRecoveryScheduledFor === generation) return;
    this.abortRecoveryScheduledFor = generation;
    // 宽限也要**排除系统挂起**:合盖睡眠期间 transport 一个字节都收不到,而裸定时器一旦在
    // 唤醒后到期就立刻开火 —— 一次午休就能让"给 interrupt 的 10s / 60s"变成 0s 有效时间,
    // 复核于是关掉一条其实还响应得动的会话(第十八轮 P1)。与 armTurnStallSlice、codex 的
    // armUpstreamIdleSlice、claude-code 的 armUpstreamResponseIdleSlice、scheduler 的
    // absorbSuspendGap、排队派发的 QUEUED_DISPATCH_SUSPEND_GAP_MS 同源:壁钟差 ≠ 清醒时间。
    this.armAbortRecoverySlice(generation, graceMs, graceMs, trigger);
  }

  /** 宽限的分片计时:片尾核对壁钟,发现被冻结过就把那一片作废重开(额度不扣)。 */
  private armAbortRecoverySlice(
    generation: number,
    remainingMs: number,
    graceMs: number,
    trigger: 'stall-watchdog' | 'manual-abort',
  ): void {
    const slice = Math.min(remainingMs, TURN_STALL_SLICE_MS);
    const startedAt = Date.now();
    const timer = setTimeout(() => {
      const elapsed = Date.now() - startedAt;
      if (elapsed > slice + TURN_STALL_SUSPEND_GAP_MS) {
        this.logger.info('abort recovery skipped a suspended slice', {
          trigger,
          sliceMs: slice,
          elapsedMs: elapsed,
        });
        this.armAbortRecoverySlice(generation, remainingMs, graceMs, trigger);
        return;
      }
      const left = remainingMs - Math.max(0, elapsed);
      if (left > 0) {
        this.armAbortRecoverySlice(generation, left, graceMs, trigger);
        return;
      }
      // 把真正生效的宽限与触发来源带进复核:两条路径的宽限不同(手动 60s / 看门狗 10s),
      // 幂等又只保留最早排定的那一次 —— 日志里写死任一常量都会误导事故排查
      // (review #944 第十八轮 Copilot)。
      void this.recoverIfTurnStillRunning(generation, { graceMs, trigger });
    }, slice);
    (timer as unknown as { unref?: () => void }).unref?.();
  }

  /**
   * abort 的兜底复核(看门狗中断与手动 abort 共用):turn 仍在跑说明 agent 层的中断没生效,
   * 会话已经不可用(isTurnRunning 恒 true → 后续 send 全被拒)。关掉它,让下一次 send 走
   * Maker 的 lazy create 重建 handle。这是所有 agent 共用的恢复出路,不需要各自实现重建。
   */
  private async recoverIfTurnStillRunning(
    stalledGeneration: number,
    ctx: { graceMs: number; trigger: 'stall-watchdog' | 'manual-abort' },
  ): Promise<void> {
    if (this.status === 'closed' || this.closePromise) return;
    // 代号变了 = 卡死那个 turn 已经停了(否则新 send 会被 SESSION_RUNNING 拒),现在跑的是
    // 新活儿。abort 生效了,不能拿"有 turn 在跑"当作"还没恢复"去关会话。
    if (this.turnGeneration !== stalledGeneration) {
      this.logger.info('abort took effect; a newer turn is running — not closing session', {
        trigger: ctx.trigger,
        stalledGeneration,
        currentGeneration: this.turnGeneration,
      });
      return;
    }
    if (!this.isTurnRunning() && !this.hasUnsettledTurn()) {
      // Watchdog may already have synthesized the missing terminal, which clears
      // turnControlState. If abort() never returns, status stays aborting and a
      // naive idle check would no-op — bypassing bounded recovery. Keep that
      // in-flight abort as evidence this diagnosed generation must close.
      if (this.status !== 'aborting' || this.abortRecoveryScheduledFor !== stalledGeneration) {
        return;
      }
    }
    this.logger.error(
      'turn still running after abort — closing session so the next send can rebuild it',
      { trigger: ctx.trigger, graceMs: ctx.graceMs },
    );
    try {
      await this.closeFromRuntime();
    } catch (e) {
      this.logger.warn('abort recovery close failed', { trigger: ctx.trigger, error: String(e) });
    }
  }

  private async runEventLoop(): Promise<void> {
    try {
      const iterator = this.handle.events()[Symbol.asyncIterator]();
      while (true) {
        const awaitingGeneration = this.turnGeneration;
        const awaitingCanAdoptNextGeneration =
          awaitingGeneration === 0 ||
          this.terminalEventObservedGeneration === awaitingGeneration;
        this.eventLoopAwaiting = true;
        let result: IteratorResult<AgentEvent>;
        try {
          result = await iterator.next();
        } finally {
          this.eventLoopAwaiting = false;
        }
        if (result.done) break;
        const event = result.value;
        this.releaseSendReservationIfObserved();
        let observedGeneration = awaitingGeneration;
        if (
          awaitingCanAdoptNextGeneration &&
          this.turnGeneration === awaitingGeneration + 1 &&
          !this.isPreDispatchReservation() &&
          !this.shouldHoldGenerationAdoption(event, awaitingGeneration)
        ) {
          // Only a next() that started while logically idle may follow the next send.
          // Capturing that fact before awaiting is essential. The terminal drain may
          // already be armed when a watchdog-generated error precedes this pending
          // next(); adopting the exact next generation lets the provider's tail done
          // clear that fence. The fence itself prevents any later generation entering.
          // Do not adopt while N+1 is still reserved / before provider dispatch:
          // a late N terminal would otherwise be cached as N+1 evidence.
          // After handle.send() accepts, a no-progress done is N+1's result-only
          // terminal when N's paired done was lost. Leftover paired done is still
          // held while the send is pending. In-flight start-failure errors still
          // belong to this send.
          observedGeneration = this.turnGeneration;
        }
        if (this.terminationStarted) continue;
        // origin 打标与终态清理都收在 fanOutEvent 里(看门狗合成的事件共用同一语义,
        // 见那里的注释)。关闭门一旦占住,旧 handle 的迟到事件不得再改写业务状态。
        this.fanOutEvent(event, observedGeneration, awaitingGeneration);
      }
    } catch (e) {
      this.logger.error('event loop crashed', { error: String(e) });
      if (this.closePromise || this.status === 'closed') return;
      // 先占住 closing gate,避免 terminal error listener 在死掉的 iterator 上重新 send。
      const closing = this.closeFromRuntime();
      if (this.terminalEventObservedGeneration !== this.turnGeneration) {
        this.fanOutEvent({
          type: 'error',
          data: {
            message: `Session event loop stopped unexpectedly: ${String(e)}`,
            isTerminal: true,
            reason: 'session_event_loop_crashed',
          },
          source: this.agentKind,
        });
      }
      try {
        await closing;
      } catch (closeError) {
        this.logger.warn('event-loop crash handle close failed', { error: String(closeError) });
      }
      return;
    }
    // handle.events() 自然结束 (iterator return) = 底层 handle 已死、不会再发任何事件。
    // 各 agent 走到这里的路径:
    //   - 本地 SDK 子进程退出 (CLI exit / stream closed)
    //   - claude-code 远端 daemon 突死 → U4b RemoteQuery messageQueue.end → U2 兜底
    //     set closed=true → finally `if (closed) eventQueue.end()`
    //   - handle.close() 主动关 (close 路径自己已 setStatus('closed'), 这里 idempotent no-op)
    //
    // 此前没有这条兜底, status 一直停在 'active' → Maker.activeSessions 永远不 delete
    // → 下次 maker:send 拿到老 Session → handle.send 把消息塞进死的 inputQueue →
    // 用户感知"发了没反应"。setStatus('closed') 触发 Maker 那边的 statusListener:
    // activeSessions.delete + emit 'session:closed' + lifecycleHooks.onClose → 下次
    // send 自然走 IPC lazy create-session 路径, 重建 handle / transport / 远端连接。
    //
    // 仅当当前 status 还是 'active' 时切 — 'closed' / 'error' 已经表达终态, 不覆盖。
    if (this.terminationStarted || this.status === 'closed' || this.status === 'error') return;
    const unfinishedTurn =
      this.hasUnsettledTurn();
    this.logger.debug('event loop ended (handle dead), auto-closing session', { unfinishedTurn });
    this.runtimeInitiatedClose = true;
    this.terminationStarted = true;
    this.closePromise = Promise.resolve();
    this.settleUnfinishedTurn('Session event loop stopped unexpectedly without a terminal event');
    this.clearTurnStallWatchdog();
    this.cancelSendReservation(this.sendReservation);
    this.sendReservation = null;
    this.unacceptedSendGeneration = null;
    this.currentTurnOrigin = null;
    this.currentTurnAttemptToken = null;
    this.turnControlState?.toolLoopMonitor?.dispose();
    this.turnControlState = null;
    this.setStatus('closed');
    this.eventListeners.clear();
    this.runtimeRecoveryListeners.clear();
    this.statusListeners.clear();
    this.interactionListener = null;
  }

  private isHandleTurnRunning(): boolean {
    return this.handle.isTurnRunning?.() ?? false;
  }

  private releaseSendReservationIfObserved(reservation = this.sendReservation): void {
    if (!reservation || this.sendReservation !== reservation) return;
    if (reservation.phase === 'accepting') return;
    if (this.isHandleTurnRunning()) {
      this.sendReservation = null;
    }
  }

  private cancelSendReservation(reservation: SendReservation | null): void {
    if (!reservation || reservation.cancelled) return;
    reservation.cancelled = true;
    reservation.abortController.abort();
  }

  private attachExternalCancellation(reservation: SendReservation, signal?: AbortSignal): () => void {
    if (!signal) return () => undefined;
    const onAbort = () => this.cancelSendReservation(reservation);
    if (signal.aborted) {
      onAbort();
      return () => undefined;
    }
    signal.addEventListener('abort', onAbort, { once: true });
    return () => signal.removeEventListener('abort', onAbort);
  }

  private async waitForGateOrAbort(gate: Promise<unknown>, signal?: AbortSignal): Promise<boolean> {
    if (!signal) {
      await gate;
      return false;
    }
    if (signal.aborted) return true;
    let onAbort!: () => void;
    const aborted = new Promise<void>((resolve) => {
      onAbort = resolve;
      signal.addEventListener('abort', onAbort, { once: true });
    });
    try {
      await Promise.race([gate, aborted]);
      return signal.aborted;
    } finally {
      signal.removeEventListener('abort', onAbort);
    }
  }

  private isPreDispatchReservation(): boolean {
    return (
      this.sendReservation !== null &&
      this.sendReservation.generation === this.turnGeneration &&
      this.sendReservation.phase === 'accepting'
    );
  }

  private shouldHoldGenerationAdoption(
    event: AgentEvent,
    awaitingGeneration: number,
  ): boolean {
    // Only a wait that already saw N's terminal can mis-adopt leftover done as N+1.
    if (awaitingGeneration <= 0) return false;
    if (this.lastObservedTerminalGeneration !== awaitingGeneration) return false;
    // Only an error-then-paired-done leftover can look like N+1 success.
    if (this.lastObservedTerminalKind !== 'error') return false;
    if (this.isNewTurnProgressEvent(event) || this.isForegroundRunningStatus(event)) {
      return false;
    }
    if (this.isSilentStopDoneEvent(event)) return false;
    if (event.type !== 'done') return false;
    // Hold leftover paired done only while N+1 is not yet accepted.
    // After accept, a no-progress done is N+1's result-only terminal when N's
    // paired done was lost; lastObserved staying `error` must not swallow it.
    // Pending handle.send / accepting reservation still fence the old tail,
    // including after reservation is released because the handle flipped running.
    return this.isUnacceptedCurrentSend();
  }

  private isUnacceptedCurrentSend(): boolean {
    const reservation = this.sendReservation;
    if (reservation && reservation.generation === this.turnGeneration) {
      return !reservation.accepted;
    }
    return this.unacceptedSendGeneration === this.turnGeneration;
  }

  private isForegroundRunningStatus(event: AgentEvent): boolean {
    if (event.turnScope === 'background') return false;
    if (event.type !== 'status') return false;
    return (event.data as { isRunning?: unknown } | null | undefined)?.isRunning === true;
  }

  private createSessionRunningError(): Error {
    const err = new Error(`SESSION_RUNNING: Session ${this.id} is already running a turn`);
    (err as { code?: string }).code = 'SESSION_RUNNING';
    return err;
  }
}

/**
 * 内部 helper:生成本地 session id(对外暴露给 host 以便落 SessionStorage)。
 */
export function generateSessionId(): string {
  return randomUUID();
}

/**
 * 把 UserMessage 摘要成日志友好的 dict —— 不打全文(可能含敏感/超长),只打长度和数量。
 */
function summarizeUserMessage(msg: UserMessage): Record<string, unknown> {
  if (typeof msg.content === 'string') {
    return {
      contentType: 'string',
      textLen: msg.content.length,
      textPreview: msg.content.slice(0, 80) + (msg.content.length > 80 ? '…' : ''),
    };
  }
  let textLen = 0;
  let imageCount = 0;
  let fileCount = 0;
  let mentionCount = 0;
  let firstTextPreview: string | undefined;
  for (const block of msg.content) {
    if (block.type === 'text') {
      textLen += block.text.length;
      if (firstTextPreview === undefined) {
        firstTextPreview = block.text.slice(0, 80) + (block.text.length > 80 ? '…' : '');
      }
    } else if (block.type === 'image') {
      imageCount += 1;
    } else if (block.type === 'file') {
      fileCount += 1;
    } else if (block.type === 'mention') {
      mentionCount += 1;
    }
  }
  return {
    contentType: 'array',
    blockCount: msg.content.length,
    textLen,
    imageCount,
    fileCount,
    mentionCount,
    textPreview: firstTextPreview,
  };
}