@tencent-ai/agent-harness 0.2.0-beta.7 → 0.2.0-beta.8

package/cli/dist-server/types/node/agent-view/handoff-policy.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 会话转后台的策略判定 —— 纯函数，无 I/O。
+ *
+ * 对照 Claude Code v2.1.216 bundle：
+ * - `jA_` / `qA_`（策略）
+ * - `nTo` / `GA_`（betweenCalls）
+ * - `DXe` 拒绝文案
+ */
+/** 成功交接时选用的路径 */
+export type HandoffVia = 'idle-fork' | 'defer-then-fork' | 'abort-then-fork' | 'detach';
+/** 拒绝转后台的原因 */
+export type HandoffRefusal = 'fleet-disabled' | 'remote' | 'persistence' | 'loading' | 'queued-commands' | 'ended-by-model';
+export type HandoffDecision = {
+    ok: true;
+    via: HandoffVia;
+} | {
+    ok: false;
+    reason: HandoffRefusal;
+};
+/** `resolveHandoffStrategy` 的输入快照 */
+export interface HandoffStrategyState {
+    /** 当前已是后台会话（attach 中）→ 只 detach */
+    isBg: boolean;
+    /** agent view / fleet 是否开启 */
+    fleetEnabled: boolean;
+    /** 远端会话 */
+    isRemote: boolean;
+    /** 会话持久化关闭 */
+    persistenceDisabled: boolean;
+    /** 外部加载态（例如正在恢复）—— 不可转后台 */
+    isExternalLoading: boolean;
+    /** 当前轮次是否在跑（模型/工具活跃） */
+    isLoading: boolean;
+    /** 上一轮已收尾、只是在等工具（见 `isBetweenCalls`） */
+    betweenCalls: boolean;
+}
+/** 判定 betweenCalls 用的最小消息形状 */
+export interface HandoffTranscriptMessage {
+    type: string;
+    message?: {
+        stop_reason?: string | null;
+    };
+}
+/** 等工具降级 / flush 超时常量（与 Claude `tengu_defer_cap_ms` / `TxS` / flush 超时对齐） */
+export declare const DEFER_CAP_MS = 10000;
+export declare const DEFER_PRESS_DEBOUNCE_MS = 1000;
+export declare const FLUSH_TIMEOUT_MS = 2000;
+/** 在跑工作条目（adopt 清单的元素，见 session-handoff 的 carryTasks） */
+export interface InFlightTask {
+    kind: string;
+    id: string;
+    label: string;
+    /** 显式标记是否可搬走；未给时由消费侧按 kind 自行判定 */
+    canCarry?: boolean;
+    /** subagent：子会话 UUID，adopt 后可按 transcript 找回 */
+    sessionId?: string;
+    /** subagent：agent 类型 */
+    agentType?: string;
+    /** shell：stdout 落盘路径（file-fd 模式），worker 侧重挂输出用 */
+    outputFilePath?: string;
+    /** shell：stderr 落盘路径 */
+    outputStderrPath?: string;
+}
+export interface RefusalMessageContext {
+    /** `queued-commands` 时必填 */
+    queuedCommandCount?: number;
+}
+/**
+ * 从会话状态选出转后台策略。
+ * 判定顺序与 Claude `jA_` 一致。
+ */
+export declare function resolveHandoffStrategy(state: HandoffStrategyState): HandoffDecision;
+/**
+ * 「上一轮已收尾、现在只是在等工具」：
+ * 输入缓冲为空，且从末尾看，助手尚未处于 `stop_reason === null` 的未收尾态。
+ * （对照 Claude `nTo` / `GA_`）
+ */
+export declare function isBetweenCalls(messages: readonly HandoffTranscriptMessage[], hasPartialInput: boolean): boolean;
+/** 每个拒绝原因产出一条用户可见文案 */
+export declare function refusalMessage(reason: HandoffRefusal, context?: RefusalMessageContext): string;

package/cli/dist-server/types/node/agent-view/launch-workspace.d.ts

