@heybox/hb-sdk 0.8.1 → 0.8.2-alpha.2

package/types/modules/companion/index.d.ts

@@ -5,51 +5,1196 @@ import type { FileHandle } from '../files';
 interface CompanionRequester extends MiniProgramOperationRequester {
     on<T extends MiniProgramEventName>(eventName: T, handler: MiniProgramEventHandler<T>): () => void;
 }
+/**
+ * `companion.prepare` 的进度与取消配置。
+ *
+ * @remarks
+ * 所有字段均可省略。SDK 会在发送请求前校验 options 必须是非 `null` 且非数组的对象、
+ * `signal` 必须符合 `AbortSignal` 接口、`onProgress` 必须是函数；不合法时以
+ * `INVALID_PARAMS` 拒绝。
+ *
+ * @see {@link MiniProgramCompanionModule.prepare | companion.prepare}
+ */
 export interface CompanionPrepareOptions {
+    /**
+     * 用于向 Host 发送准备取消意图的信号。
+     *
+     * @remarks
+     * 调用前已经 aborted 时，SDK 在发起 prepare 前以 `COMPANION_PREPARATION_CANCELLED`
+     * 拒绝。操作在途时触发 signal，SDK 会另发 `cancelPreparation(alias)`，但不会使用普通
+     * bridge cancel，也不会仅在页面本地立即 settle；最终结果仍由 Host 的取消与原子提交
+     * 竞态决定。
+     *
+     * 同 alias 的准备由 Host 共享，因此该取消意图针对整项在途准备，不只是移除当前页面的
+     * progress observer，其他 joiner 也可能收到取消结果。页面 reload 本身不会触发这个
+     * signal，也不会自动取消 Host 操作。需要观察取消请求本身是否失败时，显式 await
+     * {@link MiniProgramCompanionModule.cancelPreparation | companion.cancelPreparation}。
+     */
     signal?: AbortSignal;
+    /**
+     * 准备阶段进度回调。
+     *
+     * @remarks
+     * 回调接收经过 Runtime 校验的 {@link CompanionPrepareProgress}：Host 可能报告
+     * `downloading`、`verifying`、`extracting`；下载 `total` 可以省略，其他阶段同时提供
+     * `processed` 与 `total`。加入既有操作时，Host 可以先回放最近进度；不保证页面收到每个
+     * 中间值。回调抛错会被 SDK 隔离，不会取消 Host 操作或改变 prepare 的最终结果。
+     */
     onProgress?: (progress: CompanionPrepareProgress) => void;
 }
+/**
+ * Companion stdout/stderr 单个原始输出 chunk 的同步回调。
+ *
+ * @param data - 当前 handler 独占的新 `Uint8Array` 副本。修改它不会改变 Host 事件、其他 handler
+ * 收到的数据或后续 chunk；数组只表示本次 transport chunk，不携带 stream、sequence、文本编码或
+ * 消息边界。
+ * @returns 返回值会被 SDK 忽略。回调应同步消费或复制所需数据；SDK 不会 await 返回的 Promise。
+ *
+ * @remarks
+ * SDK 不执行文本解码、换行处理、JSON 解析或业务 framing。一个字符或业务消息可能跨多个 chunk，
+ * 多个消息也可能粘在同一 chunk；只有业务协议明确规定 UTF-8 时才应使用 streaming
+ * `TextDecoder`，并仍需自行处理消息边界与跨 controller generation 的重放。
+ *
+ * 同步抛出的异常会被 SDK 隔离，不会阻止同一 chunk 的其他 handler，也不会阻止内部 output ack；
+ * 因为返回值不被 await，异步 handler 的 rejected Promise 不属于该隔离范围，应在回调内部自行捕获。
+ *
+ * @see {@link CompanionStdio.onStdout}
+ * @see {@link CompanionStdio.onStderr}
+ */
 export type CompanionOutputHandler = (data: Uint8Array) => void;
+/**
+ * Companion Session 退出时调用的同步回调。
+ *
+ * @param exit - Runtime 校验并冻结的 {@link CompanionExit} 一次性退出结果。`reason: 'exited'` 时
+ * 必有 safe-integer `exitCode`；其他 reason 的 `exitCode` 可能缺省，调用方不应自行补 `0`。
+ * @returns 返回值会被 SDK 忽略；回调不会被 await。
+ *
+ * @remarks
+ * 同一 Session 只接受第一条有效退出事件。退出结果不是 controller ownership 转移、stdin 关闭或
+ * `terminate()` 请求的返回值；它表示 Host 确认的真实进程终态。回调可能在事件到达时同步执行，
+ * 也可能在 Session 已退出后通过 {@link CompanionSession.onExit | onExit()} 注册时同步重放。
+ *
+ * SDK 不会捕获该回调的同步异常；需要隔离异常时应在 handler 内自行 `try/catch`。因为回调返回值
+ * 不会被 await，async handler 的 rejected Promise 也不会由 SDK 接管。
+ *
+ * @see {@link CompanionExit}
+ * @see {@link CompanionSession.onExit}
+ * @see {@link CompanionSession.waitForExit}
+ */
 export type CompanionExitHandler = (exit: CompanionExit) => void;
+/** 当前 Runtime 失去 Session controller 时调用的回调。 */
+/**
+ * Companion Session controller 转移时调用的无参同步回调。
+ *
+ * @returns 返回值会被 SDK 忽略；回调不会被 await。同步异常不会由 SDK 隔离，业务应在 handler
+ * 内自行捕获；async handler 的 rejected Promise 也不会由 SDK 接管。
+ *
+ * @remarks
+ * 该回调只表示当前 Runtime 不再拥有控制权，不提供新旧 generation、Session ID 或退出原因。
+ * 需要恢复控制时调用 {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession}；
+ * 需要知道进程是否退出时使用 {@link CompanionSession.onExit | onExit()} 或
+ * {@link CompanionSession.waitForExit | waitForExit()}。
+ *
+ * @see {@link CompanionSession.onOwnershipLost}
+ * @see {@link CompanionSession.onExit}
+ * @see {@link CompanionSession.waitForExit}
+ */
 export type CompanionOwnershipLostHandler = () => void;
+/** Session 的生命周期状态；退出后不会回到 `running`。 */
 export type CompanionState = 'running' | 'exited';
+/**
+ * Companion Session 状态变化回调。
+ *
+ * @param state - 新状态。当前 SDK 只在收到首次合法退出事件时调用 handler 一次，值为 `'exited'`；
+ * 初始 `'running'` 不会在注册时回放。
+ * @returns 返回值会被 SDK 忽略；回调同步执行，返回的 Promise 不会被等待。
+ *
+ * @remarks
+ * controller ownership 转移、stdin 关闭、输出重放和权限变化都不是状态变化，不会调用本 handler。
+ * 需要知道控制权是否仍归当前 Runtime 时使用
+ * {@link CompanionSession.onOwnershipLost | CompanionSession.onOwnershipLost()}；需要退出原因、
+ * exit code 或在退出后注册时的即时回放时使用 {@link CompanionSession.onExit | onExit()}。
+ */
 export type CompanionStateChangeHandler = (state: CompanionState) => void;
+/**
+ * 请求 Host 展示的固定类别通知。
+ *
+ * @remarks
+ * 页面只选择语义类别，通知标题、正文、图标、按钮、声音和其他系统展示细节均由 Host 根据当前
+ * Mini-program、Companion 与平台规则生成。该对象不是原生 Notification options，也不允许页面
+ * 注入任意通知文本。
+ */
 export interface CompanionNotification {
+    /**
+     * 固定通知类别：`completed` 表示任务完成，`failed` 表示失败，`stopped` 表示已停止，
+     * `attention` 表示需要用户关注。Host 负责把类别转换成最终本地化通知内容。
+     */
     category: CompanionNotificationCategory;
 }
