@sema-agent/client-core 0.77.1 → 0.78.0

package/dist/controlRouter.d.ts

@@ -1,70 +1,15 @@
-/**
- * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/seam/adapter/upstream/controlRouter.ts 逐字搬入(闭包 1 文件,只 import SDK)。
- */
-/**
- * src/seam/adapter/upstream/controlRouter.ts — the UPSTREAM control-VERB router (NEW file, no CC-logic edit).
- *
- * Where `hitlBridge.ts` owns the suspended → decide → resume HITL loop (the gate-resolution verbs:
- * `approvals.decide` / `assistant.planReview` / `assistant.resume`), THIS module owns the OTHER half of the
- * upstream control channel (contract/04 §5/§6, contract/08 IH-7/IH-8): the SUPERVISION verbs that act on a
- * run *while it works* — submit a turn, steer it mid-flight, kill it, and the client-side QUEUED-COMMAND
- * ordering that has no wire of its own. It is the single choke point that maps a shell control INTENT onto
- * the right `client.runs.*` verb, branching the §9.1 error taxonomy fail-closed.
- *
- * The five routes (contract/04 §5/§6; 08 IH-7/IH-8; the catalog rows it binds):
- *
- *  1. **submit** (IH-1/IH-2, catalog L73/L74). A turn → its OWN durable run: `runs.create(TaskRequest)` →
- *     202 `RunReceipt`. The SAME `sessionId` continues the conversation (the service serializes turns per
- *     session); the SAME `jobId` groups the sub-runs into ONE Task in the work view (contract/04 §5.2,
- *     types.ts:59-63). `runs.create` is a SUBMIT → it carries an idempotency key and the SDK may retry it.
- *
- *  2. **steer** (IH-7, §5.1, catalog L81). Inject mid-flight direction into a RUNNING durable run:
- *     `runs.steer(taskId, { text, mode? })`. The text is untrusted DATA — the shell sends it RAW and the
- *     SERVER fences it (the shell does NOT pre-sanitize control markers). AT-MOST-ONCE: steer is NOT
- *     idempotent, so it is NEVER retried (runs.ts:43). `mode` drains queued steers at the TURN boundary
- *     ("all" = inject all next turn; "one-at-a-time" = one per turn, FIFO). Errors are fail-closed and
- *     dispatched by the WHOLE `steering.*` family (FIX③ 2026-08-07 — 此前只认 2 个码;server 7.4.0
- *     dist 实扫 7 个,主 run steer 路由可达 4 个)。逐码语义 + 处置见 `ControlSafetyCode` 与
- *     文件底部的 `STEERING_CODE_TO_SAFETY` / `STEERING_ADVICE` 两张表。
- *
- *  3. **cancel** (IH-8, §5.3, catalog L84). HARD-STOP an async run: `runs.cancel(taskId)` → 202 `CancelAck`
- *     (`status:"cancelling"` or a terminal no-op). The run then SETTLES to `failed` + `errorCode:"cancelled"`
- *     (NOT a new status — the UI shows "cancelled", not an error). 🔴 A 409 no longer means "suspended"
- *     (server [868] cancels a suspended/needs_review run in place — that IS the unlock handle); it now only
- *     means the pending gate was decided/expired concurrently, surfaced as
- *     `ControlSafetyError('cancel_lost_race')` = re-read state and retry. 404 =
- *     non-owner/unknown (no existence leak). Server-idempotent; not a submit → no SDK retry.
- *
- *  4. **queued commands** (§5.2, catalog L82 `contract-extension`). CC enqueues next turns with a per-message
- *     `priority: 'now'|'next'|'later'` and drops a queued message by uuid (`cancel_async_message`). The SDK
- *     has NEITHER: no `priority` on `TaskRequest`, no drop-queued verb. The faithful behavior is CLIENT-SIDE:
- *     hold a local priority-ordered queue, allow a DEQUEUE *before* submit (the only stop a queued message
- *     has — once submitted the nearest lever is `cancel`, which kills the whole run, not one message), and
- *     drain by submitting each queued turn as its own run under the same sessionId+jobId.
- *
- * Provider- and presentation-agnostic (contract/04 laws 2-3; 08 invariants): every verb stays at
- * `TaskRequest` / `RunReceipt` / `CancelAck` altitude. No Anthropic `effort`/`fast_mode`, no claude.ai
- * control-message shape, no widget/glyph crosses this seam. The router emits the SDK verb; the shell owns the
- * keybinding, the queue chrome, and the "cancelled" badge.
- */
 import type { TaskRequest, RunReceipt, CancelAck, Scenario } from '@sema-agent/sdk';
 export interface RunsResourceLike {
-    /** POST /v1/runs → 202 RunReceipt. SUBMIT-class: carries an idempotency key, SDK may retry (runs.ts:13). */
     create(req: TaskRequest, opts?: {
         idempotencyKey?: string | null;
         signal?: AbortSignal;
     }): Promise<RunReceipt>;
-    /** POST /v1/runs/:id/steer — inject mid-flight direction into a RUNNING run. AT-MOST-ONCE: NOT a submit,
-     *  NEVER retried (runs.ts:51). The text is untrusted DATA the server fences. */
     steer(taskId: string, steer: {
         text: string;
         mode?: 'all' | 'one-at-a-time';
     }, opts?: {
         signal?: AbortSignal;
     }): Promise<unknown>;
-    /** POST /v1/runs/:id/cancel → 202 CancelAck. Hard-stop; server-idempotent; not a submit → no retry
-     *  (runs.ts:34). 🔴 suspended/needs_review 也走这里就地终态化([868]);409 只剩「挂起的 gate 被
-     *  并发决定/过期」这一种(重读状态后重试);404 non-owner。 */
     cancel(taskId: string, opts?: {
         signal?: AbortSignal;
     }): Promise<CancelAck>;
@@ -72,208 +17,57 @@ export interface RunsResourceLike {
 export interface ControlClientLike {
     runs: RunsResourceLike;
 }
-/**
- * A supervision-verb stop the shell must HANDLE, not retry (contract/04 §9.1). The `code` is stable so the
- * shell can branch.
- *
- * 🔴 FIX③(2026-08-07,server 7.4.0 `dist/` 亲扫)—— steering 族此前只认 2 个码。实测 `steering.*`
- * 在 server 7.4.0 里共 **7 个**;主 run 的 `POST /v1/runs/:id/steer` 路由(本 router 唯一调用的那条)
- * 可达其中 4 个:`not_running`(409)/ `invalid_content`(422)/ `queue_full`(409,core 5.14.0 队列
- * 化后新出)/ `duplicate_input_id`(409,调用方带 `Idempotency-Key` 时可达);另外 3 个来自子代
- * steer/resume 面与 workflow agent steer 面(`ambiguous_target` / `ambiguous_label` / `still_running`)。
- * 🔴 **[7226] 包侧缺口 ①(0.68.1)**:码表补**第 8 码** `steering.blocked_by_hook`(422,部署
- * `userPromptSubmit` 门拦下;live 腿可达)。它此前落开集兜底位 `steering_other` —— 兜底位的判词
- * 逐字是「别按成员猜它的意思」,而这一码的处置恰恰是**明确的**(输入未受理、改内容自由重试)⇒
- * 兜底在这一位上不是「安全降级」,是把一条能自救的拒绝渲成一条不知道怎么办的拒绝。
- * SDK 6.3.0 侧已把整族改成**前缀分派**(`SteeringError` 基类),所以「没认全」的后果不是崩溃,
- * 而是那些码原样裸抛给壳 —— 壳只 `catch (e instanceof ControlSafetyError)` 就漏在外面。
- *
- * ⚠️ `still_running` 与 `not_running` **语义正相反**(前者=子代还在飞,该 steer 不该 resume;后者=
- * 它不在飞)。两码塌进同一个判别位会让 UI 说反话,所以它们各占一个码,永不合并。
- */
-export type ControlSafetyCode = 
-/** steer 了一个不在飞的 run(suspended/terminal/跨副本);处置=先解它的 gate,别 steer。 */
-'not_running'
-/** steer 正文带控制面越狱串,core 拒;处置=SURFACE,绝不 strip-and-retry。 */
- | 'invalid_content'
-/** 挂起 checkpoint 上的 steer 队列满了(core fail-loud,绝不驱逐已接受的指令);处置=等它 drain。 */
- | 'queue_full'
-/** 同一个 `Idempotency-Key` 配了**不同**正文;处置=换一个 key,别复用(重发原文没有意义)。 */
- | 'duplicate_input_id'
-/** `ambiguous_target`(子代面)/ `ambiguous_label`(workflow 面)—— 不止一个活体匹配;
- *  两码同一处置(换唯一定位方式),故共用一个判别位,`cause.errorCode` 保留是哪条轴。 */
- | 'ambiguous_target'
-/** 对一个**还在飞**的子代调了 resume;处置=改调 steer,或等它 settle。`not_running` 的反面。 */
- | 'still_running'
-/**
- * 部署的 `userPromptSubmit` 门拦下了这条输入([7226] 包侧缺口 ①,0.68.1;server 契约 (2) 表
- * 第 8 行;core 5.62 design/373 §4.3)。block / 超时 / 崩溃**同码 fail-closed**,成因由 message
- * 判别(携 hook 自己的 bounded reason)。
- * 🔴 **输入未被受理**:没有 `human_input` 帧、`inputId` 不入账 ⇒ 处置 = **改内容自由重试**。
- * 🔴 它与 `invalid_content` / `steering_other` 都**不许合并**:前者是「正文违规,SURFACE 别
- * strip-and-retry」,后者的判词逐字是「别按成员猜它的意思」—— 把一条**能自救**的拒绝塌进这两位
- * 任何一位,UI 都会把「改一句话再发」说成「你没救了」。
- * ⚠️ `/steer` 的 **park 腿结构性不可达本码**(hook 对 parked 转向的拦截发生在 resume 再投递时刻,
- * 走 `steering.parked_input_blocked` 通告);本路由器调的是 live 腿,所以这一位在这里可达。
- */
- | 'blocked_by_hook'
-/** 开集兜底:`steering.` 前缀但本表不认得的**未来**码(SDK 前缀分派同款姿势)。
- *  处置=按「这条 steer 没落地」呈现,并把 `cause.errorCode` 原样打进日志,别按成员猜语义。 */
- | 'steering_other'
-/** cancel 的 409:挂起的 gate 被并发决定/过期(重读状态后重试 cancel)。码缺席 / 认不出的 409 也落这一位(行为同旧)。 */
- | 'cancel_lost_race'
-/** 0.73.1:cancel 的 409 `conflict.run_not_running` —— 取消旗反复挂不上(行在 running 与 park 之间来回跳);引擎一个字节没改,处置 = **直接重试**。
- *  与 `cancel_lost_race` 处置相反(那一位是「别人已经替这条 run 做了决定,先去看结果」),所以各占一个码。 */
- | 'cancel_run_not_running'
-/** 404 — non-owner / unknown run(无存在性谕示器)。 */
- | 'not_found';
+export type ControlSafetyCode = 'not_running' | 'invalid_content' | 'queue_full' | 'duplicate_input_id' | 'ambiguous_target' | 'still_running' | 'blocked_by_hook' | 'steering_other' | 'cancel_lost_race' | 'cancel_run_not_running' | 'not_found';
 export declare class ControlSafetyError extends Error {
     readonly code: ControlSafetyCode;
-    /** The original SDK error, for logging (never re-thrown blind). */
     readonly cause?: unknown | undefined;
-    constructor(message: string, code: ControlSafetyCode, 
-    /** The original SDK error, for logging (never re-thrown blind). */
-    cause?: unknown | undefined);
+    constructor(message: string, code: ControlSafetyCode, cause?: unknown | undefined);
 }
 export type QueuePriority = 'now' | 'next' | 'later';
-/** A turn the user queued but has not yet submitted. `id` is a local uuid the shell uses to DEQUEUE it. */
 export interface QueuedCommand {
     id: string;
     text: string;
     priority: QueuePriority;
 }
 export interface ControlRouterOptions {
-    /** Continue a conversation: the SAME sessionId across turns (contract/04 §5.2; types.ts:59). Omit to start
-     *  fresh — the service mints one and the shell adopts it from the first `RunReceipt.sessionId`. */
     sessionId?: string;
-    /** Group the sub-runs of one logical job into one Task (contract/04 §5.2; types.ts:62). */
     jobId?: string;
-    /** Scenario passthrough (default/oa/code-review/team) applied to every submitted turn. */
     scenario?: Scenario;
-    /** Per-submit system prompt the integrator owns (types.ts:64 — stable cacheable prefix). */
     systemPrompt?: string;
 }
 export declare class ControlRouter {
     private readonly client;
-    /** The run currently in flight — the target of steer/cancel. Null before the first submit. */
     private taskId;
-    /** Adopted from the first RunReceipt when the caller did not pin one (service-minted continuity). */
     private sessionId;
     private readonly jobId;
     private readonly scenario;
     private readonly systemPrompt;
-    /** The client-side queued turns (contract/04 §5.2 — no wire equivalent). */
     private readonly queue;
     private seq;
     constructor(client: ControlClientLike, opts?: ControlRouterOptions);
-    /** The run currently in flight, if any. The shell reads this to know what steer/cancel will target. */
     activeTaskId(): string | null;
-    /** The session token threading the conversation (service-minted after the first submit). */
     activeSessionId(): string | undefined;
-    /**
-     * Submit a turn as a durable async run (`runs.create` → 202 `RunReceipt`). The SAME `sessionId` continues
-     * the conversation (the service serializes turns per session — a session-CAS conflict while a prior run
-     * holds the claim → 409 `Conflict`, contract/04 §5.2 / openapi:173); the SAME `jobId` groups the sub-runs
-     * into one Task in the work view. `runs.create` is a SUBMIT, so the idempotency key rides along (the SDK
-     * auto-generates one and may safely retry on transport failure).
-     *
-     * Adopts the service-minted `sessionId` from the receipt when the caller did not pin one (continuity), and
-     * latches the new run as the active steer/cancel target.
-     */
     submit(text: string, opts?: {
         signal?: AbortSignal;
     }): Promise<RunReceipt>;
-    /** Project the session context + the typed turn into the `@sema-ai` `TaskRequest` wire shape. Secret
-     *  discipline (types.ts:54-58): NEVER put tokens in `objective`/`systemPrompt`. */
     private buildTaskRequest;
-    /**
-     * Steer the RUNNING run: `runs.steer(taskId, { text, mode? })`. Hard rules this method enforces:
-     *
-     *  - **The text is untrusted DATA — sent RAW.** The shell does NOT pre-sanitize control markers; the SERVER
-     *    fences the text (contract/04 §5.1). A text carrying a control-plane escape → 422
-     *    `SteeringInvalidContentError` → surfaced as `ControlSafetyError('invalid_content')` (SURFACE the error;
-     *    never strip-and-retry).
-     *  - **`trusted` is NOT a client field** — the server derives trust from the authenticated operator role;
-     *    this method has no way to assert it, by construction.
-     *  - **AT-MOST-ONCE — never retried.** `runs.steer` is not idempotent and not a submit, so a transport
-     *    failure propagates; the router does NOT auto-resend (a double-steer must be impossible).
-     *  - **Steer needs a RUNNING run.** A suspended/terminal run → 409 `SteeringNotRunningError` → surfaced as
-     *    `ControlSafetyError('not_running')` (resolve its gate via the hitlBridge `decide`, don't steer).
-     *    🔴 FIX③:整个 `steering.*` 族(7 员)都归到 `ControlSafetyError` 上,含 core 5.14.0 队列化
-     *    新出的 `queue_full` / `duplicate_input_id`,以及与 `not_running` **语义相反**的 `still_running`
-     *    (两者永不合并);表外的未来码落开集位 `steering_other`,不再裸抛。
-     *  - **`mode` drains at the TURN boundary** (FORWARD-DRAFT per-call mapping, runs.ts:49-50): `"all"` injects
-     *    all queued steers at the next turn; `"one-at-a-time"` (default) one per turn, FIFO. Steer applies at
-     *    the next turn boundary, not instantly.
-     */
     steer(text: string, mode?: 'all' | 'one-at-a-time', opts?: {
         signal?: AbortSignal;
     }): Promise<unknown>;
-    /**
-     * Cancel (kill) the in-flight run: `runs.cancel(taskId)` → 202 `CancelAck` (`status:"cancelling"` or a
-     * terminal no-op). The run then SETTLES to `failed` + `errorCode:"cancelled"` — the UI shows "cancelled",
-     * NOT an error (the router does not synthesize that terminal; the downstream stream / `terminalToSdkResult`
-     * does). Branching (contract/04 §9.1):
-     *
-     *  - **409 = a LOST CAS RACE, not "suspended".** 🔴 2026-07-31 更正:这段原本写的是「409 = run 是
-     *    suspended,要改走 deny」—— 那是 **[868] 之前**的世界。服务端自 [868] 起对
-     *    suspended/needs_review 的 run **就地取消**(先 CAS 结掉挂起的 checkpoint,再 setTerminal
-     *    释放 session claim),`cancel` 就是那种 run 的恢复把手,不再 409。今天的 409 只剩一种成因:
-     *    挂起的那个 gate 被并发决定/过期了(server `conflict.approval_settled`)。正确处置是**重读
-     *    run 状态后重试 cancel**,而不是去 deny 一个已经不存在的审批 —— 照旧文指路只会指进空处。
-     *    Surfaced as `ControlSafetyError('cancel_lost_race')`(干净切:旧码名 `cancel_suspended` 已
-     *    退役,本仓/壳/web/桌面均无行为消费方,只有一条注释引用,同批改)。
-     *  - **404 = non-owner / unknown.** No existence oracle (404, not 403) → `ControlSafetyError('not_found')`.
-     *
-     * Server-idempotent and NOT a submit, so a successful cancel is safe to repeat (a terminal run no-ops);
-     * the router still does not auto-retry on transport failure (the shell re-invokes on the user's repeat).
-     */
     cancel(opts?: {
         signal?: AbortSignal;
     }): Promise<CancelAck>;
-    /** Enqueue a turn for later submission. `now` jumps the line, `next` (default) is FIFO, `later` trails.
-     *  Returns the queued row (its `id` is the dequeue handle). Nothing leaves the machine until `drainNext`. */
     enqueue(text: string, priority?: QueuePriority): QueuedCommand;
-    /** Drop a STILL-QUEUED turn by id BEFORE it is submitted (the only stop a queued message has —
-     *  contract/04 §5.2). Returns true if it was in the queue, false if absent / already drained (mirrors CC's
-     *  `cancel_async_message` → `{cancelled:false}` "not in the queue / already dequeued"). */
     dequeue(id: string): boolean;
-    /** A stable, priority-banded view of the queue (the shell renders this; drain order matches it). */
     pending(): readonly QueuedCommand[];
-    /**
-     * Drain the highest-priority queued turn: dequeue it and `submit` it as its own durable run (same session
-     * → continues the conversation; same jobId → one Task). Returns the `RunReceipt`, or null when the queue is
-     * empty. The session serializes turns, so the caller drains one at a time (submit, await the run, drain the
-     * next); submitting while a prior run holds the session claim surfaces the SDK's 409 `ConflictError` from
-     * `submit` — the shell waits and re-drains (contract/04 §5.2; openapi:173).
-     */
     drainNext(opts?: {
         signal?: AbortSignal;
     }): Promise<RunReceipt | null>;
     private nextId;
 }
-/** design/161 批 A 起导出:错误判型单源 —— 包内新读面(backgroundView 等)一律吃这一口,不再各自
- *  手摸 `(e as any).status`。 */
 export interface ErrCodes {
     code?: string | undefined;
     name?: string | undefined;
     status?: number | undefined;
 }
-/**
- * Read a normalized error code/status off any SDK error shape variant (errorCode / code / name / status).
- * REF-CC-135(TYPESHAPE-15,P3 wave1 卡C-argv):判型单源此前返回 3 个裸 unknown(B2/B4 违规——调用方
- * `code === 404`(status 才是数字位)这类拼写型 bug 能编译期全绿恒 false)。窄化成具名 `ErrCodes`,
- * 非匹配类型一律降到 undefined(而不是把垃圾值原样放行)。
- *
- * 🔴 [2393] sweep-F6(2026-08-03 全窗复审)**这不只是类型收窄,是运行期丢值**(裁定:保留行为,
- * 但把它记成可核的承诺):旧实现 `return { code: o.errorCode, name: o.name, status: o.status ?? o.statusCode }`
- * 是原样透传。今天,包外消费者若拿到的错误对象上 `status` 是数字**串**(某些传输层/代理把 status
- * 序列化成字符串)、或 `errorCode` 是数值码,读到的一律是 `undefined`。
- * 方向对(「拿到一个不好用的值」→「诚实地什么都没有」;下游 `code === 404` 那类拼写型 bug 也因此
- * 编译期就红),但它是**公面行为变更**:本函数是 npm 导出的判型单源,三端各自的错误对象形需要复核。
- * ⇒ 已进 `docs/refactor/README.md` 的提货单/BREAKING 清单(此前只列四条 wire BREAKING,签名级与
- * 行为级的这几条靠人工列表兜底,而列表没列)。
- * 判据:pure 门 B5 段那组钉现在也钉「脏形一律降 undefined、绝不悄悄回落成 0/空串」——
- * 谁要把某一种脏形改回透传,必须先在那里显形。
- */
 export declare function errCodes(e: unknown): ErrCodes;

package/dist/controlRouter.js

@@ -3,27 +3,21 @@ import { uuid } from './adapter/types.js';
 export class ControlSafetyError extends Error {
     code;
     cause;
-    constructor(message, code, 
-    /** The original SDK error, for logging (never re-thrown blind). */
-    cause) {
+    constructor(message, code, cause) {
         super(message);
         this.code = code;
         this.cause = cause;
         this.name = 'ControlSafetyError';
     }
 }
-/** Band rank for stable priority ordering: lower drains first. */
 const BAND_RANK = { now: 0, next: 1, later: 2 };
 export class ControlRouter {
     client;
-    /** The run currently in flight — the target of steer/cancel. Null before the first submit. */
     taskId = null;
-    /** Adopted from the first RunReceipt when the caller did not pin one (service-minted continuity). */
     sessionId;
     jobId;
     scenario;
     systemPrompt;
-    /** The client-side queued turns (contract/04 §5.2 — no wire equivalent). */
     queue = [];
     seq = 0;
     constructor(client, opts = {}) {
@@ -33,40 +27,21 @@ export class ControlRouter {
         this.scenario = opts.scenario;
         this.systemPrompt = opts.systemPrompt;
     }
-    /** The run currently in flight, if any. The shell reads this to know what steer/cancel will target. */
     activeTaskId() {
         return this.taskId;
     }
-    /** The session token threading the conversation (service-minted after the first submit). */
     activeSessionId() {
         return this.sessionId;
     }
-    // ── §1. submit — a turn → its own durable run (contract/04 §5.2; 08 IH-2, catalog L74) ───────────────────
-    /**
-     * Submit a turn as a durable async run (`runs.create` → 202 `RunReceipt`). The SAME `sessionId` continues
-     * the conversation (the service serializes turns per session — a session-CAS conflict while a prior run
-     * holds the claim → 409 `Conflict`, contract/04 §5.2 / openapi:173); the SAME `jobId` groups the sub-runs
-     * into one Task in the work view. `runs.create` is a SUBMIT, so the idempotency key rides along (the SDK
-     * auto-generates one and may safely retry on transport failure).
-     *
-     * Adopts the service-minted `sessionId` from the receipt when the caller did not pin one (continuity), and
-     * latches the new run as the active steer/cancel target.
-     */
     async submit(text, opts) {
         const req = this.buildTaskRequest(text);
         const receipt = await this.client.runs.create(req, opts?.signal !== undefined ? { signal: opts.signal } : undefined);
-        // Adopt service-minted continuity + latch the in-flight run.
         if (this.sessionId === undefined)
             this.sessionId = receipt.sessionId;
         this.taskId = receipt.taskId;
         return receipt;
     }
-    /** Project the session context + the typed turn into the `@sema-ai` `TaskRequest` wire shape. Secret
-     *  discipline (types.ts:54-58): NEVER put tokens in `objective`/`systemPrompt`. */
     buildTaskRequest(text) {
-        // 空内容守卫(2026-07-16 唤醒 400 批,同病同修):SDK/控制面递来的空/全空白 user_message 绝不作为
-        // 空 objective 上 wire——引擎会把空 user 消息写进会话持久历史(provider 400 + session 毒化)。
-        // 与 CC createUserMessage 的 NO_CONTENT_MESSAGE 同语义占位。
         const req = { objective: text.trim().length > 0 ? text : '(no content)' };
         if (this.sessionId !== undefined)
             req.sessionId = this.sessionId;
@@ -78,68 +53,23 @@ export class ControlRouter {
             req.systemPrompt = this.systemPrompt;
         return req;
     }
-    // ── §2. steer — inject mid-flight direction (contract/04 §5.1; 08 IH-7, catalog L81) ─────────────────────
-    /**
-     * Steer the RUNNING run: `runs.steer(taskId, { text, mode? })`. Hard rules this method enforces:
-     *
-     *  - **The text is untrusted DATA — sent RAW.** The shell does NOT pre-sanitize control markers; the SERVER
-     *    fences the text (contract/04 §5.1). A text carrying a control-plane escape → 422
-     *    `SteeringInvalidContentError` → surfaced as `ControlSafetyError('invalid_content')` (SURFACE the error;
-     *    never strip-and-retry).
-     *  - **`trusted` is NOT a client field** — the server derives trust from the authenticated operator role;
-     *    this method has no way to assert it, by construction.
-     *  - **AT-MOST-ONCE — never retried.** `runs.steer` is not idempotent and not a submit, so a transport
-     *    failure propagates; the router does NOT auto-resend (a double-steer must be impossible).
-     *  - **Steer needs a RUNNING run.** A suspended/terminal run → 409 `SteeringNotRunningError` → surfaced as
-     *    `ControlSafetyError('not_running')` (resolve its gate via the hitlBridge `decide`, don't steer).
-     *    🔴 FIX③:整个 `steering.*` 族(7 员)都归到 `ControlSafetyError` 上,含 core 5.14.0 队列化
-     *    新出的 `queue_full` / `duplicate_input_id`,以及与 `not_running` **语义相反**的 `still_running`
-     *    (两者永不合并);表外的未来码落开集位 `steering_other`,不再裸抛。
-     *  - **`mode` drains at the TURN boundary** (FORWARD-DRAFT per-call mapping, runs.ts:49-50): `"all"` injects
-     *    all queued steers at the next turn; `"one-at-a-time"` (default) one per turn, FIFO. Steer applies at
-     *    the next turn boundary, not instantly.
-     */
     async steer(text, mode, opts) {
         if (this.taskId === null) {
             throw new ControlSafetyError('no run in flight to steer — submit a turn first', 'not_running');
         }
-        // Raw text, no pre-sanitize (the server fences). `mode` omitted → server default one-at-a-time.
         const body = mode !== undefined ? { text, mode } : { text };
         try {
             return await this.client.runs.steer(this.taskId, body, opts?.signal !== undefined ? { signal: opts.signal } : undefined);
         }
         catch (e) {
-            // FIX③:整族逐码分派(表见文件底部)。前缀在场即归族 —— 未来新码落 `steering_other`,
-            // 绝不再裸抛给壳(裸抛 = 壳的 `instanceof ControlSafetyError` 分支整条漏在外面)。
             const verdict = steeringVerdict(e);
             if (verdict !== undefined) {
                 const wireCode = errCodes(e).code ?? errCodes(e).name ?? 'steering.<unknown>';
                 throw new ControlSafetyError(`${wireCode} — ${STEERING_ADVICE.get(verdict) ?? 'steering refused'}`, verdict, e);
             }
-            // Any other error (auth/transport): NOT retried (steer is at-most-once) — propagate to the shell.
             throw e;
         }
     }
-    // ── §3. cancel — hard-stop / kill the run (contract/04 §5.3; 08 IH-8, catalog L84) ───────────────────────
-    /**
-     * Cancel (kill) the in-flight run: `runs.cancel(taskId)` → 202 `CancelAck` (`status:"cancelling"` or a
-     * terminal no-op). The run then SETTLES to `failed` + `errorCode:"cancelled"` — the UI shows "cancelled",
-     * NOT an error (the router does not synthesize that terminal; the downstream stream / `terminalToSdkResult`
-     * does). Branching (contract/04 §9.1):
-     *
-     *  - **409 = a LOST CAS RACE, not "suspended".** 🔴 2026-07-31 更正:这段原本写的是「409 = run 是
-     *    suspended,要改走 deny」—— 那是 **[868] 之前**的世界。服务端自 [868] 起对
-     *    suspended/needs_review 的 run **就地取消**(先 CAS 结掉挂起的 checkpoint,再 setTerminal
-     *    释放 session claim),`cancel` 就是那种 run 的恢复把手,不再 409。今天的 409 只剩一种成因:
-     *    挂起的那个 gate 被并发决定/过期了(server `conflict.approval_settled`)。正确处置是**重读
-     *    run 状态后重试 cancel**,而不是去 deny 一个已经不存在的审批 —— 照旧文指路只会指进空处。
-     *    Surfaced as `ControlSafetyError('cancel_lost_race')`(干净切:旧码名 `cancel_suspended` 已
-     *    退役,本仓/壳/web/桌面均无行为消费方,只有一条注释引用,同批改)。
-     *  - **404 = non-owner / unknown.** No existence oracle (404, not 403) → `ControlSafetyError('not_found')`.
-     *
-     * Server-idempotent and NOT a submit, so a successful cancel is safe to repeat (a terminal run no-ops);
-     * the router still does not auto-retry on transport failure (the shell re-invokes on the user's repeat).
-     */
     async cancel(opts) {
         if (this.taskId === null) {
             throw new ControlSafetyError('no run in flight to cancel', 'not_found');
@@ -148,7 +78,6 @@ export class ControlRouter {
             return await this.client.runs.cancel(this.taskId, opts?.signal !== undefined ? { signal: opts.signal } : undefined);
         }
         catch (e) {
-            // 0.73.1:409 先按机器码分家(见 wireRefusalCopy.ts 头注);码缺席 / 认不出 ⇒ 落到下面那条旧臂,行为逐字同旧。
             if (cancelConflictFromError(e)?.kind === 'run_not_running') {
                 throw new ControlSafetyError(`runs.cancel 409 conflict.run_not_running — ${cancelConflictContent({ kind: 'run_not_running' })}`, 'cancel_run_not_running', e);
             }
@@ -162,21 +91,11 @@ export class ControlRouter {
             throw e;
         }
     }
-    // ── §4. queued commands — client-side priority + drop (contract/04 §5.2, catalog L82) ────────────────────
-    //
-    // The SDK has no per-message priority and no drop-queued verb. The router holds the queue locally: enqueue
-    // by priority band, dequeue a still-queued turn by its local id, and drain by submitting each as its own
-    // run under the same session. A submitted turn LEAVES the queue — its only after-submit stop is `cancel`.
-    /** Enqueue a turn for later submission. `now` jumps the line, `next` (default) is FIFO, `later` trails.
-     *  Returns the queued row (its `id` is the dequeue handle). Nothing leaves the machine until `drainNext`. */
     enqueue(text, priority = 'next') {
         const cmd = { id: this.nextId(), text, priority };
         this.queue.push(cmd);
         return cmd;
     }
-    /** Drop a STILL-QUEUED turn by id BEFORE it is submitted (the only stop a queued message has —
-     *  contract/04 §5.2). Returns true if it was in the queue, false if absent / already drained (mirrors CC's
-     *  `cancel_async_message` → `{cancelled:false}` "not in the queue / already dequeued"). */
     dequeue(id) {
         const i = this.queue.findIndex((c) => c.id === id);
         if (i < 0)
@@ -184,17 +103,9 @@ export class ControlRouter {
         this.queue.splice(i, 1);
         return true;
     }
-    /** A stable, priority-banded view of the queue (the shell renders this; drain order matches it). */
     pending() {
         return [...this.queue].sort((a, b) => BAND_RANK[a.priority] - BAND_RANK[b.priority]);
     }
-    /**
-     * Drain the highest-priority queued turn: dequeue it and `submit` it as its own durable run (same session
-     * → continues the conversation; same jobId → one Task). Returns the `RunReceipt`, or null when the queue is
-     * empty. The session serializes turns, so the caller drains one at a time (submit, await the run, drain the
-     * next); submitting while a prior run holds the session claim surfaces the SDK's 409 `ConflictError` from
-     * `submit` — the shell waits and re-drains (contract/04 §5.2; openapi:173).
-     */
     async drainNext(opts) {
         const ordered = this.pending();
         const head = ordered[0];
@@ -208,38 +119,16 @@ export class ControlRouter {
         return `q-${this.seq}-${uuid()}`;
     }
 }
-/**
- * Read a normalized error code/status off any SDK error shape variant (errorCode / code / name / status).
- * REF-CC-135(TYPESHAPE-15,P3 wave1 卡C-argv):判型单源此前返回 3 个裸 unknown(B2/B4 违规——调用方
- * `code === 404`(status 才是数字位)这类拼写型 bug 能编译期全绿恒 false)。窄化成具名 `ErrCodes`,
- * 非匹配类型一律降到 undefined(而不是把垃圾值原样放行)。
- *
- * 🔴 [2393] sweep-F6(2026-08-03 全窗复审)**这不只是类型收窄,是运行期丢值**(裁定:保留行为,
- * 但把它记成可核的承诺):旧实现 `return { code: o.errorCode, name: o.name, status: o.status ?? o.statusCode }`
- * 是原样透传。今天,包外消费者若拿到的错误对象上 `status` 是数字**串**(某些传输层/代理把 status
- * 序列化成字符串)、或 `errorCode` 是数值码,读到的一律是 `undefined`。
- * 方向对(「拿到一个不好用的值」→「诚实地什么都没有」;下游 `code === 404` 那类拼写型 bug 也因此
- * 编译期就红),但它是**公面行为变更**:本函数是 npm 导出的判型单源,三端各自的错误对象形需要复核。
- * ⇒ 已进 `docs/refactor/README.md` 的提货单/BREAKING 清单(此前只列四条 wire BREAKING,签名级与
- * 行为级的这几条靠人工列表兜底,而列表没列)。
- * 判据:pure 门 B5 段那组钉现在也钉「脏形一律降 undefined、绝不悄悄回落成 0/空串」——
- * 谁要把某一种脏形改回透传,必须先在那里显形。
- */
 export function errCodes(e) {
     if (!e || typeof e !== 'object')
         return {};
     const o = e;
-    // [1912] errorCode 恒在(server ≥1.302 canonical)——`?? o.code` 老兜底已清;status 双键保留(HTTP 层形非 wire 键)。
     const code = typeof o.errorCode === 'string' ? o.errorCode : undefined;
     const name = typeof o.name === 'string' ? o.name : undefined;
     const rawStatus = o.status ?? o.statusCode;
     const status = typeof rawStatus === 'number' ? rawStatus : undefined;
     return { code, name, status };
 }
-// ── steering 错误族的**逐码表**(FIX③,server 7.4.0 dist 亲扫 + SDK 6.3.0 errors.d.ts 对表)────
-//
-// 🔴 用 `Map` 不是对象字面量:键来自 wire 的 `errorCode` 字符串,对象字面量上 `map['__proto__']`
-//    会摸到 Object.prototype(adapt/arms.ts 头注登记的同一条纪律)。
 const STEERING_CODE_TO_SAFETY = new Map([
     ['steering.not_running', 'not_running'],
     ['steering.invalid_content', 'invalid_content'],
@@ -248,14 +137,8 @@ const STEERING_CODE_TO_SAFETY = new Map([
     ['steering.ambiguous_target', 'ambiguous_target'],
     ['steering.ambiguous_label', 'ambiguous_target'],
     ['steering.still_running', 'still_running'],
-    // [7226] 包侧缺口 ①(0.68.1):server 契约 (2) 表第 8 码(422)。SDK 8.8.0 **没有**专属子类
-    // (`errors.d.ts` 的 `Steering*Error` 只有六只)⇒ 只能按 `errorCode` 认;认不出时它会落开集位
-    // `steering_other`,而那一位的判词是「别猜它的意思」—— 恰好把一条「改内容重试即可」的拒绝
-    // 说成没救。所以码表必须点名它,不能靠前缀兜底。
     ['steering.blocked_by_hook', 'blocked_by_hook'],
 ]);
-/** SDK 的 typed 子类名兜底(错误对象被传输层剥掉 `errorCode` 时仍认得族;`SteeringError` 基类本身
- *  = 「是 steering 族但没有专属子类」⇒ 落开集臂)。 */
 const STEERING_NAME_TO_SAFETY = new Map([
     ['SteeringNotRunningError', 'not_running'],
     ['SteeringInvalidContentError', 'invalid_content'],
@@ -263,7 +146,6 @@ const STEERING_NAME_TO_SAFETY = new Map([
     ['SteeringStillRunningError', 'still_running'],
     ['SteeringError', 'steering_other'],
 ]);
-/** 每个判别位的处置指路(壳把它原样打给用户/日志 —— 判词必须说得出「现在该做什么」)。 */
 const STEERING_ADVICE = new Map([
     ['not_running', 'the run is suspended/terminal/on another replica — resolve its gate via decide, do not steer'],
     ['invalid_content', 'the steer text carried a control-plane escape; surface it, do not strip-and-retry'],
@@ -274,29 +156,19 @@ const STEERING_ADVICE = new Map([
     ['blocked_by_hook', "this deployment's userPromptSubmit gate refused the input (block, timeout and crash all report this one code, fail-closed) — the input was NOT accepted: no human_input frame, the inputId is not on the ledger, so editing the text and sending again is a normal retry, not a duplicate"],
     ['steering_other', 'an unrecognized steering.* refusal (open set) — the steer did NOT land; log the errorCode verbatim, do not guess its meaning'],
 ]);
-/**
- * 把一个 steer 抛出的错误判成 steering 族的哪一位。不是 steering 族 ⇒ `undefined`(调用方原样抛,
- * 路由器绝不越界吞 auth/transport 的错)。
- */
 function steeringVerdict(e) {
     const { code, name } = errCodes(e);
     if (typeof code === 'string' && code.startsWith('steering.')) {
-        // 前缀在场即归族:表里没有的**未来**码落开集臂,而不是漏出去(SDK 6.3.0 的同款前缀分派)。
         return STEERING_CODE_TO_SAFETY.get(code) ?? 'steering_other';
     }
     if (typeof name === 'string')
         return STEERING_NAME_TO_SAFETY.get(name);
     return undefined;
 }
-/** A 409 on `cancel` = the pending gate was decided/expired concurrently (lost CAS race; server
- *  `conflict.approval_settled`). 🔴 它**不再**表示「run 是 suspended」——[868] 起 suspended/needs_review
- *  的 run 由 cancel 就地终态化。
- *  The SDK raises a generic `ConflictError` (status 409) for this case — there is no dedicated subclass. */
 function isCancelSuspendedConflict(e) {
     const { name, status } = errCodes(e);
     return name === 'ConflictError' || status === 409;
 }
-/** 404 — non-owner / unknown run; the SDK raises `NotFoundError` (no existence oracle, contract/04 §9.1). */
 function isNotFound(e) {
     const { name, status } = errCodes(e);
     return name === 'NotFoundError' || status === 404;