@@ -0,0 +1,9 @@
+import type { AgentJobState } from './agent-view-protocol';
+export type Workspace = Pick<AgentJobState, 'cwd' | 'worktreePath' | 'worktreeBranch' | 'originCwd'>;
+export declare class LaunchWorkspaceError extends Error {
+    readonly path: string;
+    readonly code = "JOB_WORKSPACE_UNAVAILABLE";
+    constructor(path: string, reason: string, options?: ErrorOptions);
+}
+export declare function ensureLaunchWorkspace(state: Workspace): Promise<string>;
+export declare function launchWithWorkspaceRetry<T>(state: Workspace, launch: (cwd: string) => Promise<T>, prepare?: (state: Workspace) => Promise<string>): Promise<T>;

package/cli/dist-server/types/node/agent-view/session-handoff.d.ts

@@ -0,0 +1,161 @@
+/**
+ * 前台会话 → 后台 job 的交接编排。
+ *
+ * 顺序对照 Claude `Z5f` / design.md D6：job 记录先落盘，再 adopt，再 flush，
+ * 再 spawn；spawn 失败必须回滚 job 目录，前台保持存活。
+ */
+import { type PermissionMode } from '../../vendor/cbc-shared/node/index.js';
+import { type AgentViewActionDeps } from './agent-view-actions';
+import { type HandoffVia, type InFlightTask } from './handoff-policy';
+/** 派生 seed 时用的最小消息形状 */
+export interface HandoffSeedMessage {
+    type: string;
+    /** 用户消息正文；assistant 的可见摘要也可放这里 */
+    text?: string;
+    isMeta?: boolean;
+}
+export interface HandoffSeed {
+    intent: string;
+    name?: string;
+    nameSource?: 'user' | 'auto';
+    detail?: string;
+}
+/**
+ * 转后台时落盘的「在跑工作」清单。
+ *
+ * 这里**不含** abort-then-fork 的 prefill：那段没发完的输入已经作为 worker 的
+ * 首个位置参数投递了（见 {@link buildResumeArgs}），而 adopt.json 从来没有
+ * 消费方。留着它只会多出一条同文本的投递路径 —— 哪天有人接上消费侧，
+ * 用户那句话就会被执行两遍。同一段文本只允许有一个可靠承载点。
+ */
+export interface AdoptPayload {
+    writtenAtMs: number;
+    shells: Array<{
+        id: string;
+        label: string;
+        kind: string;
+        outputFilePath?: string;
+        outputStderrPath?: string;
+    }>;
+    cron: Array<{
+        id: string;
+        label: string;
+    }>;
+    agents: Array<{
+        id: string;
+        label: string;
+        sessionId?: string;
+        agentType?: string;
+    }>;
+    workflows: Array<{
+        id: string;
+        label: string;
+    }>;
+}
+export interface SessionHandoffDeps extends AgentViewActionDeps {
+    /** flush 当前 transcript；超时不阻断交接 */
+    flushTranscript: () => Promise<void>;
+    /** spawn 成功后：前台不再写 transcript */
+    releaseOwnership: () => void | Promise<void>;
+    /** abort-then-fork：中止当前轮次 */
+    abortTurn?: () => void | Promise<void>;
+    /** 可选：迁移 task-list 等附属文件 */
+    migrateSidecars?: (sessionId: string, signal: AbortSignal) => Promise<void>;
+    /**
+     * job 记录一落盘（id 已知、行已能在列表里出现）就回调。
+     *
+     * 交接的重头（flush transcript、fork worker）在这之后才发生；
+     * 调用方可以在这里就切换视图，让按键到画面切换只隔一次小文件写入，
+     * 而不是等整条流水线跑完——那是秒级的画面冻结。
+     */
+    onJobCreated?: (id: string) => void;
+    nowMs?: () => number;
+    warn?: (message: string) => void;
+}
+export interface SessionHandoffInput {
+    sessionId: string;
+    cwd: string;
+    messages: readonly HandoffSeedMessage[];
+    via: Exclude<HandoffVia, 'detach'>;
+    /** `/bg <prompt>` 附加指令 */
+    extraPrompt?: string;
+    /** abort-then-fork 时带走的未发完输入 */
+    prefill?: string;
+    boundaryUuid?: string;
+    /** 要写进 adopt.json 的可搬走工作（通常已按 canCarry 过滤） */
+    carryTasks?: readonly InFlightTask[];
+    /** 透传给子进程的 flag（--model / --permission-mode 等） */
+    inheritFlags?: readonly string[];
+    /**
+     * 交接时会话的实时权限模式。
+     *
+     * worker 是一个**新进程**，而权限模式只活在内存里：Shift+Tab 切换不落盘，
+     * `--permission-mode` 也不一定出现在 argv 里。不带过去的话，转后台的瞬间
+     * 模式就会从新进程重建出的默认值重新出发 —— auto 掉回 default，下一个
+     * 需要批准的工具调用就卡在「等待输入」，表现为「auto mode 自己关了」。
+     * 该值会覆盖 inheritFlags 里从 argv 回放出来的陈旧 --permission-mode。
+     */
+    permissionMode?: PermissionMode;
+    /** 用户显式命名 */
+    name?: string;
+    /**
+     * 左箭头允许空会话建行（seed 为 null 时用空 intent）。
+     * `/bg` 应设为 false，让「还没消息」在外层被拒绝。
+     */
+    allowEmptySeed?: boolean;
+    /**
+     * fork 语义：这是一个副本，父会话继续存活。
+     * 设置时会把关联字段写进 job 状态（design D8）。
+     */
+    fork?: {
+        parentSessionId: string;
+        sourceAlive: boolean;
+    };
+    /**
+     * 已存在的 job 记录（原地 worker 化在建行时就创建并一直维护它）：
+     * 跳过 create —— 重建会把刚落盘的 done/output 整个覆盖回 starting…，
+     * 行上的完成态就丢了；spawn 后也只补 pid/logPath，不再写死状态，
+     * settle 结果由建行方（become-worker）独写。spawn 失败也不回滚删除：
+     * 记录描述的是一段真实存在的对话，不是本次交接的临时产物。
+     */
+    existingJobId?: string;
+}
+export type SessionHandoffResult = {
+    ok: true;
+    id: string;
+    pid: number;
+    logPath: string;
+    seed: HandoffSeed;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * 从消息派生 job 的 intent / 显示名。
+ * 对照 Claude `TKe`：没有用户消息且没有 extraPrompt → null。
+ */
+export declare function deriveHandoffSeed(messages: readonly HandoffSeedMessage[], extraPrompt?: string, emptyFallback?: string): HandoffSeed | null;
+/**
+ * 交接主流程。调用方负责之后切到 agent view。
+ */
+export declare function handOffSessionToBackground(deps: SessionHandoffDeps, input: SessionHandoffInput): Promise<SessionHandoffResult>;
+/**
+ * 把交接时的实时权限模式合并进 worker 启动 flag。
+ *
+ * 先剥掉 inheritFlags 里可能从 argv 回放出来的陈旧 `--permission-mode`
+ * （会话开始后用户可能用 Shift+Tab 改过，argv 里的值已经不代表现状），
+ * 再追加当前模式；spawn 与 respawnArgs 共用同一份结果，worker 重启后
+ * 模式也不会丢。未提供模式时原样返回 inheritFlags。
+ */
+export declare function mergePermissionModeFlag(inheritFlags?: readonly string[], permissionMode?: PermissionMode): string[];
+/**
+ * 后台 worker 的启动参数。
+ *
+ * worker 是 broker PTY 里的一个**完整交互会话**（不是 `--print`、也不是 `--serve`），
+ * 它自己会一直活着；首个 prompt 作为位置参数交给启动流程消费，
+ * 决定它一起来是接着干活还是就地待命。
+ *
+ * respawnArgs 刻意不带 prompt：重启时该说的话由 pendingReply 承担，
+ * 带上会让同一条指令被执行两遍。
+ */
+export declare function buildResumeArgs(sessionId: string, inheritFlags?: readonly string[], firstPrompt?: string): string[];

package/cli/dist-server/types/node/ask/ask-protoctol.d.ts

@@ -0,0 +1,102 @@
+import { Deferred } from '@celljs/core';
+import type { Span } from '../../workspace/telemetry/lib/common/index.js';
+import { BehaviorSubject } from 'rxjs';
+import { RunToolApprovalItem } from '../../vendor/cbc-shared/node/index.js';
+export declare const AskService: unique symbol;
+export interface AskAnswers {
+    [question: string]: string;
+}
+export interface AskService {
+    /**
+     * Set ask questions
+     * @param item The tool approval item containing questions
+     */
+    setAsk(item: RunToolApprovalItem): void;
+    /**
+     * Start a user_input_wait span for the given toolCallId.
+     * Called when the question is presented to the user (setAsk time),
+     * not when acquireAnswers is called (which may be after the answer arrived).
+     * @param toolCallId The tool call id for the question
+     * @param rootSpan The conversation request root span to create the child span from
+     * @param questionCount Number of questions asked
+     * @param toolName Tool name (e.g. 'AskUserQuestion', 'Write', 'Bash') for distinguishing wait type
+     */
+    startWaitSpan(toolCallId: string, rootSpan: Span | undefined, questionCount: number, toolName?: string): void;
+    /**
+     * End the user_input_wait span for the given toolCallId.
+     * Used by callers that manage span lifecycle externally (e.g. tool approval
+     * in acp-agent.ts), as opposed to AskUserQuestion which ends via doneAsk/rejectAsk.
+     * @param toolCallId The tool call id
+     * @param success Whether the wait ended successfully
+     * @param error Optional error if the wait failed
+     */
+    endWaitSpanExternal(toolCallId: string, success: boolean, error?: Error): void;
+    /**
+     * End and clear all still-open waitSpans (superseded/interrupted). Used by
+     * conversation Stop / session teardown paths as a safety net against spans
+     * left dangling when a toolCallId is superseded without a matching doneAsk/rejectAsk.
+     * @param reason Recorded as the span's failure reason.
+     */
+    flushPendingWaitSpans(reason: string): void;
+    /**
+     * User completed answering questions.
+     * If no deferred is waiting for the given toolCallId, the answers are buffered
+     * in `earlyAnswers` and delivered to the next `acquireAnswers(toolCallId)`.
+     *
+     * @param answers User's answers to questions
+     * @param toolCallId Optional tool call id for precise routing. When omitted,
+     *                   falls back to the current ask item (legacy behavior).
+     */
+    doneAsk(answers: AskAnswers, toolCallId?: string): void;
+    /**
+     * User rejected/cancelled answering questions.
+     * @param toolCallId Optional tool call id; when omitted, targets the current ask item.
+     */
+    rejectAsk(toolCallId?: string): void;
+    /**
+     * Await the answers for a specific tool call.
+     * Returns immediately if `doneAsk` has already delivered answers (early arrival).
+     * Otherwise registers a deferred under `toolCallId` and resolves when `doneAsk` fires.
+     * Rejects if `rejectAsk` is called, the signal aborts, or `timeoutMs` elapses.
+     *
+     * @param timeoutMs Maximum wait time in milliseconds before rejecting with a
+     *                  timeout error. Defaults to 10 minutes. Pass `0` (or any
+     *                  non-finite value) to disable the timeout. The timeout is
+     *                  a safety net against lost UI messages causing the tool
+     *                  call to hang forever (see ask 工具确认框偶发卡死 root cause).
+     */
+    acquireAnswers(toolCallId: string, signal?: AbortSignal, timeoutMs?: number): Promise<AskAnswers>;
+    /**
+     * Diagnostic snapshot of internal routing state. Useful when debugging
+     * "ask panel never resolved" reports — log this on suspected hangs.
+     */
+    getRoutingState(): {
+        earlyAnswerKeys: string[];
+        waitingDeferredKeys: string[];
+        currentItemId: string | undefined;
+    };
+    /**
+     * Get current ask item
+     */
+    getCurrentAskItem(): RunToolApprovalItem | undefined;
+    /**
+     * Reactive observable of the current ask item.
+     *
+     * 方案一后续：AskPanel 的读取源从 `session.interruptionSubject.value` 切到这里。
+     * AskService 本来就是全局单例，天然不受 findMainSession fallback 造成的 session 错位影响。
+     * 之前 AskPanel 直接读 session.interruptionSubject 会在多 agent 并发下偶现错位：
+     * - 导航 hook 已通过 InterruptionService.pending$ 切到了正确的 panel
+     * - 但 AskPanel 内部再读 session.interruptionSubject.value 时，item 已被投到错的 session
+     * - 面板渲染看到 undefined，触发 "如果中断项消失但 askService 仍有待处理的 deferred" 自动清理
+     * - 用户看到的现象：面板闪一下就消失 / 面板空白
+     *
+     * 切到 currentItem$ 后 AskPanel 与 AskService 的内部状态始终同步，不再依赖 session 订阅。
+     */
+    readonly currentItem$: BehaviorSubject<RunToolApprovalItem | undefined>;
+    /**
+     * Get current deferred promise.
+     * @deprecated Prefer `acquireAnswers(toolCallId)` which avoids the
+     *             early-arrival race that dropped answers (issue #32633).
+     */
+    getCurrentDeferred(): Deferred<AskAnswers> | undefined;
+}

package/cli/dist-server/types/node/ask/ask-service.d.ts

@@ -0,0 +1,62 @@
+import { Deferred } from '@celljs/core';
+import { Logger, type Span } from '../../workspace/telemetry/lib/common/index.js';
+import { BehaviorSubject } from 'rxjs';
+import { RunToolApprovalItem } from '../../vendor/cbc-shared/node/index.js';
+import { AskAnswers, AskService } from './ask-protoctol';
+export declare class AskServiceImpl implements AskService {
+    protected readonly logger: Logger;
+    private currentDeferred;
+    private currentItem;
+    /**
+     * Reactive observable of the current ask item。
+     *
+     * AskPanel 订阅此 subject 代替旧的 `session.interruptionSubject.value` 读取，
+     * 避免多 agent 并发下因 findMainSession fallback 导致 ask item 投递到错的 session。
+     * AskService 本来就是 DI 单例，天然绕过 session 错位。
+     */
+    readonly currentItem$: BehaviorSubject<RunToolApprovalItem | undefined>;
+    /**
+     * Answers delivered by `doneAsk` before any `acquireAnswers` was waiting.
+     * Keyed by toolCallId so late-starting tool executions can still pick them up.
+     * See issue #32633: ACP approval used to race ahead of `execute()` creating the
+     * deferred, causing the answer to be dropped and the tool to see "No Question".
+     */
+    private earlyAnswers;
+    /**
+     * Deferreds registered by `acquireAnswers`, waiting for `doneAsk` to arrive.
+     */
+    private waitingDeferreds;
+    /**
+     * Active user_input_wait spans keyed by toolCallId.
+     * Created in `startWaitSpan` (when the question is presented to the user),
+     * ended in `doneAsk` / `rejectAsk` (when the answer arrives).
+     */
+    private waitSpans;
+    init(): void;
+    startWaitSpan(toolCallId: string, rootSpan: Span | undefined, questionCount: number, toolName?: string): void;
+    private endWaitSpan;
+    endWaitSpanExternal(toolCallId: string, success: boolean, error?: Error): void;
+    /**
+     * 兜底：结束并清空所有仍未 end 的 waitSpans。用于 conversation Stop / session 关闭路径，
+     * 覆盖 setAsk 覆盖链之外仍可能残留的 span（例如整轮对话中断、面板未来得及触发 rejectAsk）。
+     */
+    flushPendingWaitSpans(reason: string): void;
+    setAsk(item: RunToolApprovalItem): void;
+    doneAsk(answers: AskAnswers, toolCallId?: string): void;
+    rejectAsk(toolCallId?: string): void;
+    /**
+     * @param timeoutMs Defaults to 10 minutes. Pass `0` (or non-finite) to disable.
+     *                  Safety net against UI messages getting lost (e.g. ACP / IPC
+     *                  channel races, AskPanel cleanup竞速) that would otherwise
+     *                  leave the tool call hanging forever.
+     */
+    acquireAnswers(toolCallId: string, signal?: AbortSignal, timeoutMs?: number): Promise<AskAnswers>;
+    getCurrentAskItem(): RunToolApprovalItem | undefined;
+    getCurrentDeferred(): Deferred<AskAnswers> | undefined;
+    getRoutingState(): {
+        earlyAnswerKeys: string[];
+        waitingDeferredKeys: string[];
+        currentItemId: string | undefined;
+    };
+    private cleanup;
+}

package/cli/dist-server/types/node/ask/index.d.ts

@@ -0,0 +1,3 @@
+export * from './ask-protoctol';
+export * from './ask-service';
+export * from './session-ask-user-question-handler';

package/cli/dist-server/types/node/ask/session-ask-user-question-handler.d.ts

@@ -0,0 +1,25 @@
+import type { Session } from '../../vendor/cbc-core/node/index.js';
+import type { AskAnswers } from './ask-protoctol';
+/**
+ * A per-session answer channel for AskUserQuestion.
+ *
+ * Interactive transports bind this only while they own the physical run.
+ * The handler returns answers in the same shape already consumed by
+ * AskUserQuestionTool, so InterruptionService can reuse its existing
+ * approval + RunState continuation path.
+ */
+export interface SessionAskUserQuestionRequest {
+    toolCallId: string;
+    input: Record<string, unknown>;
+    signal: AbortSignal;
+}
+export type SessionAskUserQuestionHandler = (request: SessionAskUserQuestionRequest) => Promise<AskAnswers>;
+export declare function setSessionAskUserQuestionHandler(session: Session, handler: SessionAskUserQuestionHandler | undefined): void;
+export declare function clearSessionAskUserQuestionHandler(session: Session, owner?: SessionAskUserQuestionHandler): void;
+export declare function getSessionAskUserQuestionHandler(session: Session | undefined): SessionAskUserQuestionHandler | undefined;
+/**
+ * Prefer an explicit child-session binding, then fall back to the root run.
+ * A child agent's approval item is handled against its child Session, while
+ * the A2A task itself owns the root Session.
+ */
+export declare function resolveSessionAskUserQuestionHandler(session: Session | undefined): SessionAskUserQuestionHandler | undefined;

package/cli/dist-server/types/node/authentication/api-key-authentication-storage.d.ts

@@ -0,0 +1,17 @@
+import { ProductManager } from '../../workspace/product/lib/common/index.js';
+import { Subject } from 'rxjs';
+import { SettingsManager } from '../settings';
+import { AuthenticationStorage, AuthSession } from '../../workspace/authentication/lib/common/index.js';
+export declare class ApiKeyAuthenticationStorageImpl implements AuthenticationStorage {
+    protected readonly productManager: ProductManager;
+    protected readonly settingsManager: SettingsManager;
+    storeSessionSubject: Subject<AuthSession | undefined>;
+    protected getEnvironment(): NodeJS.ProcessEnv;
+    priority(): Promise<number>;
+    private getApiKey;
+    store(session: AuthSession): Promise<void>;
+    restore(): Promise<AuthSession | undefined>;
+    clean(): Promise<void>;
+    private getUserId;
+    private getUsername;
+}

package/cli/dist-server/types/node/authentication/custom-token-authentication-storage.d.ts

@@ -0,0 +1,10 @@
+import { AuthSession, CustomTokenAuthenticationStorageImpl } from '../../workspace/authentication/lib/common/index.js';
+import { ApiKeyHelperProductProvider, ProductEnvService } from '../product/index.js';
+export declare const CustomTokenAuthenticationStorage: unique symbol;
+export declare class CliCustomTokenAuthenticationStorageImpl extends CustomTokenAuthenticationStorageImpl {
+    protected readonly productEnvService: ProductEnvService;
+    protected readonly apiKeyHelperProductProvider: ApiKeyHelperProductProvider;
+    protected getSettingsPaths(): readonly string[] | undefined;
+    priority(): Promise<number>;
+    restore(): Promise<AuthSession | undefined>;
+}

package/cli/dist-server/types/node/authentication/file-authentication-storage.d.ts

@@ -0,0 +1,71 @@
+import { type FSWatcher } from 'node:fs';
+import { AuthenticationStorage, type AuthenticationStorageCleanOptions, type AuthenticationStorageStoreOptions, AuthSession } from '../../workspace/authentication/lib/common/index.js';
+import { FilePathService } from '../../workspace/core/lib/common/index.js';
+import { ProductManager } from '../../workspace/product/lib/common/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { Subject } from 'rxjs';
+import { ProductEnvService } from '../product';
+export declare class FileAuthenticationStorage implements AuthenticationStorage {
+    protected readonly filePathService: FilePathService;
+    protected readonly productManager: ProductManager;
+    protected readonly productEnvService: ProductEnvService;
+    protected readonly logger: Logger;
+    storeSessionSubject: Subject<AuthSession | undefined>;
+    /**
+     * CODEBUDDY_CREDENTIALS_IN_MEMORY=1（server 缺省）时的唯一登录态载体：
+     * 凭据文件的读/写/锁/watcher 全部不发生，pod 上不留凭据落盘痕迹。
+     * 宿主注入的 env token 走 custom-token storage，不经此类。
+     */
+    private memorySession;
+    private watcher;
+    private watcherRetryTimer;
+    private watcherStableTimer;
+    private watcherRetryDelayMs;
+    private externalChangeTimer;
+    private readonly reconcileMutex;
+    private disposed;
+    protected initialize(): void;
+    protected credentialsInMemory(): boolean;
+    priority(): Promise<number>;
+    store(session: AuthSession, options?: AuthenticationStorageStoreOptions): Promise<void>;
+    restore(): Promise<AuthSession | undefined>;
+    beginLogout(): Promise<string | undefined>;
+    clean(options?: AuthenticationStorageCleanOptions): Promise<boolean>;
+    /**
+     * Watch the parent directory instead of the auth-file inode. Both this
+     * storage and the WorkBuddy owner commit with temp-file + rename, which
+     * replaces the inode and would detach a watcher bound directly to the file.
+     *
+     * Activation reads storage directly before dispatch. The watcher is only
+     * responsible for auth changes that happen after the CLI becomes active.
+     */
+    private initializeWatcher;
+    protected createDirectoryWatcher(directory: string, listener: (eventType: 'rename' | 'change', filename: string | null) => void): FSWatcher;
+    private scheduleExternalReconcile;
+    private reconcileExternalChange;
+    private readAndApplyFinalState;
+    private writeLogoutMarker;
+    private ownsLogoutMarker;
+    private retireLogoutMarker;
+    private ensureSerializedSession;
+    private encodeSession;
+    private decodeSession;
+    private scheduleCredentialMigration;
+    /**
+     * 迁移写盘前回读临时文件校验：用字段 codec 尝试解密还原。
+     *
+     * 迁移把 legacy 明文重写为含密文字段的凭证文件，若序列化/落盘损坏会导致
+     * 下次读取解密失败、丢失会话。此处在 rename 之前先回读临时文件并 decode，
+     * 任一敏感字段无法解密即抛错——writeCredentialFileAtomically 会清理临时文件、
+     * 保留原文件，迁移失败仅经 onFailure 记录，不影响正常登录写入路径。
+     */
+    private verifyMigratedAuthFile;
+    private createAuthCodec;
+    private createCredentialFailureReporter;
+    private restoreBackupIfAbsent;
+    private scheduleWatcherRetry;
+    private scheduleWatcherStableReset;
+    private clearWatcherStableTimer;
+    protected dispose(): void;
+    getAuthSavePath(): Promise<string>;
+}