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

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

@@ -2,6 +2,7 @@ import { Deferred } from '@celljs/core';
 import { type AgentInputItem, ApprovalOptions, type Checkpoint, FinalStopReason, NotificationType, PermissionMode, ReasoningEffortLevel, type ResponseStreamEvent, type RunItem, type RunResult, type RunState, type RunToolApprovalItem, type SdkCapabilities, SessionEndReason, SessionStartSource, type StreamedRunResult, type TerminalEvent, type ToolDeferOverlaySnapshot, ToolPermissionContext, type Usage } from '../../../../cbc-shared/lib/node/index.js';
 import { Command } from '../../../../product/lib/common/index.js';
 import { BehaviorSubject, Subject } from 'rxjs';
+import type { CompactionLineage } from '../context/compaction-lineage.js';
 import { BackgroundTask } from './background-task-protocol.js';
 import type { SessionRunStateSnapshot } from './session-run-state-machine-protocol.js';
 import type { Lane, LanePointer, SessionKey, SessionStoreEntry } from './session-store-contract.js';
@@ -86,9 +87,11 @@ export type AgentState = 'agent_pending' | 'agent_start' | 'agent_tool_start' |
  *                              则 emit，触发 UI 显示"正在同步文件"提示)
  */
 export type AgentPhase = 'preparing' | 'model_requesting' | 'model_streaming' | 'model_done' | 'tool_executing' | 'waiting_for_permission' | 'waiting_for_user' | 'retrying' | 'finalization_file_projection_sync' | 'finalization_file_projection_sync_notify' | 'idle';
