@tencent-ai/agent-harness 0.2.0-beta.1 → 0.2.0-beta.2

package/cli/dist-server/types/workspace/cbc-core/lib/node/session/interruption-service.d.ts

@@ -8,12 +8,44 @@ import { InterruptionService, type PendingApprovalView, Session, SessionHookMana
 import { SessionRunStateMachine } from './session-run-state-machine-protocol.js';
 type IIdleQueueDrainService = import('./session-protocol.js').IdleQueueDrainService;
 export declare class InterruptionServiceImpl implements InterruptionService {
+    private readonly resolvedSandboxItems;
     private pendingInterruptions;
     private itemToSessionMap;
     private interruptionQueues;
     private parentIdToMainSession;
     private childToMainSession;
     private waitForSubscriptions;
+    private readonly approvalSources;
+    private readonly handlingStates;
+    private readonly reportedStaleStates;
+    private readonly reportedDiscardedApprovals;
+    private readonly handledResults;
+    private readonly resumeProgress;
+    /**
+     * Terminal by design: a blocked continuation already proved it cannot make
+     * progress, and a later user request arrives on a *new* RunState, so the
+     * session is never stranded.
+     */
+    private readonly blockedResumeStates;
+    /**
+     * Deliberately not `session.meta.consecutiveEmptyDrainCount`: the idle
+     * empty-drain guard both increments that counter (tripping this
+     * continuation early, aborting a legitimate resume) and resets it
+     * (stretching the budget without bound).
+     */
+    private readonly resumeNoProgressCount;
+    private assertApprovalSource;
+    private approveSource;
+    private awaitPermissionReply;
+    /**
+     * A decision the user actually clicked must never disappear without a word.
+     *
+     * The card is dequeued and the deferred rejected, but the run that owned it
+     * is already gone — so nothing downstream surfaces the rejection and the
+     * user is left believing the tool was approved.
+     */
+    private reportDiscardedDecision;
+    private reportStaleSource;
     /**
      * 权限审批全局真相源（方案一：统一数据源）。
      *
@@ -61,6 +93,8 @@ export declare class InterruptionServiceImpl implements InterruptionService {
     protected readonly idleQueueDrainService?: IIdleQueueDrainService;
     protected readonly traceCollector?: SessionInterruptionTraceHost;
     protected get startupProfiler(): SessionInterruptionProfilerHost;
+    /** Claim before calling out: sandbox callbacks can throw or synchronously re-enter. */
+    private takeSandboxResolve;
     approve(item: RunToolApprovalItem, options?: {
         alwaysApprove?: boolean;
         scope?: 'session' | 'localSettings';
@@ -101,8 +135,9 @@ export declare class InterruptionServiceImpl implements InterruptionService {
      *
      * 幂等：未注册的 sessionId 为 no-op。
      */
-    releaseSession(sessionId: string): void;
-    protected handleInterruptions(session: Session, interruptions: RunToolApprovalItem[]): Promise<void>;
+    releaseSession(target: string | Session): void;
+    protected handleInterruptions(session: Session, interruptions: RunToolApprovalItem[], result?: RunResult<any, any> | StreamedRunResult<any, any> | undefined): Promise<void>;
+    private processInterruptions;
     protected executePendingManualPostCompactHook(session: Session, result: RunResult<any, any> | StreamedRunResult<any, any>): Promise<void>;
     waitFor(session: Session): Promise<void>;
     /**
@@ -334,15 +369,26 @@ export declare class InterruptionServiceImpl implements InterruptionService {
     private static sanitizeToolNotFoundMessage;
     private hasRecentModelErrorRetry;
     /**
-     * 检测是否已有 stream timeout 重试记录
-     * 避免反复重试导致无限循环
+     * 网络 / 流错误自动恢复的统一前置步骤：认领额度 → 可取消的指数退避 → 标记恢复轮。
+     *
+     * 认领放在退避之前、且晚于本 catch 里的第一个 await：session-manager 的 gate 在
+     * `result.completed` reject 后同步读取同一份预算判据，认领若早于 gate 读取，最后
+     * 一次重试会被 gate 误判为「预算已耗尽」而提前下发终态。
+     *
+     * 退避期间会话处于 RETRYING：失败的 run 与写入中断结果的 skipRun run 都已收尾回 idle，
+     * 这里重新置为 busy，TUI 继续显示进行中并响应 Esc，用户新消息进队列而不是直接起 run。
+     * 恢复 run 带 bypassMessageQueue 从 RETRYING 直接发起，中间不回 idle，不留让新 run
+     * 插入的空窗；恢复 run 收尾（AGENT_ENDED）时回 idle 并带出排队消息。
+     *
+     * 退避期间用户取消时退回额度、以 RUN_FAILED 收回 idle 并返回 `cancelled`，调用方不得
+     * 再发起。取消信号在等待前现取：写入中断结果的 skipRun run 会替换 `session.abortController`，
+     * 用户此后按下的 Stop 作用在新 controller 上；排队消息接管 owner 时，其 abort 会级联到这里。
      *
-     * 首 token 超时：允许最多 2 次重试（含线性延迟 2s/4s），给网络波动更多恢复机会
-     * 流数据超时：保持只重试 1 次
-     * 旧的基于历史消息窗口的检测不可靠：长任务（如 8 个子任务）会产生大量消息，
-     * 将 retry marker 推出 5 条消息的窗口，导致误判为"可以再次重试"
+     * 等待结束时若状态既不是 RETRYING 也不是 idle，说明 RETRYING 被迟到的收尾事件冲掉后
+     * 已有新 run 被接纳并在执行，返回 `superseded`，否则恢复 run 会与它同时写同一个会话。
+     * 此时不退回额度——新请求边界已经清零，再减一次会扣掉新链的额度。
      */
-    private incrementStreamTimeoutRetryCount;
+    private prepareRecoveryAttempt;
     /**
      * CLI TUI 手打 `/compact` 裸跑成功后补发 SessionStart('compact')。
      *

package/cli/dist-server/types/workspace/cbc-core/lib/node/session/model-response-interceptors.d.ts

@@ -29,6 +29,24 @@ export declare class finishReasonErrorInterceptor implements ModelResponseInterc
     protected readonly sessionStore: SessionStore;
     protected readonly telemetryService: TelemetryService;
     intercept(ctx: ModelResponseInterceptorContext): Promise<boolean | void>;
+    /**
+     * 处理「已经产出实质内容之后才 `finish_reason=error`」：自动续写，最多 3 次、1s 起步 2 倍退避。
+     *
+     * 没有任何实质输出就 error 的两种形态（仅 reasoning / 零 token）在模型层被转成可重试的
+     * EmptyStreamError，走 interruption-service 的流错误恢复；三者认领同一份 error 预算。
+     *
+     * 能走到这里说明这次 run 已经结束：SDK 只要本轮还有可执行的工具调用就会继续循环，
+     * 不会把控制权交回。因此不存在「参数完整但尚未执行」的工具调用；万一出现，每次构造
+     * 请求前的 `fillFunctionCallResultHistory` 也会补齐配对，不会因孤儿调用触发上游 400。
+     * 本期只统计孤儿数量用于验证这一推论，不改补齐逻辑。
+     *
+     * 预算用尽、退避期间被取消或发起失败时都**不返回 `true`**：没有重跑在路上，本轮必须
+     * 正常收敛给上层，否则 CLI 会一直等一个不存在的 run。
+     */
+    private handleErrorFinishReason;
+    private writeErrorTerminalMessage;
+    /** 统计本轮以 error 收尾时残留的无配对结果工具调用，用于验证「此处不应有孤儿」的推论。 */
+    private logOrphanToolCallsOnError;
     private shouldSkipExpectedSubagentToolCalls;
     /**
      * 处理 length 类型的完成原因：从断点续写（#119765）。

package/cli/dist-server/types/workspace/cbc-core/lib/node/session/recovery-budget.d.ts

@@ -0,0 +1,55 @@
+import type { Session } from './session-protocol.js';
+/**
+ * `finish_reason=error` 三种表现（已有输出 / 仅 reasoning / 零 token）共用的预算键。
+ *
+ * 三者是同一次上游故障的不同形态，而且会在恢复过程中互相转化（第一次零 token、
+ * 重试后只吐 reasoning、再重试吐了内容后又 error）。各记各的会让一次故障的总轮数
+ * 远超约定上限，所以必须认领同一个键。
+ */
+export declare const ERROR_RECOVERY_COUNT_META_KEY = "errorRecoveryCount";
+/**
+ * 流开始之后的网络错误（错误仍带原始 errno）使用的预算键。
+ *
+ * 响应头之前的连接失败由模型层连接级重试处理，耗尽后被归一化成 HTTP 502 上抛，
+ * 不会再走到这里——两层不会为同一次失败接力。
+ */
+export declare const NETWORK_RECOVERY_COUNT_META_KEY = "networkErrorRetryCount";
+/**
+ * `finish_reason=error` 后注入给模型的续写提示。
+ *
+ * 与截断续写（TRUNCATION_CONTINUATION_PROMPT）的区别是刻意去掉了「把剩下的工作拆小」：
+ * 那句是在修「一次输出太长」的因果，上游内部错误与输出长度无关，带上它既是错误归因，
+ * 也可能让模型把任务切碎、多烧轮次。同样不告诉模型「是服务端出错」——那会给它道歉和
+ * 复述的由头，与 no apology / no recap 自相矛盾。
+ */
+export declare const ERROR_RECOVERY_PROMPT: string;
+/**
+ * 包成 error-recovery system-reminder：stream-json 等输出通道会把只含 system-reminder
+ * 的内部用户消息清空丢弃，避免恢复提示混进用户可见的对话。
+ */
+export declare function buildErrorRecoveryReminder(): string;
+export declare function readRecoveryBudgetCount(session: Session, key: string): number;
+export declare function hasExhaustedRecoveryBudget(session: Session, key: string, limit?: number): boolean;
+/**
+ * 同步完成「判定 + 认领」，返回本次恢复的序号（1-based）；预算已用尽返回 `undefined`。
+ *
+ * 判定与消耗必须在同一个同步段里完成：分散到 `await` 两侧时，两处调用可能同时在
+ * `count = limit - 1` 通过检查，上限就不再成立。
+ */
+export declare function claimRecoveryBudget(session: Session, key: string, limit?: number): number | undefined;
+/** 认领后没有真正发起恢复（退避期间被取消、发起失败）时退回额度。 */
+export declare function releaseRecoveryBudget(session: Session, key: string): void;
+/** 清零并返回旧值，供日志使用。 */
+export declare function resetRecoveryBudget(session: Session, key: string): number;
+/**
+ * 「下一个模型请求是自动恢复轮」的一次性标记。
+ *
+ * 恢复轮的首 token 时限比首次请求短（见模型层）。这个标记在发起恢复 run 前由恢复
+ * 入口显式写入，由模型层在该 run 的第一个模型请求上读取并清除——之后同一 run 的工具
+ * 循环请求回到普通时限。不能改用重试计数反推「是否恢复轮」：计数跨多个模型请求累计，
+ * 反推会让恢复链之后的所有请求都被当成恢复轮。
+ */
+export declare const RECOVERY_REQUEST_PENDING_META_KEY = "recoveryRequestPending";
+export declare function markRecoveryRequestPending(session: Session): void;
+export declare function consumeRecoveryRequestPending(session: Session | undefined): boolean;
+export declare function clearRecoveryRequestPending(session: Session): void;

package/cli/dist-server/types/workspace/cbc-core/lib/node/session/session-hook-manager.d.ts

@@ -208,4 +208,19 @@ export declare class SessionHookManagerImpl implements SessionHookManager {
      * Does NOT support continueRequest.
      */
     executeFinalStopHooks(session: Session, reason?: FinalStopReason): Promise<void>;
+    /**
+     * UserPromptExpansion — Claude Code 官方事件：任何用户输入的命令/skill 展开成
+     * prompt、送进模型之前统一从这里触发，可阻断展开。`command_args` / `prompt` 按
+     * 官方 schema 是必填字段（无参数时发空串，而不是整个省略 key）。
+     */
+    executeUserPromptExpansionHooks(session: Session, payload: {
+        expansionType: 'slash_command' | 'mcp_prompt' | string;
+        commandName: string;
+        commandArgs: string;
+        commandSource?: string;
+        prompt: string;
+    }): Promise<{
+        allowed: boolean;
+        message?: string;
+    }>;
 }

package/cli/dist-server/types/workspace/cbc-core/lib/node/session/session-manager.d.ts

@@ -33,6 +33,15 @@ export declare class SessionManagerImpl implements SessionManager, ApplicationLi
     private sessionStartTimes;
     private addHistoryLocks;
     private resultSubscriptions;
+    private readonly resultSubscriptionOwners;
+    /**
+     * 每个 sessionId 当前活着的会话对象。身份守卫不能只认 result 订阅的登记：
+     * 订阅由调用方事后 `initRunResultHandler` 挂上（teammate / agent-task），而
+     * drain / team-inbox / turn-metrics 在 create 时就按 id 注册了，中间那段
+     * 「已注册、无订阅」的窗口里 owner 读不到，旧任务的延迟释放会摘掉同 id 后继
+     * 会话的注册。WeakRef：登记不得延长会话寿命，deref 为空即无需保护的对象。
+     */
+    private readonly liveSessionsById;
     private overridePermissionModes;
     private overrideModels;
     /**
@@ -177,7 +186,7 @@ export declare class SessionManagerImpl implements SessionManager, ApplicationLi
      *
      * 幂等：未注册的 id 为 no-op；DI 容错：精简变体缺 service 时降级跳过。
      */
-    releaseInMemory(id: string): void;
+    releaseInMemory(target: string | Session): void;
     rename(session: Session, name: string): Promise<void>;
     setOverridePermissionMode(sessionId: string, mode: PermissionMode): void;
     getOverridePermissionMode(sessionId: string): PermissionMode | undefined;

package/cli/dist-server/types/workspace/cbc-core/lib/node/session/session-persistence-error.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Typed local-transcript I/O failure (issue #119545).
+ *
+ * The only reason this type exists: `addHistory` must be able to tell "the
+ * local JSONL copy could not be written" apart from "this turn is broken".
+ * Windows `EBUSY` on the transcript is a third-party sharing violation, and a
+ * side-channel copy must never terminate a turn that is still executing tools.
+ *
+ * Everything else about persistence stays best-effort on purpose: there is no
+ * pending queue, no cross-process outbox and no durability barrier, so nothing
+ * else in the runtime waits on, or can be vetoed by, this file.
+ */
+export type SessionPersistencePhase = 'open' | 'stat' | 'write' | 'close' | 'rollback';
+export type SessionPersistenceRollbackOutcome = 'not-needed' | 'succeeded' | 'failed';
+export interface SessionPersistenceErrorOptions {
+    phase: SessionPersistencePhase;
+    cause: unknown;
+    attempt?: number;
+    rollbackOutcome?: SessionPersistenceRollbackOutcome;
+    retryable?: boolean;
+}
+/**
+ * Windows sharing violations and their POSIX lookalikes. `EBUSY` is the one
+ * this ticket measured (25% of appends within 10ms of the previous write);
+ * `EPERM` / `EACCES` ride along because the same scanners produce them.
+ */
+export declare function isRetryableSessionPersistenceError(error: unknown): boolean;
+export declare class SessionPersistenceError extends Error {
+    readonly phase: SessionPersistencePhase;
+    readonly code?: string;
+    readonly attempt: number;
+    readonly rollbackOutcome: SessionPersistenceRollbackOutcome;
+    readonly retryable: boolean;
+    constructor(options: SessionPersistenceErrorOptions);
+}
+/**
+ * Duck-typed on purpose: core and the host package can each hold their own copy
+ * of this class, so `instanceof` is not reliable across the package boundary.
+ * The required fields keep a foreign error named `SessionPersistenceError` from
+ * being mistaken for one of ours — an unrecognized error still fails the run,
+ * which is the safe direction.
+ */
+export declare function isSessionPersistenceError(error: unknown): error is SessionPersistenceError;

package/cli/dist-server/types/workspace/cbc-core/lib/node/session/session-protocol.d.ts

@@ -89,6 +89,7 @@ export type AgentPhase = 'preparing' | 'model_requesting' | 'model_streaming' |
 export interface AgentPhaseInfo {
     phase: AgentPhase;
     toolName?: string;
+    toolCallId?: string;
     streamingToolName?: string;
     startedAt: number;
     /**
@@ -177,6 +178,8 @@ export interface PreToolUseHookResult {
     permissionDecision?: 'allow' | 'deny' | 'ask';
     permissionDecisionReason?: string;
     runtimeSecurity?: Record<string, unknown>;
+    /** PreToolUse `continue:false` — stop the current turn after the deny result is recorded. */
+    preventContinuation?: boolean;
 }
 export interface Session {
     id: string;
@@ -206,6 +209,8 @@ export interface Session {
      */
     replSandboxDepth?: number;
     state?: RunState<any, any>;
+    /** Emitted after a physical run releases its lifecycle owner and abort links. */
+    runSettledSubject?: Subject<void>;
     createdAt: number;
     updatedAt: number;
     meta?: Record<string, any>;
@@ -638,6 +643,12 @@ export interface Session {
          * Context from UserPromptSubmit hook to be injected into current user message
          */
         userPromptSubmitContext?: string;
+        /**
+         * Context from UserPromptExpansion hook (hookSpecificOutput.additionalContext),
+         * to be injected alongside the expanded prompt (Claude Code parity: same
+         * injection point as UserPromptSubmit — "alongside the submitted prompt").
+         */
+        userPromptExpansionContext?: string;
         /**
          * Context from PostToolUse hook to be injected after tool execution
          */
@@ -915,6 +926,8 @@ export interface SessionOptions {
     debugToStderr?: boolean;
     verbose?: boolean;
     print?: boolean;
+    /** Host Bash output preference; omitted preserves the CLI's PTY selection. */
+    usePty?: boolean;
     outputFormat?: 'text' | 'json' | 'stream-json';
     inputFormat?: 'text' | 'stream-json';
     /** Whether to persist the session transcript. Defaults to true; false keeps history in memory only. */
@@ -1123,9 +1136,11 @@ export interface SessionManager {
      *
      * 幂等：未注册的 sessionId 为 no-op。
      *
-     * @param id 已完成 subagent 的 session id
+     * @param target 传 Session 对象时，索引键与身份校验同源——只有注册表当前持有
+     * 的正是这个对象才释放，复用同一 sessionId 的后继对象不会被误清。只拿得到
+     * id 的调用方（RPC、`remove(id)`）传字符串，此时不做身份校验。
      */
-    releaseInMemory(id: string): void;
+    releaseInMemory(target: string | Session): void;
     /**
      * 该 sessionId 是否已在本进程通过 get() 加载过（且尚未 remove()/releaseInMemory()）。
      *
@@ -1216,8 +1231,31 @@ export interface SessionManager {
      */
     flushHistory(session: Session): Promise<void>;
 }
+/**
+ * Cumulative transcript persistence counters (issue #119545 埋点建议).
+ * A best-effort side channel, so every reader must treat the numbers as a
+ * snapshot that may be sampled at any moment.
+ */
+export interface TranscriptPersistenceMetrics {
+    /** In-band retry attempts consumed. */
+    retries: number;
+    /** Batches that only landed because of a retry. */
+    retrySucceeded: number;
+    /** Batches given up on after the retry budget. */
+    abandonedBatches: number;
+    /** Lines lost with those batches. */
+    abandonedLines: number;
+}
 export interface SessionStore {
     getSessionFilePath(id: string, parentSessionId?: string, cwd?: string): string;
+    /**
+     * Transcript persistence counters, when the implementation keeps any.
+     * Optional so in-memory and host-delegating stores do not have to fake it.
+     * Exposed so callers that observe a degradation can log the counters from
+     * their own call site: the store's own abandon audit line is best-effort
+     * and a lost line would otherwise take the only copy of the numbers.
+     */
+    transcriptPersistenceMetrics?(): Readonly<TranscriptPersistenceMetrics>;
     get(id: string, options?: SessionGetOptions): Promise<Session | undefined>;
     getAcrossProjects(id: string, options?: SessionGetOptions): Promise<Session | undefined>;
     save(session: Session, cwd?: string): Promise<void>;
@@ -1376,6 +1414,26 @@ export interface SessionHookManager {
      * Does NOT support continueRequest.
      */
     executeFinalStopHooks(session: Session, reason?: FinalStopReason): Promise<void>;
+    /**
+     * UserPromptExpansion — Claude Code 官方事件（非 cbc 专属扩展）：任何用户输入的
+     * 命令/skill 在展开成 prompt、送进模型之前统一从这里触发，可阻断展开。适用于
+     * skill、自定义命令、Dynamic Workflow、MCP prompt 等一切"输入即展开"的路径，
+     * 不是只服务某一个具体调用方（如统一资产门控）。
+     */
+    executeUserPromptExpansionHooks(session: Session, payload: {
+        /** Claude Code spec: 'slash_command' for skill/custom commands, 'mcp_prompt' for MCP prompts. */
+        expansionType: 'slash_command' | 'mcp_prompt' | string;
+        commandName: string;
+        /** Claude Code spec: required field (empty string when no args), always sent. */
+        commandArgs: string;
+        /** e.g. Skill.source / Command.scope ('project' | 'user' | 'plugin' | 'mcp' | ...). */
+        commandSource?: string;
+        /** Claude Code spec: required field — raw, pre-expansion prompt text as typed by the user. */
+        prompt: string;
+    }): Promise<{
+        allowed: boolean;
+        message?: string;
+    }>;
 }
 export interface RunItemProcessor {
     process(runItem: RunItem): Promise<void>;
@@ -1494,9 +1552,10 @@ export interface InterruptionService {
      *
      * 幂等：session 未注册时为 no-op。只清内存映射，不动磁盘 jsonl。
      *
-     * @param sessionId 已完成 subagent 的 session id
+     * @param target 传 Session 对象时按对象身份校验，同 id 的后继对象不会被误清；
+     * 只拿得到 id 的调用方传字符串，此时不做身份校验。
      */
-    releaseSession(sessionId: string): void;
+    releaseSession(target: string | Session): void;
 }
 export interface MessageQueueManager {
     enqueueMessage(session: Session, message: AgentInputItem): string;

package/cli/dist-server/types/workspace/cbc-core/lib/node/session/session-run-state-machine-protocol.d.ts

@@ -114,6 +114,7 @@ export type SessionRunEvent = {
 } | {
     type: SessionRunEventType.TOOL_STARTED;
     toolName?: string;
+    toolCallId?: string;
     reason?: string;
 } | {
     type: SessionRunEventType.TOOL_ENDED;

package/cli/dist-server/types/workspace/cbc-core/lib/node/session/session-runtime-lifecycle.d.ts

@@ -0,0 +1,5 @@
+import type { Session } from './session-protocol.js';
+export declare function isSessionRuntimeClosed(session: Session): boolean;
+export declare function closeSessionRuntime(session: Session): void;
+export declare function sessionRuntimeSignal(session: Session): AbortSignal;
+export declare function assertSessionRuntimeOpen(session: Session | undefined): void;

package/cli/dist-server/types/workspace/cbc-core/lib/node/session/session-store.d.ts

@@ -2,7 +2,7 @@ import { Logger } from '@celljs/core';
 import { type AgentInputItem } from '../../../../cbc-shared/lib/node/index.js';
 import * as fs from 'fs/promises';
 import { LocalJsonlSessionStore } from './local-jsonl-session-store.js';
-import { type Session, SessionFactory, type SessionForkMutationOptions, type SessionGetOptions, type SessionRewindMutationOptions, SessionStore } from './session-protocol.js';
+import { type Session, SessionFactory, type SessionForkMutationOptions, type SessionGetOptions, type SessionRewindMutationOptions, SessionStore, type TranscriptPersistenceMetrics } from './session-protocol.js';
 import type { Lane, LanePointer, SessionKey, SessionStoreEntry } from './session-store-contract.js';
 import { SessionImageStorage as ImageBlobService, SessionRestoreHost, SessionStoragePaths, SessionToolOutputStorage as ToolResultBlobService } from './session-store-host-protocol.js';
 /**
@@ -10,6 +10,27 @@ import { SessionImageStorage as ImageBlobService, SessionRestoreHost, SessionSto
  * 达到此阈值且遇到 user message 时停止逆序读取，避免启动时全量读 JSONL。
  */
 export declare const DEFAULT_SESSION_MAX_ITEMS = 1000;
+/**
+ * 每追加这么多条 history 行，就把当前 session-meta 快照重新补写到文件尾部。
+ *
+ * 读侧按 item 数封顶逆序读，只在窗口内找 session-meta；写侧按内容去重，身份
+ * 不变就只有创建时那一行（文件第 1 行）。会话一长，读窗口够不到它 → resume
+ * 静默丢 `codebuddy.ai/mainAgent`（PTC 掉回 cli、REPL 消失）/ `multitaskMode`
+ * / `codebuddy.ai/a2aContexts` / `codebuddy.ai/hostKind`（#128860）。
+ *
+ * 取值远小于 {@link DEFAULT_SESSION_MAX_ITEMS}，读侧即使把上限调低也仍能覆盖；
+ * 代价是每 200 行多一条约 200 字节的行（≈0.1%）。
+ *
+ * **与 {@link SESSION_META_HEAD_SCAN_BYTES} 是配对约束，必须满足**
+ * `SESSION_META_TAIL_REFRESH_LINES × 单行平均字节 << SESSION_META_HEAD_SCAN_BYTES`：
+ * 写侧靠本行距把快照压在文件尾部，读侧只有 256KB 的文件头兜底窗口 —— 一旦尾部快照
+ * 滑出头部窗口，长会话 resume 丢键（#128860 本体）就会以另一种形式回归。
+ * 当前 200 × ~200B ≈ 40KB，对 256KB 有约 6× 余量。**调大本值或让单行显著变长
+ * （例如工具结果外置后仍很大的行）都必须同步核对另一侧**，spec 里有一条边界断言钉住。
+ */
+export declare const SESSION_META_TAIL_REFRESH_LINES = 200;
+/** 文件头 session-meta 兜底读取的字节窗口（存量会话用，不做全量回扫）。与上者配对，见其注释。导出以便 spec 钉住配对约束。 */
+export declare const SESSION_META_HEAD_SCAN_BYTES: number;
 /**
  * Keys of session.meta that persist across processes (the off-tree
  * session-meta line; bin resume only — served sessions never write). A
@@ -22,6 +43,37 @@ export declare const DEFAULT_SESSION_MAX_ITEMS = 1000;
  * Role / locks / parentSessionId stay runtime-only.
  */
 export declare const PERSISTED_SESSION_META_KEYS: readonly ['codebuddy.ai/mainAgent', 'codebuddy.ai/hostKind', 'multitaskMode', 'codebuddy.ai/a2aContexts'];
+/**
+ * 白名单里「缺席即删除」的键：只认最新那一行的存在性，不向更早的行按键继承。
+ *
+ * 其余键（mainAgent / hostKind / a2aContexts）只会被赋值、不会被 delete，所以
+ * 读侧按键继承——某个写方视野不全（只快照了自己关心的键）不能把别的键擦掉
+ * （#128860：`/multitask` 盖章写出只含 multitaskMode 的行，把 PTC 站立身份永久
+ * 抹掉，`/agent-mode` 变成 Standard(cli)）。
+ *
+ * `multitaskMode` 是唯一会被真正 delete 的键（multitask/session-flags.ts 的
+ * clearMultitaskSession），所以必须留在这里，否则"关掉多任务"会被更早的
+ * `true` 复活。**新增白名单键时**：只要它的"缺席"承载语义，就必须登记到本表。
+ *
+ * 注意「缺席」要能写进文件才算数：子集被删空时 `persistSessionMeta` 会补一条
+ * `meta: {}` 的墓碑行，否则最新那条仍是删除前的快照，缺席永远不会出现。墓碑是
+ * **整份空快照**：本表登记第二个键之后，为删 A 写的墓碑会连带把 B 也判成缺席，
+ * 届时得改成按键墓碑，别直接往表里加。
+ */
+export declare const SNAPSHOT_ONLY_SESSION_META_KEYS: ReadonlyArray<string>;
+/**
+ * 参与合并的一条 session-meta 行。
+ *
+ * `id` 可能是空串：#94203 才给这行加上自身 UUIDv7，更早写下的存量行没有 id
+ * （CHANGELOG 明确「兼容旧的无 ID 记录」）。任何按 id 判等的地方都必须先处理
+ * 这个缺失，见 {@link SessionStoreImpl.metaLineIdentity}。
+ */
+interface SessionMetaLine {
+    id: string;
+    meta: Record<string, unknown>;
+    /** 行原文（trim 后）。缺 id 的存量行靠它做判等。 */
+    raw: string;
+}
 /**
  * 解析 session 历史回放的 maxItems。
  *
@@ -46,6 +98,7 @@ export declare class SessionStoreImpl implements SessionStore {
     protected readonly paths: SessionStoragePaths;
     protected readonly restoreHost: SessionRestoreHost;
     private writeLocks;
+    private readonly transcriptMetrics;
     private readonly transcriptAuditOnce;
     private transcriptAuditSequence;
     /**
@@ -113,6 +166,16 @@ export declare class SessionStoreImpl implements SessionStore {
      * behavioral loop: externalize → Read → externalize → Read …).
      */
     private externalizeToolResultIfNeeded;
+    /**
+     * Externalize the UI-only copy of a tool result. Tool implementations commonly store
+     * the same payload again in providerData.toolResult.content/renderer; keeping that copy
+     * defeats output externalization and can make a single JSONL row hundreds of KiB.
+     *
+     * The render payload is persisted as one JSON document. History keeps a text renderer
+     * pointing at that file, so clients always have a visible fallback instead of trying to
+     * parse a <persisted-output> marker as the original media/custom renderer payload.
+     */
+    private externalizeToolRenderDataIfNeeded;
     /**
      * Handle externalization for structured array output.
      * Iterates through array elements and externalizes any input_text items that exceed the threshold.
@@ -139,7 +202,25 @@ export declare class SessionStoreImpl implements SessionStore {
      */
     getSessionMetaFilePath(id: string, parentSessionId?: string, cwd?: string): string;
     private lastPersistedMeta;
+    /** 各转录文件「距上次 session-meta 行」的 history 行数（进程内，用于尾部刷新节流）。 */
+    private historyLinesSinceMeta;
+    /** 读侧靠文件头兜底才拿到 meta 的转录文件：下一批 append 立即把快照补到尾部。 */
+    private staleTailMeta;
+    /**
+     * 「据已知，该转录尾部最新那条 session-meta 还带着非空子集」——决定子集被删空时
+     * 要不要补墓碑。
+     *
+     * 判据必须是**文件事实**而不是"本进程写过什么"：resume 只 `get()` 不 `save()`
+     * （agent-task.ts 的子代理恢复就是这样），进程内缓存恒空，冷启动后第一轮就关掉
+     * 多任务会写不出墓碑，"关掉"永远落不了盘。所以读侧 load 完也要维护它。
+     *
+     * 仍是进程内状态：同一转录被两个进程同时写时，另一方的非空写入本进程不可见
+     * （与 `lastPersistedMeta` 同一层限制）。
+     */
+    private tailMetaNonEmpty;
     private persistedMetaSubset;
+    /** 一条 off-tree session-meta 行的字节形式。空 `persisted` 即墓碑快照。 */
+    private metaSnapshotLine;
     /** The off-tree session-meta line, or undefined when there is nothing to persist. */
     protected sessionMetaLineFor(fileId: string, meta: Session['meta']): string | undefined;
     /**
@@ -150,7 +231,59 @@ export declare class SessionStoreImpl implements SessionStore {
      * .meta.json overwrite. Bin surface only — served sessions never reach
      * here (persistence gate; locked by spec).
      */
-    protected persistSessionMeta(fileId: string, meta: Session['meta'], parentSessionId?: string, cwd?: string): Promise<void>;
+    protected persistSessionMeta(fileId: string, meta: Session['meta'], parentSessionId?: string, cwd?: string, options?: {
+        force?: boolean;
+    }): Promise<void>;
+    /**
+     * 尾部快照刚落盘后的进程内状态收尾 —— 四份状态必须一起动。
+     *
+     * `lastPersistedMeta` / `historyLinesSinceMeta` / `staleTailMeta` / `tailMetaNonEmpty`
+     * 都以 filePath 为键、都描述「这个转录尾部最新那条 meta 现在是什么」。任何往尾部
+     * 写快照的路径（persistSessionMeta / initializeForkHistory）都要走这里：在调用点
+     * 手写四行，下一次再加状态时必然漏一处 —— fork 初始化就是这么漏的（lastPersistedMeta
+     * 写了，另外三份没写，导致 fork 后关掉多任务写不出墓碑、行数计数带着旧值）。
+     */
+    private markTailMetaPersisted;
+    /**
+     * 让「最新 session-meta」始终留在读侧的逆序窗口内（#128860 根治的写入侧）。
+     *
+     * 只在 history 真正落盘之后调用：每 {@link SESSION_META_TAIL_REFRESH_LINES}
+     * 行补写一次快照；读侧走过文件头兜底的文件（存量长会话）立即补写一次，
+     * 这样同一个会话只会退化一次。
+     *
+     * 失败不能拖垮本轮 append —— 转录字节已经写成功了，meta 下一批还会重试。
+     */
+    private refreshTailSessionMeta;
+    /**
+     * 文件头的 session-meta 兜底读取。
+     *
+     * `session-meta` 创建行通常在文件靠前的位置（新建会话是第 1 行；子会话/迁移过的
+     * 会话可能更靠后），而 history 逆序读有 item 上限——长会话倒着读到不了那里
+     * （#128860）。这里只读文件头一小段，不做全量回扫：
+     * 29MB 的会话里末尾 1100 行只占 20% 字节，回扫到头会把 resume 的读 I/O 放大 5×。
+     *
+     * 返回窗口内所有 session-meta 的 meta（文件序，旧→新），由
+     * {@link composeSessionMeta} 统一合并。
+     */
+    protected readHeadSessionMeta(filePath: string): Promise<SessionMetaLine[] | undefined>;
+    /**
+     * 合并去重用的行身份。
+     *
+     * 不能直接用 `id`：#94203 之前的存量行没有 id，兜成空串会让「头部的创建行」
+     * 和「尾部的残缺行」撞成同一个键 —— 头部那条被当成"已经见过"丢掉，正好复现
+     * 本 issue 要修的丢键现场（本机实测 2607 条 meta 行里 1195 条没有 id）。
+     * 缺 id 时退回整行原文：内容相同的两行参与合并是幂等的，丢一条无害。
+     */
+    private metaLineIdentity;
+    /**
+     * 把若干条 session-meta（文件序，旧→新）合成一份 meta 事实。
+     *
+     * - {@link SNAPSHOT_ONLY_SESSION_META_KEYS}：只认最新那一行（缺席=已删除）。
+     * - 其余白名单键：按键向更早的行继承，最新的值优先。写方只快照了自己视野
+     *   里的键时，别人的键不会被顺带擦掉（#128860 的第二处：`/multitask` 写出
+     *   只含 multitaskMode 的行，PTC 站立身份被永久抹掉）。
+     */
+    protected composeSessionMeta(metaLinesOldestFirst: ReadonlyArray<SessionMetaLine>): Record<string, unknown> | undefined;
     private findSubagentSessionByStoreId;
     protected deserializeSessionFromJsonl(id: string, options?: SessionGetOptions): Promise<Session | undefined>;
     /**
@@ -225,13 +358,25 @@ export declare class SessionStoreImpl implements SessionStore {
      */
     protected isNonUserSession(session: Session): boolean;
     appendHistory(id: string, input: AgentInputItem[], parentSessionId?: string, session?: Session, cwd?: string): Promise<void>;
+    protected openJsonlFile(filePath: string, flags: string): ReturnType<typeof fs.open>;
+    /** Short, in-band only: this runs on the addHistory chain, so it is turn latency. */
+    protected transcriptRetryDelaysMs(): readonly number[];
+    protected sleepBeforeTranscriptRetry(delayMs: number): Promise<void>;
+    /** Cumulative transcript persistence counters (issue #119545 埋点). */
+    transcriptPersistenceMetrics(): Readonly<TranscriptPersistenceMetrics>;
     /**
-     * The transcript-line writer, extracted verbatim from the previous
-     * appendHistory body: exclusive-create or append open, chunked line
+     * The transcript-line writer: exclusive-create or append open, chunked line
      * writes, and on failure a rollback (unlink a file this batch created,
      * truncate to the original size otherwise) with forensic audit logs.
+     *
+     * A retryable failure gets a short in-band retry. When the budget runs out
+     * the batch is abandoned and reported as a typed error — the local copy is
+     * allowed to lose its tail, and `addHistory` keeps the turn running. Read
+     * paths repair the gap (unpaired tool calls are filtered out of model
+     * input), so the cost of a loss is a shorter history, not a broken one.
      */
     protected writeTranscriptLines(sessionFilePath: string, lines: string[], key?: SessionKey): Promise<void>;
+    private writeTranscriptLinesOnce;
     private readonly entriesStoreInstances;
     /**
      * The embedded SessionStore-contract backend — the single jsonl writer
@@ -312,3 +457,4 @@ export declare class SessionStoreImpl implements SessionStore {
     private cleanupFailedFork;
     rewindSession(source: Session, options: SessionRewindMutationOptions): Promise<void>;
 }
+export {};