+/**
+ * Companion 的标准输入输出能力。
+ *
+ * 仅当 Manifest 声明 `stdio` 且当前 Host 返回该能力时存在。传输的是原始字节，
+ * 不保证一次 write 对应一次 stdout/stderr 回调；业务协议必须自行处理 framing、拆包和重复。
+ */
 export interface CompanionStdio {
+    /**
+     * 向当前 Companion Session 的 stdin 写入原始字节。
+     *
+     * @param data - 要写入的 `Uint8Array`。SDK 只复制当前 view 覆盖的字节区间；`byteOffset` 之外的
+     * backing buffer 内容不会发送。空 `Uint8Array` 合法并会交给 Host，但不应把空写入当作 flush、
+     * EOF 或消息分隔符。
+     * @returns Host 确认本次 stdin 写入请求完成后以 `undefined` resolve。该时点不返回写入字节数，
+     * 也不表示 Companion 已读取、解析或处理数据，更不保证会产生 stdout/stderr。
+     * @throws {@link HbMiniProgramSDKError} `data` 不是当前 realm 的 ArrayBuffer-backed `Uint8Array`，
+     * 或使用 `SharedArrayBuffer` backing 时，在发送 bridge 请求前返回 `INVALID_PARAMS`。普通数组、
+     * `ArrayBuffer`、`DataView`、其他 typed array 也不会被隐式转换。
+     * @throws {@link HbMiniProgramSDKError} 当前 proxy 已知 Session 已退出时返回
+     * `COMPANION_SESSION_EXITED`；controller 已转移给其他 Runtime generation 时返回
+     * `COMPANION_SESSION_OWNERSHIP_LOST`。检查与 Host 写入之间仍存在竞态，Host 会用私有
+     * controller generation 再次拒绝过期调用。
+     * @throws {@link HbMiniProgramSDKError} stdin 已由 {@link CompanionStdio.closeStdin | closeStdin()}
+     * 关闭、Session 不再提供 `stdio` 或通信管道不可用时返回 `COMPANION_PIPE_CLOSED`；进程异常退出
+     * 或因输出上限结束时还可能返回 `COMPANION_PROCESS_CRASHED` / `COMPANION_OUTPUT_LIMIT`。
+     * @throws {@link HbMiniProgramSDKError} 未声明或未获批 `companion` 权限时返回
+     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放 `companion.session.write` 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。未知 Host 失败会脱敏并返回
+     * `COMPANION_HOST_FAILED`；SDK/Runtime 终止或请求超时还可能返回 `SDK_DESTROYED`、
+     * `RUNTIME_UNAVAILABLE`、`REQUEST_TIMEOUT`。
+     *
+     * @remarks
+     * `stdio` 只在 Session 快照的 capability 集合包含 `'stdio'` 时存在；调用前必须按
+     * `session.stdio` 是否存在分支。它是已声明并经平台批准的 `companion` 高风险能力的一部分，
+     * 不要求新的可信用户手势；但持有 `CompanionStdio` 对象不代表 controller、进程或管道之后一直有效。
+     * `session.state === 'running'` 也不能证明当前 Runtime 仍持有 controller，因为 ownership 转移不会
+     * 结束进程。
+     *
+     * SDK 在调用时同步复制 `data` 的可见字节，Runtime 在调用 Host 前再制作一份副本；调用返回后修改
+     * 原数组或 backing buffer 不会改变本次 payload。两层都只接受普通 `ArrayBuffer` backing，拒绝
+     * `SharedArrayBuffer`，因此该 API 不建立跨 bridge 共享内存。SDK 没有公开 stdin 单次写入大小上限，
+     * 也不会自动分块；实际可接受大小仍受 Host、IPC 和操作系统管道限制，不能据此假定无限写入。
+     *
+     * 字节不会经过 UTF-8 解码、换行处理、JSON 序列化或其他内容转换。stdin 是 byte stream，不保留
+     * JavaScript `write()` 调用边界：一次写入可被 Companion 分段读取，多次写入也可被合并。业务必须
+     * 自己定义长度前缀、转义或其他 framing，并在需要确定顺序时逐次 `await`，不要并发写入后依赖完成顺序。
+     *
+     * {@link CompanionStdio.onStdout | onStdout()} 和 {@link CompanionStdio.onStderr | onStderr()} 是独立的
+     * 异步输出流；单次写入可能对应零个、一个或多个输出 chunk，输出也可能在本 Promise settle 前后到达。
+     * 应在写入前订阅，并让业务 framing 自带关联 ID。Host 输出采用 at-least-once 投递；SDK 会在同一
+     * controller generation 内按 stream sequence 抑制已见 replay 并确认它，但 controller 转移、页面 reload
+     * 或业务重连后仍应自行处理重放和去重。
+     *
+     * `closeStdin()` 是不可逆的输入半关闭，不等于终止 Session；关闭后 stdout/stderr 和退出事件仍可继续。
+     * 应先依次 await 所有业务帧写入，再关闭 stdin；不要让 `write()` 与 `closeStdin()` 并发竞态。失去
+     * controller 后不要自动重试不确定是否已提交的写入，否则可能向进程重复发送业务命令。需要明确恢复控制时，
+     * 由业务调用 {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession}，再按自己的
+     * 幂等协议决定是否重发。
+     *
+     * V1 真实 Companion stdio 仅支持新 PC Host 的 Windows x64 与 macOS arm64；Browser Dev Host
+     * 提供确定性 Fake 用于验证 framing、输出和错误 UI，不执行真实程序。其他平台、旧 Host 或缺少
+     * `companion.session.write` operation 时 fail closed，不提供 WebSocket、worker 或 shell fallback。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const session = await hbSDK.companion.getActiveSession('runner')
+     * const stdio = session?.stdio
+     * if (session && stdio) {
+     *   const stopStdout = stdio.onStdout(chunk => consumeBusinessFrames(chunk))
+     *   const stopStderr = stdio.onStderr(chunk => appendDiagnosticBytes(chunk))
+     *   const stopOwnership = session.onOwnershipLost(() => disableCompanionControls())
+     *
+     *   try {
+     *     // encodeBusinessFrame 自行添加长度、消息 ID 等业务 framing。
+     *     await stdio.write(encodeBusinessFrame({ id: 'status-1', type: 'status' }))
+     *     await stdio.closeStdin()
+     *     await session.waitForExit() // 保留输出订阅，直到进程结束。
+     *   } catch (error) {
+     *     if (
+     *       error instanceof HbMiniProgramSDKError &&
+     *       (error.code === 'COMPANION_PIPE_CLOSED' || error.code === 'COMPANION_SESSION_OWNERSHIP_LOST')
+     *     ) {
+     *       disableCompanionControls()
+     *     } else {
+     *       throw error
+     *     }
+     *   } finally {
+     *     stopStdout()
+     *     stopStderr()
+     *     stopOwnership()
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link CompanionStdio.closeStdin}
+     * @see {@link CompanionStdio.onStdout}
+     * @see {@link CompanionStdio.onStderr}
+     * @see {@link CompanionOutputHandler}
+     * @see {@link CompanionSession.onOwnershipLost}
+     * @see {@link CompanionSession.waitForExit}
+     * @see {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/companion | 受管桌面程序}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
+     * @since 0.8.1-alpha.4
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     write(data: Uint8Array): Promise<void>;
+    /**
+     * 不可逆地关闭当前 Companion Session 的 stdin 写入端。
+     *
+     * @returns 当前 controller 对应的 Host 确认 stdin close 请求完成后以 `undefined` resolve。该时点只
+     * 表示输入半关闭已由 Host 接受，不返回退出码，不等待 Companion 消费完先前输入、stdout/stderr
+     * 排空或进程退出；使用 {@link CompanionSession.waitForExit | waitForExit()} 等待进程终态。
+     * @throws {@link HbMiniProgramSDKError} 当前 proxy 已知 Session 已退出时返回
+     * `COMPANION_SESSION_EXITED`；controller 已转移给其他 Runtime generation 时返回
+     * `COMPANION_SESSION_OWNERSHIP_LOST`。本地检查与 Host 执行之间仍存在竞态，Host 会用私有
+     * controller generation 再次拒绝过期调用。
+     * @throws {@link HbMiniProgramSDKError} stdin 已关闭、Session 不再提供 `stdio` 或通信管道不可用时
+     * 可返回 `COMPANION_PIPE_CLOSED`；进程异常退出或因输出上限结束时还可能返回
+     * `COMPANION_PROCESS_CRASHED` / `COMPANION_OUTPUT_LIMIT`。
+     * @throws {@link HbMiniProgramSDKError} 未声明或未获批 `companion` 权限时返回
+     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放
+     * `companion.session.closeStdin` 时返回 `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
+     * 未识别的 Host 失败会脱敏为 `COMPANION_HOST_FAILED`；SDK / Runtime 终止、不可用或请求超时还
+     * 可能返回 `SDK_DESTROYED`、`RUNTIME_UNAVAILABLE`、`REQUEST_TIMEOUT`。
+     *
+     * @remarks
+     * `closeStdin()` 是一次性的输入半关闭，不是 flush、取消、{@link CompanionSession.terminate | terminate()}
+     * 或“请求进程退出”的别名。成功后不能重新打开 stdin，后续 {@link CompanionStdio.write | write()}
+     * 会失败；但 Companion 仍可继续运行、处理已经收到的字节并产生 stdout/stderr，Session 的
+     * `state` 也会保持 `'running'`，直到 Host 发送独立退出事件。
+     *
+     * SDK 不维护公开的 `stdinClosed` 状态，也不会合并或短路重复调用；每次调用都会携带当前私有
+     * controller generation 发往 Host。重复关闭不属于公共幂等保证：不同 Host 可能重复确认，也可能
+     * 返回 `COMPANION_PIPE_CLOSED`。业务应只关闭一次；若请求失败或超时，Host 是否已经完成关闭可能
+     * 无法从该错误判断，不要无条件自动重试。
+     *
+     * SDK 不会在 {@link CompanionStdio.write | write()} 与 `closeStdin()` 之间建立队列。要发送最后一帧，
+     * 应先逐次 `await` 所有 write，再调用一次 close；并发调用会产生由实际请求到达顺序决定的竞态，
+     * 最后的 write 可能因管道已关闭而失败。空 `Uint8Array` 写入也不是 EOF，只有本方法表达 stdin EOF。
+     *
+     * 该调用要求 Session 快照包含 `'stdio'`（否则 `session.stdio` 为 `undefined`）、进程尚未退出，且当前
+     * Runtime generation 仍持有 controller。`session.state === 'running'` 本身不能证明仍有控制权；应监听
+     * {@link CompanionSession.onOwnershipLost | onOwnershipLost()} 并立即停止新的 write/close 操作。失去
+     * controller 或关闭 stdin 都不会让 {@link CompanionSession.waitForExit | waitForExit()} 提前完成；
+     * 后者仍绑定同一个进程的真实退出事件。
+     *
+     * 该方法属于已声明并经平台批准的 `companion` 高风险能力，不要求新的可信用户手势。V1 真实
+     * Companion stdio 仅支持新 PC Host 的 Windows x64 与 macOS arm64；Browser Dev Host 提供确定性
+     * Fake，其他平台、旧 Host 或 operation 缺失时 fail closed，不提供 WebSocket、worker 或 shell
+     * fallback。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const session = await hbSDK.companion.getActiveSession('runner')
+     * const stdio = session?.stdio
+     * if (session && stdio) {
+     *   const stopStdout = stdio.onStdout(chunk => consumeBusinessFrames(chunk))
+     *   const stopStderr = stdio.onStderr(chunk => appendDiagnosticBytes(chunk))
+     *
+     *   try {
+     *     await stdio.write(encodeBusinessFrame({ type: 'finish' }))
+     *     await stdio.closeStdin() // 只调用一次，并且在最后一次 write 完成之后。
+     *
+     *     // stdin 已关闭后输出仍可能继续；进程终态以 waitForExit() 为准。
+     *     const exit = await session.waitForExit()
+     *     console.log(exit)
+     *   } finally {
+     *     stopStdout()
+     *     stopStderr()
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link CompanionStdio.write | CompanionStdio.write()} 在关闭前写入原始字节。
+     * @see {@link CompanionStdio.onStdout | CompanionStdio.onStdout()} 订阅关闭后仍可能到达的标准输出。
+     * @see {@link CompanionStdio.onStderr | CompanionStdio.onStderr()} 订阅关闭后仍可能到达的标准错误。
+     * @see {@link CompanionSession.waitForExit | CompanionSession.waitForExit()} 等待独立的进程退出终态。
+     * @see {@link CompanionSession.onOwnershipLost | CompanionSession.onOwnershipLost()} 监听 controller 转移。
+     * @see {@link CompanionSession.terminate | CompanionSession.terminate()} 显式请求终止进程。
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/companion | 受管桌面程序}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     */
     closeStdin(): Promise<void>;
+    /**
+     * 订阅当前 Companion Session 的 stdout 原始字节 chunk。
+     *
+     * @param handler - 每个新 stdout chunk 的同步 {@link CompanionOutputHandler}。必须是函数；SDK
+     * 不会向它传入 sequence、controller generation、文本、错误或退出状态。
+     * @returns 同步返回取消订阅函数。调用后只移除当前 SDK proxy 上的本地 handler，不关闭 stdout、
+     * 不发送 Host unsubscribe、不关闭 stdin，也不终止 Session。重复调用取消函数安全且不会抛错。
+     * @throws {@link HbMiniProgramSDKError} `handler` 不是函数时同步抛出 `INVALID_PARAMS`。订阅本身
+     * 不发 bridge 请求，因此不会因权限、ownership、Session 已退出或 Host event source 缺失而拒绝。
+     *
+     * @remarks
+     * 该方法只在 `session.stdio` 存在时可调用；`stdio` 是否存在由 Session 快照的
+     * `capabilities` 是否包含 `'stdio'` 决定。没有该 capability 时整个 `session.stdio` 为
+     * `undefined`，调用方必须先分支。注册不要求新的可信用户手势，也不额外请求权限；Session 后续
+     * 仍可能因权限撤销、进程退出或 controller 转移而停止投递。
+     *
+     * stdout 是原始 byte stream，不是一次 {@link CompanionStdio.write | write()} 对应一次回调的消息
+     * 通道。SDK 不定义字符编码，也不保证 chunk 与换行、JSON、RPC frame 或业务消息对齐；业务必须
+     * 自行处理拆包、粘包和 framing。handler 每次收到独立的新 `Uint8Array` 副本，同一事件的其他
+     * handler 也收到各自副本，因此一个 handler 修改 bytes 不会污染另一个 handler。
+     *
+     * Host 输出按 at-least-once 语义投递。Runtime 先拒绝非法 Session ID、stream、generation、
+     * sequence 或 bytes；SDK 再在当前 controller generation 内分别为 stdout/stderr 记录最后一个
+     * sequence。已见或倒退的 stdout sequence 不会再次调用 handler，但有效 replay 仍会 best-effort
+     * 发送内部 `companion.session.ackOutput`；ack 失败不会转交给业务，也不会让本方法抛错。controller
+     * 转移、重新取得控制、页面 reload 或业务重连会形成新的去重边界，业务 frame 仍应携带自己的
+     * 幂等 ID，不能把 SDK 的 generation 内去重当作端到端 exactly-once 保证。
+     *
+     * handler 的同步异常会被隔离：其他 stdout handler 仍会收到同一 chunk，内部 ack 也仍会尝试。
+     * SDK 忽略 handler 返回值且不会 await Promise；若传入 async 函数，需在函数内部处理 rejected
+     * Promise。取消函数仅影响未来本地分发，已经开始执行的回调不会被中断。
+     *
+     * 订阅没有历史回放或本地缓冲。事件到达时即使没有 handler，SDK 仍可确认并丢弃该 chunk，之后
+     * 注册不会补发；应在调用 `write()` 或触发 Companion 输出之前订阅。Session exit 会清除当前已
+     * 注册的 stdout/stderr handlers，退出后不会再投递。调用取消函数后 Host 仍可继续产生输出并由
+     * SDK 内部确认，取消订阅不能用于流控或阻止 Companion 达到输出上限。
+     *
+     * ownership 丢失时，旧 proxy 不再分发旧 controller generation 的 output。调用
+     * {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession} 取得同一 Session
+     * 的更新 controller 后，SDK 会复用同一 proxy，保留已注册 handler，并为新 generation 重置
+     * stdout/stderr sequence 去重状态；业务仍需处理 Host 重放。若不希望恢复后继续接收，应在
+     * `onOwnershipLost()` 中调用本方法返回的取消函数。
+     *
+     * Host 集成还必须提供 `HostCompanionPort.onSessionEvent()` 事件源。当前该 Host Port 成员是可选的：
+     * 若 Host 返回含 `stdio` 的 Session，却没有接入事件源，本方法仍会成功注册，但 stdout、exit 与
+     * ownership 事件都不会到达 SDK，且没有轮询或 WebSocket fallback。Mini-program 无法通过本方法
+     * 检测该集成缺口；Host/Runtime 集成方应把 Session event source 作为可用 stdio 输出的必要条件。
+     *
+     * V1 真实 Companion stdio 仅支持新 PC Host 的 Windows x64 与 macOS arm64；Browser Dev Host
+     * 提供确定性 Fake 以验证 bytes、ack、framing 和错误 UI，不执行真实程序。其他平台、旧 Host 或
+     * 未开放 Companion 的环境不会提供可用 Session stdio。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const session = await hbSDK.companion.getActiveSession('runner')
+     * const stdio = session?.stdio
+     *
+     * if (session && stdio) {
+     *   // 仅当 Companion 业务协议规定 stdout 是 UTF-8 行文本时这样解码。
+     *   const decoder = new TextDecoder()
+     *   let pending = ''
+     *
+     *   const stopStdout = stdio.onStdout(bytes => {
+     *     pending += decoder.decode(bytes, { stream: true })
+     *     const lines = pending.split('\n')
+     *     pending = lines.pop() ?? ''
+     *     for (const line of lines) console.log(line)
+     *   })
+     *   const stopOwnership = session.onOwnershipLost(stopStdout)
+     *
+     *   session.onExit(() => {
+     *     pending += decoder.decode()
+     *     if (pending) console.log(pending)
+     *     stopStdout()
+     *     stopOwnership()
+     *   })
+     * }
+     * ```
+     *
+     * @see {@link CompanionOutputHandler}
+     * @see {@link CompanionStdio.onStderr | CompanionStdio.onStderr()} 订阅独立的 stderr stream。
+     * @see {@link CompanionStdio.write | CompanionStdio.write()} 向 stdin 写入原始字节。
+     * @see {@link CompanionSession.onOwnershipLost | CompanionSession.onOwnershipLost()} 观察 controller 转移。
+     * @see {@link CompanionSession.onExit | CompanionSession.onExit()} 在进程退出时完成 decoder 并清理订阅。
+     * @see {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession} 恢复活动 Session controller。
+     * @see [受管桌面程序](/guide/companion) 查看 stdio framing、重放与恢复流程。
+     *
+     * @since 0.8.1-alpha.4
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     onStdout(handler: CompanionOutputHandler): () => void;
+    /**
+     * 订阅当前 Companion Session 的 stderr 原始字节流。
+     *
+     * @param handler - 每个新 stderr chunk 到达时同步调用的处理函数。参数是 SDK 为当前 handler
+     * 单独复制的 `Uint8Array`；修改它不会改变 Host payload，也不会影响同一事件的其他 handler。
+     * @returns 取消当前 handler 的同步函数。可调用一次或多次；取消后不再接收未来 chunk，不会关闭
+     * stderr、stdin 或 Session，也不会取消其他 handler。相同函数引用重复订阅按 Set 语义只保留一项，
+     * 任一对应取消函数都会移除该项。
+     * @throws {@link HbMiniProgramSDKError} `handler` 不是函数时同步抛出 `INVALID_PARAMS`。订阅本身不发送
+     * bridge 请求，因此不会因权限、Host operation、Session 退出或 controller ownership 状态异步拒绝。
+     *
+     * @remarks
+     * `session.stdio` 只在 Session capability 集合包含 `'stdio'` 时存在；调用前必须先判空。取得
+     * Session 仍受已声明并经平台批准的 `companion` 权限、当前版本产物和 Host 支持约束，但本地注册
+     * handler 不要求新的可信用户手势，也不重新校验权限。Host 没有 Session event source 的兼容集成
+     * 即使返回了 `stdio`，订阅也只是成功注册本地 handler，之后不会收到输出事件；它不会轮询、报错或
+     * 从 `write()` 响应中推导 stderr。
+     *
+     * stderr 与 {@link CompanionStdio.onStdout | onStdout()} 使用相同的原始字节、sequence、去重和确认
+     * 合同，但两条流相互独立：各自维护最近 sequence 和 handler 集合，相同 sequence 数字可以分别在
+     * stdout 与 stderr 出现。字节不会自动按 UTF-8、换行、JSON 或消息边界解码；一个逻辑诊断可能被
+     * 拆到多个 chunk，一个 chunk 也可能含多条诊断。stderr 只是 Companion 进程选择的第二输出流，
+     * 收到数据不等于进程失败，退出结果应通过 {@link CompanionSession.waitForExit} 或
+     * {@link CompanionSession.onExit} 判断。
+     *
+     * 对当前 controller generation，每条格式合法且 sequence 大于本流已见水位的事件最多向业务
+     * handler 投递一次。较旧或重复的 sequence 不会再次投递，但 SDK 仍会发送 best-effort
+     * `companion.session.ackOutput`；即使没有 stderr handler 或某个 handler 抛错，也会继续确认。
+     * ack 是 SDK 内部 fire-and-forget 请求，失败会被吞掉，不会回调 handler，也不表示 Host 一定停止
+     * 重放。因此 Host 输出是 at-least-once，业务跨 controller 转移、页面 reload 或重连仍应按自己的
+     * framing / 消息 ID 处理重放和去重。
+     *
+     * handler 按注册集合顺序同步执行，返回值会被忽略，Promise 不会被等待。每个 handler 的同步异常
+     * 都被 SDK 单独捕获，不会阻断同一 chunk 的其他 handler 或 ack；异步 handler 的 rejected Promise
+     * 不会被 SDK 捕获，应在 handler 内显式处理。订阅不会重放注册前的 stderr，也不能读取历史缓冲区。
+     *
+     * Session 退出后，SDK 会清空 stdout/stderr handler；已有取消函数仍可安全调用。controller ownership
+     * 丢失后，旧 generation 的输出被忽略且不会确认，已有订阅不会因此收到错误或自动取消；调用方应同时
+     * 监听 {@link CompanionSession.onOwnershipLost} 并停止依赖旧 controller。之后通过
+     * {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession} 取得同一 Session 的
+     * 新 controller generation 时，SDK 会重置两条流的 sequence 水位，当前 proxy 上尚未取消的 handler
+     * 可以继续接收新 generation 输出。其他 Session ID、非法字节、非法 sequence、generation 不匹配以及
+     * 已退出 Session 的事件都会被丢弃。
+     *
+     * {@link CompanionStdio.write | write()} 只向 stdin 写入原始字节，不保证产生 stderr，也不保证一次
+     * write 对应一次回调。需要捕获启动后的早期诊断时，应在 write 前订阅，并在 Session 退出或页面销毁
+     * 时调用取消函数。V1 真实 Companion stdio 仅支持新 PC Host 的 Windows x64 与 macOS arm64；
+     * Browser Dev Host 的确定性 Fake 只用于联调，不能替代真实进程验收。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const session = await hbSDK.companion.getActiveSession('runner')
+     * if (session?.stdio) {
+     *   const decoder = new TextDecoder()
+     *   const stopStderr = session.stdio.onStderr(bytes => {
+     *     // stream: true 保留跨 chunk 的 UTF-8 解码状态；协议 framing 仍需业务自行处理。
+     *     appendDiagnosticText(decoder.decode(bytes, { stream: true }))
+     *   })
+     *   const stopOwnership = session.onOwnershipLost(() => {
+     *     disableCompanionControls()
+     *   })
+     *
+     *   try {
+     *     await session.stdio.write(encodeBusinessFrame({ type: 'status' }))
+     *     await session.waitForExit()
+     *     appendDiagnosticText(decoder.decode())
+     *   } finally {
+     *     stopStderr()
+     *     stopOwnership()
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link CompanionOutputHandler}
+     * @see {@link CompanionStdio.onStdout}
+     * @see {@link CompanionStdio.write}
+     * @see {@link CompanionStdio.closeStdin}
+     * @see {@link CompanionSession.onOwnershipLost}
+     * @see {@link CompanionSession.onExit}
+     * @see {@link CompanionSession.waitForExit}
+     * @see {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/companion | 受管桌面程序}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     */
     onStderr(handler: CompanionOutputHandler): () => void;
 }
