@x-otto/runtime 0.0.1-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,2973 @@
+import { CostSummary, Message, Model, ModelResolution, ProviderRegistry, StreamEvent, ThinkingLevel } from "@x-otto/ai";
+import { HookRegistry, HookSpec, SystemPromptTransformInput, ToolExecuteAfterInput } from "@x-otto/hooks";
+import { EventBus, Events, Logger, TypedEventEmitter } from "@x-otto/shared";
+import { AppendLog, PanelStateDraftEntry, PanelStateEditedFile, PanelStatePersistence, PanelStateSnapshot, PanelStateSubagentEntry, PanelStateTodoItem, PanelStateTurnSummary, PasteStatePersistence, PasteStateSnapshot } from "@x-otto/persistence";
+import { InMemorySession, LeaseInspection, Session, SessionEntry, SessionPersistence, SessionSnapshot } from "@x-otto/session";
+import { OttoProcessInfo } from "@x-otto/env";
+import { Agent, AgentEvent, AgentMessage, AgentSessionEvent, AgentSessionEventMap, AgentSessionEventType, AgentSessionSubscriber, AgentTool, ApprovalRisk, AskUserQuestion, ClockPort, DescribeImagesPort, GrillAnswer, GrillQuestion, GrillRequest, MemoryPort, MemoryPort as MemoryPort$1, StreamFunction, StreamRetryConfig, ToolHookExecutor, ToolResult, TraceEvent, TraceRecorder, applyMemoryTransform } from "@x-otto/agent";
+import * as _$_x_otto_session_contract0 from "@x-otto/session-contract";
+import { ResidencyBudgetConfig, TurnRecord, TurnRecord as TurnRecord$1 } from "@x-otto/session-contract";
+import { ChildProcess, SpawnOptions } from "node:child_process";
+import { Devtools } from "@x-otto/devtools";
+
+//#region src/context-source.d.ts
+interface ContextSource {
+  /** 本源的唯一标识。重复注册→覆盖前一次同 id 源。 */
+  readonly id: string;
+  /** 排序权重（越小越靠前，与 HookSpec.priority 同语义）。缺省 50。 */
+  readonly priority?: number;
+  /**
+   * 计算本轮注入的上下文片段。由 session-stable 底座做会话内冻结；
+   * 返回空/undefined 视为此轮无贡献。
+   */
+  contribute(ctx: ContextBuildInput): Promise<string | undefined> | string | undefined;
+}
+/**
+ * RFC-067 M113(A3/D3)：memory 的**上下文注入**语义端口（三端口之一）。此前是 ContextBuildInput.memory
+ * 上的内联匿名类型，消费方靠 `typeof loadMemory==='function'` 鸭子探测还原——现显式命名，供 typed 装配。
+ */
+interface ContextInjectionPort {
+  loadMemory(): Promise<void>;
+  getMemoryPrompt(): string;
+}
+interface ContextBuildInput {
+  readonly sessionId: string;
+  /** 工作区目录（用于读取文件/检测环境）。 */
+  readonly workspaceDir?: string;
+  /** 可选的 memory 上下文注入端口。 */
+  readonly memory?: ContextInjectionPort;
+}
+declare class ContextSourceRegistry {
+  private readonly sources;
+  private sealed;
+  register(source: ContextSource): void;
+  list(): ReadonlyArray<ContextSource>;
+  /**
+   * 产出 HookSpec[]（经 session-stable 包装），可注册进 hookRegistry。
+   * 调用后 registry 只读——不允许运行时增删源。
+   *
+   * `workspaceDir` 和 `memory` 在 hook 构建期闭包捕获（由 createAgentRuntime 传入）；
+   * `sessionId` 由 hook 运行时 SystemPromptTransformInput 提供（每个会话独立）。
+   *
+   * RFC-129 D4：重命名自 `buildHooks()`（纯改名，行为不变——调用即 seal）。命名变化表达
+   * 调用方必须保证的不变量：插件贡献的 context source（若有）必须在调用本方法**之前**
+   * 完成 `register()`（App 侧调用顺序见 RFC-129 D4 精确插入位置）；本方法自身不感知
+   * 插件、不做任何"等待插件"的逻辑——它仍是"此刻立即 seal 并构建"的同步语义。
+   */
+  sealAndBuildHooks(workspaceDir?: string, memory?: ContextBuildInput['memory']): HookSpec[];
+}
+//#endregion
+//#region src/context-sources/memory-delta.d.ts
+/**
+ * memory-delta（#3 volatile memory delta）
+ *
+ * session-stable 的 memory-index 把 memory 注入按 sessionId 冻结在 turn-1 快照（cache 锚点），
+ * 代价是会话中途 `memory_record`/编辑 AGENTS.md 的更新要到下一会话才生效。
+ *
+ * 本钩子补这个缺口：每轮把「相对 turn-1 基线发生变化的 memory 文件」以 **volatile 尾段**
+ * （output.systemTail，落在 prompt cache 断点之后）即时注入——既即时生效又不击穿会话稳定的
+ * memory 前缀。基线在首轮（memory 加载后）快照，session.deleted 驱逐。
+ *
+ * 注意：priority 必须 > memory-index（35），确保首轮捕获基线时 memory 已加载。
+ *
+ * **预算门（system prompt 体量治理 P0 的旁路缺口修复）**：`buildMemoryInjection`
+ * （`@x-otto/memory`）给会话首轮的稳定 memory 前缀加了总预算门，但本文件独立格式化
+ * volatile delta、不经过那道门——会话内多次 `memory_record` 大内容或反复编辑大文件，
+ * delta 段可无界累积进 `systemTail`。`runtime` 不依赖 `@x-otto/memory`（避免引入跨包
+ * 耦合/潜在循环依赖），故预算逻辑在本文件内自持一份最小实现，不与 `@x-otto/memory`
+ * 共享代码——两处判断口径一致（同款 CJK 加权估算 + 字符边界截断），但物理独立。
+ */
+interface MemoryDeltaPort {
+  /** 当前 memory 源映射（path → content）。MemoryManager.getMemories() 即此形态。 */
+  getMemories(): ReadonlyMap<string, string>;
+}
+declare function createMemoryDeltaHooks(memory: MemoryDeltaPort, priority?: 60): HookSpec[];
+//#endregion
+//#region src/session/archive-recall-port.d.ts
+/**
+ * archive-recall-port.ts — RFC-340 M2：会话归档召回的语义端口。
+ *
+ * 第四个 memory 语义端口（前三个：`MemoryPort` 压缩/裁剪、`ContextInjectionPort`
+ * 注入、`MemoryDeltaPort` 增量）。分立而非并入既有端口的理由与 RFC-067 M113 的
+ * 端口切分同源——**消费方需要的能力子集不同**：压缩路径不需要召回、召回路径不需要
+ * 压缩，合并会让两侧都被迫依赖用不到的方法。
+ *
+ * 唯一实现仍是 `@x-otto/memory` 的 `MemoryManager`（结构上已满足，无需改动它）。
+ */
+interface ArchiveRecallPort {
+  /**
+   * 读取一段被压缩折叠的历史全文。`archivePath` 形如 `archive:<sessionId>:<n>`。
+   *
+   * 实现侧优先从会话条目按 compaction 边界重建（RFC-159 保证 entries 永不删行，
+   * 故历史始终可重建），失败才回退归档存储。
+   */
+  readArchive(archivePath: string): Promise<string>;
+  /** 列举某会话已发生的压缩归档（供定位要读哪一段）。 */
+  listArchives(sessionId: string): Promise<Array<{
+    path: string;
+    timestamp: number;
+    messageCount: number;
+    summary: string;
+  }>>;
+}
+//#endregion
+//#region src/session/memory-transform.d.ts
+/**
+ * RFC-067 M113(A3/D3) + RFC-340 M2：完整 memory 子系统 = 四语义端口的交集——
+ * `MemoryPort`（compaction/prune）+ `ContextInjectionPort`（loadMemory/getMemoryPrompt）
+ * + `MemoryDeltaPort`（getMemories）+ `ArchiveRecallPort`（readArchive/listArchives，
+ * RFC-340 M2 补上"压缩折叠的历史可召回"这一环）。唯一实现 `@x-otto/memory` 的
+ * `MemoryManager` 结构上满足四者。
+ *
+ * 此前整个 seam（App.memory / context registry / hooks 注册）只把它当单端口 `MemoryProcessor`
+ * (=MemoryPort) 穿，injection/delta facet 被静态擦除→消费方靠 `typeof getMemories==='function'`
+ * 鸭子探测 + `as never` 还原。改用本 typed 交集后，seam 直接拿全能力，删全部 duck-typing/as never。
+ *
+ * 仅用于「需要注入/delta facet 的 seam」；纯压缩消费方（session-manager/agent-session）照用窄
+ * `MemoryPort`（MemorySubsystem 可赋给它）。
+ */
+interface MemorySubsystem extends MemoryPort$1, ContextInjectionPort, MemoryDeltaPort, ArchiveRecallPort {}
+//#endregion
+//#region src/session/types.d.ts
+/**
+ * 经过宿主完整解析后的 session 配置。
+ * 所有业务字段均已确定，无需再做 merge。
+ * Manager 层只接受此类型来创建 session，不持有业务默认值。
+ */
+interface ResolvedSessionConfig {
+  model: Model;
+  /**
+   * RFC-078 M134：标题生成用的便宜模型（宿主经 RFC-061 解析为同 provider 最便宜真实模型）。
+   * 缺省 → AgentSession 不启用 LLM 标题生成（仅 derived 占位）。
+   */
+  titleModel?: Model;
+  /**
+   * 模型决策溯源——选中模型由哪一层决定(explicit/slot/category/default/fallback)
+   * 及被 usability gate 拒绝的候选。供 trace/inspector 解释「为何用这个模型」。宿主解析时填充。
+   */
+  modelResolution?: ModelResolution;
+  agentName?: string;
+  systemPrompt: string;
+  /**
+   * 会话恒定的 volatile system 尾段（落在 prompt cache 断点之后）。宿主据配置填充——典型用例：
+   * append 模式子代理角色块（base system prompt 进缓存共享，角色差异走断点后尾段）。
+   */
+  systemTail?: string[];
+  tools: AgentTool[];
+  thinkingLevel: ThinkingLevel;
+  maxToolTurns: number;
+  maxToolTurnExtensions?: number;
+  /** RFC-104 D3：per-prompt output-token 预算（配置后轮次上限 ×4 退位安全阀）。 */
+  promptOutputTokenBudget?: number;
+  /** RFC-104 D3：per-prompt 墙钟预算（ms）。 */
+  promptWallClockBudgetMs?: number;
+  /**
+   * RFC-203/RFC-204 D4：早期停滞检测配置（第四层透传——ResolvedSessionConfig 是
+   * `SessionManager.createSession()` 真实接收的类型，与 AgentSessionOptions 是两份独立
+   * 结构，`buildAgentSession()` 逐字段映射；实现时才发现的第四道断链，同批修复）。
+   * 缺省启用；`false` 显式关闭。
+   */
+  stallDetection?: {
+    windowTurns?: number;
+    repeatThreshold?: number;
+  } | false;
+  /** RFC-204 D1/D2：会话累计成本软预算（美元）。缺省 = 不启用检测。 */
+  sessionCostBudgetUSD?: number;
+  /** RFC-094：todo 停机闭环硬闸配置（缺省从 env 解析：默认开、cap=3）。 */
+  todoContinuation?: {
+    enabled: boolean;
+    max: number;
+  };
+  promptRefresh?: PromptRefresh;
+  workspaceDir: string;
+  workspaceId?: string;
+  transient?: boolean;
+  depth?: number;
+  interactive?: boolean;
+  retryAccelerate?: {
+    skip: boolean;
+  };
+  /** RFC-230：流式重试策略投影（从宿主 `ResilienceConfig.stream` 而来）。缺省 = agent 包内部默认值。 */
+  streamRetry?: StreamRetryConfig;
+  /** RFC-230：网络断连重试策略投影（从宿主 `ResilienceConfig.networkDisconnect` 而来）。缺省 = agent 包内部默认值。 */
+  networkDisconnectRetry?: StreamRetryConfig;
+  /**
+   * 会话级「始终允许」工具名（弹窗运行时授权）。随快照持久化，--continue 回灌 PermissionRegistry
+   * 会话级集合——一次性授权跟随会话、不泄漏到项目其它会话。宿主（App）据此桥接 registry↔持久化。
+   */
+  permissionAlwaysAllow?: string[];
+  /**
+   * 会话级「账号可用模型 id」集合（实时拉取/刷新确认）。随快照持久化、--continue 回灌；
+   * list_models 工具据此标记/过滤可用模型，供大模型为 subagent 选型。
+   */
+  availableModels?: string[];
+  /**
+   * RFC-181 D3/M3：图像委托描述端口（宿主 VisionDelegateService 实现，coding 层的
+   * SessionConfigResolver 装配时注入）。缺省 = 主模型不支持视觉时，image block 降级为
+   * 占位文本（见 @x-otto/agent 的 vision-gate.ts 完整设计说明）。
+   */
+  describeImages?: DescribeImagesPort;
+}
+interface AgentSessionOptions {
+  id?: string;
+  /**
+   * RFC-324 D1/R5：turn-gated 压缩的超时兜底（毫秒）惰性读数。
+   *
+   * 必须是 getter 而非静态值——宿主 settings 在 App 构造**之后**才 load，
+   * 构造期快照会永远读到默认值（这正是 `compaction_timeout_ms` 此前零消费的成因）。
+   * 未注入时回退 `SESSION_COMPACTION_TIMEOUT_MS`（其本身已含 env 覆盖）。
+   */
+  getCompactionTimeoutMs?: () => number | undefined;
+  model: Model;
+  /** 模型决策溯源(为何选中此 model)——透传给观测层供 inspector 显示。 */
+  modelResolution?: ModelResolution;
+  agentName?: string;
+  systemPrompt?: string;
+  /** 会话恒定的 volatile system 尾段种子（append 子代理角色块等）；透传至 PromptParams.systemTail。 */
+  systemTail?: string[];
+  tools?: AgentTool[];
+  thinkingLevel?: ThinkingLevel;
+  maxToolTurns?: number;
+  maxToolTurnExtensions?: number;
+  /** RFC-104 D3：per-prompt output-token 预算（AgentSessionOptions 透传面）。 */
+  promptOutputTokenBudget?: number;
+  /** RFC-104 D3：per-prompt 墙钟预算（ms）。 */
+  promptWallClockBudgetMs?: number;
+  /** RFC-104 D2 缺省：顶层默认开、子 agent 默认关；OTTO_BUDGET_STEER_WRAPUP=1/0 覆盖。 */
+  budgetSteerWrapUp?: boolean;
+  /**
+   * RFC-203/RFC-204 D4：早期停滞检测配置透传（第三层，此前 AgentConfig/agent.ts 两层
+   * 断链已在 RFC-204 M2 修复）。缺省启用（走 ENGINE_DEFAULTS）；`false` 显式关闭。
+   */
+  stallDetection?: {
+    windowTurns?: number;
+    repeatThreshold?: number;
+  } | false;
+  /**
+   * RFC-204 D1/D2：会话累计成本软预算（美元）。超过阈值时一次性 emit
+   * `session.cost-budget-exceeded`（不阻断）。缺省 = 不启用预算检测。
+   */
+  sessionCostBudgetUSD?: number;
+  /**
+   * RFC-094：todo 停机闭环硬闸——prompt 结束后若 todoList 仍有未完成项，自动续跑（cap 轮内）。
+   * 缺省从 OTTO_TODO_CONTINUE / OTTO_TODO_CONTINUE_MAX 解析（默认开、cap=3）；depth>0 恒不启闸。
+   */
+  todoContinuation?: {
+    enabled: boolean;
+    max: number;
+  };
+  workspaceDir?: string;
+  /** workspace 逻辑标识（`workspaceRef.id`），按 workspace 过滤会话列表时使用。 */
+  workspaceId?: string;
+  transient?: boolean;
+  hookRegistry: HookRegistry;
+  stream: StreamFunction;
+  /**
+   * RFC-078 M134：标题生成用的便宜模型（app 层经 RFC-061 `category:'search'` + usability gate 解析）。
+   * 缺省 → 不启用 LLM 标题生成（仅保留 derived 启发式占位）。禁用对话模型/claude-OAuth（R3）。
+   */
+  titleModel?: Model;
+  logger: Logger;
+  devtools?: Devtools;
+  promptRefresh?: PromptRefresh;
+  memory?: MemoryPort;
+  recorder?: TraceRecorder;
+  /** RFC-145 D3：nondet batch 冲洗回调（透传给 Agent → work-loop）。缺省 = 不聚合。 */
+  nondetFlush?: () => void;
+  clock?: ClockPort;
+  depth?: number;
+  interactive?: boolean;
+  retryAccelerate?: {
+    skip: boolean;
+  };
+  /** RFC-230：流式重试策略投影，见 `ResolvedSessionConfig.streamRetry` 同名字段注释。 */
+  streamRetry?: StreamRetryConfig;
+  /** RFC-230：网络断连重试策略投影，见 `ResolvedSessionConfig.networkDisconnectRetry` 同名字段注释。 */
+  networkDisconnectRetry?: StreamRetryConfig;
+  /**
+   * RFC-181 D3/M3：图像委托描述端口（宿主 VisionDelegateService 实现，coding 层在会话
+   * 装配时注入）。缺省 = 主模型不支持视觉时，image block 降级为占位文本（见
+   * @x-otto/agent 的 vision-gate.ts 完整设计说明）。
+   */
+  describeImages?: DescribeImagesPort;
+}
+interface AgentSessionInfo {
+  id: string;
+  title?: string;
+  messageCount: number;
+  createdAt: Date;
+  updatedAt?: Date;
+  /** 分配模型 id（listSessions 填充自 AgentSession.model.id；service /sessions 读作 title 回退）。 */
+  model?: string;
+  status: string;
+  /** 创建此会话的 SDK 版本（`@x-otto/env` package version）。旧会话可能无此字段。 */
+  sdkVersion?: string;
+  /** workspace 逻辑标识（与 workspaceRef.id 对应）。按 workspace 过滤时使用。 */
+  workspaceId?: string;
+  /** 是否置顶（/resume 列表排序权重）。缺省 false。 */
+  pinned?: boolean;
+  /** 置顶分组名（RFC-158）。仅 pinned=true 时生效；缺省落入默认组（面板显示"置顶"）。 */
+  pinGroup?: string;
+  /**
+   * 是否被另一存活进程持有写租约（RFC-159 D3）——切进去将只读，改动不会保存。
+   * 缺省 false/undefined（无租约机制的后端，如远端/内存，恒不标注）。
+   */
+  writeLocked?: boolean;
+  /**
+   * 会话真实条目总数（不同于 messageCount——本地冷会话枚举路径 listColdSessionsOverride
+   * 出于性能考虑，messageCount 恒填 0 占位，不逐条查询）。用于区分"从未 prompt 过的
+   * 真空会话"与"有内容但未加载进内存的冷会话"，供 /resume 列表过滤真空会话展示。
+   * 缺省 undefined = 未知（内存态 listSessions 用 messages().length 即真实值，无需
+   * 额外填充；仅本地冷会话/远端会话路径才会显式填充本字段）。
+   */
+  entryCount?: number;
+}
+interface PromptOptions {
+  images?: Array<{
+    type: 'image';
+    data: string;
+    mediaType: string;
+  }>;
+  streamingBehavior?: 'steer' | 'followUp';
+}
+type PromptRefresh = () => Promise<string | undefined>;
+//#endregion
+//#region src/session/agent-session.d.ts
+declare function defaultMaxToolTurnExtensions(depth: number, transient?: boolean): number;
+/**
+ * RFC-094 D4：todo 硬闸续跑配置解析（env，语义延续 RFC-042 D5-r）——
+ * 默认开（opt-out）：显式 `OTTO_TODO_CONTINUE=0/off/false/no` 才关；
+ * cap 默认 3，允许 0（=不续），NaN/Infinity/负数/非法 → 回落 3。
+ */
+declare function resolveTodoContinuationConfig(env: {
+  OTTO_TODO_CONTINUE?: string;
+  OTTO_TODO_CONTINUE_MAX?: string;
+}): {
+  enabled: boolean;
+  max: number;
+};
+declare class AgentSession extends EventBus<AgentSessionEventMap> {
+  readonly session: Session<AgentMessage>;
+  readonly workspaceDir: string;
+  readonly workspaceId?: string;
+  private agent;
+  private disposed;
+  private promptGate;
+  /** RFC-078 M134：会话标题生成（post-RFC-092 review F7 拆出为独立 concern）。 */
+  private readonly titleManager;
+  /**
+   * 本次 prompt 是否已真正进入过 in-flight run（见过 status→streaming）。用于把 promptGate 期细分为
+   * 「prep 期(run 即将来)」vs「收尾期(run 已结束,钩子 chat.message.after/session.idle/session.error
+   * 仍在 await)」——两者 agent.status 相同(上一/本回合终态)、isExecuting 都为 false,无法用状态区分。
+   * abort 只在 prep 期才允许 arm pendingAbort;收尾期 arm 会毒化下一回合(completed/error/aborted
+   * settling 静默黑洞)。每次 prompt 入口重置,status→streaming 时置 true。
+   */
+  private runStartedThisPrompt;
+  /**
+   * RFC-194 D1：in-flight prompt 生命周期 Promise——clearContext() busy 守卫的 settle
+   * 依赖。prompt() 入口（isBusy 守卫后）赋值，finally 清除；空闲时 undefined。
+   */
+  private currentPrompt;
+  /** RFC-324 D1 M2：逃生阀压缩的 pending Promise——requestEscapeValveCompaction 写回，
+   * runPromptRound 开头 await。解决 fire-and-forget 压缩不保证收敛的问题（缺口 A）。
+   * 仅 gate 逃生阀压缩（字节维度）；主循环压缩已在 prompt 管线内同步 await。 */
+  compactionPending: Promise<{
+    compacted: boolean;
+    before: number;
+    after: number;
+  }> | undefined;
+  /** RFC-324 D1/R5：turn-gate 超时兜底的惰性读数（见 AgentSessionOptions 同名字段）。 */
+  private readonly getCompactionTimeoutMs?;
+  model: Model;
+  /** 模型决策溯源(哪层选中 + 拒了谁)——供 task-runner 透传观测层。 */
+  modelResolution?: ModelResolution;
+  tools: AgentTool[];
+  systemPrompt: string;
+  /** 会话恒定的 volatile system 尾段种子（append 子代理角色块等）；透传至每轮 PromptParams.systemTail。 */
+  systemTail?: string[];
+  agentName: string;
+  depth: number;
+  maxToolTurns: number;
+  maxToolTurnExtensions: number;
+  /** RFC-104 D3：per-prompt 预算（fork 拷贝面；depth>0 构造时已被剥除）。 */
+  promptOutputTokenBudget?: number;
+  promptWallClockBudgetMs?: number;
+  thinkingLevel: ThinkingLevel;
+  promptRefresh?: PromptRefresh;
+  private logger;
+  private hookRegistry;
+  private devtools?;
+  private memory?;
+  private readonly recorder?;
+  private readonly describeImages?;
+  /** RFC-145 D3：nondet batch 冲洗回调。 */
+  private readonly nondetFlush?;
+  private readonly clock?;
+  /** RFC-337 D2：steer 消息 id 单调计数器（会话内唯一，供 ESC 撤回按序移除）。 */
+  private steerSeq;
+  private readonly persistence;
+  /**
+   * RFC-336 D2：输入边界落盘回调（由 `PersistenceSync.track()` 注入，同
+   * `setReplacementStripEligibility` 的既有模式）。未注入 = 该会话不做输入边界落盘
+   * （transient 子会话、in-memory 后端、snapshot 远端后端均属此列）。
+   */
+  private inputBoundaryFlusher?;
+  /** RFC-336 D2：供 SessionPool 侧注入输入边界落盘策略；见 `inputBoundaryFlusher`。 */
+  setInputBoundaryFlusher(flush: () => void): void;
+  /** HITL 三 gate（approval/grill/plan）生命周期，RFC-199 D3 提取（agent-session-gates.ts）。 */
+  private readonly gates;
+  private readonly interactive;
+  private readonly agentUnsubs;
+  private readonly costTracker;
+  /** RFC-204 D1/D2：会话级成本软预算阈值（美元）；undefined = 不启用检测。 */
+  private readonly sessionCostBudgetUSD?;
+  /** RFC-204 D2：本会话是否已越过成本预算并提醒过（一次性，session 生命周期内不重复）。 */
+  private sessionCrossedCostBudget;
+  private lastTokenUsage;
+  /**
+   * RFC-019 M1：本回合缓存命中率（R1 = cacheRead / totalInput）。
+   * `null` = 供应商无缓存 API 或本回合无 usage 数据 —— 消费方（TUI summary 行）据此隐藏该字段，
+   * 不展示可能永远是 0 的误导性数字（见 docs/rfc/RFC-019-cache-hit-rate-metrics.md）。
+   */
+  private lastCacheHitRatio;
+  /** RFC-094：todo 停机闭环硬闸（post-RFC-092 review F7 拆出为独立 concern）。 */
+  private readonly todoGateRunner;
+  /**
+   * RFC-094 D4（评审细化）：闸门循环轮间隙（isExecuting=false）的 abort 捕获——
+   * 既有 abort() 守卫在间隙期是 no-op，此标记让闸门循环下一轮续跑前感知中断。
+   */
+  private abortRequested;
+  /**
+   * RFC-180 D2：turn 边界软停止请求标志（与 abortRequested 同构但语义独立）。置位后
+   * workLoop 在下一个安全的 turn 边界（onTurnPersist 已落盘）正常 return，不检查
+   * followUp、不触发 todo 闸门续跑。区别于 abort：不打断 in-flight 执行，会话保持
+   * 在正常可续跑状态（`Agent.status` 仍是 'completed'，非 'aborted'）。
+   *
+   * `isBusy` 判定本身不受本标志影响（正交状态）——暂停生效后 `promptGate` 复位为
+   * false、`isExecuting` 为 false，`isBusy` 天然变回 false。这是 D6 判忙链路必须
+   * 额外 OR `isPaused` 的原因，也是 D9 SessionPool 驱逐必须额外豁免 `isPaused` 的
+   * 原因（否则暂停态会话在 isBusy 视角下与"已空闲"完全无法区分）。
+   */
+  private pauseRequested;
+  get id(): string;
+  get title(): string | undefined;
+  get status(): string;
+  /** 置顶状态（/resume 列表排序权重，不影响是否可输入）。 */
+  get pinned(): boolean;
+  /** 置顶分组名（RFC-158）。仅 pinned=true 时有意义；未置顶或默认组时为 undefined。 */
+  get pinGroup(): string | undefined;
+  /**
+   * 暴露底层 Agent 供观测层接入（只读；attachAgentObserver 用）。
+   * task-runner 在跑 task_delegate/fork 子会话时据此把运行态接入 globalAgentObservability。
+   */
+  get coreAgent(): Agent;
+  get isExecuting(): boolean;
+  /**
+   * prompt 全生命周期忙判定。isExecuting 只覆盖 streaming/tool_executing，
+   * 漏掉 promptRefresh/buildContext/hooks 等流式开始前的窗口（此时 promptGate 已置位）；
+   * 池驱逐（idle/LRU）必须用本判定，否则会 dispose 掉一个 prompt 进行中的会话。
+   */
+  get isBusy(): boolean;
+  /**
+   * RFC-090 M0：renderer pull 式获取 session 元数据，替代 session.ready 推事件（避免竞态）。
+   * 返回纯数据对象，同进程直接调用；进程分离后（RFC-091）通过一次性请求/响应透传。
+   */
+  getSessionInfo(): {
+    sessionId: string;
+    modelId: string;
+    modelName: string;
+    systemPromptLength: number;
+    tools: string[];
+  };
+  constructor(session: Session<AgentMessage>, options: AgentSessionOptions);
+  /**
+   * 由 SessionPool / 宿主类在 session.created hook 执行完毕后调用。
+   * 此时 EventBridge 已完成订阅，session.start 事件可被正确接收。
+   */
+  notifyCreated(): void;
+  onStreamEvent: ({
+    event
+  }: {
+    event: StreamEvent;
+  }) => Promise<void>;
+  private onTurnStart;
+  private onTurnEnd;
+  private onToolCallStart;
+  private onToolCallEnd;
+  /**
+   * RFC-094 D2：todoList 会话持久化单源基线——write_todos 成功后把权威快照
+   * （result.details.todos，set/update 均为合并后完整列表）写进 session metadata。
+   * 修活非 CLI 前端（service/ACP）的 todo-reminder：其数据源 = metadata().config.todoList，
+   * 此前全仓只有 CLI 投影层回写，service 模式下 reminder 永不注入。
+   * 保序：publish 之前同步写 baseline；CLI 订阅回调随后覆写 turn-enriched 版（携回合号）。
+   * 既有条目的 turn 按 id 保留，runtime 不知道回合投影、不清 CLI 写入的 turn。
+   */
+  private syncTodoListFromToolResult;
+  /** 本次 prompt 是否触发了预算收尾 steering（供 runPrintMode 在优雅路径发提示）。 */
+  budgetSteeredThisPrompt: boolean;
+  /**
+   * 归档当前会话：将会话状态置为 archived，禁止后续输入。
+   * 仅 idle/completed/error/aborted 等终态可归档。
+   * 同步写 `metadata.archived` 持久化镜像（运行时权威仍是 Agent 状态机），
+   * 供跨重启/驱逐 restore 后回放归档态（见 `PersistenceSync.restore`）。
+   */
+  archive(): void;
+  /**
+   * 取消归档：将会话从 archived 恢复为 idle。
+   */
+  unarchive(): void;
+  /**
+   * 置顶会话（/resume 列表排序权重）。与归档状态正交，不影响是否可输入。
+   * `group`（RFC-158）：置顶分组名，空白字符串规整为默认组（`undefined`）。
+   */
+  pin(group?: string): void;
+  /** 取消置顶。无条件清空分组（不保留旧分组，见 RFC-158 §4）。 */
+  unpin(): void;
+  prompt(text: string, options?: PromptOptions): Promise<void>;
+  /** prompt() 的执行体（RFC-194 D1 拆出——prompt() 需在 isBusy 守卫后拿到本次执行的 Promise）。 */
+  private executePrompt;
+  /** 跑一轮完整 prompt 管线（buildContext → workLoop → persist），回填会话级参数。
+   *  hadToolActivity：本轮是否有真实工具调用产出（assistant tool_call 消息），供闸门
+   *  无进展判定区分"零动作卡死"（放行）与"有产出但没同步 todo 状态"（定向续跑一次）。
+   *  images（RFC-111 D4b）：仅首轮（外层 `prompt()` 调用）传入，todo 续跑等内部触发轮
+   *  不重复携带图片——避免同一张图片在续跑轮里被重复注入上下文。 */
+  private runPromptRound;
+  /**
+   * RFC-337 D2：注入一条 steer 消息并返回其稳定 `id`（供 cli 侧持有以便 ESC 撤回）。
+   *
+   * id 用会话内单调计数器生成（`steer-<n>`），不裸调 `randomUUID()`/`Date.now()`——steer 是
+   * UI 侧信道、不在确定性重放路径上，计数器已足够在队列生命周期内唯一，且天然确定性。
+   * id 写入 `Message.uuid`，`Agent.removeSteer(uuid)` 据此按序移除。
+   */
+  steer(text: string): {
+    id: string;
+  };
+  /**
+   * RFC-337 D2：按 id 移除一条尚未被模型消费的 steer 消息，返回是否命中。
+   * 未命中（已被 `drainSteeringQueue` 交付进 LLM 上下文）时返回 `false`——调用方据此退化
+   * 为「中止整回合」（见 RFC-337 §D3）。转调 `Agent.removeSteer`，只操作内存态队列。
+   */
+  removeSteer(id: string): boolean;
+  followUp(text: string): void;
+  abort(): void;
+  /**
+   * RFC-180 D4：请求在当前 turn 边界后暂停（不影响当前 in-flight turn，安全落盘后生效）。
+   * 空闲（`!isBusy`）时 no-op 并返回 false——暂停语义只对"正在跑"的 agent 有意义；
+   * 弹窗竞态场景（Esc 弹窗打开期间 agent 恰好跑完）静默忽略，与 abort() 的
+   * `inFlight`/`inPrep` 双重早退判定对齐。返回值供调用方感知（独立评审 F5）：
+   * `false` 时 CLI 层应给出"Agent 已完成当前回合，无需暂停"的 toast，而非让用户
+   * 以为按钮没反应。
+   */
+  pauseRun(): boolean;
+  /**
+   * RFC-186 D4：取消等待中的暂停请求——仅在 turn 边界尚未到达时有效（isBusy=true）。
+   * 暂停已生效（workLoop 已 break，isBusy=false）时返回 false——此时只能走 resumeRun()，
+   * 不能通过"取消"跳过已暂停态直接进入下一回合。返回值供调用方感知：false 时 CLI 层
+   * 应引导用户使用 /continue（而非 /pause），或 toast 提示"暂停已生效，请用 /continue 恢复"。
+   */
+  cancelPauseRun(): boolean;
+  /**
+   * RFC-180 D4：解除暂停。未处于暂停态时 no-op（不重复 publish 事件）。清空标志后，
+   * `isBusy` 判定的暂停附加项自动消失——TUI 侧 `busyWithPause` 判忙链路下一次读取
+   * 即感知空闲，`drainQueue` 可正常出队。
+   */
+  resumeRun(): void;
+  /** RFC-180 D4：是否已请求（或已生效）turn 边界暂停。与 `isBusy` 正交，见字段注释。 */
+  get isPaused(): boolean;
+  compact(summary: string, compactedCount: number): Promise<void>;
+  compactNow(signal?: AbortSignal): Promise<{
+    compacted: boolean;
+    before: number;
+    after: number;
+  }>;
+  private compactionDeps;
+  /**
+   * `/clear`——会话状态重置（非清屏）。在状态核打一道 clear 边界：
+   *   · buildContext()（送 LLM）此后真空——模型上下文立即释放；
+   *   · visibleMessages()（TUI/--continue 重绘）此后为空——界面不再重现旧内容；
+   *   · messages()（完整转录）保留全部——时间旅行/审计仍可回溯 clear 前。
+   * 同时驱逐 L2 工作记忆桶（previousSummaries），保 L1 持久知识、不动 L3 归档。
+   * 不换 sessionId、不销毁会话（契合 otto 显式 id 的 --continue）。
+   * publish 'session.cleared' → persistence-sync 立即落盘（保证新进程 --continue 反映清后态）。
+   */
+  clearContext(): Promise<void>;
+  /** 清除本轮临时面板状态（todo/编辑文件/子代理列表/回合摘要），保留对话历史。 */
+  clearTurnPanels(): void;
+  /** 重命名会话（custom 等级，永不被 ai/derived 覆盖）。 */
+  renameSession(title: string): void;
+  private promptUsage;
+  /** H5-20：本会话累计用量 + 成本汇总（供 /cost 命令 / TUI 状态栏消费）。 */
+  getCostSummary(): CostSummary;
+  /**
+   * RFC-019 M1：最近一回合的缓存命中率（R1）。`null` = 供应商无缓存 API 或本回合无 usage 数据
+   * ——消费方应据此隐藏该字段，而非展示误导性的 0。供 `/cache-stats`、summary 行消费。
+   */
+  getLastCacheHitRatio(): number | null;
+  subscribe(callback: AgentSessionSubscriber): () => void;
+  subscribe<K extends AgentSessionEventType>(type: K, callback: AgentSessionEventMap[K], once?: boolean): () => void;
+  requestApproval(toolName: string, args: Record<string, unknown>, description: string, risk?: ApprovalRisk): Promise<boolean>;
+  resolveApproval(approvalId: string, approved: boolean): void;
+  requestGrill(q: Omit<GrillQuestion, 'id'>): Promise<GrillAnswer>;
+  resolveAskUser(requestId: string, answer: GrillAnswer | null): void;
+  requestPlanApproval(planContent: string): Promise<{
+    action: string;
+    feedback?: string;
+  }>;
+  resolvePlanApproval(requestId: string, action: string, feedback?: string): void;
+  private rejectPendingGates;
+  private ensureNotDisposed;
+  /**
+   * RFC-078 M135-01：显式回血——对 title 空/derived 的（已加载）会话强制重生 ai 标题，
+   * 绕过「前 3 回合」成本闸（回血是一次性批处理意图）。custom 仍受守卫保护。
+   */
+  backfillTitle(): void;
+  dispose(): void;
+}
+//#endregion
+//#region src/session/checkpoint.d.ts
+type RestoreMode = 'conversation' | 'code' | 'both';
+interface FileEntrySnapshot {
+  path: string;
+  content: string | null;
+}
+interface FileSnapshot {
+  files: FileEntrySnapshot[];
+}
+interface CheckpointData {
+  sessionId: string;
+  label?: string;
+  createdAt: number;
+  traceSeq: number;
+  conversation: SessionSnapshot<AgentMessage>;
+  files?: FileSnapshot;
+}
+interface Checkpoint extends CheckpointData {
+  seq: number;
+}
+declare function captureFiles(workspaceDir: string, paths: string[]): Promise<FileSnapshot>;
+declare function restoreFiles(workspaceDir: string, snapshot: FileSnapshot): Promise<void>;
+//#endregion
+//#region src/session/sandbox.d.ts
+type ReplayLevel = 'L1' | 'L2';
+interface SandboxToolCall {
+  toolCallId: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+interface SandboxToolResult {
+  toolCallId: string;
+  result: ToolResult;
+}
+/**
+ * 可插拔沙箱执行器。x-web-container 将提供实现（VFS / worker / syscall / capability 隔离）。
+ * L2 重执行经此接口在隔离环境真实重跑工具调用，保证宿主工作区不被重放副作用污染。
+ */
+interface SandboxRunner {
+  /** 在隔离沙箱内执行一次工具调用，返回真实结果（含副作用，但作用域限于沙箱）。 */
+  execute(call: SandboxToolCall): Promise<SandboxToolResult>;
+  /** 释放沙箱资源（VFS / worker 等）。 */
+  dispose(): Promise<void>;
+}
+/**
+ * 请求 L2 但未注入 SandboxRunner 时抛出。明确"接口缝已留、实现待 x-web-container"，避免静默降级到 L1
+ * 而让调用方误以为副作用被真实重跑。
+ */
+declare class SandboxUnavailableError extends Error {
+  constructor();
+}
+//#endregion
+//#region src/session/traceback.d.ts
+interface TracebackView {
+  toSeq: number;
+  baselineCheckpointSeq: number | null;
+  fromTraceSeq: number;
+  events: TraceEvent[];
+  messages: Message[];
+}
+declare function messagesFromSnapshot(snapshot: SessionSnapshot): Message[];
+declare function reconstructMessages(baseline: Message[], events: Iterable<TraceEvent>): Message[];
+//#endregion
+//#region src/session/time-travel-controller.d.ts
+interface TimeTravelDeps {
+  logger: Logger;
+  traceStore?: AppendLog<TraceEvent>;
+  checkpointStore?: AppendLog<CheckpointData>;
+  getSession: (id: string) => AgentSession | undefined;
+  getConfig: (id: string) => ResolvedSessionConfig | undefined;
+  /** replaySession 走 Manager.createSession 正门（容量/登记/hook/active 维护）。 */
+  createSession: (config: ResolvedSessionConfig & {
+    id?: string;
+  }, ports?: SessionPorts) => Promise<AgentSession>;
+  /** fork 容量预检（同名冲突 + 容量阈值驱逐），在复制 trace/checkpoint 流之前执行。 */
+  ensureCapacity: (id: string) => void;
+  /**
+   * fork 池登记（两路 fork 共用）：构建 AgentSession + 登记 + 持久化追踪 + session.created hook
+   * + notifyCreated（一等可观测 + 落盘持久；不改 active——与历史 fork 行为一致）。
+   */
+  adoptForkedSession: (raw: InMemorySession<AgentMessage>, config: ResolvedSessionConfig) => Promise<AgentSession>;
+  /**
+   * RFC-160 D3：剥离态 compaction 的 replacement 真身回填（持久层能力，缺省 no-op 直通）。
+   * checkpoint 捕获前必须调用（剥离态固化进冷存储 = 永久丢 replacement）；restore 后
+   * 必须调用（旧 compaction 复位为末位边界，进 buildContext 的必须真身，RFC-142）。
+   */
+  hydrateEntries?: (sessionId: string, entries: readonly SessionEntry<AgentMessage>[]) => Promise<SessionEntry<AgentMessage>[]>;
+}
+declare class TimeTravelController {
+  private readonly deps;
+  constructor(deps: TimeTravelDeps);
+  private replayPorts;
+  /**
+   * 确定性重放（L1）——以录制会话的 trace 构造新会话，引擎的非确定性输入全部回灌：
+   *   clock/random/id（端口）+ LLM 流 + 工具结果（不真实调用 provider/工具）。
+   * 在该会话上重跑同一提示，产出与录制逐字节一致（含时间戳/assistant 内容/工具结果）。
+   * 复用源会话已解析的配置 + 读源会话 trace。
+   *
+   * **重现层级**：缺省 level='L1'（回灌录制工具结果，不真实执行副作用）。level='L2'
+   * 为全确定性沙箱重执行（沙箱内真实重跑工具），需注入 SandboxRunner（x-web-container 提供）；未注入
+   * 即抛 SandboxUnavailableError（不静默降级到 L1）。L2 的实际执行接线待 x-web-container，见 sandbox.ts。
+   *
+   * @param sourceSessionId 已录制（且仍在 configs 中）的源会话 id
+   * @param newId 重放会话 id（缺省自动生成）
+   * @param opts 重现层级与（L2 时）沙箱 runner
+   */
+  replaySession(sourceSessionId: string, newId?: string, opts?: {
+    level?: ReplayLevel;
+    sandbox?: SandboxRunner;
+  }): Promise<AgentSession>;
+  /**
+   * 建立 checkpoint —— 会话快照（必）+ 被追踪文件的内容快照（opts.files 提供时）。
+   * 是回溯/回滚的锚点。文件集由调用方给出（变更文件），属增量快照。
+   */
+  createCheckpoint(sessionId: string, opts?: {
+    label?: string;
+    files?: string[];
+  }): Promise<Checkpoint>;
+  listCheckpoints(sessionId: string): Promise<Checkpoint[]>;
+  /**
+   * 恢复到某 checkpoint，三模式隔离——
+   *   conversation：仅还原会话消息（restoreEntries 截断/替换）；code：仅写回文件快照；both：两者。
+   * 各模式只动该恢复的部分（gate：模式隔离）。回滚/分叉在此之上。
+   */
+  restoreCheckpoint(sessionId: string, seq: number, mode?: RestoreMode): Promise<void>;
+  /**
+   * RFC-160 D3/D4：出口 hydrate 统一入口。无剥离态 → 原样直通（快路径）；有剥离态且
+   * hydrateEntries 能力在场 → 回填真身；有剥离态但能力缺席 → 断言炸（D4 硬闸门：
+   * 接线遗漏必须立即暴露，绝不静默把剥离态放行到冷存储/模型上下文）。
+   */
+  private ensureHydrated;
+  private readCheckpoint;
+  /**
+   * **原地回滚（destructive rollback）**——在 restore 三模式（会话/代码）之上，再把 trace
+   * **截断**到该 checkpoint 的 traceSeq（丢弃其后的事件）。这是
+   * "trace 级截断/分叉"：回滚后 traceback/replay 不再看到被回滚分支，且 live 会话续跑的 trace
+   * 从 traceSeq 续号（recorder 经 store.append 自动续号，无需 rebind）。
+   *
+   * 与 restoreCheckpoint 的区别：restoreCheckpoint 只动状态、不动 trace（只读历史仍可见旧分支）；
+   * rollbackToCheckpoint 额外截断 trace（旧分支被丢弃）——"原地回退"语义。
+   */
+  rollbackToCheckpoint(sessionId: string, seq: number, mode?: RestoreMode): Promise<void>;
+  /**
+   * **从 checkpoint 分叉（fork）**——以源会话某 checkpoint 为起点开出一个新分支会话，源会话
+   * 保持不变（会话分支 / fork-from-checkpoint 语义）。新会话：
+   *   - 会话消息 = checkpoint 的会话快照（分支点之前的历史）；
+   *   - trace = 复制源会话 [0, traceSeq) 的事件到新 stream（使分叉会话的 traceback/replay 自足、独立）；
+   *   - checkpoint = 复制源会话 traceSeq ≤ 分支点 的 checkpoint 到新 stream（分叉会话保有基线锚点）；
+   *   - 工作区/代码 = 共享源会话 workspaceDir（与既有 forkSession 一致；隔离工作区属 L2 沙箱范畴）。
+   * 新会话经 session.created hook 成为一等会话（service 据此挂 trace/event 桥，可观测）。
+   */
+  forkFromCheckpoint(sessionId: string, seq: number, newId?: string): Promise<AgentSession>;
+  private countTraceEvents;
+  /**
+   * 重放 trace 到某 seq（含）——返回 [from, toSeq] 区间的 trace 事件（design TimeTravel.replay）。
+   * toSeq 缺省=全量。是回溯的底层读法（不改动会话，纯读 trace）。
+   */
+  replayTrace(sessionId: string, toSeq?: number, fromSeq?: number): Promise<TraceEvent[]>;
+  /**
+   * 回溯——重建某 trace seq 时刻的历史会话状态（只读，不改动 live 会话）。
+   * 选 traceSeq ≤ toSeq 的最近 checkpoint 作基线，把其后到 toSeq 的 trace 事件折叠回消息列表
+   * （user←prompt.before.text、assistant←stream done、tool_result←tool.call.end）。无 checkpoint 则从 seq 0 折叠。
+   */
+  traceback(sessionId: string, toSeq: number): Promise<TracebackView>;
+}
+//#endregion
+//#region src/session/panel-state-store.d.ts
+/**
+ * RFC-108 D3：面板 UI 状态读写门面。
+ *
+ * 内部调用 `PanelStatePersistence` 的 `load`/`save` 做 per-session 的四个面板
+ * 字段存取。每个 get 方法 load 后取对应字段返回；每个 set 方法先 load 现有快照
+ * （若无则初始化空对象）、更新对应字段、再 save。
+ *
+ * 当前为简单实现，不做额外缓存层——每次 get/set 都直接走持久化后端。
+ * 未来可根据 profiling 数据决定是否需要内存缓存层。
+ *
+ * RFC-338：paste 缓存经**独立的** `pasteStatePersistence` 存取（见 getPaste/setPaste），
+ * 不进 `PanelStateSnapshot`——原因见下方方法注释与 paste-state.ts 头注释。
+ */
+declare class PanelStateStore {
+  private readonly persistence;
+  /**
+   * RFC-338：paste 缓存的独立后端。可选——未注入时 paste 存取降级为
+   * 「读恒空 / 写 no-op」，与 in-memory/remote 后端不构造 PanelStateStore 的
+   * 既有降级策略同构（不 throw，不阻断输入）。
+   */
+  private readonly pasteStatePersistence?;
+  constructor(persistence: PanelStatePersistence,
+  /**
+   * RFC-338：paste 缓存的独立后端。可选——未注入时 paste 存取降级为
+   * 「读恒空 / 写 no-op」，与 in-memory/remote 后端不构造 PanelStateStore 的
+   * 既有降级策略同构（不 throw，不阻断输入）。
+   */
+
+  pasteStatePersistence?: PasteStatePersistence | undefined);
+  getTodoList(sessionId: string): Promise<PanelStateTodoItem[] | undefined>;
+  setTodoList(sessionId: string, todos: PanelStateTodoItem[]): Promise<void>;
+  getEditedFiles(sessionId: string): Promise<PanelStateEditedFile[] | undefined>;
+  setEditedFiles(sessionId: string, files: PanelStateEditedFile[]): Promise<void>;
+  getSubagents(sessionId: string): Promise<PanelStateSubagentEntry[] | undefined>;
+  setSubagents(sessionId: string, entries: PanelStateSubagentEntry[]): Promise<void>;
+  getDrafts(sessionId: string): Promise<PanelStateDraftEntry[] | undefined>;
+  setDrafts(sessionId: string, entries: PanelStateDraftEntry[]): Promise<void>;
+  getTurnSummaries(sessionId: string): Promise<PanelStateTurnSummary[] | undefined>;
+  setTurnSummaries(sessionId: string, entries: PanelStateTurnSummary[]): Promise<void>;
+  /**
+   * RFC-338：读取 paste 缓存。
+   *
+   * **不经 `loadOrInit`、不碰 `PanelStateSnapshot`**——这正是 D1 的要点：
+   * 面板态的每个 setter 都是「全量 load → 改一字段 → 全量 save」，而
+   * `setEditedFiles` 每次文件编辑就触发一次。若 paste（最大 8MB）与面板态同处
+   * 一份 JSON，每次编辑都要多序列化一遍这 8MB。两者物理分离后互不拖累。
+   *
+   * 返回值恒为规范化后的合法状态（fail-open）：后端未注入、文件缺失、内容损坏、
+   * 字段非法一律降级为空状态而非抛错——粘贴缓存丢失只该让 chip 失效（有 toast
+   * 提示的安全失败），绝不该让会话打不开。
+   */
+  getPaste(sessionId: string): Promise<PasteStateSnapshot>;
+  /**
+   * RFC-338：写入 paste 缓存（全量覆写，非 merge）。
+   *
+   * 调用方持有内存中的权威 LRU 顺序，整批写入即可。
+   * fail-soft：落盘失败吞错——粘贴/提交是用户主路径，不能因缓存写盘失败被阻断。
+   *
+   * @returns 是否真正落盘成功（供调用方按需记日志；不影响主流程）
+   */
+  setPaste(sessionId: string, snapshot: PasteStateSnapshot): Promise<boolean>;
+  /** RFC-338：删除某会话的 paste 缓存（会话删除时的连带清理）。 */
+  deletePaste(sessionId: string): Promise<boolean>;
+  /**
+   * 批量加载——直接返回 `PanelStateSnapshot`，供 persistence-sync 恢复/迁移路径使用。
+   * 比分别调用 4 次 get 方法更高效（一次 load 而非四次）。
+   */
+  loadAll(sessionId: string): Promise<PanelStateSnapshot | null>;
+  /**
+   * 批量保存——全量覆写（非 merge），供 persistence-sync 落盘路径使用。
+   * 调用方（doSave/saveSnapshot）总是读取 live session 的全部 4 个 getter 值后整批写入，
+   * 故无需与已有持久化数据做 per-field merge。
+   * RFC-118 小修（review 观察项）：sessionId 参数此前被忽略（`_` 前缀），API 不对称——
+   * 改为防御性校验，snapshot 串号（写 A 会话数据到 B 键）时 fail-fast 而非静默错写。
+   */
+  saveAll(sessionId: string, snapshot: PanelStateSnapshot): Promise<void>;
+  private loadOrInit;
+}
+//#endregion
+//#region src/session/residency-governor.d.ts
+/**
+ * residency-governor.ts — RFC-178 触发器 C：内存压力驱动的会话驻留收紧。
+ *
+ * 把 MemoryGovernor 的 warning/critical 分级信号翻译成**驻留维度**的动态收紧系数：
+ * - healthy  → 系数 1（cap 用全值：条数 2000 / 字节 256MB）
+ * - warning  → 系数 1/2（条数 1000 / 字节 128MB）
+ * - critical → 系数 1/4（条数 500 / 字节 64MB）
+ *
+ * 设计约束（RFC-178 D1/D4）：
+ * - **离散阶梯**而非连续值——内存采样受 GC 时机影响非确定，阶梯化把非确定性收敛到
+ *   "处于哪一档"；同一档位下裁剪结果完全确定（执行器不变式）。
+ * - 本类不做采样、不订阅 MemoryGovernor——纯状态容器 + 系数换算，由组装层
+ *   （app-lifecycle）在 MemoryGovernor 回调里调用 `setLevel`，接线放 app 层使
+ *   headless/serve 同享（不依赖 TUI）。
+ * - 所有收紧只影响内存视图（capStoredHistory* 的入参），DB append-forever 不动。
+ */
+type ResidencyPressureLevel = 'healthy' | 'warning' | 'critical';
+declare const LEVEL_DIVISOR: Record<ResidencyPressureLevel, number>;
+declare class ResidencyGovernor {
+  private level;
+  /** 由组装层在 MemoryGovernor 分级回调（onLevelChange 语义）里调用。幂等。 */
+  setLevel(level: ResidencyPressureLevel): void;
+  get currentLevel(): ResidencyPressureLevel;
+  /** 当前压力档位下的有效条数上限（base=SESSION_MAX_HISTORY_MESSAGES）。至少 1。 */
+  effectiveMaxMessages(base: number): number;
+  /** 当前压力档位下的有效字节预算（base=SESSION_MAX_CONTENT_BYTES）。至少 1。 */
+  effectiveMaxBytes(base: number): number;
+}
+//#endregion
+//#region src/session/session-manager.d.ts
+/**
+ * Manager 只持有基础设施配置（持久化、网络、日志）。
+ * 业务配置（model、systemPrompt、tools 等）由宿主（coding/第二宿主）解析后
+ * 经 ResolvedSessionConfig 传入 createSession，Manager 不做二次 merge。
+ */
+interface ResidencyDiagnostics {
+  activeSessionCount: number;
+  totalResidentBytes: number;
+  globalPressure: number;
+  isGlobalPressure: boolean;
+  maxBytesPerSession: number;
+  pressureLevel: 'healthy' | 'warning' | 'critical';
+}
+interface SessionPoolOptions {
+  hookRegistry: HookRegistry;
+  providerRegistry: ProviderRegistry;
+  maxSessions?: number;
+  idleTimeoutMs?: number;
+  threshold?: number;
+  logger: Logger;
+  devtools?: Devtools;
+  /**
+   * 自动上下文管理器。注入后由引擎 pipeline 的 context-transform 阶段驱动
+   * needsPrune/needsCompaction→process。app 级基础设施，跨所有 session 共享。
+   */
+  memory?: MemoryPort;
+  /**
+   * trace 落盘 store。app 级共享，per-session 以 sessionId 分流。注入后 manager 为每个
+   * session 构造绑定 sessionId 的 TraceRecorder 并透传引擎；未注入即不录制。
+   */
+  traceStore?: AppendLog<TraceEvent>;
+  /**
+   * checkpoint 落盘 store。app 级共享，per-session 以 sessionId 分流（append-only，seq=checkpoint 序号）。
+   * 注入后 createCheckpoint/restoreCheckpoint 可用；未注入则相关方法抛错。
+   */
+  checkpointStore?: AppendLog<CheckpointData>;
+  /**
+   * 确定性时钟端口。缺省=真实系统时钟（行为不变）；replay 由 trace 回灌。
+   */
+  clock?: ClockPort;
+  /**
+   * 仅用于 restore / restoreAll 场景。
+   * 正常 createSession 路径必须传入完整 ResolvedSessionConfig，不使用此字段。
+   * 使用 factory function 而非静态快照，确保每次 restore 拿到最新配置。
+   * 可接 agentName，restore 据此重解析子代理 prompt 身份（缺省=main）。
+   */
+  configProvider?: (agentName?: string, modelId?: string) => ResolvedSessionConfig;
+  /**
+   * RFC-108 D3：面板态（todoList/editedFiles/subagents/drafts）独立持久化门店。
+   * 未注入时优雅降级为不独立持久化——面板态仅存在于内存，重启后丢失但不报错崩溃。
+   */
+  panelStateStore?: PanelStateStore;
+  /**
+   * RFC-178 触发器 C：驻留收紧系数源（可选）。组装层把 MemoryGovernor 分级信号写入
+   * 其 setLevel；未注入时 cap 恒用全值（行为与此前一致）。透传给 PersistenceSync。
+   */
+  residencyGovernor?: ResidencyGovernor;
+  /** RFC-323 M4：驻留预算运行时配置 getter（settings 注入，透传给 PersistenceSync）。 */
+  getResidencyConfig?: () => _$_x_otto_session_contract0.ResidencyBudgetConfig | undefined;
+  /**
+   * RFC-146：本地高效冷会话枚举策略（可选注入）。仅本地 SQLite 后端在
+   * `session-pool-factory.ts` 构造期注入（内部持有 `SqliteSessionRepository`，
+   * 单次 SQL 查询即拿到完整 `AgentSessionInfo[]`，远快于"逐个 HTTP load()"）；
+   * 远端后端（`otto serve` / `remote-persistence-server`）不注入，缺省走
+   * `listAllPersistedSessions` 的 `persistence.listPaginated()+load()` 兜底路径。
+   * `SessionPool` 只判断"策略是否已注入"，不感知底层是什么仓储实现——
+   * 消灭对具体仓储类型的依赖（见 RFC-146 §6b「sessionRepoRef 迁移策略」）。
+   */
+  listColdSessionsOverride?: (workspaceKey: string) => Promise<AgentSessionInfo[]>;
+  /**
+   * 只读探测（可选注入）：某会话当前是否被**另一存活进程**持有写租约（RFC-159 D3
+   * SessionWriteLeaseManager.peekLockedByOther 的薄封装，无副作用）。仅本地 SQLite 后端
+   * 注入（`session-pool-factory.ts`）；未注入时 `listSessions`/`listAllPersistedSessions`
+   * 恒不标注只读（远端/内存后端无租约机制，行为与迁移前一致）。用于 `/resume` 列表
+   * 提前展示"切进去会是只读"，而非等到真正 save 被拒才事后感知。
+   */
+  isSessionWriteLocked?: (sessionId: string) => boolean;
+  /**
+   * RFC-171 D4：写租约只读诊断（可选注入）——`SessionWriteLeaseManager.inspect` 的薄封装。
+   * 仅本地 SQLite 后端注入。供 `/session unlock` 只读诊断模式消费（持有者 pid/hostname/
+   * 存活性/mtime 距今）；未注入时恒返回 `{ locked: false }`（远端/内存后端无租约机制）。
+   */
+  inspectSessionWriteLease?: (sessionId: string) => LeaseInspection;
+  /**
+   * RFC-171 D4：强制释放写租约（可选注入）——`SessionWriteLeaseManager.forceRelease` 的
+   * 薄封装。跳过 token 实核，仅供用户主动触发的 `/session unlock --force` 使用。
+   */
+  forceReleaseSessionWriteLease?: (sessionId: string) => void;
+}
+interface DiskSessionPoolOptions extends SessionPoolOptions {
+  sessionDir: string;
+}
+interface RemoteSessionPoolOptions extends SessionPoolOptions {
+  sessionUrl: string;
+  /** fetch 实现（必填）。在浏览器环境可传 globalThis.fetch，Node.js 需传兼容实现。 */
+  fetch: typeof globalThis.fetch;
+  /** 返回认证 token 的工厂函数（必填）。 */
+  getAuth: () => Promise<{
+    token: string;
+  }>;
+  timeoutMs?: number;
+  /** user identity id，非空时请求带 `X-Otto-User-Id` header。 */
+  userId?: string;
+  /** workspace 分区键（缺省 'default'）——修复（N3）：remote 后端此前恒 'default'，多本地
+   * workspace 共享同一 --session-url 时互相冲突，见 RemoteSessionPersistenceOptions.wsKey。
+   * 支持惰性 getter（App 构造期 workspaceRef 尚未解析完成）。 */
+  wsKey?: string | (() => string | undefined);
+}
+interface SessionPorts {
+  clock?: ClockPort;
+  recorder?: TraceRecorder;
+  /** RFC-145 D3：nondet batch 冲洗回调（RecordingPorts.flushNondetBatch）。缺省 = 不聚合。 */
+  nondetFlush?: () => void;
+  stream?: StreamFunction;
+  tools?: AgentTool[];
+  disableMemory?: boolean;
+}
+declare class SessionPool {
+  /** RFC-338 D7：面板态门店引用（供 panelState getter 暴露给 cli）。 */
+  private readonly panelStateStoreRef;
+  private readonly sessions;
+  private readonly configs;
+  private readonly persistence;
+  private readonly maxSessions;
+  private readonly idleTimeoutMs;
+  private readonly threshold;
+  private activeSessionId?;
+  readonly stream: StreamFunction;
+  private readonly hookRegistry;
+  private readonly logger;
+  private readonly devtools?;
+  private readonly memory?;
+  private readonly traceStore?;
+  private readonly checkpointStore?;
+  private readonly clock?;
+  private readonly residencyGovernor?;
+  private readonly getResidencyConfig?;
+  private readonly configProvider?;
+  /** RFC-146：本地高效冷会话枚举策略（可选，见 SessionPoolOptions.listColdSessionsOverride）。 */
+  private readonly listColdSessionsOverride?;
+  /** 只读探测（可选，见 SessionPoolOptions.isSessionWriteLocked）。 */
+  private readonly isSessionWriteLocked?;
+  /** RFC-171 D4：写租约诊断/强制释放（可选，见 SessionPoolOptions 对应字段）。 */
+  private readonly inspectSessionWriteLeaseFn?;
+  private readonly forceReleaseSessionWriteLeaseFn?;
+  /**
+   * 持久化是否为「自动行为」。disk/remote 后端 = true（prompt 终态增量落盘 +
+   * 宿主 start/stop 自动 restoreAll/saveAll）；in-memory 缺省 = false（行为与历史一致，
+   * 不向 in-memory persistence 写无意义快照）。遵循"写入是默认行为非手动 API"
+   * 的原则（会话持续落盘 + --continue 恢复）。
+   */
+  readonly autoPersist: boolean;
+  /** 时间旅行编排控制器（checkpoint/rollback/fork/replay/traceback 的实现归属）。 */
+  readonly timeTravel: TimeTravelController;
+  /** 快照持久化同步（增量落盘 + 重启恢复，第二变更轴）。 */
+  private readonly persistenceSync;
+  constructor(options: SessionPoolOptions, persistence: SessionPersistence<AgentMessage>, autoPersist?: boolean);
+  /**
+   * RFC-338 D7：面板态门店的只读暴露。
+   *
+   * cli 侧需要它来读写 paste 缓存（`getPaste`/`setPaste`）——粘贴缓存的加载/落盘
+   * 时机由 UI 事件驱动（启动、切会话、fork、提交后），不在 PersistenceSync 的
+   * 回合级落盘节奏上，故不能只走 persistence-sync 内部通路。
+   * 只读 getter：调用方不得替换门店实例。未注入后端时为 undefined（优雅降级）。
+   */
+  get panelState(): PanelStateStore | undefined;
+  get active(): AgentSession | undefined;
+  /**
+   * 会话级「始终允许」工具名读写（宿主桥接 PermissionRegistry↔持久化用）。写入会话当前
+   * ResolvedSessionConfig（= getConfig 同一引用），随 autoPersist 落盘、restore 经 applyPersistedConfig
+   * 回灌；未知会话为 no-op / 空数组。空集合写入即清除该字段。
+   */
+  getSessionPermissionAllow(id: string): string[];
+  setSessionPermissionAllow(id: string, tools: readonly string[]): void;
+  /** 会话级「账号可用模型」读写（同 permissionAlwaysAllow 持久化语义）。 */
+  getSessionAvailableModels(id: string): string[];
+  setSessionAvailableModels(id: string, models: readonly string[]): void;
+  /**
+   * 保持既有 private 外观（createSession/fork/restore 调用点不变）。
+   */
+  private trackPersistence;
+  /**
+   * RFC-336 D1/D1-c：新会话（createSession / fork adopt）落盘行预建。
+   *
+   * 与 `trackPersistence` 成对出现——track 订阅"此后的变更"，本方法保证"此刻的存在性"。
+   * 两条新建路径都需要：`adoptForkedSession` 此前同样只 track 不写 DB，fork 出的会话在
+   * 首个事件前被强杀同样蒸发（D1-c）。restore 路径**不需要**——那条路径的会话按定义
+   * 已在 DB 中。
+   */
+  private precreateSessionRow;
+  /**
+   * 两路 fork——`forkSession`（当前 leaf 全量）与 `forkFromCheckpoint`（历史 checkpoint 点）——
+   * 共用的会话采纳：登记 + 持久化追踪 + `session.created` hook + `notifyCreated`。使 fork 出的会话
+   * **既一等可观测**（service/桥接据 created 挂 trace/event）**又落盘持久**（重启经 restoreAll 恢复）。
+   * 不改 active（fork 不抢用户当前会话，与历史行为一致）；transient=false（fork 是一等持久分支，落盘）。
+   */
+  private adoptForkedSession;
+  private buildAgentSession;
+  private recordPorts;
+  /**
+   * 使用由宿主完整解析好的配置创建 session。
+   * Manager 层不再进行任何业务默认值填充。
+   */
+  createSession(config: ResolvedSessionConfig & {
+    id?: string;
+  }, ports?: SessionPorts): Promise<AgentSession>;
+  replaySession(sourceSessionId: string, newId?: string, opts?: {
+    level?: ReplayLevel;
+    sandbox?: SandboxRunner;
+  }): Promise<AgentSession>;
+  createCheckpoint(sessionId: string, opts?: {
+    label?: string;
+    files?: string[];
+  }): Promise<Checkpoint>;
+  listCheckpoints(sessionId: string): Promise<Checkpoint[]>;
+  restoreCheckpoint(sessionId: string, seq: number, mode?: RestoreMode): Promise<void>;
+  rollbackToCheckpoint(sessionId: string, seq: number, mode?: RestoreMode): Promise<void>;
+  forkFromCheckpoint(sessionId: string, seq: number, newId?: string): Promise<AgentSession>;
+  replayTrace(sessionId: string, toSeq?: number, fromSeq?: number): Promise<TraceEvent[]>;
+  traceback(sessionId: string, toSeq: number): Promise<TracebackView>;
+  getSession(id: string): AgentSession | undefined;
+  /** RFC-325 M5：仅暴露聚合驻留状态，供受控 doctor attach 读取；不泄露会话内容。 */
+  getResidencyDiagnostics(): ResidencyDiagnostics;
+  listSessions(filter?: {
+    workspaceId?: string;
+  }): AgentSessionInfo[];
+  /**
+   * RFC-146：枚举"持久化后端已知、但未必已加载进内存"的会话（本地磁盘冷会话 /
+   * 远端历史会话）——`listSessions()` 的超集，供 `/resume` 一类需要看到完整历史的
+   * 场景使用。统一返回 `AgentSessionInfo[]`，调用方不感知底层是本地 SQLite 直连
+   * 还是远端 HTTP 分页拉取。
+   *
+   * 两条实现路径（见 RFC-146 §6b「sessionRepoRef 迁移策略」，只统一契约不统一实现）：
+   * - `listColdSessionsOverride` 已注入（本地场景）：直接委托，内部走高效 SQL 查询。
+   * - 未注入（远端场景，含 otto serve 与 remote-persistence-server 两种）：走
+   *   `persistence.listPaginated()` 取 id 列表（天然限流，不新发明 cap 机制）+
+   *   逐个 `load()` 补 title/createdAt（远端会话缺 messages()，取 metadata.title
+   *   回落 id 前 8 位，与本地冷会话降级展示模式一致）。
+   *
+   * 失败语义（两种失败互不掩盖，见 RFC-146 §6b）：
+   * - `listPaginated()` 整体失败 → 返回空数组 + warn（批量不可用，非单条问题）。
+   * - 单条 `load()` 失败 → 跳过该条、不中止其余（数据损坏/网络抖动等局部问题）。
+   *
+   * @param filter.workspaceKey 已转换好的分区键（`ws_<id>` 或 `'default'`）——身份→
+   *   分区键的转换由调用方（App）负责，本方法不感知 `workspaceId`、不依赖 `@x-otto/workspace`。
+   */
+  listAllPersistedSessions(filter?: {
+    workspaceKey?: string;
+  }): Promise<AgentSessionInfo[]>;
+  /**
+   * RFC-078 M135-01：回血标题——对所有已加载会话中 title 为空/derived 的，fire-and-forget
+   * 触发 ai 重生（跳过 custom）。便宜模型 + 各会话自带 abort/超时，非阻塞。返回触发计数。
+   * 冷会话（未 restore 进内存）经 listSessions/resume 读取时已懒解析为 derived（resolveSessionTitle）。
+   */
+  backfillTitles(): {
+    triggered: number;
+    skipped: number;
+  };
+  archiveSession(id: string): Promise<boolean>;
+  removeSession(id: string): Promise<boolean>;
+  /**
+   * 删除会话的 trace/checkpoint 落盘数据。此前 removeSession 只删 session 快照，
+   * trace JSONL（delta 级、单会话可达数百 MB）与 checkpoint 永久残留——
+   * ~/.otto/sessions/trace 累积数十 GB 的直接来源。失败仅告警（孤儿文件可后续清理，
+   * 不阻塞会话删除本身）。
+   */
+  private clearSessionStores;
+  /**
+   * fork 直接复用 source session 自身的已解析配置，
+   * 消息通过复制 snapshot entries 完整迁移。
+   */
+  /**
+   * RFC-160 D3/D4：出口 hydrate（fork 用）。无剥离态直通；有剥离态且持久层具备能力则回填；
+   * 能力缺席 → 断言炸（接线遗漏立即暴露，绝不把剥离态固化为新会话正文）。
+   */
+  private ensureEntriesHydrated;
+  forkSession(sourceId: string, newId?: string): Promise<AgentSession | undefined>;
+  save(id: string): Promise<void>;
+  saveAll(): Promise<void>;
+  /**
+   * RFC-171 D4：写租约只读诊断（无副作用）——持有者 pid/hostname/存活性/mtime 距今，
+   * 供 `/session unlock` 只读模式展示。未注入策略（远端/内存后端）恒返回 `{ locked: false }`。
+   */
+  inspectSessionWriteLease(sessionId: string): LeaseInspection;
+  /**
+   * RFC-171 D4：强制释放写租约——跳过 token 实核，仅供用户主动触发的 `/session unlock
+   * --force` 使用。未注入策略（远端/内存后端）为 no-op（无租约机制，无需处理）。
+   */
+  forceReleaseSessionWriteLease(sessionId: string): void;
+  restore(id: string): Promise<AgentSession | null>;
+  /** RFC-305 D3：消费本次恢复检出的崩溃缺口（CLI resume 路径在订阅建立后读取）。 */
+  consumeCrashGap(id: string): {
+    lostTurns: number;
+  } | undefined;
+  restoreAll(): Promise<number>;
+  /**
+   * 修复（不一致性，2026-07-12 独立 review 后续核实）：此前 idle 驱逐只 dispose+delete，
+   * 完全不落盘——若最近一次 auto-persist（prompt.end 触发）因瞬时故障失败（DB 抖动，仅
+   * `logger.warn` 无重试，见 `track()` persist 闭包的 catch 分支），内存里的未落盘改动会
+   * 被静默丢弃。`evictLeastRecent`（LRU 驱逐）早已对称处理这一点（驱逐前同步捕获快照
+   * 入 `saveSnapshot` 链），本方法此前遗漏同样的防御，是纯粹的不一致而非有意设计。
+   */
+  private collectIdle;
+  /** 会话条目数（含全部分支）。空判定不能用 messages()——它只走当前分支，多分支会话会被误判为空。 */
+  private entryCount;
+  /**
+   * 满池兜底：collectIdle 之后仍满池时，按 lastActiveAt LRU 驱逐会话。
+   * 不可驱逐：active、busy（prompt 全生命周期，含流式前窗口）、transient（M18-PR-02：
+   * 不许落盘，且生命周期归 orchestrator 管，中途 dispose 会打断编排）。
+   * autoPersist 后端驱逐前同步捕获快照入 save 链，内存驱逐零数据损失（restore(id) 可复活）；
+   * in-memory 后端驱逐非空会话=丢数据，只允许驱逐空会话（从未 prompt 过，无可丢内容）。
+   */
+  private evictLeastRecent;
+  private prepareCapacity;
+  private canAccommodate;
+  dispose(): void;
+}
+declare function createDiskSessionPool(options: DiskSessionPoolOptions): SessionPool;
+declare function createRemoteSessionPool(options: RemoteSessionPoolOptions): SessionPool;
+declare function createInMemorySessionPool(options: SessionPoolOptions): SessionPool;
+//#endregion
+//#region src/create-agent-runtime.d.ts
+type SessionStorageConfig = {
+  kind: 'in-memory';
+} | {
+  kind: 'disk';
+  sessionDir: string;
+} | {
+  kind: 'remote';
+  sessionUrl: string;
+  fetch: typeof globalThis.fetch;
+  getAuth: () => Promise<{
+    token: string;
+  }>;
+  timeoutMs?: number; /** user identity id，非空时请求带 `X-Otto-User-Id` header 实现 session 分区。 */
+  userId?: string;
+  /** workspace 分区键（缺省 'default'）——修复（N3）：remote 后端此前恒 'default'，
+   * 与本地 SQLite 后端按 workspace_key 分区行为不一致。见 RemoteSessionPoolOptions.wsKey。
+   * 支持惰性 getter（App 构造期 workspaceRef 尚未解析完成）。 */
+  wsKey?: string | (() => string | undefined);
+} | {
+  /**
+   * 调用方注入的持久化后端（关系化 SQLite 等联合内建无法表达的后端）。让 createAgentRuntime
+   * 成为唯一装配权威——宿主不再手搓平行 AgentRuntime 字面量（消除装配漂移）。
+   * trace/checkpoint store 由调用方经 options 注入（ownsXxx=false，dispose 不替其 close）。
+   */
+  kind: 'custom';
+  persistence: SessionPersistence<AgentMessage>; /** 缺省 true（与关系化后端既有行为一致）。 */
+  autoPersist?: boolean; /** 后端专属资源释放（如 SqliteSessionRepository.close()）；dispose 时在 sessions.dispose 后调用。 */
+  onDispose?: () => void | Promise<void>;
+  /**
+   * RFC-146：本地高效冷会话枚举策略透传（见 SessionPoolOptions.listColdSessionsOverride）。
+   * 关系化 SQLite 分支（session-pool-factory.ts）经此注入，走 SqliteSessionRepository 单次
+   * SQL 查询而非通用 listPaginated+load 慢路径。
+   */
+  listColdSessionsOverride?: (workspaceKey: string) => Promise<AgentSessionInfo[]>;
+  /**
+   * 只读探测策略透传（见 SessionPoolOptions.isSessionWriteLocked）。关系化 SQLite 分支
+   * 经此注入 SessionWriteLeaseManager.peekLockedByOther 的薄封装。
+   */
+  isSessionWriteLocked?: (sessionId: string) => boolean;
+  /**
+   * RFC-171 D4：写租约诊断/强制释放策略透传（见 SessionPoolOptions 对应字段）。
+   * 关系化 SQLite 分支经此注入 SessionWriteLeaseManager.inspect/forceRelease 的薄封装。
+   */
+  inspectSessionWriteLease?: (sessionId: string) => LeaseInspection;
+  forceReleaseSessionWriteLease?: (sessionId: string) => void;
+  /**
+   * RFC-108 D3 面板态（todoList/editedFiles/subagents/drafts）独立持久化的落盘目录。
+   * 2026-07-21 修复：`kind:'custom'`（coding 默认的关系化 SQLite 后端）此前不构造
+   * PanelStateStore——面板态仅存内存，进程重启即丢（drafts e2e 恒红暴露的真实生产
+   * 缺口，非测试环境问题）。调用方传入目录（惯例 `<sessionDir>/panel-state`）即启用，
+   * 缺省不构造（保持 in-memory/remote 的既有降级行为）。
+   */
+  panelStateDir?: string;
+  /**
+   * RFC-345 §D8：显式注入的面板态/粘贴态持久化后端（影子模式用 InMemory 实现）。
+   * 优先于 panelStateDir——两者同时缺省时不构造 PanelStateStore（既有降级）。
+   * 由 §D1 白名单点 session-pool-factory 在影子态注入内存实现，磁盘零写。
+   */
+  panelStatePersistence?: PanelStatePersistence;
+  pasteStatePersistence?: PasteStatePersistence;
+};
+interface RuntimeOptions {
+  /** LLM provider 注册表。缺省=createDefaultProviderRegistry()。 */
+  providerRegistry?: ProviderRegistry;
+  /** hook 注册表（tool.execute / system.prompt.transform 等的容器）。缺省=default preset。 */
+  hookRegistry?: HookRegistry;
+  logger?: Logger;
+  /** 工作区目录（environment ContextSource + 会话缺省根）。缺省=process.cwd()。 */
+  workspaceDir?: string;
+  /** 确定性时钟端口。缺省=真实系统时钟。 */
+  clock?: ClockPort;
+  /** trace 落盘 store。缺省=内存 append-log（零磁盘、实时观测）。 */
+  traceStore?: AppendLog<TraceEvent>;
+  /** checkpoint 落盘 store。缺省=内存 append-log。 */
+  checkpointStore?: AppendLog<CheckpointData>;
+  /** 自动上下文管理端口。注入后引擎按 token 阈值在循环内压缩；未注入即不自动压缩。 */
+  memory?: MemorySubsystem;
+  /** 会话池容量上限。缺省由 SessionPool 取 env SESSION_MAX。 */
+  maxSessions?: number;
+  idleTimeoutMs?: number;
+  /** 会话持久化后端。缺省=纯内存（不落盘）。 */
+  storage?: SessionStorageConfig;
+  /** devtools 实例（可选调试端口）。缺省=无调试。 */
+  devtools?: Devtools;
+  /** 仅用于 restore / restoreAll 路径的配置工厂。同一 runtime 所有会话共享同一缺省配置模板。 */
+  configProvider?: (agentName?: string, modelId?: string) => ResolvedSessionConfig;
+  /**
+   * RFC-178 触发器 C：驻留收紧系数源（可选）。组装层（app-lifecycle）把 MemoryGovernor
+   * 分级信号写入其 setLevel，PersistenceSync 的 cap 执行读取其收紧系数。未注入=恒全值。
+   */
+  residencyGovernor?: ResidencyGovernor;
+  /** RFC-323 M4：驻留预算运行时配置 getter（settings 注入透传）。 */
+  getResidencyConfig?: () => _$_x_otto_session_contract0.ResidencyBudgetConfig | undefined;
+}
+interface AgentRuntime {
+  /** 统一派生入口：子 runtime / 宿主 / swarm / task-runner 皆经此（§4-11）。 */
+  createSession(config: ResolvedSessionConfig & {
+    id?: string;
+  }, ports?: SessionPorts): Promise<AgentSession>;
+  /** 会话池（fork/replay/checkpoint/持久化同步等编排门面）。 */
+  readonly sessions: SessionPool;
+  readonly hookRegistry: HookRegistry;
+  /** 引擎 stream（从 providerRegistry 派生，§4-11：子 runtime 用之而非各自 createStreamFunction）。 */
+  readonly stream: StreamFunction;
+  /** ContextSource 有序注册表（D33）：通用源已内置注册，coding 策略源由宿主追加。 */
+  readonly contextSources: ContextSourceRegistry;
+  readonly traceStore: AppendLog<TraceEvent>;
+  readonly checkpointStore: AppendLog<CheckpointData>;
+  readonly clock?: ClockPort;
+  dispose(): Promise<void>;
+}
+/**
+ * 通用 ContextSource 注册表（D33 单一来源）：environment + memory-index（有注入面时）。
+ * createAgentRuntime 内置调用之；宿主的离线装配路径（不经 createAgentRuntime）亦复用，
+ * 确保「App 经 rt.contextSources 构建注入 hooks」对所有后端一致——消灭 App 端的二次造表。
+ */
+declare function createDefaultContextSourceRegistry(workspaceDir: string, memory?: MemorySubsystem): ContextSourceRegistry;
+declare function createAgentRuntime(options?: RuntimeOptions): AgentRuntime;
+//#endregion
+//#region src/engine-stores.d.ts
+/**
+ * trace/checkpoint AppendLog 后端选择的**单一权威**。
+ *
+ * 坑：remote 后端必须用 Http 变体，否则远端会话的 trace 落内存、重启即丢。
+ */
+interface EngineStoreLocation {
+  /** 会话快照落盘目录（disk 后端）：trace/checkpoint 落 <dir>/trace、<dir>/checkpoint。最高优先。 */
+  sessionDir?: string;
+  /** 远端 AppendLog 选项（remote 后端，HttpAppendLog）；sessionDir 在场时被忽略。
+   * fetch 可选——HttpAppendLog 内部对缺省回落 globalThis.fetch（兼容 App 的可选 remote.fetch）。 */
+  remoteLog?: {
+    baseUrl: string;
+    getAuth: () => Promise<{
+      token: string;
+    }>;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+  };
+  /**
+   * RFC-345 §D8：影子模式旗标。为真时**强制** trace/checkpoint 走 MemoryAppendLog，
+   * 即便 sessionDir/remoteLog 在场。
+   *
+   * 为何需要独立旗标而非"不传 sessionDir"：sessionDir 对其他子系统（如 settings、
+   * lesson 等非会话存储的目录惯例）仍可能有用途，不能靠"不给目录"顺带关掉 trace 落盘。
+   * ephemeral 让 devtools.inspect() 的实时观测（LiveTap 内存旁路）在影子态仍可用，
+   * 而磁盘零写入。由 §D1 白名单装配点（storage-wiring / create-agent-runtime）注入。
+   */
+  ephemeral?: boolean;
+}
+interface EngineStoreOverrides {
+  /** 显式注入的 trace store（最高优先，覆盖一切后端选择）。 */
+  traceStore?: AppendLog<TraceEvent>;
+  /** 显式注入的 checkpoint store（最高优先）。 */
+  checkpointStore?: AppendLog<CheckpointData>;
+}
+/**
+ * 选择 trace/checkpoint 后端。优先级：显式 override > ephemeral(Memory) >
+ * sessionDir(File) > remoteLog(Http) > Memory。
+ */
+declare function buildEngineStores(loc: EngineStoreLocation, overrides?: EngineStoreOverrides): {
+  traceStore: AppendLog<TraceEvent>;
+  checkpointStore: AppendLog<CheckpointData>;
+};
+//#endregion
+//#region src/defaults.d.ts
+declare const RUNTIME_DEFAULTS: {
+  /** 工具轮次预算缺省（RFC-057 M89-01 单源）：引用 agent 核心 ENGINE_DEFAULTS.maxToolTurns，
+   * 不再硬编码——改其一全生效，消除散落 `?? 50` 漂移。 */
+  readonly maxToolTurns: 120;
+};
+//#endregion
+//#region src/memory-governor.d.ts
+/**
+ * memory-governor.ts — RFC-115 M1：长驻进程内存自我感知。
+ *
+ * 背景：otto 支持 `--continue` 长驻会话，进程可连续运行数十小时。此前对自身堆内存
+ * 增长零监控——唯一"处理机制"是 V8 自己在 old-space 撞上限时 `FatalProcessOutOfMemory`
+ * 直接 SIGABRT，靠 RFC-085 重启陪跑被动兜底（且该窗口内 `app.stop()`/`saveAll` 完全没有
+ * 机会执行，存在状态丢失风险）。见 RFC-115 §1。
+ *
+ * M1 范围：只做周期采样 + 分级 + 回调触发，不实现任何降级/重启动作本身（回调是否执行
+ * 压缩/弹窗由调用方注入，M2/M3 接线）——这是刻意的里程碑切分（RFC-115-todo.md M1）。
+ *
+ * 不引入通用 `HealthMetricSampler` 接口（RFC-115 D7，经独立评审 P2-1 撤回）：本类是
+ * 内存专用的具体实现，YAGNI——渲染帧率等其他维度若未来需要，从两个具体实现里再提炼
+ * 共性，不预先猜测未来的抽象形状。
+ */
+type MemoryPressureLevel = 'healthy' | 'warning' | 'critical';
+interface MemoryGovernorOptions {
+  /** 告警阈值（占 V8 heap_size_limit 的百分比）。默认 70，经 OTTO_MEMORY_WARN_PCT 覆盖。 */
+  warnThresholdPct?: number;
+  /** 危险阈值（占 V8 heap_size_limit 的百分比）。默认 85，经 OTTO_MEMORY_HARD_PCT 覆盖。 */
+  hardThresholdPct?: number;
+  /** 采样间隔（ms）。默认 30_000，经 OTTO_MEMORY_SAMPLE_INTERVAL_MS 覆盖。 */
+  sampleIntervalMs?: number;
+  /** warning 分级下的采样间隔（ms）。默认 10_000，经 OTTO_MEMORY_WARNING_INTERVAL_MS 覆盖。RFC-133 D7。 */
+  warningIntervalMs?: number;
+  /** critical 分级下的采样间隔（ms）。默认 5_000，经 OTTO_MEMORY_CRITICAL_INTERVAL_MS 覆盖。RFC-133 D7。 */
+  criticalIntervalMs?: number;
+  /**
+   * 软降级触发冷却期（ms，RFC-115 D4）。默认 300_000（5 分钟）。防止 usedPct 在阈值附近
+   * 抖动（如 69%↔71%）导致 onWarning 被高频重复触发——压缩本身有 CPU/延迟代价，且刚压缩完
+   * 内存短期回升是正常现象。冷却期内即使分级变化仍触发（healthy↔warning 往返），
+   * 只是不调用 onWarning；level 状态本身不受冷却期影响，仍如实反映当前采样结果。
+   * 只作用于 warning 级别；critical 级别（Layer 2 硬阈值）不受冷却期约束，应立即响应。
+   */
+  warnCooldownMs?: number;
+  /** 分级变化时触发（level 从非 warning/critical 变为该级别时各触发一次，非每次采样都触发）。 */
+  onWarning?: () => void;
+  /**
+   * critical 分级触发，且当前不处于重启后宽限期（见 `postRestartGraceMs`）时调用。
+   * 传入触发时刻的采样结果（`tick()` 内部已算好，避免调用方重复 `sample()` 造成值漂移
+   * 与多余开销——经独立评审 P1-2 修正）。
+   */
+  onCritical?: (sample: MemorySample) => void;
+  /**
+   * critical 分级触发，但当前处于重启后宽限期内时调用（RFC-115 D5 残留风险缓解）——
+   * 调用方应降级为非阻塞提示（如 TUI 常驻通知区），而非再次弹出确认重启 Dialog，
+   * 避免"重启→同样内存状态→立刻又弹窗"的连续打断。`onCritical`/`onCriticalDuringGrace`
+   * 互斥，同一次触发只调用其一。同样传入触发时刻的采样结果。
+   */
+  onCriticalDuringGrace?: (sample: MemorySample) => void;
+  /**
+   * RFC-116 M3：任意分级变化时触发（含恢复到 healthy 的降级方向）——`onWarning`/
+   * `onCritical`/`onCriticalDuringGrace` 均只在"变为 warning/critical"时触发，缺少
+   * "从 warning/critical 恢复到 healthy"这个方向的信号。footer 常驻指示器（异常时
+   * 才显示、健康时零宽度）需要感知这个恢复事件才能自行清除，故新增本回调覆盖全部
+   * 变化方向。不受冷却期/宽限期约束（纯粹的状态变化通知，不驱动任何降级动作）。
+   */
+  onLevelChange?: (level: MemoryPressureLevel) => void;
+  /**
+   * RFC-115 追补：每次 tick 都触发（不像 onWarning/onCritical 只在分级变化时触发）——
+   * 供调用方把完整采样时间序列落 trace（诊断专用，见 engine-nodes.ts 的
+   * 'process.memory.sample' 节点）。MemoryGovernor 本身不知道 trace 系统的存在，
+   * 只负责把采样结果透传出去，写入哪里由调用方（App 层）决定，保持职责分离。
+   */
+  onSample?: (sample: MemorySample) => void;
+  logger?: Logger;
+  /** 时间源注入（测试用；对齐 scheduler.ts 的 `deps.now` 模式）。默认 `Date.now`。 */
+  now?: () => number;
+  /**
+   * 重启后宽限期（ms，RFC-115 D5）。默认 600_000（10 分钟）。宽限期从 MemoryGovernor
+   * **构造时刻**起算——调用方（App）应只在检测到本次启动是重启恢复（如 `--continue`）
+   * 时传入非零值；全新会话不传（默认 0 = 无宽限期，立即响应 critical）。
+   */
+  postRestartGraceMs?: number;
+  /**
+   * RFC-167 D1/D5：critical 分级"持续时长"超时阈值（ms）。默认 900_000（15 分钟），
+   * 经 `OTTO_MEMORY_CRITICAL_TIMEOUT_MS` 覆盖。
+   *
+   * 背景：`onCritical` 只在状态**跃迁**（healthy/warning → critical）时触发一次；若
+   * critical 分级持续存在（内存单调爬升不再回落，不产生第二次跃迁），用户错过那一次
+   * 弹窗后不会再收到任何提醒，直至 V8 物理 OOM（2026-07-15 事故实测：跃迁触发 3 小时
+   * 20 分钟后崩溃，期间零第二次通知）。本字段驱动 `onCriticalTimeout` 的触发阈值，
+   * 与"状态跃迁检测"（`onCritical`）完全独立、互不影响。
+   */
+  criticalTimeoutMs?: number;
+  /**
+   * RFC-167 D1：critical 分级持续超过 `criticalTimeoutMs` 时触发（与 `onCritical` 的
+   * "状态跃迁触发"正交——即使从未再次跃迁，只要持续时长超过阈值就会触发一次）。
+   *
+   * 同一次 critical 区间内只触发一次（`criticalEnteredAt` 归零前不重复触发，避免
+   * 每个 tick 都调用）；恢复到非 critical 分级后 `criticalEnteredAt` 清空，下次重新
+   * 进入 critical 会重新计时、可以再次触发一次超时。
+   *
+   * 调用方（interactive-memory-governor.ts）据此实现"Dialog 从未被响应则自动执行
+   * 用户已看到过的默认建议（重启）；已响应过（无论确认还是取消）则改走持续通知 +
+   * 二级兜底"的两分支路由（RFC-167 D2/D3）。
+   */
+  onCriticalTimeout?: (sample: MemorySample) => void;
+}
+/** 单次采样结果——供 M1 日志与后续里程碑（M2/M3）复用同一份读数，不重复采样。 */
+interface MemorySample {
+  level: MemoryPressureLevel;
+  heapUsed: number;
+  heapSizeLimit: number;
+  usedPct: number;
+  /**
+   * RFC-178 P2（观察维度，不参与分级）：常驻集大小（进程全部内存含 V8 堆外）。
+   * 分级仍只看 heapUsed/heap_size_limit（针对 V8 FatalProcessOutOfMemory 这一实证
+   * 事故形态，指标已两次验证正确）；rss/external 仅落 trace 供诊断——覆盖容器
+   * OOM killer（按 RSS 杀）与图片 Buffer/ArrayBuffer（external，不计入 heapUsed）
+   * 两类 V8 堆内指标的盲区。同一 `process.memoryUsage()` 调用返回值，零额外开销。
+   */
+  rss: number;
+  /** V8 堆外的 C++ 对象/Buffer 内存（见 rss 注释——观察维度，不参与分级）。 */
+  external: number;
+  /**
+   * 采样时刻（epoch ms，独立评审 P2-2）——用 MemoryGovernor 内部注入的 `now`（测试可
+   * mock），而非消费方（如 onSample 回调）自行调用 `Date.now()`。避免测试用 fake timer
+   * 时，MemoryGovernor 采样用的是 mock 时间，但 trace 事件时间戳却是真实系统时间的
+   * 不一致。
+   */
+  ts: number;
+}
+/**
+ * 进程内存自我感知组件——App 生命周期内单例，`start()`/`dispose()` 对齐既有子系统模式
+ * （如 `SchedulerService` 的 unref ticker，见 `packages/schedule/src/scheduler.ts`，
+ * RFC-161 M2 已迁出 @x-otto/coding）。
+ */
+declare class MemoryGovernor {
+  /** RFC-324 D2：非 readonly——支持 settings load 后晚绑定（与 onWarning 等回调的晚绑定模式一致）。
+   * 构造期先走 env/默认值；settings load 后若 env 未设，由 app 层调 updateThresholds 覆盖。 */
+  private warnThresholdPct;
+  private hardThresholdPct;
+  private readonly sampleIntervalMs;
+  private readonly warningIntervalMs;
+  private readonly criticalIntervalMs;
+  private readonly warnCooldownMs;
+  /** 非 readonly——支持构造后晚绑定（session 在 App 构造时尚不存在，对齐 `setScheduleService` 的晚绑定模式）。 */
+  private onWarning;
+  private onCritical;
+  private readonly logger;
+  private readonly now;
+  private readonly postRestartGraceMs;
+  private ticker;
+  private lastLevel;
+  /** 上一次 onWarning 实际触发的时间戳（epoch ms）；undefined = 从未触发过。RFC-115 D4 冷却期基准。 */
+  private lastWarningFiredAt;
+  /** 宽限期起点（epoch ms）；undefined = 不处于宽限期（全新会话，或宽限期未由调用方设置）。 */
+  private graceStartedAt;
+  private onCriticalDuringGrace;
+  private onLevelChange;
+  private onSample;
+  /** RFC-133 D7：dispose 竞态防护——tick() 执行期间同步 dispose 后防止继续调度新定时器。 */
+  private disposed;
+  /** RFC-167 D1：critical 持续时长超时阈值（ms）。 */
+  private readonly criticalTimeoutMs;
+  private onCriticalTimeout;
+  /** 首次进入 critical 分级的时间戳（epoch ms）；恢复非 critical 时清空。RFC-167 D1。 */
+  private criticalEnteredAt;
+  /** 本次 critical 区间内是否已触发过一次 onCriticalTimeout（同一区间只触发一次）。 */
+  private criticalTimeoutFired;
+  constructor(options?: MemoryGovernorOptions);
+  /** 当前分级（供外部只读查询，如 TUI 状态展示）。 */
+  get currentLevel(): MemoryPressureLevel;
+  /**
+   * 晚绑定 onWarning/onCritical/onCriticalDuringGrace（App 构造时活跃 session 尚不存在，
+   * M2/M3 在 session 就绪后调用注入）。对齐 `App.setScheduleService` 的晚绑定模式，
+   * 非构造期可选依赖。
+   */
+  /**
+   * 合并式更新（每个字段独立覆盖，未传的字段保留原值）——RFC-115 追补：`app.ts`
+   * 启动期注入 `onSample`（trace 落盘）后，`interactive.ts` 会话就绪时再调用一次
+   * 注入 `onWarning`/`onCritical` 等；若采用整体覆盖语义，后一次调用会把前一次
+   * 设置的 `onSample` 清空。多个调用方各自只关心自己负责的字段，改为逐字段合并，
+   * 避免调用顺序耦合。
+   */
+  setCallbacks(callbacks: {
+    onWarning?: () => void;
+    onCritical?: (sample: MemorySample) => void;
+    onCriticalDuringGrace?: (sample: MemorySample) => void;
+    onLevelChange?: (level: MemoryPressureLevel) => void;
+    onSample?: (sample: MemorySample) => void;
+    onCriticalTimeout?: (sample: MemorySample) => void;
+  }): void;
+  /**
+   * RFC-115 D5：标记本次启动为重启恢复（如 `--continue`），从当前时刻起算宽限期
+   * `postRestartGraceMs`。宽限期内 critical 触发走 `onCriticalDuringGrace`（降级通知）
+   * 而非 `onCritical`（弹窗）。调用方（interactive.ts）应仅在检测到 `--continue` 时调用；
+   * 全新会话不调用，`onCritical` 立即生效无宽限期。
+   */
+  markRestarted(): void;
+  /** RFC-324 D2：settings load 后晚绑定阈值（优先级 env > config > 默认）。
+   * 仅当对应 env 未设时才覆盖——env 设了则构造期已读 env 值，此处不覆盖。 */
+  updateThresholds(opts: {
+    warnThresholdPct?: number;
+    hardThresholdPct?: number;
+  }): void;
+  /** 当前是否处于重启后宽限期内（供测试/可观测查询）。 */
+  get inPostRestartGrace(): boolean;
+  /** 单次采样 + 分级（不依赖 ticker，供测试与 onDemand 查询复用）。 */
+  sample(): MemorySample;
+  private grade;
+  /** 启动周期采样（unref，不阻止进程退出）。幂等——重复调用是 no-op。 */
+  start(): void;
+  private tick;
+  /** 停止采样，清 timeout。App.stop() 中调用。幂等。 */
+  dispose(): void;
+}
+//#endregion
+//#region src/fleet-monitor.d.ts
+interface FleetSample {
+  /** 全机 otto 主进程数。 */
+  readonly processCount: number;
+  /** 总 RSS（MB，`ps` 口径含共享库——趋势观测用，勿作精算）。 */
+  readonly totalRssMb: number;
+  /** 疑似孤儿计数（ppid==1 且无 TTY 的枚举近似，非租约级判定）。 */
+  readonly suspectedOrphanCount: number;
+  /** 进程中最大代际计数（--restart-generation，M3 后有值；无则 0）。 */
+  readonly maxGeneration: number;
+  /** 采样时刻（epoch ms，注入 now 时间源）。 */
+  readonly ts: number;
+}
+interface FleetMonitorOptions {
+  /** 采样间隔（ms）。默认 600_000（10 分钟），经 OTTO_FLEET_SAMPLE_INTERVAL_MS 覆盖。 */
+  sampleIntervalMs?: number;
+  /** 进程数预算。默认 8，经 OTTO_FLEET_MAX_PROCESSES 覆盖。 */
+  maxProcesses?: number;
+  /** 总 RSS 预算（MB）。默认 8192，经 OTTO_FLEET_MAX_TOTAL_RSS_MB 覆盖。 */
+  maxTotalRssMb?: number;
+  /** 每次采样触发（落 trace 用，完整时间序列）。 */
+  onSample?: (sample: FleetSample) => void;
+  /** 预算首次超限触发（去重后）；恢复到预算内后再次超限会再触发。 */
+  onBudgetExceeded?: (sample: FleetSample, reason: 'process-count' | 'total-rss') => void;
+  /** 进程枚举（测试注入）。默认 listOttoProcesses。 */
+  listProcesses?: () => OttoProcessInfo[];
+  logger?: Logger;
+  /** 时间源注入（测试用，对齐 MemoryGovernor 的 deps.now 模式）。 */
+  now?: () => number;
+}
+declare class FleetMonitor {
+  private readonly sampleIntervalMs;
+  private readonly maxProcesses;
+  private readonly maxTotalRssMb;
+  private readonly listProcesses;
+  private readonly logger;
+  private readonly now;
+  private onSample;
+  private onBudgetExceeded;
+  private ticker;
+  private disposed;
+  /** 超限通知去重：当前是否处于"已通知过的超限区间"内。恢复预算内后清零可再触发。 */
+  private budgetExceededNotified;
+  constructor(options?: FleetMonitorOptions);
+  /** 合并式回调更新（逐字段，对齐 MemoryGovernor.setCallbacks 语义）。 */
+  setCallbacks(callbacks: {
+    onSample?: (sample: FleetSample) => void;
+    onBudgetExceeded?: (sample: FleetSample, reason: 'process-count' | 'total-rss') => void;
+  }): void;
+  /** 单次采样（不依赖 ticker，供测试/onDemand 查询）。枚举失败返回 undefined（fail-soft）。 */
+  sample(): FleetSample | undefined;
+  private tick;
+  /** 启动周期采样（unref 不阻止进程退出）。幂等。首轮延迟一个完整间隔（启动期不抢 CPU）。 */
+  start(): void;
+  /** 停止采样。幂等。 */
+  dispose(): void;
+}
+//#endregion
+//#region src/process-registry.d.ts
+type BackgroundProcessStatus = 'running' | 'killing' | 'exited' | 'killed';
+/**
+ * RFC-223：委托后台进程的服务协议分类——从运行时输出识别，best-effort。
+ * 结构上与 `@x-otto/tools` 的 `background-types.ts` 同名类型一致，但**不 import 它**——
+ * 沿用本文件头注释既定的 tools↔runtime 解耦策略（两者都依赖 agent，互不依赖，靠结构化
+ * 类型满足契约，避免循环依赖）。
+ */
+type ServiceProtocol = 'http' | 'ws' | 'tcp';
+/** RFC-223：从后台进程运行时输出识别到的服务信息（url 优先，退化到纯端口）。 */
+interface DetectedService {
+  url?: string;
+  port?: number;
+  protocol: ServiceProtocol;
+}
+interface BackgroundProcess {
+  /** 返回给模型的句柄，如 bg_xxx。 */
+  id: string;
+  sessionId: string;
+  /** 归属宿主（App）标识：App.stop 据此只杀本 App 起的进程，不越界杀兄弟 App。register 时打标，
+   *  与 session pool 成员无关 → 会话被驱逐后其进程仍归本 App。缺省 undefined（未分宿主）。 */
+  owner?: string;
+  pid: number;
+  /** 进程组 id；unix detached 下 == pid，killpg 用。 */
+  pgid: number;
+  command: string;
+  cwd: string;
+  /** 从参数/输出 best-effort 嗅探（可能缺）。 */
+  port?: number;
+  url?: string;
+  /** 输出落临时文件路径（P1 由 bash 工具填）。 */
+  logPath?: string;
+  startedAt: number;
+  lastUsed: number;
+  status: BackgroundProcessStatus;
+  exitCode?: number;
+  /** 显式保护，免被上限 LRU 驱逐。 */
+  keepAlive?: boolean;
+  /** RFC-223：运行时输出识别到的服务信息（D2 去重规则见 `updateDetectedService`）。 */
+  detectedService?: DetectedService;
+}
+interface RegisterInput {
+  id: string;
+  sessionId: string;
+  /** 归属宿主（App）标识，见 BackgroundProcess.owner。 */
+  owner?: string;
+  /** 子进程句柄：用于监听自然退出 + 推导 pgid。 */
+  child: ChildProcess;
+  command: string;
+  cwd: string;
+  logPath?: string;
+  port?: number;
+  url?: string;
+  keepAlive?: boolean;
+  /** 注入时钟，便于测试；缺省 Date.now。 */
+  now?: number;
+}
+interface ProcessRegistryOptions {
+  maxProcesses?: number;
+  graceMs?: number;
+  /** 可注入的时钟，仅用于 lastUsed/startedAt 戳（测试用）。 */
+  clock?: () => number;
+}
+type ProcessListener = (process: BackgroundProcess) => void;
+declare class ProcessRegistry {
+  private readonly entries;
+  private readonly maxProcesses;
+  private readonly graceMs;
+  private readonly clock;
+  private readonly spawnListeners;
+  private readonly exitListeners;
+  constructor(options?: ProcessRegistryOptions);
+  /** 订阅后台进程登记事件。返回退订函数。 */
+  onSpawn(listener: ProcessListener): () => void;
+  /**
+   * 订阅后台进程退出事件（自然退出或被杀都触发一次，单一来源）。返回退订函数。
+   * 注意：宿主优雅关闭时应先退订再 killAll，避免 teardown 期误发通知。
+   */
+  onExit(listener: ProcessListener): () => void;
+  private notify;
+  /**
+   * 登记后台进程。撞满上限时先驱逐最久未用的非 keepAlive 进程；若无可驱逐则抛错
+   * （提示模型先 kill_shell）。
+   */
+  register(input: RegisterInput): BackgroundProcess;
+  get(id: string): BackgroundProcess | undefined;
+  getForSession(sessionId: string, id: string): BackgroundProcess | undefined;
+  list(): BackgroundProcess[];
+  listForSession(sessionId: string): BackgroundProcess[];
+  touch(id: string): void;
+  /**
+   * RFC-223 D2：运行时输出识别到新的服务信息时调用。去重规则——"最近一条更优先"：
+   *   - 新结果含 url 而当前无 url → 覆盖。
+   *   - 新旧都含 url 但内容不同（如 localhost → 局域网地址）→ 覆盖为最新一条
+   *     （dev server 常见先打印 Local 后打印 Network，后者对想跨设备访问的用户更有用）。
+   *   - 新结果仅 port（无 url）而当前已有 url → 不覆盖（避免更差信息覆盖更好信息）。
+   *   - 其余情况（当前为空，或新旧完全相同）→ 直接采用新结果。
+   * 进程已不在册（已退出/被驱逐/从未注册过该 id）时静默忽略，不抛错——识别回调是
+   * fire-and-forget 的旁路信号，注册表状态是唯一真源，找不到 entry 不代表错误。
+   */
+  updateDetectedService(id: string, service: DetectedService): void;
+  remove(id: string): void;
+  size(): number;
+  /** 优雅杀单个：SIGTERM → grace → SIGKILL。status 机防重复杀（BP7）。 */
+  kill(id: string): Promise<void>;
+  /** 优雅杀光（宿主 SIGINT/SIGTERM 等优雅退出路径用）。 */
+  killAll(): Promise<void>;
+  /**
+   * 优雅杀某宿主（App）起的全部进程（App.stop 用）。按 register 时打的 owner 标过滤——多 App 同进程时
+   * 不越界杀兄弟 App，且涵盖会话已被 pool 驱逐但进程仍在的（owner 与 pool 成员无关）。
+   */
+  killAllForOwner(owner: string): Promise<void>;
+  /** 优雅杀某会话全部（SessionPool.dispose 用）。 */
+  killAllForSession(sessionId: string): Promise<void>;
+  /**
+   * 同步杀光（`process.on('exit')` 兜底用——退出回调**不能** await）。
+   * 直接 SIGKILL 整组，best-effort。
+   */
+  killAllSync(): void;
+  /** 同步 SIGKILL 单个；已退/已杀则跳过。 */
+  private killEntrySync;
+  /**
+   * 撞满上限时驱逐：优先已退出的，其次最久未用的非 keepAlive 进程（同步杀 + 移除）。
+   * 全为 keepAlive 时不驱逐（register 随后抛错）。
+   */
+  private evictLeastRecent;
+  private killEntry;
+  private waitForExit;
+}
+/** 进程级单例：宿主与工具层共享同一注册表。 */
+declare const globalProcessRegistry: ProcessRegistry;
+/**
+ * 安装宿主退出兜底：`process.on('exit')` → 同步 killAllSync。
+ * 幂等。**不**安装 SIGINT/SIGTERM（交互式 TUI 自有处理；非交互宿主在各自
+ * shutdown 路径里调 killAll）。
+ */
+declare function installProcessReaper(registry?: ProcessRegistry): void;
+//#endregion
+//#region src/process-runtime.d.ts
+type ProcessCategory = 'mcp' | 'lsp' | 'shell' | 'plugin' | 'browser' | 'tool' | 'cli';
+type ProcessStatus = 'starting' | 'running' | 'killing' | 'killed' | 'exited' | 'errored';
+type ProcessLifecycle = 'pinned' | 'evictable';
+interface ProcessOwner {
+  /** 归属类型：mcp-server / lsp-server / plugin-hook / plugin-script / agent-tool / cli-shell / cli-chaperone / browser / notification / background-bash */
+  type: string;
+  /** 归属 id：mcp server name / plugin id / session id */
+  id: string;
+}
+interface ProcessSpawnConfig {
+  command: string;
+  args?: string[];
+  options?: SpawnOptions;
+  /** 必填：谁 spawn 的 */
+  owner: ProcessOwner;
+  /** 关联 session */
+  sessionId?: string;
+  /** 进程分类 */
+  category: ProcessCategory;
+  /** 人类可读标签（调试/日志） */
+  label?: string;
+  /** 生命周期：pinned（常驻，免 LRU 驱逐）/ evictable（短命，可驱逐）。默认 evictable */
+  lifecycle?: ProcessLifecycle;
+  /** detached + 免批量 kill（OAuth 浏览器 / notify launcher）。与 lifecycle 正交 */
+  keepAlive?: boolean;
+  /** 覆盖全局默认 SIGTERM→SIGKILL 宽限期（默认 2000ms） */
+  killGraceMs?: number;
+  /** 硬上限（默认 30000ms） */
+  killTimeoutMs?: number;
+  /** 外部取消信号 */
+  signal?: AbortSignal;
+  /**
+   * 环境变量覆盖。spawn() 会以此为 override 调 buildAllowedEnv（规则 7）：
+   * 白名单基座（PATH/HOME/LANG/… strip 凭证）+ 本 override，凭证永不 bypass。
+   * 注意：registerChild 路径不经此（子进程已由调用方 spawn，env 已定）。
+   */
+  env?: Record<string, string>;
+  cwd?: string;
+}
+interface KillOptions {
+  graceMs?: number;
+  timeoutMs?: number;
+  reason?: string;
+}
+interface ExitResult {
+  code: number | null;
+  signal: NodeJS.Signals | null;
+  timedOut: boolean;
+}
+interface ProcessFilter {
+  owner?: ProcessOwner;
+  sessionId?: string;
+  category?: ProcessCategory;
+}
+interface ManagedProcess {
+  readonly id: string;
+  readonly pid: number | undefined;
+  /** 进程组 id；unix detached 下 == pid，非-detached 下可能不等于 pid */
+  readonly pgid: number | undefined;
+  readonly status: ProcessStatus;
+  readonly config: ProcessSpawnConfig;
+  /** 原始字节流 stdin/stdout/stderr（规则 5/H2：非行缓冲，帧解析由消费者负责） */
+  readonly stdin: NodeJS.WritableStream | null;
+  readonly stdout: NodeJS.ReadableStream | null;
+  readonly stderr: NodeJS.ReadableStream | null;
+  /** 便利层；LSP/MCP 等帧协议应直接消费字节流。 */
+  onStdoutLine(cb: (line: string) => void): () => void;
+  onStderrLine(cb: (line: string) => void): () => void;
+  onExit(cb: (result: ExitResult) => void): () => void;
+  onError(cb: (err: Error) => void): () => void;
+  /** 优雅杀：SIGTERM → grace → SIGKILL（Windows 走 taskkill；复用 signalGroup 单 pid 回退——C1） */
+  kill(opts?: KillOptions): Promise<void>;
+  waitForExit(timeoutMs?: number): Promise<ExitResult>;
+  /** 上次活跃时间戳（LRU 驱逐用） */
+  lastUsed: number;
+}
+interface ProcessRuntimeOptions {
+  maxProcesses?: number;
+  killGraceMs?: number;
+  killTimeoutMs?: number;
+  clock?: () => number;
+}
+declare class ProcessRuntime {
+  private readonly _entries;
+  private readonly _maxProcesses;
+  readonly killGraceMs: number;
+  readonly killTimeoutMs: number;
+  private readonly _clock;
+  private readonly _spawnListeners;
+  private readonly _exitListeners;
+  constructor(options?: ProcessRuntimeOptions);
+  onSpawn(listener: (proc: ManagedProcess) => void): () => void;
+  onExit(listener: (proc: ManagedProcess) => void): () => void;
+  /** 池空时触发。 */
+  onAllExited(listener: () => void): () => void;
+  /**
+   * 启动子进程并返回 ManagedProcess 句柄。
+   * 非-keepAlive 子进程强制 `detached: true`（C1/规则 4：使子进程成为组长，-pgid 生效）。
+   */
+  spawn(config: ProcessSpawnConfig): ManagedProcess;
+  get(id: string): ManagedProcess | undefined;
+  list(filter?: ProcessFilter): ManagedProcess[];
+  listForSession(sessionId: string): ManagedProcess[];
+  listForOwner(owner: ProcessOwner): ManagedProcess[];
+  touch(id: string): void;
+  remove(id: string): void;
+  size(): number;
+  /** kill 满足 filter 的非 keepAlive 进程。pinned 进程也杀——killAll 是显式操作非 LRU 驱逐。 */
+  killAll(filter?: ProcessFilter, opts?: KillOptions): Promise<void>;
+  /**
+   * 同步 SIGKILL 所有非 keepAlive 进程。
+   * `process.on('exit')` 兜底用——不声称覆盖信号退出（C2/规则 3）。
+   * 复用 `signalGroup` 单 pid 回退（C1/规则 4），禁裸 `process.kill(-pid)`。
+   * Windows 单次批量 taskkill（规则 9）。
+   */
+  killAllSync(): void;
+  killAllForOwner(ownerType: string, ownerId: string): Promise<void>;
+  killAllForSession(sessionId: string): Promise<void>;
+  /**
+   * 低级注册：包装一个已被外部 `child_process.spawn()` 创建的 ChildProcess 为 ManagedProcess。
+   * 用于兼容 shim（旧 ProcessRegistry API 预 spawn 了 child）和后续子系统渐进迁移。
+   *
+   * 规则 4/C1：非-keepAlive 若未 detached，调用方应确保进程组长语义正确。
+   */
+  registerChild(config: ProcessSpawnConfig, child: ChildProcess): ManagedProcess;
+  private _evictLeastRecent;
+}
+/** 全局进程运行时单例。 */
+declare const globalProcessRuntime: ProcessRuntime;
+/**
+ * 安装宿主退出兜底：`process.on('exit')` → 同步 `killAllSync()`。
+ * 幂等。不覆盖 SIGINT/SIGTERM——交互式 TUI 自有处理。
+ *
+ * **C2/规则 3**：不声称覆盖信号退出——`process.on('exit')` 在 SIGTERM/SIGKILL/SIGHUP 下不触发。
+ * 正常 `process.exit()` 和可捕获崩溃路径才触发。
+ */
+declare function installExitReaper(rt?: ProcessRuntime): void;
+//#endregion
+//#region src/git-worktree.d.ts
+/**
+ * git-worktree.ts —— RFC-023 Phase 1：agent-session 作业的 git worktree 隔离。
+ *
+ * 后台 agent 作业**绝不能**背着用户改主工作区（本会话 cli.ts 被并发改的事故即反例）。
+ * 每个作业跑在独立 worktree（临时分支）：agent 在 worktree 内自由改 → 产出 diff → 主会话
+ * 评审后带冲突 apply（worktreePath/worktreeBranch 隔离 + apply-patch 回主区）。
+ *
+ * 纯 git 子进程封装（execFileSync 数组参数，无 shell 注入）；不持状态。
+ */
+interface Worktree {
+  /** worktree 绝对路径（agent 作业的 cwd / workspaceDir）。 */
+  path: string;
+  /** 临时分支名。 */
+  branch: string;
+  /** 建 worktree 时主仓 HEAD 的 sha（apply 时检漂移）。 */
+  base: string;
+  /** 主仓根（remove 时用）。 */
+  repoRoot: string;
+}
+/**
+ * 为作业建一个 worktree：基于主仓当前 HEAD 拉临时分支，落在系统临时目录（不污染主仓树）。
+ *
+ * L2 注意：worktree 落在 `os.tmpdir()` 下**有意为之**——沙箱可写根含 tmpdir（computeSandboxRoots），
+ * 故沙箱开启时 agent 对 worktree 的写恰好被放行。若改 worktree 位置，须同步把该路径加入沙箱可写根，
+ * 否则沙箱模式下 agent 作业写文件会被拒。
+ */
+declare function createWorktree(repoRoot: string, jobId: string): Worktree;
+/**
+ * 捕获 agent 在 worktree 内的全部改动为统一 diff（含未跟踪文件 + 删除）。
+ * worktree 分支 HEAD == base（作业不 commit），故 stage 全部后 `diff --cached` 即作业产物。
+ *
+ * M2 已知限制：`git add -A` **遵守 .gitignore**——agent 创建的被忽略文件不进 diff、apply 不带过去
+ * （这通常是想要的：忽略文件本就不该入库）。若将来需带忽略产物，改用 `add -A --force`。
+ */
+declare function worktreeDiff(wt: Worktree): string;
+interface ApplyDiffResult {
+  applied: boolean;
+  /** 冲突/失败的文件路径（best-effort 从 git stderr 解析）。 */
+  conflictPaths: string[];
+}
+/**
+ * review J6：worktree 建立后主仓 HEAD 是否已经前进（`Worktree.base` 字段此前"apply 时检漂移"
+ * 的注释所指，但从未被消费——apply 只靠 `git apply --check` 判定能否干净应用）。这是一个
+ * **提示性**信号（`applyDiff` 的 `--check` 才是真正的冲突判定），用于向用户解释"为什么这个
+ * apply 可能出乎意料地冲突/无冲突"，不用来拒绝 apply。
+ */
+declare function hasRepoDrifted(repoRoot: string, base: string): boolean;
+/**
+ * 把作业 diff apply 到主仓工作区。**check-first，不强改**：先 `git apply --check` 验证能否干净
+ * 应用——能才真 apply；不能（主仓漂移/冲突）则返回 applied=false + conflictPaths，**绝不**往主树
+ * 写冲突标记（区别于 `--3way` 会留 `>>>>>>>` 撕裂工作区）。让用户在 worktree 解决后重试或 cancel。
+ */
+declare function applyDiff(repoRoot: string, diff: string): ApplyDiffResult;
+/**
+ * 把已 apply 的 diff 从主仓工作区**反向撤销**（`git apply --reverse`）。RFC-026 §4.2 回退。
+ * 同样 **check-first，不强改**：工作树自 apply 后漂移（用户又改了那些文件）→ reverse check 失败 →
+ * 返回 applied=false + conflictPaths，绝不强撤。干净才真撤。
+ */
+declare function revertDiff(repoRoot: string, diff: string): ApplyDiffResult;
+/**
+ * 移除 worktree + 删临时分支（幂等 best-effort：已不在/已删不报错）。
+ *
+ * review J4：三步仍各自 best-effort（单步失败不阻塞后续——分支已被 prune 掉的场景下
+ * `branch -D` 失败是正常噪音），但**不再完全静默**——失败会经可选 `onError` 报告，调用方
+ * 可接 logger 观测到"清理不彻底"（此前三个空 catch 让权限/NFS stale handle/进程占用等
+ * 真实失败无声吞掉，运维完全无感知）。`onError` 缺省不传时行为与修复前一致（纯静默）。
+ */
+declare function removeWorktree(wt: Worktree, onError?: (op: 'worktree remove' | 'branch delete' | 'worktree prune', err: unknown) => void): void;
+/**
+ * 扫描并清理孤儿 worktree（SIGKILL/OOM 未走 exit reaper 留下的残留）。
+ * 用 `git -C repoRoot worktree list --porcelain` 列出该仓的全部已注册 worktree，
+ * 筛选出：① 路径匹配 tmpdir 下 `otto-wt-*` 模式的（本系统创建的），
+ *        ② 分支名匹配 `otto/job-*` 的，
+ * 且这些 worktree 不在 `activeJobIds`（当前存活作业 id 集合，调用方传入，避免误删正在跑的）里对应的路径中。
+ * 对匹配到的孤儿逐个 `git worktree remove --force` + `git branch -D`，
+ * 最后 `git worktree prune`。全程 best-effort（单条失败不中断其余）。
+ * 返回被清理的路径列表（供日志/测试断言）。
+ */
+declare function pruneOrphanWorktrees(repoRoot: string, activeJobIds: Iterable<string>): string[];
+//#endregion
+//#region src/governance/forbidden-zone.d.ts
+/**
+ * forbidden-zone.ts —— RFC-026 §4.0 治理禁区锁（自我进化的前提铁律）。
+ *
+ * 自我修改系统最大的风险是**改写绑住自己的绳子**：一个 delegate 的 diff 里夹带改自主分级、
+ * 出网 allowlist、权限/沙箱、apply/revert 能力、设置 schema……于是任何"自主级"最终都能解除
+ * 约束自己的规则。本模块提供一个**独立守卫**：扫 diff 触及的路径 ∩ 禁区集合 → 命中即"高危"。
+ *
+ * 用法（分级）：
+ *   - 手动 apply（L0，人即闸）：命中只**高危警示**，仍可应用（人已在审）。
+ *   - 未来自主层（L≥2 自动 apply）：命中**强制降 L0、拒绝自动落地**（不可被任何自主级旁路）。
+ *
+ * **自含**：禁区清单包含本文件自身（`governance/forbidden-zone`）——改禁区清单的 diff 自身即被
+ * 标记，故无法被悄悄缩小/移除。终局还应把清单**外置/签名**（本阶段先在引擎内 + 自含兜底）。
+ */
+/** 禁区路径模式（匹配 repo 相对路径）。保守从宽——宁可多标人审，不可漏放（RFC §4.0）。 */
+declare const FORBIDDEN_ZONE_PATTERNS: readonly RegExp[];
+/**
+ * 从统一 diff 里提取触及的文件路径（repo 相对）。覆盖 diff --git / +++ / --- 行；跳过 /dev/null。
+ * 还原 git quotepath（引号化/八进制转义）——否则特殊字符文件名绕过治理守卫（fail-open）。
+ */
+declare function diffTouchedPaths(diff: string): string[];
+/**
+ * 某 diff 触及的**禁区文件**（空数组=未触禁区）。调用方据此：手动 apply 高危警示 / 自主层强制 L0。
+ */
+declare function touchesForbiddenZone(diff: string): string[];
+//#endregion
+//#region src/governance/capability-surfaces.d.ts
+/**
+ * capability-surfaces.ts —— RFC-026 阶段2：识别一个 diff 是否触及"能力面"。
+ *
+ * delegate 给 otto 加能力（MCP / provider / 声明式 agent·skill·team）= 改项目级配置/声明文件。
+ * apply 后若 diff 触及能力面 → 自动热重载（reloadCapabilities），不重启即认到新能力。
+ *
+ * delegate 的 diff 只能改 worktree（repo）内文件，故能力新增必落在项目级 `.otto/`（agents/skills/
+ * teams/config）或代码里——全局 `~/.otto/` 不在 worktree 范围。这里只认项目级配置/声明面。
+ */
+/** 能力面路径模式（匹配 repo 相对路径）。命中即该 diff 改动了可热重载的能力配置/声明。 */
+declare const CAPABILITY_SURFACE_PATTERNS: readonly RegExp[];
+/** 某 diff 触及的**能力面文件**（空数组=未触；非空=apply 后应热重载）。 */
+declare function touchesCapabilitySurface(diff: string): string[];
+//#endregion
+//#region src/governance/apply-policy.d.ts
+/**
+ * apply-policy.ts —— 自主 apply 策略层的**纯决策核**。
+ *
+ * 自我进化闭环里那道「闸」：一个 delegate 作业产出的 diff 要不要自动落主仓。本模块只回答
+ * "怎么落"（自动 / 建议人审 / 强制人审 / 禁区拒绝），**不执行任何 apply**——执行由调用方
+ * （agent-job-service.apply 回路）据 Verdict 决定。纯函数：无 IO、无副作用，全 L0–L4 × 信号
+ * 矩阵可单测覆盖。
+ *
+ * 铁律（第一判定，不可旁路）：
+ *   origin='main'（自主）+ 触禁区 → 永远 forbid，不存在任何 autonomy 级/配置能让它自动落地。
+ *   禁区清单见 governance/forbidden-zone（自含：改禁区清单的 diff 自身即触禁区）。
+ *
+ * 人手路径（origin='user'）：人即闸——只产建议（advise），从不 forbid/auto。
+ */
+/** 自主分级。默认 0 = 人即闸 = 现状，零行为变化。 */
+type AutonomyLevel = 0 | 1 | 2 | 3 | 4;
+/** decideApply 的输入信号——全部由调用方计算后注入（保持本函数纯粹）。 */
+interface ApplySignals {
+  /** touchesForbiddenZone(diff) 的结果（空=未触禁区）。 */
+  forbiddenZone: string[];
+  /** touchesCapabilitySurface(diff) 的结果（空=未触能力面）。 */
+  capabilityTouched: string[];
+  /** diff 规模（增/删行）。 */
+  diffStat: {
+    added: number;
+    removed: number;
+  };
+  /** applyDiff --check 预检：true=有冲突，不可干净落地。 */
+  conflict: boolean;
+  /** 发起方：user=人手 /job apply；main=模型自主作业；plugin=插件代码自主发起（RFC-287 R2）。 */
+  origin: 'user' | 'main' | 'plugin';
+}
+interface ApplyPolicy {
+  level: AutonomyLevel;
+  /** 自动落地的 diff 规模上限（增+删行）；超过则降人手。默认 DEFAULT_MAX_AUTO_APPLY_LINES。 */
+  maxAutoApplyLines?: number;
+}
+type Verdict = /** 自动落地（仅 origin='main' + level≥2 + 全部低风险条件满足）。 */{
+  action: 'auto';
+} /** 人手落地 + 推荐（人即闸或 L1）。recommend=apply/review。 */ | {
+  action: 'advise';
+  recommend: 'apply' | 'review';
+  reasons: string[];
+} /** 强制人手（自主但被降级：L0 / 冲突 / 超规模 / 能力面越级）。 */ | {
+  action: 'gate';
+  reasons: string[];
+} /** 禁区命中：拒绝自动落地（铁律，自主路径专属）。 */ | {
+  action: 'forbid';
+  reasons: string[];
+};
+/** 自动落地默认规模上限（保守）。超过即便低风险也降人手——大改动人审。 */
+declare const DEFAULT_MAX_AUTO_APPLY_LINES = 200;
+/**
+ * 纯决策：据信号 + 策略产出 Verdict。无副作用。
+ *
+ * 判定顺序（铁律优先）：
+ *   1. origin='main'|'plugin' + 触禁区 → forbid（第一判定，任何级别不可旁路）。
+ *   2. origin='plugin' → 永不自动落地（RFC-287 R2）：触禁区已被上一条 forbid，其余一律
+ *      gate（强制人手）。插件代码自主发起的作业不享受 user 的"人即闸 advise"待遇（那条
+ *      分支从不 forbid），也不参与 main 的 autonomy 自动落地——独立且最保守的一档。
+ *   3. origin='user' → advise（人即闸；有风险信号则 recommend=review，否则 apply）。
+ *   4. origin='main' + level≤1 → 不自动：L0=gate（必须人手），L1=advise（带推荐）。
+ *   5. origin='main' + level≥2 → 低风险则 auto；否则 gate（列出 blocker）。
+ *      低风险 = 无冲突 ∧ 规模≤上限 ∧（L2:未触能力面 / L3+:允许能力面）。
+ */
+declare function decideApply(signals: ApplySignals, policy: ApplyPolicy): Verdict;
+//#endregion
+//#region src/agent-job-registry.d.ts
+type AgentJobStatus = 'running' | 'needs_input' | 'ready' | 'applied' | 'failed' | 'canceled';
+/**
+ * 作业来源（RFC-026）：user = 用户 /delegate 委派的；main = 主对话（模型）在答复过程中起的。
+ *
+ * RFC-287 D2/R2 新增 `plugin`：插件代码经 `PluginHostCapabilities.startJob` 自主发起的作业
+ * （需高危能力 `agent.dispatch`）。**必须是独立取值、不可复用 user/main**——`decideApply`
+ * （governance/apply-policy）按 origin 分流：`'user'` 视为"人即闸"从不 forbid、`'main'` 在
+ * 高 autonomy 下可 auto 落地，两者都不适用于"插件代码自主发起"这一档信任级别。独立取值
+ * 使插件作业在策略层永远走最保守分支（见 apply-policy `decideApply`）。
+ */
+type JobOrigin = 'user' | 'main' | 'plugin';
+interface AgentSessionJob {
+  id: string;
+  sessionId: string;
+  type: 'agent-session';
+  title: string;
+  /** 来源：用户委派 vs 主对话委派（面板分组用）。 */
+  origin: JobOrigin;
+  status: AgentJobStatus;
+  /** 隔离 worktree（产物所在）。 */
+  worktree: Worktree;
+  /** 转录输出文件（logPath 式；/jobs tail + 完成通知指针）。 */
+  outputPath: string;
+  startedAt: number;
+  /** ready 后填：worktree vs base 的统一 diff。 */
+  diff?: string;
+  /** failed 时填。 */
+  error?: string;
+}
+interface RegisterAgentJobInput {
+  id: string;
+  sessionId: string;
+  title: string;
+  worktree: Worktree;
+  outputPath: string;
+  /** 来源（缺省 user）。 */
+  origin?: JobOrigin;
+  /** 取消该作业的 detached run（spawnDetachedRun 返回的 abort）。 */
+  abort: () => void;
+  now?: number;
+}
+type AgentJobListener = (job: AgentSessionJob) => void;
+interface AgentJobRegistryOptions {
+  maxJobs?: number;
+  clock?: () => number;
+  /**
+   * worktree 清理失败上报（review J4）。缺省不传时 `removeWorktree` 的三步失败仍完全静默
+   * （行为等同修复前）——传入后可接 logger 观测权限/NFS stale handle/进程占用等真实失败。
+   */
+  onWorktreeCleanupError?: (jobId: string, op: 'worktree remove' | 'branch delete' | 'worktree prune', err: unknown) => void;
+}
+declare class AgentJobRegistry {
+  private readonly entries;
+  private readonly maxJobs;
+  private readonly clock;
+  private onWorktreeCleanupError?;
+  private readonly spawnListeners;
+  private readonly updateListeners;
+  private readonly exitListeners;
+  private readonly removeListeners;
+  private readonly retained;
+  constructor(options?: AgentJobRegistryOptions);
+  /**
+   * 补设 worktree 清理失败上报（review J4）。`globalAgentJobRegistry` 是模块级单例，构造时
+   * 无法从 app 层注入 logger——app 装配阶段调用本方法一次即可后接。
+   */
+  setWorktreeCleanupErrorHandler(handler: AgentJobRegistryOptions['onWorktreeCleanupError']): void;
+  onSpawn(listener: AgentJobListener): () => void;
+  /** 状态/diff 变更（running→ready/needs_input 等）。 */
+  onUpdate(listener: AgentJobListener): () => void;
+  /** 终态（applied/failed/canceled）通知一次。 */
+  onExit(listener: AgentJobListener): () => void;
+  /** 作业从表中移除（手动删除/容量驱逐后）。cli 据此重推 /jobs（作业消失）。 */
+  onRemove(listener: AgentJobListener): () => void;
+  /**
+   * R4：查看某作业时 retain；停止查看时 off。
+   *
+   * 2026-07-30 语义变更（applied 后 3 秒条目蒸发的终局修复）：终态作业**不再定时驱逐**，
+   * 保留至用户手动 `d` 删除（onBackgroundDelete → remove）或容量压力驱逐（register 满员
+   * 时 evictTerminal）。retain 从"阻断驱逐定时器"改为"容量驱逐保护"——正在被查看的
+   * 终态作业不会被 evictTerminal 腾退。对照社区（Claude Code / Roo Code）：终态任务历史
+   * 持续可见；原 3s graceMs 系对 CC STOPPED_DISPLAY_MS 的语义误用（那是 UI 显示宽限，
+   * 不是数据条目驱逐宽限）。
+   */
+  retain(id: string, on: boolean): void;
+  private notify;
+  /**
+   * 登记作业。撞满上限时先驱逐已终态的；若全在跑则抛错（提示先 cancel）。
+   * **不**驱逐在跑的 agent 作业（不像进程 LRU——杀活作业会丢工作）。
+   */
+  register(input: RegisterAgentJobInput): AgentSessionJob;
+  get(id: string): AgentSessionJob | undefined;
+  getForSession(sessionId: string, id: string): AgentSessionJob | undefined;
+  list(): AgentSessionJob[];
+  listForSession(sessionId: string): AgentSessionJob[];
+  size(): number;
+  /**
+   * 更新作业状态/diff/error（running→ready 等）。终态（applied/failed/canceled）额外触发 onExit
+   * 并清理 worktree（applied/failed；canceled 由 cancel() 自己清）。
+   */
+  update(id: string, patch: Partial<Pick<AgentSessionJob, 'status' | 'diff' | 'error'>>): void;
+  /**
+   * 取消作业：abort detached run + removeWorktree + status=canceled（onExit 一次）。
+   *
+   * review J5：改走 `update()` 流转状态（而非直改 `e.info.status` + 手动发 onExit），使
+   * canceled 与 applied/failed 一样触发 onUpdate——此前 onUpdate 订阅者（如需据状态变化刷新
+   * UI 的消费者）会漏收 canceled 事件。worktree 仍在此处**先行**清理（update() 对已是
+   * 'canceled' 的状态会跳过它自己的 removeWorktree，避免重复清理）。
+   */
+  cancel(id: string): void;
+  /**
+   * 从表中移除（用户 `d` 手动删除 / 容量驱逐后调用）。清 retain 并通知 onRemove。
+   * 防御性兜底：再调一次 removeWorktree（review P1：正常终态流转在 update()/cancel() 已清理过，
+   * 这里是"清理被跳过"异常路径的兜底——removeWorktree 内部 try/catch 逐步执行，对已清理/
+   * 不存在的 worktree 是安全空操作，不会因重复调用报错或产生副作用）。
+   */
+  remove(id: string): void;
+  /**
+   * 撞上限时驱逐已终态作业（不动在跑的；跳过 retained——正被查看的终态作业不腾退）。
+   * 走 remove 以发 onRemove。终态不再定时驱逐后，这里是唯一的自动驱逐路径（容量压力）。
+   */
+  private evictTerminal;
+  /** 宿主退出兜底：同步 cancel 所有在跑作业（abort + removeWorktree），防 worktree 泄漏。 */
+  cleanupAll(): void;
+}
+/** 进程级单例：宿主与作业服务共享。 */
+declare const globalAgentJobRegistry: AgentJobRegistry;
+/** 安装宿主退出兜底：process.on('exit') → cleanupAll（清 worktree）。幂等。 */
+declare function installAgentJobReaper(registry?: AgentJobRegistry, repoRoot?: string): void;
+//#endregion
+//#region src/agent-observability.d.ts
+/**
+ * 观测态：比引擎 AgentStatus 多两个派生态——`awaiting_gate`（等审批）、
+ * `tool_waiting`（RFC-144 M1：有 lifecycleAsync 工具在后台执行，loop 未阻塞但也非常规
+ * streaming/tool_executing，供宿主面板区分"模型在想"与"后台任务在跑，模型可继续其他工作"）。
+ *
+ * `tool_waiting` 是接口占位（M1 设计，M3 才由 workLoop 控制流真正驱动状态转换）——
+ * 当前无生产者调用 `setToolWaiting`/`clearToolWaiting`（下方新增方法），这是刻意的：
+ * M1 的范围是"pending 追踪"而非"控制流改造"（后者需要 runTurnsUntilTerminate 在
+ * post-runTools 检查 pending 非空后 yield，这是 M3 的工作）。
+ */
+type AgentObsStatus = 'streaming' | 'tool_executing' | 'awaiting_gate' | 'tool_waiting' | 'done' | 'error' | 'aborted';
+/** 阻塞类别——映射「四类无界等待」中子代理可见的三类（外部进程超时化为 D 类 backlog）。 */
+type BlockClass = 'model_io' | 'approval' | 'process';
+/** 一个被观测 Agent 的累积运行态（不含派生量）。 */
+interface AgentObservation {
+  /** 唯一观测键（swarm=`${runId}:${memberId}`，detached=runId）。 */
+  id: string;
+  agentName: string;
+  title?: string;
+  /** 完整的委托提示词（供 SubagentsPane / 详情面板展示）。 */
+  prompt?: string;
+  origin: 'user' | 'main';
+  depth: number;
+  status: AgentObsStatus;
+  turnIndex: number;
+  toolUseCount: number;
+  /** 累积文件编辑次数（edit/write/edit_file/write_file 工具调用）。 */
+  filesEdited: number;
+  /** 累积输出 token（逐 turn.end 累加）。 */
+  tokenCount: number;
+  inputTokens: number;
+  /** 分配模型 id（供 SubagentsPane 面板显示；缺省空串）。 */
+  model?: string;
+  /** 模型决策层(explicit/slot/category/default/fallback)——面板显示「为何用这个模型」。 */
+  modelDecidedBy?: string;
+  /** 人类可读的当前活动：thinking / responding / using <tool> / reconnecting / done。 */
+  lastActivity: string;
+  /** 最近一次事件时刻（含高频 stream delta）——stall 判定基准。 */
+  lastEventAt: number;
+  /** 当前等待类别（仅在「停住」时有诊断意义；配合 stall 级别看）。 */
+  blockedOn?: BlockClass;
+  blockDetail?: string;
+  /** 父 abort 能否中断它（fork_call 修复前曾为 false；现恒 true，保留字段以暴露未来回归）。 */
+  abortable: boolean;
+  startedAt: number;
+  endedAt?: number;
+}
+/** 快照 = 观测态 + 派生量（idleMs / stall 级别）。 */
+interface AgentObservationSnapshot extends AgentObservation {
+  /** 距上次事件毫秒（已结束则 0）。 */
+  idleMs: number;
+  /** stall 级别：none / warn（>warnMs）/ stalled（>stalledMs）；已结束恒 none。 */
+  stall: 'none' | 'warn' | 'stalled';
+}
+interface AgentObservationMeta {
+  id: string;
+  agentName: string;
+  title?: string;
+  /** 完整的委托提示词（供 SubagentsPane / 详情面板展示）。 */
+  prompt?: string;
+  /** 分配模型 id（供 SubagentsPane 面板显示）。 */
+  model?: string;
+  /** 模型决策层(供面板显示选型溯源)。 */
+  modelDecidedBy?: string;
+  origin?: 'user' | 'main';
+  depth?: number;
+  /** 中止该 agent 的回调（swarm=agent.abort；detached=清 pending approval + agent.abort）。
+   *  提供即 `abortable=true`；面板 `x`/`k` 经 `registry.abort(id)` 调用它中止卡死的子代理。 */
+  abort?: () => void;
+  /** 显式覆盖 abortable（缺省由 abort 是否提供推断）。 */
+  abortable?: boolean;
+  /** 视图A：子代理的 live 转录数组引用（=AgentRunContext.messages，agent 原地 push）。
+   *  registry 只持引用、读取时取快照；供「对话」视图渲染。不进 list() 轻量快照（按需 getMessages）。
+   *  可传**取值函数**——AgentSession 子代理（task_delegate/fork 等）无稳定 live 数组，
+   *  传 `() => session.session.messages()` 让 getMessages 每次取最新（task-runner finally 再 setMessages 冻结终态）。 */
+  messages?: readonly AgentMessage[] | (() => readonly AgentMessage[]);
+}
+interface AgentObservabilityOptions {
+  now?: () => number;
+  /** stall 黄阈（默认 3s）。 */
+  warnMs?: number;
+  /** stall 红阈（默认 30s）。 */
+  stalledMs?: number;
+  /** 结束后保留多久再驱逐（默认 15s）。 */
+  evictMs?: number;
+}
+type ObservabilityEvents = Events & {
+  change: () => void;
+};
+declare class AgentObservabilityRegistry extends TypedEventEmitter<ObservabilityEvents> {
+  private readonly observations;
+  private readonly abortFns;
+  private readonly messagesRefs;
+  private readonly streamingTexts;
+  private readonly turns;
+  private readonly evictTimers;
+  /** 被 pin 的 id 不受驱逐 timer 影响（用于 s 键查看 sub-agent 时阻止消息被清除）。 */
+  private readonly pinned;
+  private readonly now;
+  private readonly warnMs;
+  private readonly stalledMs;
+  private readonly evictMs;
+  constructor(opts?: AgentObservabilityOptions);
+  /** 登记一个待观测 Agent（attachAgentObserver 首先调用）。重复 id 覆盖（同 id 复用即续命）。 */
+  register(meta: AgentObservationMeta): void;
+  /**
+   * 中止一个被观测 agent（面板 `x`/`k` → 这里）。调用其 abort 回调（swarm=agent.abort / detached=
+   * 清 pending approval + agent.abort）；已结束或无回调返回 false。中止后状态由 abort/status.change 事件收敛。
+   */
+  abort(id: string): boolean;
+  /** 摄入一个引擎事件并归约到观测态。高频 stream delta 只更 lastEventAt、不 notify（防风暴）。 */
+  record(id: string, event: AgentEvent): void;
+  /** detached /job 的审批挂起——经此显式标记（裸 Agent 不在事件总线上发 approval）。 */
+  setAwaitingApproval(id: string, detail: string): void;
+  clearAwaitingApproval(id: string): void;
+  /**
+   * RFC-144 M1 接口占位（M3 接线）：lifecycleAsync 工具在后台执行、loop 已 yield 等待。
+   * 与 `setAwaitingApproval` 同构（外部显式标记 + 显式清除），供 M3 的 workLoop 控制流
+   * 在 post-runTools 检测到 `pendingLifecycleTools` 非空时调用。
+   */
+  setToolWaiting(id: string, detail: string): void;
+  clearToolWaiting(id: string): void;
+  /** 兜底收尾（wiring 站点 finally 调用）：若仍活跃则置 done。status.change('completed') 通常已覆盖。 */
+  markEnded(id: string, status?: AgentObsStatus): void;
+  /** 阻止 id 关联的数据被驱逐。取消已排队的 evict timer 并标记为 pinned。
+   *   - 已终态 agent：timer 被取消，数据保留到 unpin 后重启 timer。
+   *   - 运行中 agent：无 timer 可取消，仅标记 pinned，未来 markTerminal 的 scheduleEvict 会跳过。
+   *   重复 pin 幂等。 */
+  pin(id: string): void;
+  /** 取消 id 的 pin 保护。若 agent 已终态（endedAt 存在），重启驱逐 timer（默认 evictMs）。
+   *   若仍在运行中（未结束），不操作——终态时 markTerminal 会自行 scheduleEvict。
+   *   重复 unpin 幂等。 */
+  unpin(id: string): void;
+  /**
+   * 从表中立即移除（面板手动删除一项，不等自动驱逐 timer）。终态/运行中皆可调——运行中直接
+   * 静默移除观测记录（不中止真实 agent，中止走 abort()；本方法只影响 UI 可见性）。
+   * 清 evictTimer/abortFn/messagesRef/streamingText/turns/pinned，幂等（不存在的 id 安全跳过）。
+   */
+  remove(id: string): void;
+  get(id: string): AgentObservationSnapshot | undefined;
+  /** P1 视图A：取某 agent 转录的**快照副本**（防消费方读到后被 agent 继续 mutate 的活引用）。
+   *  ref 可为数组或取值函数（AgentSession 子代理传 getter，每次取最新）。 */
+  getMessages(id: string): AgentMessage[] | undefined;
+  /** 冻结某 agent 转录终态快照。task-runner 在 ephemeral removeSession 前调，
+   *  使切入对话/Transcript 在子会话被 dispose 后仍可读最终内容（驱逐前 evictMs 窗口内）。 */
+  setMessages(id: string, msgs: readonly AgentMessage[]): void;
+  /** P1 视图A：当前 turn 尚未落入 messages 的 in-flight 流式文本（无则空串）。 */
+  getStreamingText(id: string): string;
+  /** P2 视图B：单轮记录（turn timeline）副本；无则空数组。 */
+  getTurns(id: string): TurnRecord$1[];
+  /** 全部观测快照（含派生 idleMs/stall）。 */
+  list(): AgentObservationSnapshot[];
+  /** 仅活跃（未结束）的观测。 */
+  listActive(): AgentObservationSnapshot[];
+  subscribe(listener: () => void): () => void;
+  /** 测试用：清空。 */
+  clear(): void;
+  private applyTerminal;
+  private markTerminal;
+  private scheduleEvict;
+  private toSnapshot;
+}
+/** 全局单例（照 globalProcessRegistry / globalAgentJobRegistry）。 */
+declare const globalAgentObservability: AgentObservabilityRegistry;
+/**
+ * ① AgentObserver：把一个裸 Agent 的事件转发进观测注册表（路 B——不升格 AgentSession、不动执行语义、
+ * 保留转录隔离；observer 只读）。在 swarm-runtime / detached-run 的 `new Agent` 后调用；wiring 站点
+ * 应在 `await agent.run()` 的 finally 里调返回的 detach + `registry.markEnded(id)` 兜底收尾。
+ *
+ * @returns detach 函数：解订阅所有事件监听（不删观测，结束态由 status.change/abort/error + markEnded 处理）。
+ */
+declare function attachAgentObserver(agent: Agent, meta: AgentObservationMeta, registry?: AgentObservabilityRegistry): () => void;
+//#endregion
+//#region src/context-sources/environment.d.ts
+declare function createEnvironmentContextSource(workspaceDir: string): ContextSource;
+//#endregion
+//#region src/context-sources/memory-index.d.ts
+declare function createMemoryIndexContextSource(_workspaceDir: string, memory?: ContextBuildInput['memory']): ContextSource;
+//#endregion
+//#region src/context-sources/todo-reminder.d.ts
+/**
+ * todo-reminder（RFC-042）
+ *
+ * 病灶：`✓ done` 是回合生命周期标记，与 write_todos 的 todo 完成度零耦合——模型可在 todo 仍有
+ * pending/in_progress 时 end_turn，UI 却照显 done（见 RFC-042 根因 1/3）。
+ *
+ * 本钩子实现 todo 护栏：每次 buildContext 时，若当前会话 todoList 仍有未完成项，就把最新
+ * todo 状态作为 **volatile 尾段**（output.systemTail，落在 prompt cache 断点之后）注入一个
+ * `<system-reminder>`，让模型在下一次推理时"看见"未竟工作从而继续/纠偏。
+ *
+ * 关键约束（RFC-042 重要事项规则 1/3）：
+ *   - 只进 volatile systemTail，绝不进 stable 前缀——否则逐轮击穿 prompt cache（[[RFC-018]]）。
+ *   - 数据源 = session.metadata().config?.todoList（持久化真源，经稳定 Session 接口读取），
+ *     不耦合 CLI projState；故无 per-session 基线、无状态、无 cleanup（与 memory-delta 不同）。
+ *   - buildContext 每用户 prompt 只跑一次，故 reminder 在"即将停"的当轮无效——它靠续轮（M74-04）
+ *     触发的下一次 buildContext 生效，二者是耦合闭环（RFC-042 D1）。
+ */
+interface TodoReminderPort {
+  /**
+   * 取指定会话的 todo 快照（read-only）。返回 undefined / 空数组表示无 todo。
+   * 形态 = session.metadata().config?.todoList。
+   */
+  getTodoList(sessionId: string): ReadonlyArray<{
+    id?: string;
+    title?: string;
+    status?: string;
+  }> | undefined;
+}
+declare function createTodoReminderHooks(port: TodoReminderPort, priority?: 62): HookSpec[];
+//#endregion
+//#region src/context-sources/doc-sync-reminder.d.ts
+/**
+ * doc-sync-reminder（RFC-100）
+ *
+ * 病灶：write_todos（会话级 UI 状态）与外部持久化文档（如 RFC/TODO/milestone markdown）是两套
+ * 完全独立、不会自动互相同步的记账系统。模型在多阶段任务中容易把 write_todos 当"第一阶段的一次性
+ * 草稿本"用完即弃，转而只维护文档，导致 UI 常驻 todo 清单停留在早期快照，与仓库真实进度脱节
+ * （lesson_50 记录的真实复现案例）。
+ *
+ * 本钩子抄 todo-reminder.ts 同一模式（system-reminder 注入护栏），但检测的是"外部文档同步"而非
+ * "todo 内部完成度"——两者互补，不重叠：
+ *   - todo-reminder 检测「todoList 内部有 pending/in_progress 却想结束回合」
+ *   - doc-sync-reminder 检测「本回合写过被判定为需同步的文档，但没有调用 write_todos」
+ *
+ * 判定"什么算需要同步的文档变更"完全下放给调用方注入的 DocSyncPort（不硬编码任何本仓库专属的
+ * 文件名/内容模式到 runtime 通用层——对不使用这套约定的项目零污染，不注册这个 hook 即可）。
+ *
+ * 状态机：
+ *   tool.execute.after   → 累积"本轮是否触碰过需同步文档" + "本轮是否调用过 write_todos"
+ *   chat.message.before  → 新用户消息到达 = 新回合开始，重置累积状态
+ *   system.prompt.transform → 若"触碰过需同步文档"且"未调用 write_todos"，注入提醒
+ *   session.deleted       → 驱逐会话状态（同 memory-delta.ts 模式）
+ */
+interface DocSyncPort {
+  /**
+   * 判定一次工具调用是否构成"需要同步 write_todos 的文档变更"。
+   * 典型实现：检查 toolName 是否为 edit/write、args.path 是否匹配约定的文档命名模式（如
+   * `*-milestone.md`）、写入的新内容是否包含状态翻转标记（如 `Status: Done`）。
+   * 返回 true 即计入"本轮触碰过需同步文档"。
+   */
+  isDocSyncTrigger(input: ToolExecuteAfterInput): boolean;
+}
+declare function formatDocSyncReminder(toolName: string): string;
+declare function createDocSyncReminderHooks(port: DocSyncPort, priority?: 64): HookSpec[];
+//#endregion
+//#region src/context-sources/section-order.d.ts
+/**
+ * RFC-020 Phase 3（M54）P3-04：system-prompt 注入 section 的**唯一有序声明**。
+ *
+ * 治病灶——此前各 section 的 priority 数字（20/25/35/38/40/60）散在 coding hooks 与 runtime
+ * context-sources 两包里，"system prompt 各段什么顺序"得捞齐多处数字才能拼出。现收敛为此处一张表：
+ *   - 数组/字段顺序即 priority 升序 = 实际 `system.prompt.transform` hook 的执行/拼接顺序；
+ *   - `lane` 标明该段落 **stable 前缀**（systemPrompt，进 prompt cache）还是 **volatile 尾段**
+ *     （systemTail，落在 cache 断点之后，逐轮可变不击穿缓存）；
+ *   - runtime context-sources（environment/memory-index/memory-delta）与 coding hooks
+ *     （tool-guidance/lesson/skill-catalog）均从此处取 priority —— 单一真相源，改序只此一处。
+ *
+ * 放在 @x-otto/runtime（coding 依赖 runtime、反向不依赖）：coding 侧 hook 经 `@x-otto/runtime` import。
+ * 注：本表是**排序权威**（方案 H：section 仍由各自 hook 自注册，priority 数字降级为对本表的引用）；
+ * 不强行把 `SYSTEM_PROMPT_SECTIONS` 各 section 物理并入单一 registry（那超出外科尺度、非目标）——
+ * section 数量以该常量的字段数为准，不在本段注释里重复写死具体数字（history: 建表时 7 个，
+ * 后追加 docSyncReminder 成 8 个，写死数字会重犯本次发现的漂移）。
+ */
+type SystemPromptLane = 'stable' | 'volatile';
+interface SystemPromptSectionSpec {
+  /** 对应 hook / ContextSource 的 name/id（与注册名一致，供 drift guard 比对）。 */
+  readonly name: string;
+  readonly priority: number;
+  readonly lane: SystemPromptLane;
+}
+declare const SYSTEM_PROMPT_SECTIONS: {
+  readonly toolGuidance: {
+    readonly name: "tool-guidance-injection";
+    readonly priority: 20;
+    readonly lane: "stable";
+  };
+  /**
+   * RFC-318 D7：三分流判别（缺工具 / 流程重复 / 其余）。紧跟 toolGuidance——它是对
+   * "现有工具够不够用"的元判断，语义上属工具指引的延伸；内容恒定故走 stable lane。
+   */
+  readonly skillLoopGuidance: {
+    readonly name: "skill-loop-guidance-injection";
+    readonly priority: 21;
+    readonly lane: "stable";
+  };
+  readonly environment: {
+    readonly name: "runtime:environment";
+    readonly priority: 25;
+    readonly lane: "stable";
+  };
+  readonly memoryIndex: {
+    readonly name: "runtime:memory-index";
+    readonly priority: 35;
+    readonly lane: "stable";
+  };
+  readonly skillCatalog: {
+    readonly name: "skill-catalog-injection";
+    readonly priority: 38;
+    readonly lane: "stable";
+  };
+  readonly lesson: {
+    readonly name: "lesson-injection";
+    readonly priority: 40;
+    readonly lane: "stable";
+  };
+  readonly memoryDelta: {
+    readonly name: "memory-delta-injection";
+    readonly priority: 60;
+    readonly lane: "volatile";
+  };
+  readonly todoReminder: {
+    readonly name: "todo-reminder-injection";
+    readonly priority: 62;
+    readonly lane: "volatile";
+  };
+  readonly docSyncReminder: {
+    readonly name: "doc-sync-reminder-injection";
+    readonly priority: 64;
+    readonly lane: "volatile";
+  };
+};
+//#endregion
+//#region src/session-stable.d.ts
+interface SessionStableInjectionOptions {
+  name: string;
+  priority: number;
+  /** 首轮计算注入块；返回空/undefined 表示本会话无注入（也会被冻结，不再重算）。 */
+  compute: (input: SystemPromptTransformInput) => Promise<string | undefined> | string | undefined;
+}
+declare function createSessionStableInjectionHooks(options: SessionStableInjectionOptions): HookSpec[];
+//#endregion
+//#region src/session/derive-title.d.ts
+/**
+ * 从会话消息列表中派生标题（RFC-030 P1）。
+ *
+ * 回落链：meta.title → deriveSessionTitle(messages()) → id.slice(0, 8)
+ *
+ * 策略：
+ * - 找第一条 role==='user' 的真实消息（跳过 system/assistant/summary 标记消息）。
+ * - 跳过 compact_boundary 子类型的系统消息（summary 边界标记，不是用户输入）。
+ * - 文本归一：换行/多空格 → 单空格，trim，截 MAX_TITLE_LENGTH 字符。
+ * - 空则返回 undefined，由调用方继续回落到 id.slice(0, 8)。
+ */
+declare function deriveSessionTitle(messages: readonly AgentMessage[]): string | undefined;
+/**
+ * 统一标题回落链（RFC-078 D1/R5 单一真源）——三表面（service / 终端 / resume）共用。
+ *
+ * 回落：persistedTitle(meta.title，已是最高优先来源) → deriveSessionTitle(首条 user 消息) → id 前 8 位。
+ *
+ * 说明：`titleSource` 只在**写入**时决定覆盖（见 InMemorySession.setTitle 等级守卫），
+ * 故读取时 `meta.title` 必为当前最高优先值，本函数无需再分辨来源。
+ */
+declare function resolveSessionTitle(persistedTitle: string | undefined, messages: readonly AgentMessage[], id: string): string;
+//#endregion
+//#region src/session/hooks.d.ts
+interface ToolHookOptions {
+  hookRegistry: HookRegistry;
+  agentName: string;
+  sessionId: string;
+}
+declare function createToolHookExecutor(options: ToolHookOptions): ToolHookExecutor;
+//#endregion
+//#region src/session/persistence-sync.d.ts
+interface PersistenceSyncDeps {
+  persistence: SessionPersistence<AgentMessage>;
+  logger: Logger;
+  /** disk/remote 后端 = true（prompt 终态增量落盘）；in-memory 缺省 false。 */
+  autoPersist: boolean;
+  getSession: (id: string) => AgentSession | undefined;
+  hasSession: (id: string) => boolean;
+  listSessionIds: () => Iterable<string>;
+  /** 容量预检（含 idle 驱逐 + 满池 LRU 驱逐）。restore 单条不足时抛错。 */
+  canAccommodate: (id: string) => boolean;
+  /** 剩余容量（纯查询，无驱逐副作用）。restoreAll 用它截断入池数量，不挤掉在池会话。 */
+  capacityLeft: () => number;
+  /** restore 路径池登记：构建 AgentSession + 登记进池（不改 active；track 由本类负责）。 */
+  adoptRestoredSession: (raw: InMemorySession<AgentMessage>, config: ResolvedSessionConfig) => Promise<AgentSession>;
+  /** restoreAll 的 active 选举（恢复后无 active 时设为最近活跃者）。 */
+  setActiveIfNone: (id: string) => void;
+  /** 仅 restore/restoreAll 使用；未提供则两方法分别返回 null / 0。 */
+  /** restore 模板工厂。传持久化 agentName 以重解析子代理 prompt 身份（缺省=main）。 */
+  configProvider?: (agentName?: string, modelId?: string) => ResolvedSessionConfig;
+  /** save 时取会话当前解析后配置，抽取 per-session 子集入快照 metadata。 */
+  getConfig?: (id: string) => ResolvedSessionConfig | undefined;
+  /**
+   * RFC-178 触发器 C：驻留收紧系数源（可选——未提供时恒用全值 cap，行为与此前一致）。
+   * 由组装层（app-lifecycle）把 MemoryGovernor 分级信号写入其 setLevel。
+   */
+  residencyGovernor?: ResidencyGovernor;
+  /**
+   * RFC-323 M4：驻留预算运行时配置（settings.json 覆盖经此注入，缺省回退 env/常量）。
+   * 惰性 getter——app 层 ensureSettingsLoaded 后才有值，故每次读而非构造期快照。
+   */
+  getResidencyConfig?: () => _$_x_otto_session_contract0.ResidencyBudgetConfig | undefined;
+  /**
+   * RFC-108 D3：面板态独立持久化门店（可选——未提供时降级为不独立持久化，
+   * 面板态仅存在于内存，重启后丢失但不报错崩溃）。
+   */
+  panelStateStore?: PanelStateStore;
+  /**
+   * RFC-305 D3：trace↔DB 崩溃对账数据源（可选——未提供时对账整体跳过，restore 行为
+   * 与此前一致）。trace append-log 逐事件实时落盘（独立于 session DB 的 save 链），
+   * 崩溃时 trace 记录的 turn 覆盖领先于 DB——restore 时比对可检出"已发生未落库"缺口。
+   */
+  traceStore?: AppendLog<TraceEvent>;
+  /**
+   * RFC-305 M3：持久化后端 turn-flush 能力（缺省 'incremental'，由装配层透传
+   * persistence.turnFlush）。'snapshot' 后端（远端 PUT 整份快照/旧 blob 逃生口整份覆写）
+   * 对 turn 级落库节流，'incremental'（本地 relational 游标增量）每 turn 落库。
+   * 这是后端能力事实，不是用户配置——未来远端支持 append-tail 后改声明即可自动升级。
+   */
+  turnFlush?: 'incremental' | 'snapshot';
+}
+declare class PersistenceSync {
+  private readonly deps;
+  private readonly saveChains;
+  /**
+   * RFC-328 D4：崩溃缺口对账已提取为独立可替换单元（`CrashGapDetector`）。
+   * 本类保留**唯一发布 owner** 身份：detector 只缓存事实，事件/提示由 `consumeCrashGap()`
+   * 沿既有恢复通知链发出——恢复通知层不得绕过本类直接读 detector。
+   */
+  private readonly crashGapDetector;
+  /**
+   * RFC-328 D4：面板态恢复与遗留 metadata 迁移已提取为独立单元。
+   * 它只写 PanelStateStore 与内存 panel setter，不碰主快照/写租约。
+   */
+  private readonly panelStateRestorer;
+  /** RFC-305 M3：snapshot 后端 per-session turn 节流状态（仅 turnFlush='snapshot' 使用）。 */
+  private readonly turnSaveState;
+  /**
+   * 2026-07-14：per-session "此前是否处于写租约被拒态"标记——用于探测"denied→恢复可写"
+   * 的状态转换，据此 publish 对称的 session.write-lease-restored 事件（仅在真实发生
+   * 状态转换时发一次，不随每次成功 save 重复发）。会话销毁/驱逐时清理
+   * （forgetSession/flushPending），避免无限期残留。
+   */
+  private readonly leaseDeniedState;
+  /** RFC-178 D5：per-session 上次在线 cap 评估时的消息条数基准（在线间隔判定用）。 */
+  /**
+   * M1 远端权威：per-session 已知的服务端 revision。每次 CAS 成功后更新；
+   * 409 reload/rebase 后用最新 revision 重 PUT。本地后端不使用此字段。
+   */
+  private readonly remoteRevisions;
+  /**
+   * RFC-328 D3：驻留动作的输入收集、executor 消费与动作执行已提取为
+   * `ResidencyActionCoordinator`——它拥有在线评估基线、发布基线、压缩失败计数、
+   * 逃生阀节流基线这四个**只与驻留治理相关**的 per-session 状态机。
+   *
+   * 本类保留 `session.history-capped` 的**唯一发布 owner** 身份：coordinator 只返回
+   * 发布所需事实，事件由 `applyResidencyCaps` 沿既有出口发出。
+   */
+  private readonly residencyCoordinator;
+  constructor(deps: PersistenceSyncDeps);
+  /**
+   * RFC-178 三触发一执行器的**执行汇聚点**：条数 cap（触发器 A，含触发器 C 的压力收紧
+   * 系数）+ 字节 cap（触发器 B 硬段，同受 C 收紧）。所有裁剪只影响内存视图（DB
+   * append-forever），capped 时 publish `session.history-capped` 供前端提示。
+   * doSave 与在线评估（D5）共用本方法，保证两条触发路径行为一致。
+   */
+  private applyResidencyCaps;
+  /**
+   * RFC-321 D1-a′ 逃生阀执行体：请求一次强制压缩（fire-and-forget，不阻塞落盘）。
+   *
+   * **必须节流**：`activeOversized` 在活跃区持续超限期间会**每次 save/在线评估都为真**，
+   * 无节流将导致每次落盘都发起一次 LLM 摘要调用（成本与限流灾难）。节流语义与
+   * `capPublishBaseline` 同构——自上次请求以来消息数须再涨一个滞回增量才允许再请求；
+   * 压缩成功会使活跃区骤降，信号自然消失，故正常情况下每个"超限期"只请求一次。
+   *
+   * 失败不上抛：压缩失败（LLM 异常/无可压缩内容）只记日志，下一个增量窗口会再试；
+   * 裁剪结果与落盘均不受影响。
+   */
+  private requestEscapeValveCompaction;
+  /**
+   * RFC-178 D5（收编 RFC-147 E-2）：在线 cap 评估——消息条数自上次评估以来增长超过
+   * `CAP_INLINE_CHECK_INTERVAL` 时立即执行驻留裁剪，不等 doSave 节奏。挂在 turn.end
+   * 订阅（每 turn 一次 O(n) 计数，非每条消息），把"两次 save 之间无界增长"收敛到有界。
+   */
+  private maybeInlineCapEval;
+  /**
+   * autoPersist 时订阅 prompt 终态（prompt.end / error）与 session.cleared（clear 后增量落盘清空态）→ 增量落盘。
+   * fire-and-forget + 告警日志：落盘失败不阻塞会话主流程，stop() 的 saveAll 仍兜底。
+   * transient（orchestrator ephemeral 子会话）不订阅——避免写盘后又 removeSession
+   * 删、且被 restoreAll 当一等会话复活。
+   *
+   * RFC-305 D1（2026-07-31）：turn.end 每次入链落 entries 增量（doSaveEntries，无节流、
+   * 不含 panelState）——长循环 DB 崩溃窗口收窄到毫秒级，见常量头注释与 RFC-305 §3。
+   */
+  track(agentSession: AgentSession, transient: boolean): void;
+  flushPending(id: string): Promise<void>;
+  /**
+   * P2 缓解（独立 review 补充，2026-07-12）：会话可能经 idle 驱逐（`collectIdle`）或满池 LRU
+   * 驱逐（`evictLeastRecent`）消失，这两条路径不经过 `removeSession`/`flushPending`（前者是
+   * 同步批量收集不适合 await 落盘完成，后者已自行 fire-and-forget 触发 `saveSnapshot`）——
+   * 提供一个轻量同步纯清理方法，供这两条驱逐路径调用，与 `flushPending` 共享同一清理意图
+   * 但不附带"等待落盘完成"的语义（驱逐场景不需要，也不应阻塞驱逐循环）。
+   */
+  /**
+   * RFC-323 D4：计算用于预算分配的活跃会话数（排除 transient）。
+   *
+   * transient 会话（orchestrator ephemeral 子会话）不订阅 persistence track、
+   * 不被 applyResidencyCaps 管理，但存在于 sessions Map 中（listSessionIds 会返回）。
+   * 若计入 N 会摊薄正常会话的预算。故过滤 configs.get(id)?.transient === true。
+   */
+  private countActiveSessionsForAllocation;
+  /**
+   * RFC-325 M2：汇总所有活跃会话的总估算字节驻留——供 GlobalResidencyEngine 做压力计算。
+   * 只读 estimatedContentBytes 增量计数器（O(会话数)，不遍历消息）。
+   *
+   * 口径：**含被评估的目标会话本身**。pressure 是"全局已用/总预算"的比值，
+   * 目标会话的驻留同样占用全局预算，排除它会低估压力。与 countActiveSessionsForAllocation
+   * 一致地排除 transient（不订阅持久化、不参与预算分摊）。
+   */
+  private sumEstimatedContentBytes;
+  forgetSession(id: string): void;
+  /**
+   * RFC-352 D2：驱逐的最终 snapshot 仍在队列中时不能提前清 residency 状态。
+   * 若同 id 已被 restore/recreate，则新 session 已取得该 id 的状态所有权，旧驱逐完成
+   * 不得反向清掉它。
+   */
+  forgetEvictedSession(id: string): void;
+  save(id: string): Promise<void>;
+  /**
+   * RFC-336 D1：会话行预建——会话创建即落 `sessions` 一行（无 entries），不等首条消息。
+   *
+   * **要解决的问题**（实测复现，2026-08-10）：`repo.createSession()` 的唯一调用点是
+   * `RelationalSessionPersistence.save()`，而 save 由 `track()` 订阅的 `turn.end`/
+   * `prompt.end` 触发——两者都发生在**首个模型回合完成之后**。因此"用户已回车、模型还没
+   * 回任何东西"这段窗口（≈ 一次完整模型往返，数秒~数十秒）内进程若被强杀（SIGKILL/OOM/
+   * 断电），DB 里连 `sessions` 行都不存在 → 整个会话蒸发，`/resume` 完全看不到，
+   * 且 `detectCrashGap` 因 `load()` 返回 null 而根本不执行（RFC-305 D3 的盲区）。
+   *
+   * **为什么复用 doSaveEntries 而非直调 repo**（D1-b，RFC-159 D3）：写租约检查在
+   * `RelationalSessionPersistence.save()` 入口，是所有会话写路径的单一汇聚点。直调
+   * `repo.createSession()` 会开一条无租约的写路径先例。走这里则天然经 `enqueue` 串行链
+   * → `doSaveEntries` → `persistence.save()`，租约与写序语义全部继承，零新增写路径。
+   * 空 entries 快照在 save 内部即 `createSession()` + 零次 `appendEntry()`，正是所需语义。
+   *
+   * **幂等**：`createSession` 是 `ON CONFLICT DO NOTHING`；重复调用安全。
+   * **fire-and-forget**（规则 3）：失败只 warn，绝不阻塞会话创建——预建是可用性增强，
+   * 不是创建流程的正确性前提（失败时退化为改动前行为：首个 turn 后才落行）。
+   */
+  /**
+   * RFC-336 D2：输入边界落盘——prep 成功、模型往返开始**之前**把新增 entries 落库。
+   *
+   * 要解决的问题：落库此前只由 `turn.end`/`prompt.end` 触发（RFC-305 D1），两者都在首个
+   * 模型回合完成之后。M1 的会话行预建保证了"会话不蒸发"，但那条 user message 本身仍要
+   * 等首个 turn 才进 DB——强杀窗口 ≈ 一次完整模型往返（数秒~数十秒）。本方法把该窗口
+   * 压到"单条入链在途（毫秒级）"，与 RFC-305 对 turn 2+ 的保证对齐。
+   *
+   * **T336-8 后端能力分流**（与 `persistOnTurnEnd` 同源判据 `deps.turnFlush`）：
+   * - `'incremental'`（本地 relational SQLite，缺省）：游标增量 append，O(新增条数)，
+   *   WAL 单事务毫秒级 → 每次输入边界都落，拿满收益。
+   * - `'snapshot'`（远端 PUT / 旧 blob 逃生口）：每次落库都是**整份快照上传/覆写**，
+   *   随会话线性变贵。为一条 user message 付全量上传代价不划算，且远端本就有
+   *   30s/5turn 节流的既定策略（RFC-305 M3）→ **豁免**，维持 `prompt.end` 强制落库
+   *   兜底。这不是能力缺失，是后端能力边界下的正确取舍（RFC-336 §D2 约束）。
+   *
+   * fire-and-forget（规则 3）+ 复用 `enqueue` 串行链（规则 2/9）：与预建、turn 落盘、
+   * prompt 终态落盘共用同一条 per-session 链，天然串行、写租约语义一致。
+   */
+  requestInputBoundaryFlush(agentSession: AgentSession, transient: boolean): void;
+  precreateSessionRow(agentSession: AgentSession, transient: boolean): void;
+  /**
+   * 驱逐路径专用：用调用方**同步捕获**的快照入链落盘。
+   * 会话即将出池，doSave 经 getSession 会扑空；同链串行保证不被在途旧写覆盖。
+   *
+   * 终局 review 复核（2026-07-21）：曾怀疑"若同一会话有更早入链、尚未完成的 doSave job，
+   * 本方法用调用方在驱逐时刻捕获的（可能更旧的）metadata 覆盖 doSave 写入的更新值"——
+   * 追踪 enqueue() 的调用序保证后确认**不成立**，理由：
+   * ① 调用方（session-manager 的 collectIdle/evictLeastRecent）捕获快照与紧随其后的
+   *    `agentSession.dispose()` 之间没有任何 await/yield 点，JS 单线程保证这段同步区间
+   *    会话状态不可能再变化——本方法拿到的 snapshot 是驱逐那一刻真正最新的状态；
+   * ② `enqueue()` 严格按调用顺序串行执行同一 session 的 job 链——若有更早的 doSave job
+   *    仍在途（尚未执行到位），它必然排在本方法的 job **之前**执行，不可能反过来；
+   * ③ `dispose()` 会 unsub 掉 `prompt.end`/`turn.end` 订阅，故此后不会再有新 doSave 入链；
+   * ④ 即便某个更早的 doSave job 直到 dispose 之后才真正开始执行，届时 `getSession(id)`
+   *    已因会话被 `sessions.delete(id)` 而扑空，`doSave` 提前 return（no-op），不写入
+   *    任何数据——不存在"新值被旧值覆盖"的路径。
+   * 结论：本方法在当前单进程同步模型下天然是该会话 job 链的最后一环，写入的是最新状态，
+   * 无需额外的新鲜度校验。跨进程并发写由写租约（RFC-159 D3）独立兜底，与本方法无关。
+   */
+  saveSnapshot(id: string, snapshot: Omit<SessionSnapshot<AgentMessage>, 'version' | 'id'>, onSettled?: () => void): Promise<void>;
+  /**
+   * 合并快照 metadata.config——外部解析配置（getConfig→pickPersistableConfig）
+   * 与快照内已有的 inputHistory 叠加。两条落盘路径（saveSnapshot/doSave）共用，
+   * 避免合并逻辑 split-brain。无任何来源时原样返回 metadata。
+   *
+   * RFC-108 D3：todoList/editedFiles/subagents/drafts 四个面板字段已从 metadata.config
+   * 分离至 PanelStateStore，不再在此合并——落盘时由 doSave/saveSnapshot 额外调用
+   * panelStateStore.saveAll() 独立持久化。
+   *
+   * inputHistory（@deprecated RFC-088 M4b）保留现有迁移路径不变。
+   */
+  private mergeSnapshotConfig;
+  private enqueue;
+  /**
+   * RFC-305 D2：entries 档——residency cap 评估 + 快照增量 append（游标式，O(新消息)）。
+   * turn.end 高频路径走此档；panelState（每次全量重写 5 个存储）不在其中，避免每 turn
+   * 纯写放大。residency cap 保留在两档共同前缀（RFC-178 D5 在线评估语义不变）。
+   */
+  private doSaveEntries;
+  /** M1：duck-type 检测远端 CAS 能力——避免硬 import RemoteSessionPersistence（保持 runtime 不反向依赖 session 具体类）。 */
+  private isRemoteCasPersistence;
+  /**
+   * M1 远端权威写入：CAS + 409 自动 reload/rebase/单次重试。
+   *
+   * 策略：
+   * 1. 首次 PUT 带本进程已知的 `expectedRevision`（首次写入时 undefined = 无条件建）。
+   * 2. 409 冲突 → 从服务端 load 最新快照 + revision。
+   * 3. rebase：以服务端 entries 为基线，追加本进程内存中比基线更新的 entry（按 entry_id 去重）。
+   * 4. 用新 revision 重 PUT 一次。再失败则抛出（不递归重试，防死循环）。
+   *
+   * rebase 语义对齐本地 append-only 模型：不删除服务端已有 entry，只追加本进程的新尾。
+   * 这与 RelationalSessionPersistence 的"cursor 增量 append"同构——区别仅在远端是整份
+   * PUT 而非 per-entry INSERT，所以 rebase 后仍需整份上传（直到远端支持 append-tail API）。
+   */
+  private saveRemoteWithCas;
+  /**
+   * M1 rebase：把本地新尾追加到服务端快照之后。
+   *
+   * 按 entry_id 去重——服务端已有的 entry 保留，本地比服务端新的 entry 追加到尾部。
+   * 不删除任何服务端 entry（append-only 红线在远端同样适用）。
+   * metadata 取本地版本（本地有最新的 lastActiveAt/config 等可变字段）。
+   */
+  private rebaseSnapshotAgainstRemote;
+  /** RFC-305 D2：完整档 = entries + panelState。prompt 终态/clear/驱逐/saveAll 走此档。 */
+  private doSave;
+  saveAll(): Promise<void>;
+  /**
+   * 从持久化存储恢复单个 session。
+   * 若未提供 configProvider 则返回 null。
+   */
+  restore(id: string): Promise<AgentSession | null>;
+  /**
+   * RFC-305 D3：restore 时 trace↔DB 对账——检出"上次进程异常终止时已发生但未落库"的
+   * turn 缺口并告警。对账基准 = trace append-log（逐事件实时落盘，独立于 save 链）：
+   * DB 最后一条已持久化 entry 时间戳之后，trace 仍有 `turn.end` lifecycle 事件 →
+   * 这些 turn 的消息只进过内存、从未进 DB，已随崩溃永久丢失。
+   *
+   * 用时间戳而非 turn 号对账：trace 的 turn 字段 per-prompt 从 0 重置，跨 prompt 不可比；
+   * ts 与 entry.timestamp 同源（Date.now 系时钟），单机单调可比。
+   *
+   * 容忍度：正常退出路径（prompt.end 立即落盘 + turn 级入链）下 trace turn.end 与 DB
+   * 落库几乎同时，容忍 CRASH_GAP_TOLERANCE_MS 内的尾差（在途写 + 时钟粒度），超出才告警。
+   *
+   * fail-soft：traceStore 缺失/读取异常/无 turn.end 事件 → 静默跳过（debug 日志），
+   * 绝不阻塞 restore、绝不产生假告警。
+   */
+  /**
+   * RFC-305 D3：对账结果查询口——restore/restoreAll 内部把本次恢复检出的崩溃缺口记入
+   * per-session 缓存，调用方（CLI resume 路径）在订阅建立后读取并 toast。缓存随
+   * forgetSession 清理，避免陈旧告警在后续 restore 重复弹出。
+   */
+  consumeCrashGap(id: string): {
+    lostTurns: number;
+  } | undefined;
+  /**
+   * 从持久化存储批量恢复 session：最近活跃优先，最多填到剩余容量。
+   * 装不下的更旧快照留在盘上（restore(id) 可按需复活），不挤掉在池会话。
+   * 若未提供 configProvider 则直接返回 0。
+   */
+  restoreAll(): Promise<number>;
+}
+//#endregion
+//#region src/session/residency-allocator.d.ts
+/**
+ * RFC-323 D3：两层叠加——分配层 × 压力档缩放。
+ *
+ * 分配层解决"并发数不确定"（结构性、确定性）；
+ * 压力层解决"真实内存压力超预期"（反应式、RFC-178 触发器 C 保留）。
+ *
+ * 两者相乘：`allocateResidencyBudget(N) ÷ 压力档除数(1/2/4)`。
+ * 下界 clamp(MIN ÷ 除数, 1) 防止极端收紧塌到 0。
+ */
+declare function effectiveResidencyBudget(activeSessionCount: number, pressureDivisor: number, config?: ResidencyBudgetConfig): number;
+//#endregion
+//#region src/session/global-residency-engine.d.ts
+/** 引擎运行的快照——调用方提供，引擎不持有状态（RN 严格）。 */
+interface EngineSnapshot {
+  /** 当前活跃会话数（estimatedBytes > 0 的非 transient 会话）。 */
+  activeSessionCount: number;
+  /** 当前所有会话的总估算字节驻留（来自 InMemorySession.estimatedContentBytes 的汇总）。 */
+  currentTotalResidentBytes: number;
+  /** 压力档除数（来自 ResidencyGovernor，healthy=1 / warning=2 / critical=4）。 */
+  pressureDivisor: number;
+  /** 运行时注入的 residency 配置覆盖。 */
+  config?: ResidencyBudgetConfig;
+}
+/** 引擎产出的治理决策（所有字段确定性）。 */
+interface ResidencyDecision {
+  /** 单会话当前有效字节预算（已/处分配层 × 压力档）。 */
+  maxBytesPerSession: number;
+  /** 当前全局驻留压力比例（0.0 ~ 1.0）。 */
+  globalPressure: number;
+  /** 是否处于全局超限压力（高压力下才需要紧急治理）。 */
+  isGlobalPressure: boolean;
+}
+/**
+ * 计算“每个会话当前 应该  byte budget — 给定 snapshot，治理一个值。
+ *
+ * 特性:
+ * - 负反馈：currentTotalResidentBytes 越大 pressure 越高 → 每个会话预算*越低*。
+ * - 下界 MIN_PER_SESSION：防止分配结果不可用作 （如果 N 极大, SESSION_MAX=50×16=800MB < totalBudget).
+ * - 上界 MAX_PER_SESSION：模型折叠输入的最大（imageasher, window by compression）约为 214MB/会话。
+ * - 确定性：相同 snapshot → 相同 decision（R4，皱纹是稳定 的。
+ */
+declare function decide(snapshot: EngineSnapshot): ResidencyDecision;
+//#endregion
+export { type AgentJobListener, AgentJobRegistry, type AgentJobRegistryOptions, type AgentJobStatus, type AgentObsStatus, type AgentObservabilityOptions, AgentObservabilityRegistry, type AgentObservation, type AgentObservationMeta, type AgentObservationSnapshot, type AgentRuntime, AgentSession, type AgentSessionEvent, type AgentSessionEventMap, type AgentSessionEventType, type AgentSessionInfo, type AgentSessionJob, type AgentSessionOptions, type AgentSessionSubscriber, type ApplyDiffResult, type ApplyPolicy, type ApplySignals, type ArchiveRecallPort, type AskUserQuestion, type AutonomyLevel, type BackgroundProcess, type BackgroundProcessStatus, CAPABILITY_SURFACE_PATTERNS, type Checkpoint, type CheckpointData, type ContextBuildInput, type ContextInjectionPort, type ContextSource, ContextSourceRegistry, DEFAULT_MAX_AUTO_APPLY_LINES, type DiskSessionPoolOptions, type DocSyncPort, type EngineStoreLocation, type EngineStoreOverrides, type ExitResult, FORBIDDEN_ZONE_PATTERNS, type FileEntrySnapshot, type FileSnapshot, FleetMonitor, type FleetMonitorOptions, type FleetSample, type GrillAnswer, type GrillQuestion, type GrillRequest, type KillOptions, LEVEL_DIVISOR, type ManagedProcess, type MemoryDeltaPort, MemoryGovernor, type MemoryGovernorOptions, type MemoryPort, type MemoryPressureLevel, type MemorySample, type MemorySubsystem, PanelStateStore, PersistenceSync, type PersistenceSyncDeps, type ProcessCategory, type ProcessFilter, type ProcessLifecycle, type ProcessListener, type ProcessOwner, ProcessRegistry, type ProcessRegistryOptions, ProcessRuntime, type ProcessRuntimeOptions, type ProcessSpawnConfig, type ProcessStatus, type PromptOptions, type PromptRefresh, RUNTIME_DEFAULTS, type RegisterAgentJobInput, type RegisterInput, type RemoteSessionPoolOptions, type ReplayLevel, type ResidencyDiagnostics, ResidencyGovernor, type ResidencyPressureLevel, type ResolvedSessionConfig, type RestoreMode, type RuntimeOptions, SYSTEM_PROMPT_SECTIONS, type SandboxRunner, type SandboxToolCall, type SandboxToolResult, SandboxUnavailableError, SessionPool, type SessionPoolOptions, type SessionPorts, type SessionStableInjectionOptions, type SessionStorageConfig, type SystemPromptSectionSpec, TimeTravelController, type TimeTravelDeps, type TodoReminderPort, type TracebackView, type TurnRecord, type Verdict, type Worktree, applyDiff, applyMemoryTransform, attachAgentObserver, buildEngineStores, captureFiles, createAgentRuntime, createDefaultContextSourceRegistry, createDiskSessionPool, createDocSyncReminderHooks, createEnvironmentContextSource, createInMemorySessionPool, createMemoryDeltaHooks, createMemoryIndexContextSource, createRemoteSessionPool, createSessionStableInjectionHooks, createTodoReminderHooks, createToolHookExecutor, createWorktree, decideApply, decide as decideResidency, defaultMaxToolTurnExtensions, deriveSessionTitle, diffTouchedPaths, effectiveResidencyBudget, formatDocSyncReminder, globalAgentJobRegistry, globalAgentObservability, globalProcessRegistry, globalProcessRuntime, hasRepoDrifted, installAgentJobReaper, installExitReaper, installProcessReaper, messagesFromSnapshot, pruneOrphanWorktrees, reconstructMessages, removeWorktree, resolveSessionTitle, resolveTodoContinuationConfig, restoreFiles, revertDiff, touchesCapabilitySurface, touchesForbiddenZone, worktreeDiff };
+//# sourceMappingURL=index.d.ts.map