+export type AgentRetryReason = 'network';
 export interface AgentPhaseInfo {
     phase: AgentPhase;
     toolName?: string;
+    toolCallId?: string;
     streamingToolName?: string;
     startedAt: number;
     /**
@@ -101,6 +104,13 @@ export interface AgentPhaseInfo {
         current: number;
         total: number;
     };
+    /**
+     * 仅 retrying phase 使用，经 ACP `_meta['codebuddy.ai/agentPhase']` 透传给上层。
+     * 缺省表示原因未分类（如流超时），不代表网络正常。
+     */
+    retry?: {
+        reason: AgentRetryReason;
+    };
 }
 export declare const AgentPhaseUtils: {
     /** Create an AgentPhaseInfo with the current timestamp. */
@@ -177,6 +187,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 +218,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>;
@@ -348,6 +362,14 @@ export interface Session {
      * field and pass it through as `options.maxTurns` explicitly.
      */
     lastRunMaxTurns?: number;
+    /**
+     * Latest agent-loop model call number (`providerData.stepSeq`). Unlike the
+     * SDK turn counter it survives runs, compaction and resume; see
+     * `allocateModelStepSeq`.
+     */
+    modelStepSeq?: number;
+    /** Compactions of this Session's context; see `getCompactionLineage`. */
+    compactionLineage?: CompactionLineage;
     queue: AgentInputItem[];
     queueSubject: BehaviorSubject<AgentInputItem[]>;
     /**
@@ -638,6 +660,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
          */
@@ -849,7 +877,7 @@ export interface SubagentInvocationRecord {
     lifecycle: SubagentLifecycleSnapshot;
 }
 export type SubagentLifecycleDescriptor = Omit<SubagentLifecycleSnapshot, 'status' | 'updatedAt' | 'usage'>;
-export type CombineEvent = (AgentInputItemEvent | ModelRawResponseEvent | ResultEndEvent | InterruptResultEvent | NoticeEvent | SubagentStatusEvent | CompactionLifecycleEvent | TerminalEvent) & CombineEventMeta;
+export type CombineEvent = (AgentInputItemEvent | AgentSdkStreamEvent | ModelRawResponseEvent | ResultEndEvent | InterruptResultEvent | NoticeEvent | SubagentStatusEvent | CompactionLifecycleEvent | TerminalEvent) & CombineEventMeta;
 export interface CompactionLifecycleEvent {
     type: 'compaction';
     data: {
@@ -864,6 +892,11 @@ export interface SubagentStatusEvent {
     type: 'subagent_status';
     data: SubagentLifecycleSnapshot;
 }
+/** Original SDK stream payload, observed by the existing single stream consumer. */
+export interface AgentSdkStreamEvent {
+    type: 'sdk';
+    data: import('../../../../cbc-shared/lib/node/index.js').RunStreamEvent;
+}
 export interface AgentInputItemEvent {
     type: 'input';
     data: AgentInputItem;
@@ -915,6 +948,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. */
@@ -1050,6 +1085,13 @@ export interface SessionRewindMutationOptions {
     cwd: string;
     headMessageId: string | undefined;
 }
+/**
+ * model override 的意图来源：决定该值是否等价于「用户显式选择」。
+ * - 'user'：/model 命令、ACP set_model、SDK 控制信号等用户动作；
+ * - 'declared'：主 Agent 声明模型（declaredModel）联动写入；
+ * - 'materialized'：Web UI 会话装配期钉住的兜底解析值（非用户意图）。
+ */
+export type OverrideModelSource = 'user' | 'declared' | 'materialized';
 export interface SessionManager {
     getCurrent(): Session;
     setCurrent(session: Session): void;
@@ -1123,9 +1165,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()）。
      *
@@ -1150,11 +1194,15 @@ export interface SessionManager {
     setOverridePermissionMode(sessionId: string, mode: PermissionMode): void;
     getOverridePermissionMode(sessionId: string): PermissionMode | undefined;
     /**
-     * 设置 session 的 model 覆盖值（来自 SDK control signal）
-     * 这些值会覆盖 CLI 参数和配置文件的设置
+     * 设置 session 的 model 覆盖值。source 记录意图来源，供「是否用户显式选择」判定：
+     * - 'user'（默认）：/model 命令、ACP set_model、SDK 控制信号等用户动作；
+     * - 'declared'：主 Agent 声明模型（declaredModel）联动写入；
+     * - 'materialized'：Web UI 会话装配期钉住的兜底解析值（非用户意图）。
      */
-    setOverrideModel(sessionId: string, model: string): void;
+    setOverrideModel(sessionId: string, model: string, source?: OverrideModelSource): void;
     getOverrideModel(sessionId: string): string | undefined;
+    getOverrideModelSource(sessionId: string): OverrideModelSource | undefined;
+    clearOverrideModel(sessionId: string): void;
     /**
      * 设置会话运行时模型：同步写 session.options.model + requestOptions.model + override map。
      *
@@ -1163,7 +1211,7 @@ export interface SessionManager {
      * 供 applyOverrideModel 每轮重建 requestOptions（Issue #82146）。/model 命令与模型面板
      * 共用此入口；ACP set_model（applyRuntimeSessionModel）仍为独立实现，待统一收敛。
      */
-    setRuntimeModel(session: Session | undefined, modelId: string): void;
+    setRuntimeModel(session: Session | undefined, modelId: string, source?: OverrideModelSource): void;
     /**
      * 设置会话运行时 outputStyle：同步写 session.options.outputStyle。
      *
@@ -1216,8 +1264,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 +1447,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>;
@@ -1444,6 +1535,7 @@ export interface InterruptionService {
     approve(item: RunToolApprovalItem, options?: ApprovalOptions): void;
     reject(item: RunToolApprovalItem, options?: {
         decision?: 'deny' | 'rejectAndExitPlan';
+        cancelTurn?: boolean;
     }): void;
     waitFor(session: Session): Promise<void>;
     /** Resolve the main/leader session for a given session (returns self if already main). */
@@ -1494,9 +1586,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;
@@ -1653,6 +1746,12 @@ export interface TurnMetricsReporter {
      */
     unregister(sessionId: string): void;
 }
+/** Ids of one model call, as stamped by the model wrapper. */
+export interface ModelCallGeneration {
+    messageId: string;
+    conversationRequestId?: string;
+    stepSeq?: number;
+}
 export interface ModelResponseMetadata {
     /** 响应中的模型 ID */
     model?: string;
@@ -1666,6 +1765,8 @@ export interface ModelResponseMetadata {
      * 都带 providerData.messageId === 此值，handleContentFilteredResponse 据此剔除并替换为安全提示。
      */
     contentFilterMessageId?: string;
+    /** Correlation of the generation that just completed, as stamped by the model wrapper. */
+    generation?: ModelCallGeneration;
     usage?: {
         prompt_tokens: number;
         completion_tokens: number;

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

@@ -1,5 +1,5 @@
 import type { Observable } from 'rxjs';
-import type { Session } from './session-protocol.js';
+import type { AgentRetryReason, Session } from './session-protocol.js';
 export declare const SessionRunStateMachine: unique symbol;
 export declare const SessionRunStateProjectionService: unique symbol;
 export declare const SESSION_RUN_STATE_PROJECTION_SCHEMA: 'session-run-state.v1';
@@ -114,6 +114,7 @@ export type SessionRunEvent = {
 } | {
     type: SessionRunEventType.TOOL_STARTED;
     toolName?: string;
+    toolCallId?: string;
     reason?: string;
 } | {
     type: SessionRunEventType.TOOL_ENDED;
@@ -143,6 +144,7 @@ export type SessionRunEvent = {
 } | {
     type: SessionRunEventType.RETRYING;
     reason?: string;
+    retryReason?: AgentRetryReason;
 } | {
     type: SessionRunEventType.COMPACT_STARTED;
     reason?: string;
@@ -188,6 +190,18 @@ export interface SessionRunStateMachine {
      */
     getChange$(session: Session, skipFirst?: boolean): Observable<void>;
 }
+export declare const ModelRequestRetryPhase: unique symbol;
+/**
+ * 模型请求层（宿主 provider）在同一次请求内部退避重发时，借此把会话投影为 retrying。
+ * 状态写入与守卫收口在 core，宿主只包住退避等待，不直接驱动状态机。
+ */
+export interface ModelRequestRetryPhase {
+    /**
+     * `wait` 期间会话显示 retrying 并携带 `reason`；结束（含抛错 / 取消）后恢复 model_requesting。
+     * 非本轮主请求（无 session、辅助型 purpose、状态不在 model_requesting）时只执行 `wait`。
+     */
+    during<T>(session: Session | undefined, reason: AgentRetryReason, wait: () => Promise<T>): Promise<T>;
+}
 /**
  * Pure derivations from a `SessionRunStatus`. The state machine implementation
  * MUST keep its instance methods (`getLifecycle`, `isBusy`, etc.) consistent

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 {};

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

@@ -6,9 +6,28 @@ import type { Session } from './session-protocol.js';
  * terminal results are suppressed only while a retry will actually be scheduled.
  */
 export declare function hasExhaustedStreamTimeoutRetryBudget(session: Session, isFirstTokenTimeout: boolean): boolean;
+/**
+ * `finish_reason=error` 且没有可用输出的两种空流：reasoning-only 与 no-token。
+ * placeholder（空 200 / 心跳帧）仍是会话层终态，由拦截器切一次备站。
+ *
+ * 额外的时长闸门（#132616）：这两种 kind 之所以可重试，前提是「上游瞬时失败」——秒级
+ * 空响应重跑一次大概率就好了。但当这条流已经跑满上游的硬时限才收到 error 时，前提不成立：
+ * 同一段 prompt 重跑必然再次跑满同一个时限。实测 7 个会话全部重试、全部再次撞墙、0 次恢复，
+ * 而 `#130098` 把预算从 1 提到 3 之后，同样的输入会从 2×900s 变成 4×900s ≈ 60 分钟静默。
+ * 重试的期望收益不随 elapsed 增长，成本却线性增长，所以按 elapsed 收口。
+ */
 export declare function isRetryableEmptyStreamError(error: unknown): boolean;
 /**
  * Empty 200 / placeholder-only：拦截器最多切一次备站，会话层终态（#115866）。
- * reasoning-only + finish_reason=error：上游瞬时失败，会话层最多重试 1 次（#122115）。
+ * reasoning-only / no-token + finish_reason=error：上游瞬时失败，按 error 预算重试；
+ * 已烧满上游硬时限的那些除外，见 {@link isRetryableEmptyStreamError} 的时长闸门（#132616）。
+ * 流空闲超时 / 首 token 超时：按各自的超时预算重试。
  */
 export declare function shouldAutoRetryStreamTimeout(session: Session, error: unknown): boolean;
+/**
+ * 为一次流错误恢复认领额度，返回序号（1-based）；不可重试或已耗尽返回 `undefined`。
+ * 调用方必须先用 {@link shouldAutoRetryStreamTimeout} 判定，本函数只负责同步认领。
+ */
+export declare function claimStreamRecoveryAttempt(session: Session, error: unknown): number | undefined;
+/** 认领后没有真正发起恢复时退回额度。 */
+export declare function releaseStreamRecoveryAttempt(session: Session, error: unknown): void;

package/cli/dist-server/types/workspace/cbc-core/lib/node/trace/turn-context.d.ts

@@ -34,6 +34,33 @@ export interface TurnContext {
     /** Canonical id assigned when the external user input is admitted. */
     conversationRequestId?: string;
 }
+export interface RequestOwner {
+    readonly session: Session;
+    readonly requestId: string;
+    readonly turn: TurnContext;
+    latestExecution?: object;
+}
+export type RequestTerminalOutcome = 'written' | 'failed' | 'unconfirmed';
+export interface RequestTerminal {
+    readonly attempt: object;
+    outcome?: RequestTerminalOutcome;
+    readonly completed: Promise<RequestTerminalOutcome>;
+}
+export declare function getRequestOwner(ref: object): RequestOwner | undefined;
+export declare function getRequestExecution(ref: object): object | undefined;
+export declare function associateRequestOwner(ref: object, owner: RequestOwner, execution?: object): void;
+/** Carry physical execution through admission without inventing a request owner. */
+export declare function associateRequestExecution(ref: object, execution: object): void;
+/** Reserve completion ownership at admission, retaining the prior result if startup fails. */
+export declare function beginRequestExecution(owner: RequestOwner, execution: object): void;
+/** A failed startup never owns a result; restore only the execution it actually replaced. */
+export declare function abandonRequestExecution(execution: object): Session['resultSubject']['value'];
+export declare function getRequestTerminal(owner: RequestOwner, destination: string): RequestTerminal | undefined;
+export declare function claimRequestTerminal(owner: RequestOwner, destination: string, attempt: object): boolean;
+export declare function settleRequestTerminal(owner: RequestOwner, destination: string, attempt: object, outcome: RequestTerminalOutcome): void;
+/** The admission boundary, not trace binding, creates a new logical request. */
+export declare function admitRequestOwner(session: Session, requestId: string): RequestOwner;
+export declare function runInRequestOwner<T>(owner: RequestOwner, callback: () => T): T;
 /** Transient provider-data key; stripped before history/model persistence. */
 export declare const TURN_CARRIER_CANDIDATE_KEY = "codebuddy.ai/turnCarrierCandidate";
 export declare const BAGGAGE_KEY_SESSION_ID = "codebuddy.session_id";
@@ -83,7 +110,7 @@ export declare function bindCurrentTurnContext(session: Session, conversationReq
 /** Carrier for one exact admitted request; never returns the latest other turn. */
 export declare function turnCarrierForRequest(session: Session, conversationRequestId: string | undefined): W3CTraceContextMeta;
 /** Release an exact request binding. */
-export declare function releaseTurnContext(session: Session, conversationRequestId: string | undefined): void;
+export declare function releaseTurnContext(session: Session, conversationRequestId: string | undefined, owner?: RequestOwner): void;
 /** The current turn as an injectable three-key carrier; `{}` outside a turn. */
 export declare function currentTurnCarrier(): W3CTraceContextMeta;
 /**

package/cli/dist-server/types/workspace/cbc-core/lib/node/utils/command-message-utils.d.ts

@@ -58,6 +58,26 @@ export declare abstract class CommandMessageUtils {
      * 解析XML格式的命令输出
      */
     static parseOutput(xmlText: string): ParseCommandMessage | undefined;
+    /**
+     * 是否为本地命令在会话历史里留下的记账项：caveat、命令回显（`<command-name>`）、
+     * 命令输出（`<local-command-stdout>`）、本地 bash 的输入输出、plan 输出。
+     *
+     * 这些 item 的 role 是 user、也不带 skipRun，因此按「真实用户消息」判定会命中；
+     * 但它们只是本地命令的痕迹，**不代表用户开启了新一轮对话**。调用方（如 TUI 的
+     * loading 计时器）需要区分「新一轮」和「本地命令留痕」时用这个判据。
+     *
+     * 识别口径复用 parseInput / parseOutput / parsePlanOutput，避免调用方各自
+     * 维护一份 XML 标签清单而漂移。
+     */
+    static isLocalCommandRecord(text: string): boolean;
+    /**
+     * {@link isLocalCommandRecord} 的 item 版本。
+     *
+     * 必须读 **原始** content：`MessageContentUtils.extractTextContent` 已经把命令 XML
+     * 拆开（`<command-name>/doctor</command-name>` → `/doctor`），拿它的结果再判就永远
+     * 判不出来。
+     */
+    static isLocalCommandRecordItem(item: UserMessageItem): boolean;
     /**
      * 解析计划输出
      */