+/**
+ * Companion 产生的受控附件访问能力。
+ *
+ * `id` 是 Companion 业务协议中的不透明标识，不是路径、URL 或文件句柄；返回的文件只能按
+ * 当前 `FileHandle` 权限读取。
+ */
 export interface CompanionAttachments {
+    /**
+     * 按 Companion 业务协议中的 opaque ID 打开一个受控附件。
+     *
+     * @param id - Companion 自己产生并通过业务协议交给页面的附件 ID。SDK 只要求它是长度大于 `0` 的
+     * string，不 trim、不限制格式或长度；空字符串和非字符串在发送请求前返回 `INVALID_PARAMS`。
+     * 空白字符串虽通过本地结构校验，通常仍会由 Host 按未知 ID 拒绝。
+     * @returns 当前 Runtime session 中新注册的冻结 {@link FileHandle} direct proxy。`kind` 固定为
+     * `'file'`，`mode` 固定衰减为 `'read'`，`name` 是 Host 提供并经校验的 basename；不返回物理路径、
+     * 原生句柄、URL、controller generation 或可持久化的 wire ref。
+     * @throws {@link HbMiniProgramSDKError} `id` 为空或不是 string 时返回 `INVALID_PARAMS`；Host 找不到
+     * 当前 Session 对应的 ID、该 ID 已失效或 Session 没有 attachments capability 时通常返回
+     * `COMPANION_ATTACHMENT_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} 当前 proxy 已知 Session 已退出时返回
+     * `COMPANION_SESSION_EXITED`；controller 已转移给其他 Runtime generation 时返回
+     * `COMPANION_SESSION_OWNERSHIP_LOST`。本地检查与 Host 打开之间存在竞态，Host 会用未公开的
+     * controller generation 再次校验当前调用。
+     * @throws {@link HbMiniProgramSDKError} 未声明或未获批 `companion` 权限时返回
+     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放 `companion.openAttachment` 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。Host 不支持 Companion 或附件描述符
+     * 暂不可用时还可能返回 `COMPANION_UNSUPPORTED` / `COMPANION_DESCRIPTOR_UNAVAILABLE`。
+     * @throws {@link HbMiniProgramSDKError} 当前 Runtime session 的 direct handles 已达到 1024 上限时
+     * 返回 `FILE_QUOTA_EXCEEDED`。Host 返回的对象不是完整 File capability、名称/mode/ref 非法、不是
+     * 精确 direct File，或 Runtime 无法注册安全 opaque handle 时返回 `FILE_IO_FAILED`；其他未知 Host
+     * 失败会脱敏为 `COMPANION_HOST_FAILED`。SDK/Runtime 终止或请求超时还可能返回
+     * `SDK_DESTROYED`、`RUNTIME_UNAVAILABLE`、`REQUEST_TIMEOUT`。
+     *
+     * @remarks
+     * `id` 是当前 Companion 业务协议的不透明标识，不是路径、文件名、URL、下载地址或系统 bookmark。
+     * 页面不能用 `../`、绝对路径或自己拼接的字符串访问任意文件，也不应解析 ID 推断物理位置。Host
+     * 将 ID 解析为当前 Session 明确暴露的一个附件，并只把对应 File capability 交给 Runtime。
+     * `open()` 本身不读取内容，也不根据扩展名推断格式。
+     *
+     * `session.attachments` 仅在 Session 快照的 capability 集合包含 `'attachments'` 时存在；调用前应按
+     * 属性是否存在分支。打开动作需要当前 Runtime 持有 Session controller，但不要求新的可信用户手势。
+     * `session.state === 'running'` 不能证明仍有控制权；有 Session event source 时应监听
+     * {@link CompanionSession.onOwnershipLost | onOwnershipLost()} 并停止新的 `open()`。自定义 Host 缺少
+     * event source 时本地状态可能不会主动更新，但 Host 仍必须拒绝旧 generation，不能把事件监听当作授权边界。
+     *
+     * 成功后附件 provenance 保存在 Runtime 文件 registry 中，不进入公开 proxy。返回句柄是独立的当前
+     * Runtime session 能力：SDK 不会仅因随后收到 ownership-lost 或 exit 事件就在本地删除它，但 Host 可随
+     * Session、授权或底层附件生命周期撤销访问，后续读取会以 `FILE_ACCESS_REVOKED` 等错误失败。因此不能
+     * 序列化、跨页面保存或假定它在 controller 转移/进程退出后仍可读；需要新句柄时先明确取得当前 controller
+     * 并重新按业务 ID 打开。
+     *
+     * 每次成功 `open()` 都注册一个新的 direct handle，即使 ID 相同也不缓存或复用 proxy，并与
+     * `files.pickFiles()`、`files.pickDirectory()`、`files.saveFile()` 共享当前 Runtime session 的 1024
+     * handle 上限。页面应复用已经返回的 FileHandle，避免循环重复打开同一 ID；Runtime session 结束时
+     * registry 会统一失效。
+     *
+     * 返回句柄始终只读，即使底层 Host File 原本可写：`create()`、`writeText()`、`writeBytes()` 和
+     * `remove()` 都会以 `FILE_ACCESS_DENIED` 拒绝，也不能从中派生父目录或兄弟文件。已启用的
+     * `companion` 权限只为 registry 证明 provenance 的附件开放 {@link FileHandle.readText | readText()}、
+     * {@link FileHandle.readBytes | readBytes()} 和 {@link FileHandle.stat | stat()}；这三项不要求另行声明
+     * `filesystem`。其他 FileHandle operation 不因 attachment provenance 获得通用 filesystem 权限。
+     *
+     * `readText()` / `readBytes()` 都会把完整附件载入内存，没有公开 stream、range read 或自动分段 API。
+     * `open()` 不受文件内容大小影响，但后续读取仍受实际 PC Host 的单次 I/O 与内存限制，可能返回
+     * `FILE_TOO_LARGE`；新 PC Host 没有公开沿用 Android/iOS 的固定 8 MiB 上限。可先用 `stat()` 做业务
+     * 大小门槛，但附件可能在两次异步调用之间变化，stat 与 read 不是原子操作。
+     *
+     * V1 真实 attachments 仅支持实现该 capability 的新 PC Host（Windows x64 / macOS arm64）；
+     * Browser Dev Host 只提供 ID 为 `'report'` 的确定性 Fake 文件，用于验证 UI 与读取流程，不访问本机
+     * 任意路径。其他平台、旧 Host 或 operation 缺失时 fail closed，不提供浏览器 File / Blob、URL fetch
+     * 或内存 fallback。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const session = await hbSDK.companion.getActiveSession('runner')
+     * const attachments = session?.attachments
+     * if (session && attachments) {
+     *   let ownsController = true
+     *   const stopOwnership = session.onOwnershipLost(() => {
+     *     ownsController = false
+     *   })
+     *
+     *   try {
+     *     const attachmentId = readAttachmentIdFromBusinessFrame()
+     *     if (!ownsController) return
+     *
+     *     const file = await attachments.open(attachmentId)
+     *     const stat = await file.stat()
+     *     if (stat.size > 4 * 1024 * 1024) throw new Error('附件超过业务读取上限')
+     *
+     *     const bytes = await file.readBytes()
+     *     consumeAttachment(file.name, bytes)
+     *   } catch (error) {
+     *     if (
+     *       error instanceof HbMiniProgramSDKError &&
+     *       (error.code === 'COMPANION_ATTACHMENT_NOT_FOUND' ||
+     *         error.code === 'COMPANION_SESSION_OWNERSHIP_LOST')
+     *     ) {
+     *       showAttachmentUnavailable()
+     *     } else {
+     *       throw error
+     *     }
+     *   } finally {
+     *     stopOwnership()
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link FileHandle}
+     * @see {@link FileHandle.readText}
+     * @see {@link FileHandle.readBytes}
+     * @see {@link FileHandle.stat}
+     * @see {@link CompanionSession.onOwnershipLost}
+     * @see {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/companion | 受管桌面程序}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
+     * @since 0.8.1-alpha.4
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     open(id: string): Promise<FileHandle>;
 }
+/** Companion 请求 Host 展示固定类别系统通知的能力。 */
 export interface CompanionNotifications {
+    /**
+     * 请求 Host 为当前 Companion Session 展示固定类别的系统通知。
+     *
+     * @param input - 必须是包含合法 `category` 的非数组对象，详见 {@link CompanionNotification}。
+     * 支持 `completed`、`failed`、`stopped`、`attention` 四类。缺失或其他值返回 `INVALID_PARAMS`。
+     * JavaScript 传入的额外字段会被忽略并从 bridge payload 移除，不会作为自定义标题、正文、按钮、
+     * URL 或原生通知参数传给 Host。
+     * @returns Host 确认本次通知请求已处理后以 `undefined` resolve。不返回通知 ID，也不保证操作系统
+     * 最终展示、用户看见或点击通知；系统通知权限、免打扰和平台投递策略仍由 Host / 操作系统决定。
+     * @throws {@link HbMiniProgramSDKError} input 缺失、不是对象、是数组，或 `category` 不在四个固定值中
+     * 时，在发送 bridge 请求前返回 `INVALID_PARAMS`。
+     * @throws {@link HbMiniProgramSDKError} 当前 proxy 已知 Session 已退出时返回
+     * `COMPANION_SESSION_EXITED`；controller 已转移给其他 Runtime generation 时返回
+     * `COMPANION_SESSION_OWNERSHIP_LOST`。本地检查与 Host 展示之间存在竞态，Host 会用私有
+     * controller generation 再次拒绝过期调用。
+     * @throws {@link HbMiniProgramSDKError} 当前 Host、操作系统或 Session 无法展示通知时返回
+     * `COMPANION_NOTIFICATION_UNAVAILABLE`；Companion 不受支持、进程已异常退出或因输出上限结束时
+     * 还可能返回 `COMPANION_UNSUPPORTED`、`COMPANION_PROCESS_CRASHED`、`COMPANION_OUTPUT_LIMIT`。
+     * @throws {@link HbMiniProgramSDKError} 未声明或未获批 `companion` 权限时返回
+     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放 `companion.showNotification` 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。未知 Host 失败会脱敏为
+     * `COMPANION_HOST_FAILED`；SDK / Runtime 终止、不可用或请求超时还可能返回 `SDK_DESTROYED`、
+     * `RUNTIME_UNAVAILABLE`、`REQUEST_TIMEOUT`。
+     *
+     * @remarks
+     * `notifications` 只在 Session 快照的 capability 集合包含 `'notifications'` 时存在；调用前必须按
+     * `session.notifications` 是否存在分支。该 capability 与 `stdio`、`attachments` 相互独立：Session
+     * 可以只提供其中一项；显示通知不要求 stdio framing，也不会创建附件、返回 `FileHandle`、消耗
+     * direct-handle 配额或要求 `filesystem` / `network` 权限。
+     *
+     * SDK 先校验 input 和当前 controller，再只发送私有 Session ID、controller generation 与固定
+     * `category`；Runtime 重复校验并裁剪 payload。页面无法传入标题、正文或任意系统通知配置，Host
+     * 根据 category 生成安全、平台一致的固定文案。需要展示业务详情时，应在 Mini-program UI 内呈现，
+     * 不要把未知字段附加到 input 期待 Host 透传。
+     *
+     * 调用不要求新的可信用户手势，但要求当前进程仍在运行且当前 Runtime generation 持有 controller。
+     * `session.state === 'running'` 不能证明 controller 未转移；应监听
+     * {@link CompanionSession.onOwnershipLost | onOwnershipLost()} 并停止后续通知请求。页面完全断开后
+     * 不承诺继续发送业务通知；该 API 不是 Host 后台定时通知、推送订阅或持久通知队列。
+     *
+     * V1 真实 Companion notifications 仅支持新 PC Host 的 Windows x64 与 macOS arm64；Browser Dev
+     * Host 只记录确定性 Fake diagnostic，不展示真实系统通知。其他平台、旧 Host、Session 未声明
+     * capability 或 operation 缺失时 fail closed，不回退为浏览器 Notification API、toast 或 stdio 消息。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const session = await hbSDK.companion.getActiveSession('runner')
+     * const notifications = session?.notifications
+     * if (notifications) {
+     *   try {
+     *     await notifications.show({ category: 'completed' })
+     *   } catch (error) {
+     *     if (
+     *       error instanceof HbMiniProgramSDKError &&
+     *       error.code === 'COMPANION_NOTIFICATION_UNAVAILABLE'
+     *     ) {
+     *       showCompletionInPage()
+     *     } else {
+     *       throw error
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link CompanionNotification}
+     * @see {@link CompanionSession.onOwnershipLost | CompanionSession.onOwnershipLost()} 监听 controller 转移。
+     * @see {@link CompanionAttachments.open | CompanionAttachments.open()} 通过 opaque ID 打开受控只读附件。
+     * @see {@link CompanionStdio.write | CompanionStdio.write()} 向 Companion 的原始字节流写入业务协议。
+     * @see {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession} 取得活动 Session controller。
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/companion | 受管桌面程序}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     */
     show(input: CompanionNotification): Promise<void>;
 }
+/**
+ * 受 Host 监管的 Companion 活动进程 Session。
+ *
+ * Session 只暴露审核版本 Manifest 声明的能力，不暴露 PID、原生句柄、路径、命令行或环境变量。
+ * 页面 reload 不会结束进程；可通过 `getActiveSession()` 重新取得当前 controller。
+ */
 export interface CompanionSession {
+    /** Host 为当前活动进程分配的 opaque Session id。 */
     readonly id: string;
+    /** `package.json#heybox.companions` 中声明的 alias。 */
     readonly alias: string;
+    /** 当前 Session 使用的目标平台。 */
     readonly target: CompanionTarget;
+    /** 当前审核版本实际开放给 Session 的能力集合。 */
     readonly capabilities: readonly CompanionCapability[];
+    /** 当前状态；退出后固定为 `exited`。 */
     readonly state: CompanionState;
+    /** 声明并获 Host 支持 `stdio` 时存在。 */
     readonly stdio?: CompanionStdio;
+    /** 声明并获 Host 支持 `attachments` 时存在。 */
     readonly attachments?: CompanionAttachments;
+    /** 声明并获 Host 支持 `notifications` 时存在。 */
     readonly notifications?: CompanionNotifications;
+    /**
+     * 请求 Host 强制结束当前 Session 的完整受管进程树。
+     *
+     * @returns 当前 controller 对应的 Host terminate 请求成功后以 `undefined` resolve。返回值不包含
+     * {@link CompanionExit}、退出码或已结束的进程数量，也不等待 SDK 收到独立的 Session exit 事件；
+     * terminate 响应与 exit 事件可能以任意顺序到达。需要确认最终退出原因时应同时使用
+     * {@link CompanionSession.waitForExit | waitForExit()} 或 {@link CompanionSession.onExit | onExit()}。
+     * @throws {@link HbMiniProgramSDKError} 当前 proxy 已知 Session 已退出时以
+     * `COMPANION_SESSION_EXITED` 拒绝；当前 Runtime 已失去 controller 时以
+     * `COMPANION_SESSION_OWNERSHIP_LOST` 拒绝。本地检查与 Host 执行之间仍存在竞态，Host 会根据私有
+     * Session ID 与 controller generation 再次拒绝已退出进程或过期 controller。
+     * @throws {@link HbMiniProgramSDKError} Host 无法终止完整进程树时以
+     * `COMPANION_TERMINATE_FAILED` 拒绝；进程已异常退出、因输出上限结束或 Session 状态已变化时还
+     * 可能返回 `COMPANION_PROCESS_CRASHED`、`COMPANION_OUTPUT_LIMIT`、
+     * `COMPANION_SESSION_EXITED` 等对应稳定 Companion 错误码。
+     * @throws {@link HbMiniProgramSDKError} 未声明或未获批 `companion` 权限时返回
+     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放
+     * `companion.session.terminate` 时返回 `METHOD_FORBIDDEN`，旧 Runtime 也可能返回
+     * `METHOD_NOT_FOUND`。未知 Host 失败会脱敏为 `COMPANION_HOST_FAILED`；SDK / Runtime 已终止、
+     * 不可用或请求超时时还可能返回 `SDK_DESTROYED`、`RUNTIME_UNAVAILABLE`、`REQUEST_TIMEOUT`。
+     *
+     * @remarks
+     * 这是强制、非优雅终止，不会先发送业务 shutdown 消息，不会隐式调用
+     * {@link CompanionStdio.closeStdin | closeStdin()}，也不保证 Companion 有机会刷新业务数据、清空
+     * stdout/stderr、完成附件写入或运行自己的退出清理。Host 负责终止由该 Session 监管的完整进程树，
+     * Mini-program 不能选择 PID、只杀子进程、发送自定义 signal 或取得原生进程句柄。
+     *
+     * 正常业务退出应优先使用 Companion 自己定义的 stdio 协议：通过
+     * {@link CompanionStdio.write | write()} 发送带幂等 ID 的 shutdown frame，按协议决定是否
+     * `closeStdin()`，再用 `waitForExit()` 等待进程自行退出。`terminate()` 适合用户明确执行“强制停止”、
+     * 进程无响应、业务协议不可用或 Host 风险处置；不要把它当作 graceful close、页面卸载清理或
+     * `closeStdin()` 的同义词。页面 hide、reload 本身不会自动调用本方法。
+     *
+     * `terminate()` 是每个 {@link CompanionSession} 都有的核心 controller 操作，不依赖可选的
+     * `'stdio'`、`'attachments'` 或 `'notifications'` capability；没有 `session.stdio` 的 Session 仍可
+     * 强制结束。它属于已声明并经平台批准的 `companion` 高风险能力，但调用本身不要求新的可信用户
+     * 手势，也不展示 prepare / launch 授权弹窗。
+     *
+     * 只有当前 controller 可以终止进程。`session.state === 'running'` 不证明当前 Runtime 仍持有
+     * controller；其他 Runtime 通过
+     * {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession} 取得控制后，旧
+     * proxy 的本方法会以 `COMPANION_SESSION_OWNERSHIP_LOST` 失败。失去 controller 不影响同一 proxy 的
+     * `waitForExit()`：它仍可观察进程由新 controller、权限撤销或 Host shutdown 导致的最终退出。
+     *
+     * SDK 不维护“termination requested”状态，也不会合并、缓存或短路重复调用。在 exit 事件到达前
+     * 重复调用会再次向 Host 发送 terminate；不保证幂等，Host 可以再次确认，也可以返回
+     * `COMPANION_SESSION_EXITED` / `COMPANION_TERMINATE_FAILED`。请求超时或连接中断时无法从错误判断
+     * Host 是否已经执行终止，因此不要无条件自动重试；应等待 exit 事件或通过明确的恢复流程重新取得
+     * Session 状态。
+     *
+     * `terminate()` resolve 不会直接把本地 `session.state` 改成 `'exited'`。SDK 只在收到合法的
+     * `companion.session.exit` 事件后更新状态、resolve `waitForExit()` 并调用 `onExit()`；Host 通常会把
+     * 强制终止报告为 `{ reason: 'terminated' }`，但调用方应以实际 {@link CompanionExit} 为准。若 Host
+     * 没有接入 `HostCompanionPort.onSessionEvent()`，terminate 请求仍可能成功，而 `state` 不更新、
+     * `waitForExit()` 一直 pending；Mini-program 没有轮询 fallback，Host/Runtime 集成方必须提供事件源。
+     *
+     * V1 真实 Companion Session 仅支持新 PC Host 的 Windows x64 与 macOS arm64；Browser Dev Host
+     * Fake 会立即发出 `reason: 'terminated'` 的确定性 exit 事件，仅用于 UI 与状态机联调，不代表真实
+     * 操作系统的终止时序。其他平台、旧 Host 或未开放 operation 的环境 fail closed。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const session = await hbSDK.companion.getActiveSession('runner')
+     * if (session) {
+     *   // 先取得持久的退出 Promise，避免假设 terminate response 与 exit event 的先后顺序。
+     *   const exitPromise = session.waitForExit()
+     *
+     *   try {
+     *     await session.terminate()
+     *     const exit = await exitPromise
+     *     console.log(exit.reason, exit.exitCode)
+     *   } catch (error) {
+     *     if (
+     *       error instanceof HbMiniProgramSDKError &&
+     *       (error.code === 'COMPANION_SESSION_EXITED' ||
+     *         error.code === 'COMPANION_SESSION_OWNERSHIP_LOST')
+     *     ) {
+     *       console.warn('Session 已退出或控制权已转移')
+     *     } else {
+     *       throw error
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link CompanionSession.waitForExit | CompanionSession.waitForExit()} 等待独立的进程退出事件。
+     * @see {@link CompanionSession.onExit | CompanionSession.onExit()} 订阅并同步回放已收到的退出结果。
+     * @see {@link CompanionSession.onOwnershipLost | CompanionSession.onOwnershipLost()} 监听 controller 转移。
+     * @see {@link CompanionStdio.write | CompanionStdio.write()} 优先发送业务定义的优雅退出 frame。
+     * @see {@link CompanionStdio.closeStdin | CompanionStdio.closeStdin()} 执行输入半关闭而不终止进程。
+     * @see {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession} 恢复活动 Session controller。
+     * @see [受管桌面程序](/guide/companion) 查看 Session、stdio 与进程树生命周期。
+     *
+     * @since 0.8.1-alpha.4
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     terminate(): Promise<void>;
+    /**
+     * 等待 Host 确认当前 Companion Session 的进程终态。
+     *
+     * @returns 当前 Session proxy 持有的同一个 `Promise<CompanionExit>`。同一 proxy 每次调用都严格
+     * 返回同一个 Promise 实例；第一个有效退出事件到达时以冻结的 {@link CompanionExit} resolve
+     * 一次。若 Session 已退出，后续调用仍返回该已 fulfilled Promise，并取得同一个退出对象引用。
+     * @throws 该方法不接收参数、不执行校验、不发 bridge 请求，调用本身不会同步抛出
+     * {@link HbMiniProgramSDKError}，返回的 Promise 也不会因权限、controller ownership、SDK / Runtime
+     * 终止或 Host 操作错误而 reject。异常终止通过 {@link CompanionExit} 的 `reason` 作为成功结果表达。
+     *
+     * @remarks
+     * `waitForExit()` 是纯本地一次性观察器。Session proxy 构造时即创建退出 Promise，不会因每次调用
+     * 新建请求、listener、timer 或轮询，也不要求新的可信用户手势。取得该 Session 的 `launch()` /
+     * `getActiveSession()` 仍要求已声明并经平台批准的 `companion` 权限，但等待本身不重新检查权限。
+     * `permission-revoked` 是可能 resolve 的退出 reason，不是该 Promise 的 rejection。
+     *
+     * SDK 只接受与当前 Session ID 匹配、由 Runtime 校验过的 `companion.session.exit` 事件。Runtime 会
+     * 丢弃未知 reason、缺失 `exited.exitCode` 或包含非 safe-integer exit code 的非法 Host 事件；SDK
+     * 对同一 Session 只处理第一条有效 exit，之后重复事件不会改变结果或再次触发生命周期迁移。退出
+     * 对象由 Runtime 与 SDK 分别复制/冻结，不包含 PID、路径、原生句柄、controller generation 或
+     * Host 私有诊断。
+     *
+     * Promise resolve 发生在 SDK 把 `session.state` 置为 `exited` 后，并且早于同步派发
+     * `onStateChange('exited')` 与 {@link CompanionSession.onExit | onExit()} handler。任一本地 handler
+     * 抛错都不会把已经确定的退出 Promise 改为 rejected。`onExit()` 适合需要取消订阅或在已退出时
+     * 同步回放的回调风格；`waitForExit()` 适合一次性 `await`，不需要也不提供 unsubscribe。
+     *
+     * Host 的 `onSessionEvent` 是可选集成 Port。当前支持的新 PC Host 与 Browser Dev Host Fake 会提供
+     * 退出事件；自定义/兼容 Host 如果返回 Session 却没有 event source，或者 Runtime/页面在退出事件
+     * 到达前被销毁，本 Promise 可能永久 pending。它没有 timeout、AbortSignal、取消方法或主动状态查询
+     * fallback；调用方不能通过取消 `await` 停止 Host 进程，也不能把 Promise pending 当作进程仍存活。
+     *
+     * controller ownership 转移与进程退出是独立状态。收到
+     * {@link CompanionSession.onOwnershipLost | onOwnershipLost()} 后，控制类 API 会以
+     * `COMPANION_SESSION_OWNERSHIP_LOST` 失败，但此 Promise 不 resolve/reject，仍等待同一 Host 进程的
+     * exit 事件；通过 {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession}
+     * 重新取得同一 Session 的新 controller generation 时，同一 proxy 和退出 Promise 继续复用。
+     * 页面 reload 会创建新的 SDK/proxy，需要重新取得活动 Session 后重新等待。
+     *
+     * {@link CompanionSession.terminate | terminate()} 只请求 Host 强制终止进程，其 Promise 完成不等于
+     * exit 事件已经抵达，也不保证最终 {@link CompanionExit} 的 `reason`。为避免 terminate response 与 exit event 的先后竞态，
+     * 先保存 `const exitPromise = session.waitForExit()`，再调用 `terminate()`，最后 await 该 Promise。
+     * `waitForExit()` 本身不能终止、关闭 stdin 或取消 Session；正常退出应优先使用 Companion 自己的
+     * stdio 协议。
+     *
+     * V1 真实 Session 仅支持新 PC Host 的 Windows x64 与 macOS arm64。Browser Dev Host 的确定性
+     * Fake 会产生 `exited`、`crashed`、`output-limit` 和 `terminated` 等测试终态，但不执行真实进程，
+     * 不能替代目标系统对 exit code、崩溃和 Host shutdown 的验收。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const session = await hbSDK.companion.getActiveSession('runner')
+     * if (session) {
+     *   const exitPromise = session.waitForExit()
+     *   console.assert(exitPromise === session.waitForExit())
+     *
+     *   const stopOwnership = session.onOwnershipLost(() => {
+     *     disableCompanionControls()
+     *     // ownership 丢失不代表进程退出；继续等待同一个 exitPromise。
+     *   })
+     *
+     *   try {
+     *     const exit = await exitPromise
+     *     if (exit.reason === 'exited') {
+     *       renderProcessExitCode(exit.exitCode)
+     *     } else {
+     *       renderHostTermination(exit.reason, exit.exitCode)
+     *     }
+     *   } finally {
+     *     stopOwnership()
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link CompanionExit}
+     * @see {@link CompanionSession.onExit}
+     * @see {@link CompanionSession.onStateChange}
+     * @see {@link CompanionSession.onOwnershipLost}
+     * @see {@link CompanionSession.terminate}
+     * @see {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession}
+     * @see {@link CompanionStdio.closeStdin}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/companion | 受管桌面程序}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     */
     waitForExit(): Promise<CompanionExit>;
+    /**
+     * 订阅当前 Session 的生命周期状态变化。
+     *
+     * @param handler - 收到新状态时同步调用的函数。当前唯一的回调参数是 `'exited'`；不会在注册时
+     * 立即收到当前的 `'running'`，也不会收到 ownership 转移或 stdin 关闭通知。
+     * @returns 取消当前 handler 的同步函数。可调用一次或多次；取消后不再接收未来状态变化，不会
+     * 终止 Session、关闭 stdio 或取消其他 handler。相同函数引用重复注册按 `Set` 语义只保留一项，
+     * 任一对应取消函数都会移除该项。
+     * @throws {@link HbMiniProgramSDKError} `handler` 不是函数时同步抛出 `INVALID_PARAMS`。订阅本身
+     * 不发送 bridge 请求，因此不会因为权限、Host operation、Session 已退出或 controller 状态异步拒绝。
+     *
+     * @remarks
+     * 注册只是本地订阅，不会查询或回放 `session.state`。要初始化 UI，应立即读取
+     * `session.state`，再注册 handler；对于已经是 `'exited'` 的 proxy，注册本方法不会回放，若需要
+     * 退出结果应改用 {@link CompanionSession.onExit | onExit()}（它会在已收到退出后同步回放）或
+     * {@link CompanionSession.waitForExit | waitForExit()}（已退出时会 resolve 保存的结果）。
+     *
+     * 实际状态迁移只有 Host/Runtime 收到当前 Session ID 的合法 `companion.session.exit` 事件时才会发生：
+     * proxy 的 `state` 从 `'running'` 变为 `'exited'`，等待 Promise resolve，然后依次派发本 handler
+     * 与 `onExit` handler，最后清理状态和输出订阅。若 Host 没有提供可选的 Session event source，
+     * 本方法仍可注册成功，但不会主动收到变化；`state` 可能继续显示 `'running'`，
+     * `waitForExit()` 也可能一直 pending。SDK 没有轮询或 WebSocket fallback。
+     *
+     * handler 的同步异常不会被 SDK 捕获或转换：由于状态 handler 按 `Set` 顺序同步遍历，异常可能阻止
+     * 后续状态 handler、`onExit` handler 和退出后的订阅清理。请在 handler 内捕获业务异常，或使用
+     * 不会抛出的薄回调把错误交给自己的异步日志通道。handler 返回的 Promise 同样不会被等待；rejected
+     * Promise 需由业务自行处理。
+     *
+     * Session ownership 丢失不会改变 `state`，进程仍可能是 `'running'`；收到
+     * {@link CompanionSession.onOwnershipLost | onOwnershipLost()} 后应停止控制调用，需要恢复时由
+     * {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession} 取得新 controller。
+     * 新 generation 复用同一 proxy 时，本地状态 handler 保持注册，但只有后续真实退出事件才会派发 `'exited'`。
+     * 组件销毁时应显式调用返回的取消函数，避免把页面闭包留在活动 Session 上。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const session = await hbSDK.companion.getActiveSession('runner')
+     * if (session) {
+     *   // 先读取当前值，再订阅未来的 running -> exited 迁移。
+     *   renderState(session.state)
+     *
+     *   const stopState = session.onStateChange(state => {
+     *     renderState(state)
+     *   })
+     *   const stopExit = session.onExit(exit => {
+     *     renderExit(exit)
+     *     stopState()
+     *     stopExit()
+     *   })
+     * }
+     * ```
+     *
+     * @see {@link CompanionStateChangeHandler}
+     * @see {@link CompanionSession.state}
+     * @see {@link CompanionSession.onExit | CompanionSession.onExit()} 退出结果与已退出 proxy 的即时回放。
+     * @see {@link CompanionSession.waitForExit | CompanionSession.waitForExit()} 等待同一进程的退出结果。
+     * @see {@link CompanionSession.onOwnershipLost | CompanionSession.onOwnershipLost()} 观察 controller 转移。
+     * @see {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession} 恢复活动 Session。
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/companion | 受管桌面程序}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     */
     onStateChange(handler: CompanionStateChangeHandler): () => void;
+    /**
+     * 订阅当前 Companion Session 的一次性退出结果。
+     *
+     * @param handler - 接收 {@link CompanionExit} 的同步函数。必须是 function；传入其他值会在请求前
+     * 同步抛出 `INVALID_PARAMS`。
+     * @returns 取消该函数引用的订阅函数。Session 尚未退出时，调用后不再收到未来退出事件；同一
+     * 函数引用重复注册只保留一个订阅，取消函数可重复调用。Session 已退出时，handler 会在本次注册
+     * 调用中同步收到已保存的退出结果，并返回一个无操作取消函数。
+     * @throws {@link HbMiniProgramSDKError} 仅当 `handler` 不是函数时同步返回 `INVALID_PARAMS`；该方法
+     * 不发送 bridge 请求，不检查权限、Host capability、controller ownership，也不会因 Session 退出、
+     * 事件源缺失或 Host 错误返回 Promise rejection。
+     *
+     * @remarks
+     * 未来事件由当前 proxy 的本地 `Set` 监听集合派发，退出处理完成后集合会清空；每个 proxy 对同一
+     * Session 只派发一次退出。退出 handler 与 `onStateChange('exited')` 在 SDK 已将 `state` 置为
+     * `'exited'`、并 resolve 同一个 {@link CompanionSession.waitForExit | waitForExit()} Promise 后同步
+     * 执行。handler 抛出的同步异常不会被 SDK 捕获，可能阻断同次退出事件中尚未执行的其他 handler；
+     * 它不会撤销已经确定的 `waitForExit()` 结果。
+     *
+     * `onExit()` 的同步回放只适用于 SDK 已经收到并保存退出事件的 proxy。若 Host 没有接入可选的
+     * Session event source，或 SDK / 页面在退出事件到达前被销毁，注册不会轮询或主动查询，handler
+     * 可能永远不会调用；页面应在组件销毁时调用仍有效的取消函数。controller ownership 丢失只触发
+     * {@link CompanionSession.onOwnershipLost | onOwnershipLost()}，不触发 `onExit()`，因为进程可能仍在运行。
+     *
+     * 已退出时的同步回放发生在注册调用栈内：如果 handler 本身抛错，该异常会直接从 `onExit()` 调用
+     * 冒出，调用方应在注册外层捕获。若需要等待风格且不需要取消订阅，使用
+     * {@link CompanionSession.waitForExit | waitForExit()}；它与 `onExit()` 观察同一个退出结果。
+     *
+     * V1 真实 Session 仅支持新 PC Host 的 Windows x64 与 macOS arm64；Browser Dev Host Fake 提供
+     * 确定性退出事件。其他平台或缺少事件源的集成不会提供回调重放或事件轮询 fallback。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const session = await hbSDK.companion.getActiveSession('runner')
+     * if (session) {
+     *   const stop = session.onExit(exit => {
+     *     if (exit.reason === 'exited') {
+     *       renderExitCode(exit.exitCode)
+     *     } else {
+     *       renderTermination(exit.reason, exit.exitCode)
+     *     }
+     *   })
+     *
+     *   // ownership 丢失不代表退出；它只应停止新的控制调用。
+     *   const stopOwnership = session.onOwnershipLost(() => disableCompanionControls())
+     *   try {
+     *     await doPageWork()
+     *   } finally {
+     *     stop()
+     *     stopOwnership()
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link CompanionExitHandler}
+     * @see {@link CompanionExit}
+     * @see {@link CompanionSession.waitForExit | CompanionSession.waitForExit()} 等待同一退出结果。
+     * @see {@link CompanionSession.onStateChange | CompanionSession.onStateChange()} 观察 `running` 到 `exited`。
+     * @see {@link CompanionSession.onOwnershipLost | CompanionSession.onOwnershipLost()} 区分 controller 转移。
+     * @see {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession} 取得活动 Session。
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/companion | 受管桌面程序}
+     */
     onExit(handler: CompanionExitHandler): () => void;
+    /**
+     * 订阅当前 Runtime 丢失 Companion Session controller 的事件。
+     *
+     * @param handler - 控制权从当前 Runtime 转移给其他 Runtime / 页面时调用的无参同步
+     * {@link CompanionOwnershipLostHandler}。它不接收新 generation、Session ID、退出原因或错误对象。
+     * @returns 同步返回取消订阅函数。调用后仅移除当前 SDK proxy 的本地 handler，不释放 controller、
+     * 不停止进程、不关闭 stdio，也不向 Host 发送 unsubscribe；重复调用取消函数安全且不会抛错。
+     * 相同函数引用重复注册按 Set 语义只保留一项，任一对应取消函数都会移除该项。
+     * @throws {@link HbMiniProgramSDKError} `handler` 不是函数时同步抛出 `INVALID_PARAMS`。注册本身
+     * 不发送 bridge 请求，因此不会因权限、Session 已退出、当前已失去 ownership 或 Host event source
+     * 缺失而拒绝。
+     *
+     * @remarks
+     * ownership lost 不是进程退出：Session 的 `state` 仍可能是 `'running'`，
+     * {@link CompanionSession.waitForExit | waitForExit()} 继续等待同一进程，`onExit()` 不会因本事件
+     * 触发。收到通知后，旧 proxy 的 `write()`、`closeStdin()`、`terminate()`、Attachment 和
+     * Notification 控制操作都会在本地以 `COMPANION_SESSION_OWNERSHIP_LOST` 拒绝；Host 仍会用私有
+     * controller generation 做最终校验。输出、退出和 ownership 事件的先后由 Host 决定，不能用本
+     * 回调判断进程何时终止。
+     *
+     * Runtime 只接受 Session ID 匹配且 `controllerGeneration` 为非负 safe integer 的合法
+     * `companion.session.ownershipLost` 事件。SDK 只在事件 generation 等于当前 proxy generation 且
+     * proxy 仍标记为拥有 controller 时调用 handler；旧 generation、重复事件或已退出/已丢失控制权的
+     * proxy 会被静默丢弃。该事件触发时 SDK 先把本地 ownership 标记为 false，再同步遍历当前 handlers。
+     * SDK 不捕获 handler 的同步异常，也不会 await handler 返回的 Promise；业务应自行隔离异常。
+     *
+     * 通过 {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession} 取得同一
+     * Session 的更高 generation 时，SDK 会复用同一个 proxy、将 ownership 恢复为 true、重置 output
+     * sequence 水位，并保留已注册的 handler；之后新的 ownership-lost 事件仍可再次触发同一订阅。
+     * 页面 reload 会创建新的 SDK/proxy，旧订阅不会跨页面保留。
+     *
+     * Host 的 `HostCompanionPort.onSessionEvent()` 是可选集成 Port。若 Host 返回活动 Session 却不提供
+     * event source，本方法仍会成功注册，但不会收到 ownership-lost、output 或 exit 事件，且没有轮询或
+     * WebSocket fallback；控制请求仍可能直接失败为 `COMPANION_SESSION_OWNERSHIP_LOST`。Host/Runtime
+     * 集成方必须提供事件源，业务不能把“尚未收到通知”当作仍拥有控制权。
+     *
+     * 不要求新的可信用户手势，也不改变权限或 Session 生命周期。它适用于在 ownership 丢失后立即
+     * 禁用按钮、停止发送新命令并显示恢复入口；不要在回调中自动抢占 controller 或无条件重发可能已
+     * 提交的 stdin/terminate 请求。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const session = await hbSDK.companion.getActiveSession('runner')
+     * if (session) {
+     *   const stopOwnership = session.onOwnershipLost(() => {
+     *     // 这不是退出通知；先停止新控制调用，进程仍可能运行。
+     *     disableCompanionControls()
+     *     showReacquireButton()
+     *   })
+     *   const stopExit = session.onExit(exit => renderExit(exit))
+     *
+     *   try {
+     *     await runPageLifetime()
+     *   } finally {
+     *     stopOwnership()
+     *     stopExit()
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link CompanionOwnershipLostHandler}
+     * @see {@link CompanionSession.onExit | CompanionSession.onExit()} 监听真实进程退出。
+     * @see {@link CompanionSession.waitForExit | CompanionSession.waitForExit()} 等待真实退出结果。
+     * @see {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession} 恢复 controller。
+     * @see {@link CompanionSession.terminate | CompanionSession.terminate()} 强制终止进程树。
+     * @see {@link CompanionStdio.write | CompanionStdio.write()} 发送业务协议命令。
+     * @see [受管桌面程序](/guide/companion) 查看 ownership、Session 与恢复流程。
+     *
+     * @since 0.8.1-alpha.4
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient windows none
+     * @hbClient macos none
+     */
     onOwnershipLost(handler: CompanionOwnershipLostHandler): () => void;
 }
 export interface MiniProgramCompanionModule {
     /**
-     * 读取指定 alias 的 Companion 信息与就绪状态。
+     * 读取指定 alias 在当前版本与当前平台上的 Companion 描述快照。
+     *
+     * @param alias - `package.json#heybox.companions` 中声明的 Companion alias。必须完整匹配
+     * `[a-z][a-z0-9-]{0,31}`：长度为 1 至 32，第一个字符是小写 ASCII 字母，其余字符
+     * 只能是小写字母、数字或连字符；SDK 不会 trim 或改变大小写。
+     * @returns Host 绑定的当前审核版本、精确预览版本或本地开发快照对应的冻结
+     * {@link CompanionInfo}。返回只描述当前平台选中的制品，不包含准备状态或活动 Session。
+     * @throws {@link HbMiniProgramSDKError} alias 不符合格式时在请求前以 `INVALID_PARAMS`
+     * 拒绝；当前版本未声明 alias、当前平台没有匹配 target、预览 Host 不支持 Companion、
+     * 描述符暂不可用或当前 Host 不支持能力时，可能以 `COMPANION_NOT_DECLARED`、
+     * `COMPANION_TARGET_UNSUPPORTED`、`COMPANION_PREVIEW_UNSUPPORTED`、
+     * `COMPANION_DESCRIPTOR_UNAVAILABLE`、`COMPANION_UNSUPPORTED` 或 `METHOD_FORBIDDEN` 拒绝。
+     * 未声明或未获批 `companion` 权限时分别以 `PERMISSION_NOT_DECLARED`、
+     * `PERMISSION_DENIED` 拒绝；Host 返回 alias 不匹配、未知 target/capability/source、非法大小
+     * 或签名状态时以 `COMPANION_HOST_FAILED` 拒绝。握手失败、SDK/Runtime 已销毁、bridge
+     * 超时及其他 Host 失败会保留对应 SDK 错误码。
+     *
+     * @remarks
+     * 该方法是只读查询：不会下载、校验、解压、准备或启动程序，也不会创建或取得 Session
+     * controller。它不要求可信用户手势，不展示 prepare/launch 的 Host 授权弹窗，但仍需要
+     * Manifest 声明且平台批准 `companion` 权限。V1 真实能力仅支持新 PC Host 的
+     * `windows-x64` 与 `macos-arm64`；Browser Dev Host 返回固定 Fake 描述，仅用于状态联调。
+     *
+     * SDK 不缓存该结果，每次调用都会重新向 Host 查询当前绑定上下文。返回字段包括请求的
+     * `alias`、展示名 `displayName`、当前平台选中的 `target`、去重后的 `capabilities`、压缩
+     * 归档字节数 `archiveBytes`、签名检查状态 `signatureStatus` 和可选来源 `source`。Runtime
+     * 会丢弃 Host 提供的路径、下载 URL、SHA-256、entrypoint 等敏感或非公开字段。
+     *
+     * {@link CompanionInfo} 没有 `state` 或版本字段。使用
+     * {@link MiniProgramCompanionModule.getPreparationStatus | companion.getPreparationStatus}
+     * 区分 `not-prepared`、`preparing`、`ready`、`failed`；需要开始准备时，必须在新的可信
+     * 用户操作中显式调用 {@link MiniProgramCompanionModule.prepare | companion.prepare}。
+     * `getInfo()` 成功不表示制品已经下载、签名有效、可以启动或存在活动 Session。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const info = await hbSDK.companion.getInfo('runner')
+     * const status = await hbSDK.companion.getPreparationStatus('runner')
+     *
+     * renderCompanionSummary({
+     *   name: info.displayName,
+     *   target: info.target,
+     *   archiveBytes: info.archiveBytes,
+     *   source: info.source ?? 'unknown',
+     *   capabilities: info.capabilities,
+     *   preparationState: status.state,
+     * })
+     * ```
+     *
+     * @see {@link CompanionInfo}
+     * @see {@link MiniProgramCompanionModule.getPreparationStatus | companion.getPreparationStatus}
+     * @see {@link MiniProgramCompanionModule.prepare | companion.prepare}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/companion | 受管桌面程序}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
      *
-     * @param alias - `package.json#heybox.companions` 中声明的 Companion alias。
-     * @returns 当前审核版本对应的 Companion 信息。
      * @since 0.8.1-alpha.4
      * @hbPlatform windows
      * @hbPlatform macos
@@ -60,8 +1205,74 @@ export interface MiniProgramCompanionModule {
     /**
      * 查询指定 alias 的准备状态；页面 reload 后可据此重新加入在途准备。
      *
-     * @param alias - `package.json#heybox.companions` 中声明的 Companion alias。
-     * @returns 当前准备状态。
+     * @param alias - `package.json#heybox.companions` 中声明的 Companion alias。必须完整匹配
+     * `[a-z][a-z0-9-]{0,31}`：长度为 1 至 32，第一个字符是小写 ASCII 字母，其余字符
+     * 只能是小写字母、数字或连字符；SDK 不会 trim 或改变大小写。
+     * @returns Host 当前保存的冻结 {@link CompanionPreparationStatus} 快照，以 `state` 区分
+     * `not-prepared`、`preparing`、`ready` 与 `failed`。
+     * @throws {@link HbMiniProgramSDKError} alias 不符合格式时在请求前以 `INVALID_PARAMS`
+     * 拒绝；当前版本未声明 alias、当前平台没有匹配 target、预览 Host 不支持 Companion、
+     * 描述符暂不可用或 Host 不支持该能力时，可能以 `COMPANION_NOT_DECLARED`、
+     * `COMPANION_TARGET_UNSUPPORTED`、`COMPANION_PREVIEW_UNSUPPORTED`、
+     * `COMPANION_DESCRIPTOR_UNAVAILABLE`、`COMPANION_UNSUPPORTED` 或 `METHOD_FORBIDDEN` 拒绝。
+     * 未声明或未获批 `companion` 权限时分别以 `PERMISSION_NOT_DECLARED`、
+     * `PERMISSION_DENIED` 拒绝；Host 返回未知 state、非法进度、非法 `preparedAt` 或失败摘要
+     * 时以 `COMPANION_HOST_FAILED` 拒绝。握手失败、SDK/Runtime 已销毁、bridge 超时及其他
+     * Host 失败会保留对应 SDK 错误码。
+     *
+     * @remarks
+     * 该方法是只读查询：不会开始、加入或取消准备，不会下载、校验、解压或启动程序。
+     * 它不要求可信用户手势，也不展示 prepare/launch 的 Host 授权弹窗，但仍需要 Manifest
+     * 声明且平台批准 `companion` 权限。V1 真实能力仅支持新 PC Host 的 `windows-x64` 与
+     * `macos-arm64`；Browser Dev Host 的固定 Fake 状态只用于恢复流程联调。
+     *
+     * - `not-prepared`：当前版本与 target 没有已提交产物，也没有在途操作。需要由新的可信
+     *   用户操作调用 {@link MiniProgramCompanionModule.prepare | companion.prepare}。
+     * - `preparing`：Host 持有在途操作，`progress` 是查询时的最近快照。页面 reload、最小化
+     *   或进入后台不会取消它；需要持续进度时可再次调用 `prepare()` 加入同一操作并传
+     *   `onProgress`，而不是轮询本方法模拟事件流。
+     * - `ready`：产物已完成原子提交；`preparedAt` 是 Host 时间戳，不是过期时间或版本号。
+     *   启动仍需新的可信用户手势和独立 Host 授权。
+     * - `failed`：`error.code` 是稳定分支字段，`message` 是 Runtime 规范化文案；
+     *   `retryable` 只建议一次新的 prepare 是否可能成功，不会自动重试或绕过门禁。
+     *
+     * 状态由 Host 按当前小程序 identity、版本、target 与 alias 持有，页面 reload 后可以重新
+     * 查询恢复 UI。快照不随状态变化自动更新：调用 `prepare()`、
+     * {@link MiniProgramCompanionModule.cancelPreparation | companion.cancelPreparation} 或发生
+     * 原子提交竞态后，应再次查询对账。取消意图不保证赢得提交竞态，因此取消后仍可能得到
+     * `ready`，不能直接在页面本地假设 `not-prepared`。
+     *
+     * {@link MiniProgramCompanionModule.getInfo | companion.getInfo} 读取当前产物的名称、target、
+     * capability、大小、签名与来源，但不包含准备 state；两者不能互相替代。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const status = await hbSDK.companion.getPreparationStatus('runner')
+     * switch (status.state) {
+     *   case 'not-prepared':
+     *     showPrepareButton()
+     *     break
+     *   case 'preparing':
+     *     renderProgress(status.progress)
+     *     break
+     *   case 'ready':
+     *     showLaunchButton(status.preparedAt)
+     *     break
+     *   case 'failed':
+     *     renderPreparationError(status.error.code, status.error.retryable)
+     * }
+     * ```
+     *
+     * @see {@link CompanionPreparationStatus}
+     * @see {@link CompanionPrepareProgress}
+     * @see {@link MiniProgramCompanionModule.getInfo | companion.getInfo}
+     * @see {@link MiniProgramCompanionModule.prepare | companion.prepare}
+     * @see {@link MiniProgramCompanionModule.cancelPreparation | companion.cancelPreparation}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/companion | 受管桌面程序}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
      * @since 0.8.1-alpha.4
      * @hbPlatform windows
      * @hbPlatform macos
@@ -70,12 +1281,98 @@ export interface MiniProgramCompanionModule {
      */
     getPreparationStatus(alias: string): Promise<CompanionPreparationStatus>;
     /**
-     * 在可信用户手势下准备指定 alias 的 Companion 产物，并可观察进度或通过 `AbortSignal` 取消。
+     * 准备指定 alias 的 Companion 产物，并可观察进度或请求取消。
+     *
+     * @param alias - `package.json#heybox.companions` 中声明的 Companion alias。必须完整匹配
+     * `[a-z][a-z0-9-]{0,31}`：长度为 1 至 32，第一个字符是小写 ASCII 字母，其余字符
+     * 只能是小写字母、数字或连字符；SDK 不会 trim 或改变大小写。
+     * @param options - 可选取消信号与进度回调；字段合同见 {@link CompanionPrepareOptions}。
+     * @returns Host 完成原子提交后返回当前产物的冻结 {@link CompanionInfo}。如果产物已经
+     * `ready`，Host 可直接返回；如果加入同 alias 在途操作，则与该共享操作一同 settle。
+     * 返回值没有 `state` 或 `preparedAt`，需要这些字段时调用
+     * {@link MiniProgramCompanionModule.getPreparationStatus | companion.getPreparationStatus}。
+     * @throws {@link HbMiniProgramSDKError} alias、options、`signal` 或 `onProgress` 不合法时在
+     * 请求前以 `INVALID_PARAMS` 拒绝。真正开始新准备时，缺少新的可信用户手势以
+     * `USER_GESTURE_REQUIRED` 拒绝，用户取消 Host 授权以 `COMPANION_USER_CANCELLED` 拒绝；
+     * 下载、归档、完整性或入口失败，以及准备被取消时，分别可能以 `COMPANION_DOWNLOAD_FAILED`、
+     * `COMPANION_ARCHIVE_INVALID`、`COMPANION_INTEGRITY_FAILED`、
+     * `COMPANION_ENTRYPOINT_INVALID`、`COMPANION_PREPARATION_CANCELLED` 拒绝。
+     *
+     * 当前版本未声明 alias、当前平台没有匹配 target、预览 Host 不支持 Companion、描述符
+     * 暂不可用或当前 Host 未开放能力时，可能以 `COMPANION_NOT_DECLARED`、
+     * `COMPANION_TARGET_UNSUPPORTED`、`COMPANION_PREVIEW_UNSUPPORTED`、
+     * `COMPANION_DESCRIPTOR_UNAVAILABLE`、`COMPANION_UNSUPPORTED` 或 `METHOD_FORBIDDEN` 拒绝。
+     * 未声明或未获批 `companion` 权限时分别以 `PERMISSION_NOT_DECLARED`、
+     * `PERMISSION_DENIED` 拒绝；Host 返回非法状态、进度或产物描述时以
+     * `COMPANION_HOST_FAILED` 拒绝。握手失败、SDK/Runtime 已销毁及其他 bridge 或 Host 失败
+     * 会保留对应 SDK 错误码。
+     *
+     * @remarks
+     * 准备由 Host 持有，包含下载、SHA-256/归档校验、受控解压和原子提交。真正开始一项新
+     * 准备前，Runtime 要求新的可信用户手势，并展示一次 Host 授权；调用应直接发生在准备
+     * 按钮回调中，作为该回调的第一个异步操作，不要预先等待握手或其他 Promise。
+     *
+     * 同一小程序 identity、版本、target 与 alias 同时只运行一项准备。状态已经
+     * `preparing` 时，再次调用会加入同一操作、复用下载并接收进度，不重复授权；状态已经
+     * `ready` 时也不重复授权或下载。因而 join/ready 快路径可以在没有新手势时完成，但业务
+     * 不应依赖它绕过真正新准备的手势要求。
+     *
+     * 页面 reload、最小化或进入后台只断开当前 observer，不会取消 Host 操作。新页面先调用
+     * `getPreparationStatus()` 恢复 UI；若为 `preparing`，可再次调用 `prepare()` 加入并继续
+     * 观察。该长操作不使用普通 SDK 请求的固定总时长 timeout，仍可能因 Host、网络、权限
+     * 撤销或 Runtime 终止失败。
+     *
+     * `onProgress` 只用于展示，完整阶段为 `downloading`、`verifying`、`extracting`。业务不能
+     * 根据进度值自行判断 ready；Promise resolve 或重新查询到 `ready` 才表示 Host 已完成
+     * 原子提交。
+     *
+     * 在途 `signal` 触发或显式调用
+     * {@link MiniProgramCompanionModule.cancelPreparation | companion.cancelPreparation} 都只发送
+     * best-effort 取消意图。取消先于提交生效时，prepare 通常以
+     * `COMPANION_PREPARATION_CANCELLED` 拒绝；原子提交已开始时提交结果优先，本 Promise 仍
+     * 可能成功并返回 {@link CompanionInfo}。取消后应重新查询状态，不能直接假设
+     * `not-prepared`。
+     *
+     * `prepare()` 只使产物 ready，不会启动进程。真正新启动必须由另一场可信用户操作调用
+     * {@link MiniProgramCompanionModule.launch | companion.launch}，不能在同一个点击中
+     * `await prepare()` 后串联。只需要名称、target、能力、大小、签名或来源时，使用
+     * {@link MiniProgramCompanionModule.getInfo | companion.getInfo}，避免触发准备工作流。
+     *
+     * 该调用需要 Manifest 声明且平台批准 `companion` 权限。V1 真实准备仅支持新 PC Host 的
+     * `windows-x64` 与 `macos-arm64`；Browser Dev Host 只模拟固定进度和状态，不下载、校验或
+     * 解压真实归档，不能替代目标系统验收。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * prepareButton.addEventListener('click', () => {
+     *   const controller = new AbortController()
+     *   cancelButton.onclick = () => controller.abort()
+     *
+     *   // prepare() 是本次点击中的第一个异步操作。
+     *   void hbSDK.companion.prepare('runner', {
+     *     signal: controller.signal,
+     *     onProgress(progress) {
+     *       renderProgress(progress)
+     *     },
+     *   }).then(info => {
+     *     renderPreparedArtifact(info.displayName, info.source)
+     *     showLaunchButton() // launch 由之后另一场点击触发。
+     *   }).catch(showPreparationError)
+     * })
+     * ```
+     *
+     * @see {@link CompanionPrepareOptions}
+     * @see {@link CompanionPrepareProgress}
+     * @see {@link CompanionInfo}
+     * @see {@link MiniProgramCompanionModule.getInfo | companion.getInfo}
+     * @see {@link MiniProgramCompanionModule.getPreparationStatus | companion.getPreparationStatus}
+     * @see {@link MiniProgramCompanionModule.cancelPreparation | companion.cancelPreparation}
+     * @see {@link MiniProgramCompanionModule.launch | companion.launch}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/companion | 受管桌面程序}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
      *
-     * @param alias - `package.json#heybox.companions` 中声明的 Companion alias。
-     * @param options - 进度回调与取消信号。
-     * @returns 准备完成后的 Companion 信息。
-     * @remarks 准备操作由 Host 持有，页面 reload 只断开观察者；同一 alias 可加入同一在途准备。
      * @since 0.8.1-alpha.4
      * @hbPlatform windows
      * @hbPlatform macos
@@ -86,7 +1383,56 @@ export interface MiniProgramCompanionModule {
     /**
      * 取消指定 alias 的在途准备；已进入原子提交时最终提交结果优先于取消意图。
      *
-     * @param alias - `package.json#heybox.companions` 中声明的 Companion alias。
+     * @param alias - `package.json#heybox.companions` 中声明的 Companion alias。必须完整匹配
+     * `[a-z][a-z0-9-]{0,31}`：长度为 1 至 32，第一个字符是小写 ASCII 字母，其余字符
+     * 只能是小写字母、数字或连字符；SDK 不会 trim 或改变大小写。
+     * @returns Host 处理本次取消意图后以 `undefined` resolve。该时点不表示关联的
+     * `prepare()` Promise 已经 settle，也不返回是否找到在途操作或取消是否赢得竞态。
+     * @throws {@link HbMiniProgramSDKError} alias 不符合格式时在请求前以 `INVALID_PARAMS`
+     * 拒绝；当前审核版本未声明该 alias、目标平台不匹配或 Host 不支持 Companion 时可能以
+     * `COMPANION_NOT_DECLARED`、`COMPANION_TARGET_UNSUPPORTED`、`COMPANION_UNSUPPORTED` 或
+     * `METHOD_FORBIDDEN` 拒绝。未声明或未获批 `companion` 权限时分别以
+     * `PERMISSION_NOT_DECLARED`、`PERMISSION_DENIED` 拒绝；握手失败、SDK/Runtime 已销毁、
+     * bridge 超时及其他 Host 失败会保留对应 SDK 错误码。
+     *
+     * @remarks
+     * 这是幂等、best-effort 的 Host 取消请求。没有在途准备时调用会成功 no-op；alias 已经
+     * `ready` 时也会成功，但不会删除、回滚或使已提交产物变回 `not-prepared`。重复调用不会
+     * 叠加取消次数，也不会停止已启动的 Companion Session。
+     *
+     * 取消只在 Host 原子提交开始前保证有机会终止下载、校验或解压。取消和提交并发时，
+     * 原子提交结果优先：本方法可能已经 resolve，而受影响的 `prepare()` 仍成功返回，随后
+     * {@link MiniProgramCompanionModule.getPreparationStatus | companion.getPreparationStatus}
+     * 也可能是 `ready`。取消抢先生效时，在途 `prepare()` 通常以
+     * `COMPANION_PREPARATION_CANCELLED` 拒绝；该错误属于准备调用，不是本方法成功 resolve 的
+     * 返回值。调用后应重新查询 Host 状态，不能直接把 UI 固定为 `not-prepared`。
+     *
+     * 本方法需要已声明并经平台批准的 `companion` 权限，但不需要可信用户手势，也不会显示
+     * prepare/launch 的 Host 授权弹窗。显式取消按钮或新页面取消旧的 Host 操作时应 await
+     * 本方法；若取消只与当前 `prepare()` 调用的生命周期绑定，可传入 `AbortSignal`，在途
+     * 调用的 signal 触发时 SDK 会向 Host 发送同类取消意图，但页面 reload 本身不会自动取消
+     * Host 操作。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * await hbSDK.companion.cancelPreparation('runner')
+     *
+     * const status = await hbSDK.companion.getPreparationStatus('runner')
+     * if (status.state === 'ready') {
+     *   // 原子提交赢得竞态，产物仍然可以由新的用户操作启动。
+     *   showReadyState()
+     * } else {
+     *   renderPreparationStatus(status)
+     * }
+     * ```
+     *
+     * @see {@link MiniProgramCompanionModule.prepare | companion.prepare}
+     * @see {@link MiniProgramCompanionModule.getPreparationStatus | companion.getPreparationStatus}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/companion | 受管桌面程序}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
      * @since 0.8.1-alpha.4
      * @hbPlatform windows
      * @hbPlatform macos
@@ -95,11 +1441,97 @@ export interface MiniProgramCompanionModule {
      */
     cancelPreparation(alias: string): Promise<void>;
     /**
-     * 在独立的可信用户手势与 Host 授权下启动指定 alias 的 Companion，并返回当前 Session。
+     * 启动指定 alias 的 Companion，或取得已经活动的同 alias Session。
+     *
+     * @param alias - `package.json#heybox.companions` 中声明的 Companion alias。必须完整匹配
+     * `[a-z][a-z0-9-]{0,31}`：长度为 1 至 32，第一个字符是小写 ASCII 字母，其余字符
+     * 只能是小写字母、数字或连字符；SDK 不会 trim 或改变大小写。
+     * @returns Host 确认进程处于 `running` 并把当前 controller 交给本 Runtime 后返回
+     * {@link CompanionSession} proxy。如果同 alias 已有活动 Session，则返回该进程而不是
+     * 创建第二个；同一 SDK 页面内相同 Session ID 会复用同一个 proxy 对象。
+     * @throws {@link HbMiniProgramSDKError} alias 不符合格式时在请求前以 `INVALID_PARAMS`
+     * 拒绝。真正创建新进程时，缺少新的可信用户手势以 `USER_GESTURE_REQUIRED` 拒绝，用户
+     * 取消 Host 授权以 `COMPANION_USER_CANCELLED` 拒绝，产物尚未 ready 以
+     * `COMPANION_NOT_PREPARED` 拒绝；描述符不可用、操作系统阻止、启动失败或未来管理员权限
+     * 被拒绝时，可能以 `COMPANION_DESCRIPTOR_UNAVAILABLE`、`COMPANION_OS_BLOCKED`、
+     * `COMPANION_LAUNCH_FAILED`、`COMPANION_ELEVATION_DENIED` 拒绝。
+     *
+     * 当前版本未声明 alias、当前平台没有匹配 target、预览 Host 不支持 Companion 或当前
+     * Host 未开放能力时，可能以 `COMPANION_NOT_DECLARED`、`COMPANION_TARGET_UNSUPPORTED`、
+     * `COMPANION_PREVIEW_UNSUPPORTED`、`COMPANION_UNSUPPORTED` 或 `METHOD_FORBIDDEN` 拒绝。
+     * 未声明或未获批 `companion` 权限时分别以 `PERMISSION_NOT_DECLARED`、
+     * `PERMISSION_DENIED` 拒绝；Host 返回非法 Session 快照时以 `COMPANION_HOST_FAILED` 拒绝，
+     * 同一 Session ID 的 alias、target 或 capability 集合发生不兼容变化时以
+     * `COMPANION_SESSION_VERSION_MISMATCH` 拒绝。握手失败、SDK/Runtime 已销毁及其他 bridge
+     * 或 Host 失败会保留对应 SDK 错误码。
+     *
+     * @remarks
+     * `launch()` 不会隐式调用 {@link MiniProgramCompanionModule.prepare | companion.prepare}，
+     * 也不会下载、校验或解压产物。没有活动 Session 时，产物必须已通过原子提交进入
+     * `ready`；应先用
+     * {@link MiniProgramCompanionModule.getPreparationStatus | companion.getPreparationStatus}
+     * 展示准备状态，并由单独的用户操作完成准备。
+     *
+     * 真正创建新进程的 `launch()` 与开始新准备的 `prepare()` 必须来自两次独立的可信用户
+     * 手势和两次 Host 授权。不要在一个点击回调中 `await prepare()` 后串联 launch，也不要在
+     * 页面挂载、定时器或 Promise continuation 中自动启动。调用 `launch()` 时应把它作为用户
+     * 回调中的第一个异步操作；SDK/Runtime 会自行处理握手。
+     *
+     * 同一小程序 identity 与 alias 同时最多有一个活动 Session。Runtime 会先查询活动进程；
+     * 若存在，则直接取得并返回它，不要求新的手势、不显示 launch 授权，也不调用 Host 的新
+     * 进程启动原语。页面 reload 后只需恢复现有进程时，优先使用
+     * {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession}，更清楚地
+     * 表达“重新取得 controller”而不是“启动”。
+     *
+     * 返回的 proxy 公开稳定的 `id`、`alias`、`target`、只读 `capabilities` 与初始
+     * `state: 'running'`，以及 `terminate()`、`waitForExit()`、`onStateChange()`、`onExit()`、
+     * `onOwnershipLost()`。它不暴露 PID、物理路径、命令行、原生句柄或 controller
+     * generation。只有 Host 返回的 capability 集合包含对应项时，`stdio`、`attachments`、
+     * `notifications` 才存在；调用方必须按属性是否存在分支。
+     *
+     * 进程由 Host 持有，页面隐藏或 reload 不会结束它。当前受支持的新 PC Host 提供 Session
+     * event source；其他 Runtime 取得 controller 后，当前 proxy 会触发 `onOwnershipLost()`，控制类操作随后以
+     * `COMPANION_SESSION_OWNERSHIP_LOST` 失败，但 `waitForExit()` 仍等待同一进程退出。退出后
+     * `state` 变为 `exited`，`onExit()` 与 `waitForExit()` 获得同一份退出结果。自定义 Host 若未提供
+     * 可选的 Session 事件源，则这些本地监听不会主动更新，`waitForExit()` 也可能一直 pending；集成方应补齐事件源。
+     *
+     * 该调用需要 Manifest 声明且平台批准 `companion` 权限。V1 真实启动仅支持新 PC Host 的
+     * `windows-x64` 与 `macos-arm64`；Browser Dev Host 只启动确定性 Fake，不下载、不解压、
+     * 不执行本机程序，不能替代目标系统验收。可先用
+     * {@link MiniProgramCompanionModule.getInfo | companion.getInfo} 展示 target、capability、签名
+     * 与产物来源，但这些元数据本身不表示已经 ready。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * launchButton.addEventListener('click', () => {
+     *   // launch() 是点击回调中的第一个异步操作，不复用 prepare() 的手势。
+     *   void launchRunner().catch(showLaunchError)
+     * })
+     *
+     * async function launchRunner() {
+     *   const session = await hbSDK.companion.launch('runner')
+     *   const stopOwnership = session.onOwnershipLost(disableCompanionControls)
+     *   const stopOutput = session.stdio?.onStdout(handleCompanionBytes)
+     *
+     *   const exit = await session.waitForExit()
+     *   stopOutput?.()
+     *   stopOwnership()
+     *   renderCompanionExit(exit)
+     * }
+     * ```
+     *
+     * @see {@link CompanionSession}
+     * @see {@link CompanionSession.waitForExit}
+     * @see {@link CompanionSession.onOwnershipLost}
+     * @see {@link MiniProgramCompanionModule.getInfo | companion.getInfo}
+     * @see {@link MiniProgramCompanionModule.getPreparationStatus | companion.getPreparationStatus}
+     * @see {@link MiniProgramCompanionModule.prepare | companion.prepare}
+     * @see {@link MiniProgramCompanionModule.getActiveSession | companion.getActiveSession}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/companion | 受管桌面程序}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
      *
-     * @param alias - `package.json#heybox.companions` 中声明的 Companion alias。
-     * @returns 新启动进程对应的 Session 代理。
-     * @remarks 不会隐式准备，未准备时稳定失败；启动不会触发隐式下载。
      * @since 0.8.1-alpha.4
      * @hbPlatform windows
      * @hbPlatform macos
@@ -110,8 +1542,77 @@ export interface MiniProgramCompanionModule {
     /**
      * 取得指定 alias 当前活动 Session 的控制权。
      *
-     * @param alias - `package.json#heybox.companions` 中声明的 Companion alias。
-     * @returns 当前活动 Session；没有活动进程时返回 `undefined`。
+     * @param alias - `package.json#heybox.companions` 中声明的 Companion alias。必须完整匹配
+     * `[a-z][a-z0-9-]{0,31}`：长度为 1 至 32，第一个字符是小写 ASCII 字母，其余字符
+     * 只能是小写字母、数字或连字符；SDK 不会 trim 或改变大小写。
+     * @returns Host 没有该 alias 的活动进程时返回 `undefined`；否则返回取得当前 controller
+     * 的 {@link CompanionSession} proxy。`undefined` 只表示没有正在运行的进程，可能是尚未
+     * 启动、已经退出或从未启动，不表示产物未准备。
+     * @throws {@link HbMiniProgramSDKError} alias 不符合格式时在请求前以 `INVALID_PARAMS`
+     * 拒绝；当前审核版本未声明 alias、目标平台不匹配或 Host 不支持时可能以
+     * `COMPANION_NOT_DECLARED`、`COMPANION_TARGET_UNSUPPORTED`、`COMPANION_UNSUPPORTED` 或
+     * `METHOD_FORBIDDEN` 拒绝。未声明或未获批 `companion` 权限时分别以
+     * `PERMISSION_NOT_DECLARED`、`PERMISSION_DENIED` 拒绝；Host 返回非法 Session 快照时以
+     * `COMPANION_HOST_FAILED` 拒绝，同一 Session ID 的 alias、target 或 capability 集合发生
+     * 不兼容变化时以 `COMPANION_SESSION_VERSION_MISMATCH` 拒绝。握手失败、SDK/Runtime 已
+     * 销毁、bridge 超时及其他 Host 失败会保留对应 SDK 错误码。
+     *
+     * @remarks
+     * 这不是只读状态查询。Host 成功返回活动 Session 时会把该 Session 的 controller 转移
+     * 给当前 Runtime，并使用递增的私有 generation 使旧 controller 失效；generation 不会暴露
+     * 在 {@link CompanionSession} 上。其他页面或 Runtime 后续取得控制权时，当前 proxy 的
+     * {@link CompanionSession.onOwnershipLost} 会收到通知，之后 `write()`、`closeStdin()`、
+     * `terminate()`、附件和通知等控制操作以 `COMPANION_SESSION_OWNERSHIP_LOST` 失败。
+     *
+     * SDK 每次调用都会询问 Host，不会因为本地已有 proxy 而跳过请求。同一 SDK 页面内按
+     * Session `id` 缓存 proxy：若 {@link MiniProgramCompanionModule.launch | companion.launch}
+     * 或本方法再次返回同一个 Session ID 和更新的 generation，SDK 更新同一个对象并返回原
+     * 引用，因此 `===` 保持成立，已注册的输出、状态、退出与 ownership listener，以及
+     * {@link CompanionSession.waitForExit} 都继续有效。低于或等于当前值的旧 generation 不会
+     * 让已丢失控制权的 proxy 重新获得控制。页面 reload 会创建新的 SDK 和 proxy，不保证
+     * JavaScript 对象身份跨页面保持。
+     *
+     * 返回的 proxy 公开稳定的 `id`、`alias`、`target`、只读 `capabilities` 和 `state`，不暴露
+     * PID、物理路径、原生句柄或 generation。只有 Host 快照实际包含对应 capability 时，
+     * `stdio`、`attachments`、`notifications` 才存在；调用前应按属性是否存在分支，不能只按
+     * 操作系统猜测。
+     *
+     * 失去控制权不会让进程退出，`state` 仍可为 `running`，
+     * {@link CompanionSession.waitForExit} 也会继续等待同一进程的退出事件。需要继续控制时，
+     * 可在明确的恢复动作中重新调用本方法；不要轮询抢占 controller。该方法本身不会准备或
+     * 启动进程，也不需要可信用户手势或 Host 授权弹窗；创建新进程仍应由新的用户操作调用
+     * `launch()`。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const session = await hbSDK.companion.getActiveSession('runner')
+     * if (!session) {
+     *   const preparation = await hbSDK.companion.getPreparationStatus('runner')
+     *   renderIdleState(preparation)
+     * } else {
+     *   const stopOwnership = session.onOwnershipLost(() => {
+     *     disableCompanionControls()
+     *   })
+     *
+     *   try {
+     *     const exit = await session.waitForExit()
+     *     renderExit(exit)
+     *   } finally {
+     *     stopOwnership()
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link CompanionSession}
+     * @see {@link CompanionSession.waitForExit}
+     * @see {@link CompanionSession.onOwnershipLost}
+     * @see {@link MiniProgramCompanionModule.launch | companion.launch}
+     * @see {@link MiniProgramCompanionModule.getPreparationStatus | companion.getPreparationStatus}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/companion | 受管桌面程序}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
      * @since 0.8.1-alpha.4
      * @hbPlatform windows
      * @hbPlatform macos