@sema-agent/sdk 4.0.1 → 4.2.0

package/dist/events.d.ts

@@ -18,7 +18,9 @@
  *    (design/158 B2 corrected the earlier "LIVE-only, never persisted" claim here — see the arm's own doc).
  *  - §E13: a `workspace_changed` arm (a `cd` moved the tracked cwd — LIVE-only, for the shell's path display).
  */
-import type { TaskResult, CheckpointGate, ModelUsageDelta } from "./types.js";
+import type { TaskResult, ActiveRunConflictDoneResult, CheckpointGate, ModelUsageDelta } from "./types.js";
+/** TR-7:`question` 臂的载荷与 `client.questions` 面**同一个**类型(单源)—— 类型-only 导入,运行时零边。 */
+import type { AskQuestion } from "./resources/questions.js";
 /**
  * design/99 §E2 (core `TaskEventIdentity` types.ts:986-989; service `identityFields` project.ts:78-83) — the
  * lightweight per-event identity carried by every CONTENT event (live + durable). ADDITIVE / tolerate-absent:
@@ -306,10 +308,20 @@ export type AgentEvent =
     type: "model_usage";
     usage: Record<string, ModelUsageDelta>;
 }
-/** carries the full TaskResult (output string at .result, stats at .stats) — service Drift 4 */
+/** The stream's terminal. `result` 是**判别联合**(契约调和车1 E,2026-08-02)——别假定完整 TaskResult:
+ *   · {@link TaskResult} —— 正常终态(输出文本在 `.result`,统计在 `.stats`),service Drift 4;
+ *   · {@link ActiveRunConflictDoneResult} —— SSE 提交腿的**拒绝**终帧(session 已有活跃 run;server
+ *     `routes/tasks.ts:234` 把 409 编码成这一帧),**没有** `taskId`/`sessionId`/`stats`。
+ *  窄化:`if ("stats" in ev.result)` ⇒ 完整 TaskResult,`else` ⇒ 拒绝形(或按
+ *  `ev.result.errorCode === "conflict.session_active_run"`)。⚠️ `status` 不是判别位,两形都有。
+ *
+ *  `replay`(契约调和车1 F;server `routes/tasks.ts:71` 缓存命中重放 / `:919` 并发去重腿)= `true` 表示
+ *  这条终态**不是**你这次提交真跑出来的:同 `Idempotency-Key` 命中在飞/已结算的那一次,`result` 是原
+ *  run 的终态逐字回放。live 腿恒**缺席**(不发 `false`)——UI 据此说「重放」,而不是暗示活干了两遍。 */
  | {
     type: "done";
-    result: TaskResult;
+    result: TaskResult | ActiveRunConflictDoneResult;
+    replay?: boolean;
 }
 /** DURABLE-only (the live loop never writes `failed`; the durable leg synthesizes it from the run row). */
  | {
@@ -437,7 +449,67 @@ export type AgentEvent =
     source: string;
     preview: string;
     [k: string]: unknown;
-} & EventIdentity);
+} & EventIdentity)
+/** 🔴 CB-1(=TR-6)—— 流的 **15 分钟帽帧**,不是 run 的失败(server `src/http/sse-log.ts:86`;
+ *  trace 腿同形,`routes/trace-usage.ts:294`)。server 写的是命名帧 `event: error` + 载荷里回声 `type`。
+ *
+ *  🔴 **到达 ≠ run 死了**:它明说「run 仍然活着」。正确处置 = 按 `Last-Event-ID` **重连续读**
+ *  (durable 腿本就带 `id:`,SDK 的 `runs.events` 自动做这件事);把它当终态渲染会把一条还在跑的任务
+ *  在 UI 上判死。`done`/`failed` 才是终态臂 —— 本臂**不终止**生成器。
+ *  已知 `errorCode`:`STREAM_MAX_DURATION`(开集:按码分支,未知码按「可重连的流控信号」通用降级)。 */
+ | {
+    type: "error";
+    errorCode: string;
+    message?: string;
+}
+/** TR-7 —— AskUserQuestion 的**开问**帧。live 腿走 `event: question` 名分派(`routes/tasks.ts:677`,
+ *  与 `elicitation` / `tool_approval` 同一条 out-of-band 通道);durable 腿由 `runs.ts:498` 的
+ *  `append(type, rest)` 落库,于是同名帧也出现在 `GET /v1/runs/:id/events` 的重放上 —— 这一半此前
+ *  SDK/spec 两侧同缺。键形抄 server `src/question.ts:38` 的 `QuestionFrame` 真铸点。
+ *  🔴 UNTRUSTED-for-display:`questions` 已脱敏,渲染即可,**永不回喂模型**。
+ *  `questions` 缺席 = 载荷超 16 KiB 帽被丢(那一问 headless-default,人看不到也答不了)。 */
+ | {
+    type: "question";
+    questionId: string;
+    questions?: AskQuestion[];
+}
+/** TR-7 —— AskUserQuestion 的**收尾**帧(对话框消失信号)。`outcome`:`answered` = 人答了;
+ *  `unanswered` = ttl/abort/限流放行(模型拿到 headless 默认值)。纯装饰,不影响 run 状态。 */
+ | {
+    type: "question_complete";
+    questionId: string;
+    outcome?: "answered" | "unanswered";
+}
+/** TR-7 —— 入站 MCP elicitation 的**开问**帧(server `src/elicitation.ts:42` 的 `ElicitationFrame`)。
+ *  两腿同上:live 走 `event:` 名分派,durable 腿经 `append` 落库后在重放里以本臂出现。
+ *  🔴 UNTRUSTED:`message` 已 fence + 脱敏,`requestedSchema` 是**不解释**的透传(仍需壳侧 fence)。
+ *  v1 恒 `mode:"form"`(url-mode 在上游被拒——钓鱼面)。 */
+ | {
+    type: "elicitation";
+    elicitationId: string;
+    mcpServerName: string;
+    message?: string;
+    requestedSchema?: unknown;
+    mode?: "form";
+}
+/** TR-7 —— elicitation 的**收尾**帧;`action` = 它怎么了结的(对话框消失原因)。 */
+ | {
+    type: "elicitation_complete";
+    elicitationId: string;
+    mcpServerName: string;
+    action?: "accept" | "decline" | "cancel";
+}
+/** TR-7 —— 异步 workflow 完成的**带外投递**帧(server `src/orchestration/workflow-completion-inbox.ts:522`
+ *  的 `emit({type:"workflow_complete", runId, status, summary})`)。投递时机 = 该 session **下一条腿开流**
+ *  时排空 inbox:sync 腿直接写 live 帧,bg / resume 腿把它 `append` 成 durable 事件供 tailing 客户端重放。
+ *  🔴 **至少一次**语义(两阶段:emit 成功才 ack)—— 两条腿同时开可能双发,消费方按 `runId` 去重。
+ *  `summary` 是脱敏过的自由文本(UNTRUSTED-for-display)。 */
+ | {
+    type: "workflow_complete";
+    runId: string;
+    status: string;
+    summary: string;
+};
 /** Exhaustiveness helper for consumers' switch statements.
  *  ⚠️ COMPILE-TIME aid only ([1543] SDK-H): the wire is an OPEN set — a newer server may emit frame types
  *  this union does not yet name, and a `default: assertNever(ev)` switch would then THROW AT RUNTIME on a

package/dist/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAsXA;;;;8GAI8G;AAC9G,MAAM,UAAU,WAAW,CAAC,CAAQ;IAClC,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAChE,CAAC"}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAsaA;;;;8GAI8G;AAC9G,MAAM,UAAU,WAAW,CAAC,CAAQ;IAClC,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAChE,CAAC"}

package/dist/health.d.ts

@@ -3,7 +3,7 @@
  * require an AgentClient:
  *
  *  ① {@link probeHealth} — process-noise liveness. `/health` is the worker's UNAUTHENTICATED door
- *     (server 1.214 server.js:296 — no token, no principal), and the probe's whole job is "is anything
+ *     (server `src/http/server.ts:713` — no token, no principal), and the probe's whole job is "is anything
  *     alive there?" BEFORE credentials/TOFU exist (engine spawn wait-loops, port arbitration, dead-engine
  *     triage, teardown confirmation — the shell's 6-strong probe family). Constructing a principal-first,
  *     token-bearing client to ask that would invert the trust order, so the SDK ships the probe as a STATIC
@@ -17,7 +17,7 @@
  * Everything ELSE goes through AgentClient — these two are the WHOLE exception surface (plus labelled
  * contract-probe raws in tests; see the SDK constitution in the repo CLAUDE.md).
  */
-/** The `/health` 200 body, subset-typed (server 1.214 server.js:296-320 — exact producer; open set for the
+/** The `/health` 200 body, subset-typed (server `src/http/server.ts:713` 起的 /health 分支 — exact producer; open set for the
  *  conditional fields: draining/durable/ready/restartRequired etc. appear only when true/degraded). */
 export interface EngineHealth {
     /** "ok" on the live door — {@link probeHealth} requires it for `alive` (a 200 with anything else is `not_ok`). */

package/dist/health.js

@@ -3,7 +3,7 @@
  * require an AgentClient:
  *
  *  ① {@link probeHealth} — process-noise liveness. `/health` is the worker's UNAUTHENTICATED door
- *     (server 1.214 server.js:296 — no token, no principal), and the probe's whole job is "is anything
+ *     (server `src/http/server.ts:713` — no token, no principal), and the probe's whole job is "is anything
  *     alive there?" BEFORE credentials/TOFU exist (engine spawn wait-loops, port arbitration, dead-engine
  *     triage, teardown confirmation — the shell's 6-strong probe family). Constructing a principal-first,
  *     token-bearing client to ask that would invert the trust order, so the SDK ships the probe as a STATIC

package/dist/idempotency.d.ts

@@ -2,7 +2,17 @@
  * Idempotency — auto UUID key for submit-class requests (DESIGN §2.3) + the RED LINE: a submit (POST tasks/
  * runs) is retried ONLY when an idempotency key exists. The SDK auto-generates one, so retries are safe by
  * default; a caller that explicitly sets `idempotencyKey: null` to disable it also LOSES auto-retry on submits.
- * (The worker dedups by this key: same key in-flight/settled → reuse, concurrent → 409 — server-verified.)
+ *
+ * 🔴 [2400] CB-10 — what the worker actually does with the key (server `src/http/idempotency.ts`
+ * `IdempotencyCache.run`): the FIRST request under a key stores its **promise**, and every later request under
+ * the same key — **including a CONCURRENT one** — `await`s that SAME promise and receives the SAME response.
+ * There is NO 409 on a concurrent duplicate (the old note here said there was; nothing in the server mints one).
+ * A settled CACHEABLE result is replayed for the entry TTL (15 min); a REJECTION, or a resolution the route
+ * marked un-cacheable (e.g. a transient 409), is evicted so a genuine retry re-runs.
+ * ⚠️ Scope + reach: the key is namespaced by the credential-derived source + principal server-side
+ * (`scopedIdempotencyKey`, BL-3) so a replay is same-caller-only; and the cache is PER-POD/in-memory — for
+ * cross-instance exactly-once use the durable door instead (`POST /v1/runs` with a caller-minted
+ * `body.taskId`, see `TaskRequest.taskId`).
  */
 export declare function newIdempotencyKey(): string;
 /** Resolve the effective key: explicit string keeps it; `null` disables (and disables submit retry); undefined

package/dist/idempotency.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;iHACiH;AACjH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAGxF"}
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;iHACiH;AACjH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAGxF"}

package/dist/idempotency.js

@@ -2,7 +2,17 @@
  * Idempotency — auto UUID key for submit-class requests (DESIGN §2.3) + the RED LINE: a submit (POST tasks/
  * runs) is retried ONLY when an idempotency key exists. The SDK auto-generates one, so retries are safe by
  * default; a caller that explicitly sets `idempotencyKey: null` to disable it also LOSES auto-retry on submits.
- * (The worker dedups by this key: same key in-flight/settled → reuse, concurrent → 409 — server-verified.)
+ *
+ * 🔴 [2400] CB-10 — what the worker actually does with the key (server `src/http/idempotency.ts`
+ * `IdempotencyCache.run`): the FIRST request under a key stores its **promise**, and every later request under
+ * the same key — **including a CONCURRENT one** — `await`s that SAME promise and receives the SAME response.
+ * There is NO 409 on a concurrent duplicate (the old note here said there was; nothing in the server mints one).
+ * A settled CACHEABLE result is replayed for the entry TTL (15 min); a REJECTION, or a resolution the route
+ * marked un-cacheable (e.g. a transient 409), is evicted so a genuine retry re-runs.
+ * ⚠️ Scope + reach: the key is namespaced by the credential-derived source + principal server-side
+ * (`scopedIdempotencyKey`, BL-3) so a replay is same-caller-only; and the cache is PER-POD/in-memory — for
+ * cross-instance exactly-once use the durable door instead (`POST /v1/runs` with a caller-minted
+ * `body.taskId`, see `TaskRequest.taskId`).
  */
 export function newIdempotencyKey() {
     return crypto.randomUUID();

package/dist/idempotency.js.map

@@ -1 +1 @@
-{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC;AAC7B,CAAC;AAED;iHACiH;AACjH,MAAM,UAAU,qBAAqB,CAAC,QAAmC;IACvE,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,QAAQ,IAAI,iBAAiB,EAAE,CAAC;AACzC,CAAC"}
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC;AAC7B,CAAC;AAED;iHACiH;AACjH,MAAM,UAAU,qBAAqB,CAAC,QAAmC;IACvE,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,QAAQ,IAAI,iBAAiB,EAAE,CAAC;AACzC,CAAC"}

package/dist/index.d.ts

@@ -3,19 +3,19 @@ export { AgentClient, type AgentClientConfig, type AgentAuthToken } from "./clie
 /** Control plane (TOB): sema-registry / config-center `/api/config/*`. A peer client (different backend +
  *  secret) for managing the fleet config — see control-client.ts. */
 export { ControlClient, type ControlClientConfig } from "./control-client.js";
-export type { Principal, Scenario, RunStatus, TaskStats, TaskRequest, TaskAgentDefinition, TaskResult, RunReceipt, RunRecord, CancelAck, Artifact, LeaderReceipt, LeaderRecord, SupervisorCostBreakdown, Capabilities, ScenarioDetail, PendingCheckpoint, SessionRecord, SkillSpec, TaskSummary, CheckpointGate, TraceTurn, TraceBlock, PromptManifest, PromptEpoch, SessionSummary, SessionListPage, SessionPermissionRules, StoredSessionRules, McpServerStatus, McpStatusPanel, SessionWindow, SessionMessageEnvelope, SyncEntry, SyncSnapshot, SyncAnchor, SessionRulesRecord, SessionManifest, SessionBundle, SyncRelation, SyncConflictRelation, ImportStaged, ImportCommitted, TraceStreamEvent, WorkflowStreamEvent, CheckpointSummary, InboxRow, AssistantGate, AssistantTask, PlanReviewRequest, AssistantTaskStatus, ImageIndexEntry, ImageSelectResult, ModelInfo, UsageInfo, PolicyInfo, ModelUsageDelta, WorkflowRunStatus, WorkflowRunSummary, WorkflowRun, WorkflowAgentRow, WorkflowActivityBeat, } from "./types.js";
+export type { Principal, Scenario, RunStatus, TaskStats, TaskRequest, TaskAgentDefinition, TaskResult, ActiveRunConflictDoneResult, RunReceipt, RunRecord, CancelAck, Artifact, LeaderReceipt, LeaderRecord, SupervisorCostBreakdown, Capabilities, ScenarioDetail, PendingCheckpoint, SessionRecord, SkillSpec, TaskSummary, CheckpointGate, TraceTurn, TraceBlock, PromptManifest, PromptEpoch, SessionSummary, SessionListPage, SessionPermissionRules, StoredSessionRules, McpServerStatus, McpStatusPanel, SessionWindow, SessionMessageEnvelope, SyncEntry, SyncSnapshot, SyncAnchor, SessionRulesRecord, SessionManifest, SessionBundle, SyncRelation, SyncConflictRelation, ImportStaged, ImportCommitted, TraceStreamEvent, WorkflowStreamEvent, CheckpointSummary, InboxRow, AssistantGate, AssistantTask, PlanReviewRequest, AssistantTaskStatus, ImageIndexEntry, ImageSelectResult, ModelInfo, UsageInfo, PolicyInfo, ModelUsageDelta, WorkflowRunStatus, WorkflowRunSummary, WorkflowRun, WorkflowAgentRow, WorkflowActivityBeat, } from "./types.js";
 /** TOC `settings.json` — the SHARED environment-customization contract (CC-parity v1: permissions/hooks/env/model/
  *  outputStyle). ONE schema, two wirings: TOC-local (shell adapter → local Runner) + TOB-fleet (carried to service via
  *  {@link TaskRequest.settings}). SDK owns the CONTRACT only — no interpreter, no shell-hook runner. core/search AI
  *  2026-06-27 / research/toc-settings-adapter/01-design.md §5①. */
-export type { SemaSettings, SettingsPermissions, SettingsHooks, SettingsHookMatcher, SettingsHookCommand, SettingsEnv, } from "./settings.js";
+export type { SemaSettings, SettingsPermissions, SettingsHooks, SettingsHookMatcher, SettingsHookCommand, SettingsEnv, SettingsWebSearch, } from "./settings.js";
 export type { AgentEvent, EventIdentity, BrainStatusPhase } from "./events.js";
 export type { StampedAgentEvent } from "./sse.js";
 export { assertNever } from "./events.js";
 export { MetricsResource, OutcomesResource, SendfileLinksResource, type OutcomeRow, type SendfileLinkRow } from "./resources/ops.js";
 export { BakesResource, type BakeClaim } from "./resources/images.js";
 export { type UsageAnalyticsParams, type UsageMetric, type UsageGranularity, type UsageTotals, type UsageSummary, type UsageSeries, type UsageBreakdown, type UsageDimension } from "./resources/usage.js";
-export { APIError, AuthError, RateLimitedError, QuotaExhaustedError, ScenarioNotAllowedError, BudgetExceededError, ConflictError, SyncConflictError, ApprovalStaleError, ApprovalBindingMismatchError, ApprovalConcurrentlyReopenedError, SteeringNotRunningError, SteeringInvalidContentError, PayloadTooLargeError, TaskStopConflictError, PrincipalUnverifiedError, PrincipalUnboundError, ApprovalMacRequiredError, ApprovalMacInvalidError, GateNotResumableError, GateNotPlanReviewError, WorkspaceFileTooLargeError, SubagentResumeConflictError, WakeGatePendingError, RunNotLiveError, DrainingError, ResumeOutcomeInvalidError, ResumeBlockedByPolicyError, DecideError, DecideParkMovedError, DecideUnsupportedError, DecideStoreUnreachableError, BadRequestError, NotFoundError, LimitExceededError, CapabilityUnavailableError, FeatureDisabledError, InternalServerError, ServiceStateError, SteeringError, SteeringAmbiguousTargetError, SteeringStillRunningError } from "./errors.js";
+export { APIError, AuthError, RateLimitedError, QuotaExhaustedError, ScenarioNotAllowedError, BudgetExceededError, ConflictError, SyncConflictError, ApprovalStaleError, ApprovalBindingMismatchError, ApprovalConcurrentlyReopenedError, SteeringNotRunningError, SteeringInvalidContentError, PayloadTooLargeError, TaskStopConflictError, PrincipalUnverifiedError, PrincipalUnboundError, ApprovalMacRequiredError, ApprovalMacInvalidError, GateNotResumableError, GateNotPlanReviewError, WorkspaceFileTooLargeError, SubagentResumeConflictError, WakeGatePendingError, RunNotLiveError, DrainingError, ResumeOutcomeInvalidError, ResumeBlockedByPolicyError, DecideError, DecideParkMovedError, DecideUnsupportedError, DecideStoreUnreachableError, BadRequestError, NotFoundError, LimitExceededError, CapabilityUnavailableError, FeatureDisabledError, InternalServerError, ServiceStateError, SteeringError, SteeringAmbiguousTargetError, SteeringStillRunningError, GateNotToolApprovalError } from "./errors.js";
 /** E4 quota deny (pinned wire shape) — structured detail on the 429 `quota_exhausted` typed error. */
 export type { QuotaExhaustedDetail } from "./errors.js";
 /** 2c session-sync — the NDJSON entry-stream truncation error + the PURE §7 relation classifier (the local peer
@@ -24,6 +24,10 @@ export { SyncTruncatedError } from "./sse.js";
 /** P0-2 S1 — typed heartbeat-silence watchdog error (tasks.stream / readSseFrames). Message literal is FROZEN
  *  (`SSE: no data for ${ms}ms (heartbeat silence)`); carries `elapsedMs` for the caller's idle diagnosis. */
 export { SseIdleError } from "./sse.js";
+/** [2400] X-2 — the durable tail kept re-opening EMPTY: overwhelmingly a PARKED run (`suspended`/`needs_review`,
+ *  where the server closes a non-`running` tail immediately). Carries `lastEventId` as the resume cursor. The SDK
+ *  deliberately does not auto-diagnose: go read `runs.get(taskId)` and branch on the row's status. */
+export { StreamEndedWithoutTerminalError } from "./sse.js";
 /** core [1642] co-design — write-side helper for a BFF host re-serving a `StampedAgentEvent` generator as a
  *  live SSE `Response` to its own browser client (native `EventSource`, no SDK counterpart needed there). */
 export { toSseResponse } from "./sse.js";
@@ -33,6 +37,8 @@ export type { SessionSyncPeer, PushSessionOptions, PushSessionResult, PullSessio
 export { SessionSyncResource } from "./resources/session-sync.js";
 export { SideQueryResource, type SideQueryRequest, type SideQueryResult } from "./resources/side-query.js";
 export type { SubagentSteerReceipt, SubagentOutputResult, CompactAck, DetachAck } from "./resources/runs.js";
+/** [2400] TR-4 — `runs.steer` 的判别联合回执(applied / queued / parked_for_wake)+ 每条消息的建议优先级。 */
+export type { SteerReceipt, SteerPriority } from "./resources/runs.js";
 export type { SessionGetParams, SessionInitBundle, SessionInitModel, SessionSettingsResponse, SessionEffectiveSettings, SessionAppliedSettings, SessionEffectiveLimits, SessionNotifyBody, SessionNotifyStatus, } from "./resources/sessions.js";
 export type { WorkflowAgentSteerReceipt, WorkflowJournalPage, WorkflowJournalRow, WorkflowJournalEntry, WorkflowJournalEntryTruncated, } from "./resources/workflows.js";
 /** Control-plane (sema-registry) typed errors — distinct hierarchy from the worker APIError tree. */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,OAAO,EAAE,WAAW,EAAE,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACvF;qEACqE;AACrE,OAAO,EAAE,aAAa,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,YAAY,EACV,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,mBAAmB,EAAE,UAAU,EAAE,2BAA2B,EACpH,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,uBAAuB,EAChG,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAC1J,cAAc,EAAE,eAAe,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,eAAe,EAAE,cAAc,EAC5G,aAAa,EAAE,sBAAsB,EACrC,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,eAAe,EAAE,aAAa,EACvF,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,eAAe,EACjE,gBAAgB,EAAE,mBAAmB,EACrC,iBAAiB,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,iBAAiB,EAAE,mBAAmB,EACjG,eAAe,EAAE,iBAAiB,EAAE,SAAS,EAC7C,SAAS,EAAE,UAAU,EAAE,eAAe,EACtC,iBAAiB,EAAE,kBAAkB,EAAE,WAAW,EAAE,gBAAgB,EAAE,oBAAoB,GAC3F,MAAM,YAAY,CAAC;AACpB;;;mEAGmE;AACnE,YAAY,EACV,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,WAAW,EAGvG,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/E,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrI,OAAO,EAAE,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,EAAE,KAAK,oBAAoB,EAAE,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3M,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,aAAa,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,4BAA4B,EAAE,iCAAiC,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,oBAAoB,EAAE,eAAe,EAI5jB,aAAa,EAEb,yBAAyB,EAAE,0BAA0B,EACrD,WAAW,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,2BAA2B,EAGtF,eAAe,EAAE,aAAa,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,oBAAoB,EACpG,mBAAmB,EAAE,iBAAiB,EAEtC,aAAa,EAAE,4BAA4B,EAAE,yBAAyB,EAEtE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAChD,sGAAsG;AACtG,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD;yDACyD;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C;6GAC6G;AAC7G,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC;;sGAEsG;AACtG,OAAO,EAAE,+BAA+B,EAAE,MAAM,UAAU,CAAC;AAC3D;6GAC6G;AAC7G,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,6BAA6B,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACrH,8GAA8G;AAC9G,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC3H,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC3G,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC7G,0FAA0F;AAC1F,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACvE,YAAY,EACV,gBAAgB,EAAE,iBAAiB,EAAE,gBAAgB,EACrD,uBAAuB,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,sBAAsB,EACjG,iBAAiB,EAAE,mBAAmB,GACvC,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,yBAAyB,EAAE,mBAAmB,EAAE,kBAAkB,EAClE,oBAAoB,EAAE,6BAA6B,GACpD,MAAM,0BAA0B,CAAC;AAClC,qGAAqG;AACrG,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACxK,8DAA8D;AAC9D,YAAY,EACV,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EACxF,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAC5E,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,mBAAmB,EACrG,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAC9D,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,kBAAkB,EAAE,WAAW,EACzE,iBAAiB,EAAE,gBAAgB,EAAE,cAAc,EAAE,gBAAgB,EAAE,qBAAqB,EAC5F,eAAe,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,gBAAgB,EAC5F,kBAAkB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,wBAAwB,EACrF,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,qBAAqB,GACvF,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD;6FAC6F;AAC7F,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAChE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACnE,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC/H,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACtG,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,iBAAiB,EAAE,cAAc,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACtJ,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACrH;iHACiH;AACjH,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,UAAU,EAAE,SAAS,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGzJ,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAEvJ,OAAO,EAAE,iBAAiB,EAAE,KAAK,oBAAoB,EAAE,KAAK,kBAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -18,13 +18,19 @@ ResumeOutcomeInvalidError, ResumeBlockedByPolicyError, DecideError, DecideParkMo
 // AuthError / ConflictError,其余七族各一个类。整族一把 catch,未知新码有信息地降级(见 errors.ts 顶注)。
 BadRequestError, NotFoundError, LimitExceededError, CapabilityUnavailableError, FeatureDisabledError, InternalServerError, ServiceStateError, 
 // `steering.*` 从逐码枚举改前缀分派(与 stop.*/decide.* 同形):基类 + 两个新 typed 码。
-SteeringError, SteeringAmbiguousTargetError, SteeringStillRunningError } from "./errors.js";
+SteeringError, SteeringAmbiguousTargetError, SteeringStillRunningError, 
+// [2400] CB-2(4.2.0):语义错门守卫的第三个成员(/decide 撞非 tool-approval 门)。
+GateNotToolApprovalError } from "./errors.js";
 /** 2c session-sync — the NDJSON entry-stream truncation error + the PURE §7 relation classifier (the local peer
  *  decides fast-forward/fork BEFORE pulling/pushing). */
 export { SyncTruncatedError } from "./sse.js";
 /** P0-2 S1 — typed heartbeat-silence watchdog error (tasks.stream / readSseFrames). Message literal is FROZEN
  *  (`SSE: no data for ${ms}ms (heartbeat silence)`); carries `elapsedMs` for the caller's idle diagnosis. */
 export { SseIdleError } from "./sse.js";
+/** [2400] X-2 — the durable tail kept re-opening EMPTY: overwhelmingly a PARKED run (`suspended`/`needs_review`,
+ *  where the server closes a non-`running` tail immediately). Carries `lastEventId` as the resume cursor. The SDK
+ *  deliberately does not auto-diagnose: go read `runs.get(taskId)` and branch on the row's status. */
+export { StreamEndedWithoutTerminalError } from "./sse.js";
 /** core [1642] co-design — write-side helper for a BFF host re-serving a `StampedAgentEvent` generator as a
  *  live SSE `Response` to its own browser client (native `EventSource`, no SDK counterpart needed there). */
 export { toSseResponse } from "./sse.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,OAAO,EAAE,WAAW,EAA+C,MAAM,aAAa,CAAC;AACvF;qEACqE;AACrE,OAAO,EAAE,aAAa,EAA4B,MAAM,qBAAqB,CAAC;AAwB9E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,wEAAwE;AACxE,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,qBAAqB,EAAyC,MAAM,oBAAoB,CAAC;AACrI,OAAO,EAAE,aAAa,EAAkB,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,aAAa,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,4BAA4B,EAAE,iCAAiC,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,oBAAoB,EAAE,eAAe;AAC5jB,6EAA6E;AAC7E,2FAA2F;AAC3F,iCAAiC;AACjC,aAAa;AACb,2FAA2F;AAC3F,yBAAyB,EAAE,0BAA0B,EACrD,WAAW,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,2BAA2B;AACtF,2EAA2E;AAC3E,4EAA4E;AAC5E,eAAe,EAAE,aAAa,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,oBAAoB,EACpG,mBAAmB,EAAE,iBAAiB;AACtC,kEAAkE;AAClE,aAAa,EAAE,4BAA4B,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAG9F;yDACyD;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C;6GAC6G;AAC7G,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC;6GAC6G;AAC7G,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,6BAA6B,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAGrH,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAA+C,MAAM,2BAA2B,CAAC;AAW3G,qGAAqG;AACrG,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAaxK,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD;6FAC6F;AAC7F,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAOhE;iHACiH;AACjH,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,qEAAqE;AACrE,sEAAsE;AACtE,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,gBAAgB,EAAiB,MAAM,gBAAgB,CAAC;AACvJ,qDAAqD;AACrD,OAAO,EAAE,iBAAiB,EAA0E,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,OAAO,EAAE,WAAW,EAA+C,MAAM,aAAa,CAAC;AACvF;qEACqE;AACrE,OAAO,EAAE,aAAa,EAA4B,MAAM,qBAAqB,CAAC;AA2B9E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,wEAAwE;AACxE,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,qBAAqB,EAAyC,MAAM,oBAAoB,CAAC;AACrI,OAAO,EAAE,aAAa,EAAkB,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,aAAa,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,4BAA4B,EAAE,iCAAiC,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,oBAAoB,EAAE,eAAe;AAC5jB,6EAA6E;AAC7E,2FAA2F;AAC3F,iCAAiC;AACjC,aAAa;AACb,2FAA2F;AAC3F,yBAAyB,EAAE,0BAA0B,EACrD,WAAW,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,2BAA2B;AACtF,2EAA2E;AAC3E,4EAA4E;AAC5E,eAAe,EAAE,aAAa,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,oBAAoB,EACpG,mBAAmB,EAAE,iBAAiB;AACtC,kEAAkE;AAClE,aAAa,EAAE,4BAA4B,EAAE,yBAAyB;AACtE,+DAA+D;AAC/D,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAGhD;yDACyD;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C;6GAC6G;AAC7G,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC;;sGAEsG;AACtG,OAAO,EAAE,+BAA+B,EAAE,MAAM,UAAU,CAAC;AAC3D;6GAC6G;AAC7G,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,6BAA6B,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAGrH,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAA+C,MAAM,2BAA2B,CAAC;AAa3G,qGAAqG;AACrG,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAaxK,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD;6FAC6F;AAC7F,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAOhE;iHACiH;AACjH,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,qEAAqE;AACrE,sEAAsE;AACtE,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,gBAAgB,EAAiB,MAAM,gBAAgB,CAAC;AACvJ,qDAAqD;AACrD,OAAO,EAAE,iBAAiB,EAA0E,MAAM,0BAA0B,CAAC"}

package/dist/resources/approvals.d.ts

@@ -3,6 +3,7 @@
  *  (web-native, non-expert users authorizing/answering); also usable by door A. */
 import type { Transport } from "../transport.js";
 import type { PendingCheckpoint } from "../types.js";
+import type { QuestionAnswer } from "./questions.js";
 /** One per-session approval exemption ("本会话不再询问", service exemptions ruling — an APPROVAL MEMORY, not a
  *  policy loosen: deny/neverAuto always outrank it). Keyed in CANONICAL tool-name space (service
  *  `ApprovalExemptionRow`, approval-exemption-store.ts). */
@@ -13,18 +14,36 @@ export interface ApprovalExemption {
     /** Epoch MS of the FIRST grant (a re-grant refreshes grantedBy, not this). */
     createdAt: number;
 }
-/** A delta event from `GET /v1/approvals/stream` (native push, service [83]). Open shape — `type` discriminates
- *  `pending` / `resolved` / `synced` (initial) / `heartbeat`; payload fields are FORWARD-DRAFT pending service's
- *  shape confirmation. A consumer that doesn't parse the delta can treat any non-heartbeat event
- *  as a "changed" signal and refetch the authoritative list (`list()`). */
+/** A delta event from `GET /v1/approvals/stream` (native push, service [83]).
+ *
+ *  🔴 [2400] HITL-9 —— 形状**已实核**(server `streamApprovals`,`src/http/routes/approvals-assistant.ts:650-698`),
+ *  「FORWARD-DRAFT pending service's shape confirmation」那句已删:它写在核对之前,而核对结果是既有的四个
+ *  `type` 值漏了**两个**真发的帧。每条 `data:` 载荷都回声一个 `type`(与 SSE `event:` 名同值),所以剥了
+ *  事件名的中继也能分派。六个真值:
+ *   · `meta`      — 开流第一帧,`{version, mode:"approvals-delta", pollMs}`(服务端 diff 轮询周期,3000ms)。
+ *   · `pending`   — 一条新挂起(首帧快照期逐条发一遍,随后才是增量)。载荷 = 富行 {@link PendingCheckpoint} 展开。
+ *   · `synced`    — 首帧快照发完,`{count}`。**这之后**才是真增量。
+ *   · `resolved`  — 一条挂起消失(被决/过期/GC),`{sessionId, toolCallId}`。
+ *   · `heartbeat` — 15s 保活;注意它是**真帧**(`data:{"type":"heartbeat"}`),不是裸 `:` 注释行。
+ *   · `error`     — 15 分钟帽:`{errorCode:"STREAM_MAX_DURATION", message}`,之后 server 主动收流 ⇒ **重连**。
+ *  仍是**开集**(`(string & {})`):不解析增量的消费方可以把任何非 heartbeat 事件当「变了」信号,回头拉
+ *  权威列表(`list()`)—— 那条兜底路子一直有效,只是不再是「因为形状没确认」。 */
 export interface ApprovalStreamEvent {
-    type: "pending" | "resolved" | "synced" | "heartbeat" | (string & {});
+    type: "meta" | "pending" | "resolved" | "synced" | "heartbeat" | "error" | (string & {});
     [k: string]: unknown;
 }
 export interface ApprovalDecision {
     decision: "approve" | "deny";
-    /** For AskUserQuestion: the operator's answer. Omit for a plain F4 approve/deny. */
-    answer?: unknown;
+    /** For AskUserQuestion: the operator's answer. Omit for a plain F4 approve/deny.
+     *
+     *  🔴 [2400] HITL-8 —— 从 `unknown` 收成 {@link QuestionAnswer}(与 `client.questions.respond` **同一个**类型,
+     *  单源)。server 侧 `isQuestionAnswer`(`routes/approvals-assistant.ts:36-50`)按这个结构严校,坏形 400。
+     *  ⚠️ **两腿严格度不同**,别把 live 腿的宽松当契约:
+     *   · DURABLE 腿(本 verb)`answers[]` 必须**非空**,每项 `selected` 也必须非空 —— 空数组是 400。
+     *   · LIVE 腿(`POST /v1/questions/:id/respond`,`src/question.ts:95`)只校 `Array.isArray(answers)` ⇒
+     *     **空数组被接受**(它有 headless-default 的语义位置)。
+     *  语义栅栏在 core:`selected ⊆ options`,`note` 走 untrusted-DATA fence —— 客户端不必也不该自己重算。 */
+    answer?: QuestionAnswer;
     reason?: string;
     /** design/80 D-1 — action binding (TOCTOU guard). Read these TWO off the `PendingCheckpoint` the human saw
      *  and pass them back VERBATIM; the server resolves THIS exact checkpoint, fail-closed on mismatch
@@ -74,8 +93,14 @@ export declare class ApprovalsResource {
         signal?: AbortSignal;
     }): Promise<Record<string, unknown>>;
     /** GET /v1/approvals — pending checkpoints (operator-scoped; envelope key `pending`).
-     *  NEVER returns the capability token. ⚠️ item createdAt/deadline are epoch MS. */
+     *  NEVER returns the capability token. ⚠️ item createdAt/deadline are epoch MS.
+     *
+     *  🔴 [2400] HITL-5 `opts.owner` —— **OPERATOR 语义**,不是过滤器(server
+     *  `src/http/routes/approvals-assistant.ts:88-92`):调用方是 operator 时 `?owner=` 把队列切到**那个 owner**
+     *  的 scope(不传 = 全租户视图,这是本面与 per-user 的 `assistant.inbox` 的分野);调用方**不是** operator
+     *  时,server 无条件用它自己的 principal —— 传了也**静默无效**,绝不是越权入口。 */
     list(opts?: {
+        owner?: string;
         signal?: AbortSignal;
     }): Promise<{
         pending: PendingCheckpoint[];
@@ -110,13 +135,18 @@ export declare class ApprovalsResource {
     revokeExemption(sessionId: string, toolName: string, opts?: {
         signal?: AbortSignal;
     }): Promise<boolean>;
-    /** GET /v1/approvals/stream — native push (SSE delta, meta `mode:"approvals-delta"`, service [83]). Replaces
-     *  BFF-side polling of `list()`. LONG-LIVED + operator-scoped: there is NO terminal event — this reconnects on
-     *  drops / heartbeat-silence and tails on (uses `readSseFrames`, NOT `parseSse`, which would end on done/failed).
+    /** GET /v1/approvals/stream — native push (SSE delta, `meta.mode:"approvals-delta"`, service [83]). Replaces
+     *  BFF-side polling of `list()`. LONG-LIVED: there is NO terminal event — this reconnects on drops /
+     *  heartbeat-silence and tails on (uses `readSseFrames`, NOT `parseSse`, which would end on done/failed).
      *  A non-`ok` first response (e.g. 404 on a worker without the endpoint) throws → caller falls back to polling.
-     *  FORWARD-DRAFT: event payloads pending service confirmation — consumers refetch `list()` on
-     *  any non-heartbeat event rather than trusting an unconfirmed delta shape. */
+     *  Frame vocabulary + scoping: see {@link ApprovalStreamEvent} (six real `type` values, shape实核 2026-08-02)
+     *  and {@link ApprovalsResource.list} for the operator `owner` semantics — `?owner=` is honored identically here
+     *  (`routes/approvals-assistant.ts:81-86`).
+     *  ⚠️ The server ends the stream itself at its 15-minute cap, announcing it with an `error` frame
+     *  (`errorCode: "STREAM_MAX_DURATION"`); this loop simply reconnects — but a consumer that mirrors frames
+     *  onward should not forward that one as a failure. */
     stream(opts?: {
+        owner?: string;
         signal?: AbortSignal;
     }): AsyncGenerator<ApprovalStreamEvent>;
 }

package/dist/resources/approvals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../../src/resources/approvals.ts"],"names":[],"mappings":"AAAA;;mFAEmF;AACnF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAIrD;;4DAE4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;2EAG2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACtE,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,SAAS,GAAG,MAAM,CAAC;IAC7B,oFAAoF;IACpF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAKhB;;;uEAGmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6GAA6G;IAC7G,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;4GACwG;IACxG,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;wFAKoF;IACpF,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;wFAGwF;AACxF,MAAM,WAAW,oBAAoB;IACnC,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,SAAS,GAAG,MAAM,CAAC;CAC9B;AAED,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC;;;;;;;;;;;;oCAYgC;IAC1B,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAOxF;uFACmF;IAC7E,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,iBAAiB,EAAE,CAAA;KAAE,CAAC;IAOtF;;;;;;;;;;;;2CAYuC;IACjC,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAS9G;+EAC2E;IACrE,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,iBAAiB,EAAE,CAAA;KAAE,CAAC;IAStH;;;uHAGmH;IAC7G,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAc7G;;;;;mFAK+E;IACxE,MAAM,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,cAAc,CAAC,mBAAmB,CAAC;CA8BpF"}
+{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../../src/resources/approvals.ts"],"names":[],"mappings":"AAAA;;mFAEmF;AACnF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAIrD;;4DAE4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;kDAakD;AAClD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACzF,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,SAAS,GAAG,MAAM,CAAC;IAC7B;;;;;;;;yFAQqF;IACrF,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAKhB;;;uEAGmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6GAA6G;IAC7G,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;4GACwG;IACxG,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;wFAKoF;IACpF,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;wFAGwF;AACxF,MAAM,WAAW,oBAAoB;IACnC,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,SAAS,GAAG,MAAM,CAAC;CAC9B;AAED,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC;;;;;;;;;;;;oCAYgC;IAC1B,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAOxF;;;;;;8DAM0D;IACpD,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,iBAAiB,EAAE,CAAA;KAAE,CAAC;IAQtG;;;;;;;;;;;;2CAYuC;IACjC,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAS9G;+EAC2E;IACrE,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,iBAAiB,EAAE,CAAA;KAAE,CAAC;IAStH;;;uHAGmH;IAC7G,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAc7G;;;;;;;;;2DASuD;IAChD,MAAM,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,cAAc,CAAC,mBAAmB,CAAC;CA0CpG"}

package/dist/resources/approvals.js

@@ -26,12 +26,18 @@ export class ApprovalsResource {
         throw new APIError(404, "not_found", `no pending approval for session ${id}`);
     }
     /** GET /v1/approvals — pending checkpoints (operator-scoped; envelope key `pending`).
-     *  NEVER returns the capability token. ⚠️ item createdAt/deadline are epoch MS. */
+     *  NEVER returns the capability token. ⚠️ item createdAt/deadline are epoch MS.
+     *
+     *  🔴 [2400] HITL-5 `opts.owner` —— **OPERATOR 语义**,不是过滤器(server
+     *  `src/http/routes/approvals-assistant.ts:88-92`):调用方是 operator 时 `?owner=` 把队列切到**那个 owner**
+     *  的 scope(不传 = 全租户视图,这是本面与 per-user 的 `assistant.inbox` 的分野);调用方**不是** operator
+     *  时,server 无条件用它自己的 principal —— 传了也**静默无效**,绝不是越权入口。 */
     async list(opts) {
         // 🔴 BREAKING(clay 拍 2026-07-28,list() 归一):返回 wire 信封原样 `{pending}`,不再拆封——
         // 全 SDK 规约=verbs 返回 wire body VERBATIM(拆封会丢未来 additive 元数据,且 13 个 list 站点
         // 此前 7 信封 6 拆封各行其是)。迁移:`await approvals.list()` → `(await approvals.list()).pending`。
-        return this.t.request({ method: "GET", path: "/v1/approvals", signal: opts?.signal });
+        const q = opts?.owner ? `?owner=${encodeURIComponent(opts.owner)}` : ""; // 手拼(同 assistant.inbox 的既有拼法)
+        return this.t.request({ method: "GET", path: `/v1/approvals${q}`, signal: opts?.signal });
     }
     /** POST /v1/approvals/:sessionId/decide — resolve a suspend; the resumed run continues its stream.
      *  Not a submit → no SDK retry (a decide must not double-act).
@@ -83,20 +89,25 @@ export class ApprovalsResource {
             throw e;
         }
     }
-    /** GET /v1/approvals/stream — native push (SSE delta, meta `mode:"approvals-delta"`, service [83]). Replaces
-     *  BFF-side polling of `list()`. LONG-LIVED + operator-scoped: there is NO terminal event — this reconnects on
-     *  drops / heartbeat-silence and tails on (uses `readSseFrames`, NOT `parseSse`, which would end on done/failed).
+    /** GET /v1/approvals/stream — native push (SSE delta, `meta.mode:"approvals-delta"`, service [83]). Replaces
+     *  BFF-side polling of `list()`. LONG-LIVED: there is NO terminal event — this reconnects on drops /
+     *  heartbeat-silence and tails on (uses `readSseFrames`, NOT `parseSse`, which would end on done/failed).
      *  A non-`ok` first response (e.g. 404 on a worker without the endpoint) throws → caller falls back to polling.
-     *  FORWARD-DRAFT: event payloads pending service confirmation — consumers refetch `list()` on
-     *  any non-heartbeat event rather than trusting an unconfirmed delta shape. */
+     *  Frame vocabulary + scoping: see {@link ApprovalStreamEvent} (six real `type` values, shape实核 2026-08-02)
+     *  and {@link ApprovalsResource.list} for the operator `owner` semantics — `?owner=` is honored identically here
+     *  (`routes/approvals-assistant.ts:81-86`).
+     *  ⚠️ The server ends the stream itself at its 15-minute cap, announcing it with an `error` frame
+     *  (`errorCode: "STREAM_MAX_DURATION"`); this loop simply reconnects — but a consumer that mirrors frames
+     *  onward should not forward that one as a failure. */
     async *stream(opts) {
         let failures = 0;
+        const q = opts?.owner ? `?owner=${encodeURIComponent(opts.owner)}` : "";
         for (;;) {
             if (opts?.signal?.aborted)
                 return;
             let res;
             try {
-                const o = { method: "GET", path: "/v1/approvals/stream" };
+                const o = { method: "GET", path: `/v1/approvals/stream${q}` };
                 if (opts?.signal)
                     o.signal = opts.signal;
                 res = await this.t.openStream(o);
@@ -111,13 +122,25 @@ export class ApprovalsResource {
                 throw await this.t.errorFrom(res); // 404/4xx → caller polls
             try {
                 for await (const frame of readSseFrames(res, HEARTBEAT_GRACE_MS, opts?.signal)) {
-                    failures = 0; // a frame arrived = progress
+                    // 🔴 [2400] CB-8:`!frame.data` **不是**在滤心跳 —— 这条流的心跳是真帧
+                    // (`event: heartbeat\ndata: {"type":"heartbeat"}`,`routes/approvals-assistant.ts:675/694`),
+                    // `data` 是非空串,所以它**照常被 yield**(`heartbeat` 是文档化的一个臂)。这一行挡的是没有
+                    // `data` 行的帧(裸注释/协议噪声)。旧注释「heartbeat comment」两处都错。
                     if (!frame.data)
-                        continue; // heartbeat comment
-                    yield JSON.parse(frame.data);
+                        continue;
+                    // 🔴 [2400] HITL-14:坏 JSON = **契约违约,上抛**(照 parseSse:85 形——同一个 SyntaxError 判别,
+                    // 不靠文案分支)。此前它被下面那个裸 `catch` 吞掉,变成一次静默重连 —— 于是「对端在发我们解不了
+                    // 的东西」这件事永远测不出来,消费方看到的只是一条一直在重连、一帧不出的流。
+                    const ev = JSON.parse(frame.data); // SyntaxError = contract breach → rethrown below
+                    // 🔴 [2400] HITL-14:`failures` 归零挪到**解析成功之后**。放在帧到达处 = 把「收到了看不懂的字节」
+                    // 当成 progress,一条持续吐坏帧的流会把重连预算永远清零、无限空转。
+                    failures = 0;
+                    yield ev;
                 }
             }
-            catch {
+            catch (e) {
+                if (e instanceof SyntaxError)
+                    throw new Error(`approvals.stream: malformed event data (contract breach): ${e.message}`);
                 // mid-stream drop or heartbeat silence → reconnect (long-lived stream has no terminal event)
             }
             finally {

package/dist/resources/approvals.js.map

@@ -1 +1 @@
-{"version":3,"file":"approvals.js","sourceRoot":"","sources":["../../src/resources/approvals.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"approvals.js","sourceRoot":"","sources":["../../src/resources/approvals.ts"],"names":[],"mappings":"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"}

package/dist/resources/assistant.d.ts

@@ -5,7 +5,17 @@
  *  SDK 服务端用, 不进浏览器/CLI。withPrincipal 自动重建本 resource —— BFF 的 sdk(principal).assistant.* 天然成立。
  *
  *  🔴 D-G 边界（§6）: 这 5 个 verb **不需要**签名证明 —— 走 owner 门（principal header, transport 已注入 x-agent-principal）。
- *  只 /decide 要签名（approvals.decide + BFF 签, 不在本 resource）。owner 非属 → 404（无存在性 oracle）不是 403。 */
+ *  只 /decide 要签名（approvals.decide + BFF 签, 不在本 resource）。owner 非属 → 404（无存在性 oracle）不是 403。
+ *
+ *  🔴 [2400] HITL-13 挂载前置 —— **先读 `capabilities().approvals`,别 trial-by-error**:
+ *  server 的整条 `/v1/assistant/*` 车道与 `/v1/approvals` 共用同一个挂载条件,分支头逐字是
+ *  `if (deps.checkpointStore && (url.startsWith("/v1/approvals") || url.startsWith("/v1/assistant")))`
+ *  (`src/http/routes/approvals-assistant.ts`),而 `capabilities.approvals = Boolean(deps.checkpointStore)`
+ *  (`routes/capabilities.ts:65`)—— 所以那一位就是本 resource 全部 5 个 verb 的挂载位,尽管名字只提 approvals。
+ *  ⚠️ 名字窄、谓词宽:**别用 `capabilities.scheduler` 判本 resource**(那位说的是 host 腿的自唤醒 cron 工具,
+ *  与调度视图无关;web 曾按名字猜,在 local 部署形上永久渲「不可达」)。
+ *  ⚠️ 没接 checkpointStore 的部署上,这条车道**根本不匹配**,请求落到域尾的 404 `not_found.route` —— 那是
+ *  「面不在」不是「东西没找到」;下面三个写 verb 各自另有更细的 501(见各条)。 */
 import type { Transport } from "../transport.js";
 import type { InboxRow, AssistantTask, PlanReviewRequest, AssistantTaskStatus } from "../types.js";
 export declare class AssistantResource {
@@ -33,20 +43,27 @@ export declare class AssistantResource {
     }>;
     /** §4b POST /v1/assistant/tasks/:id/resume（:id = taskId）—— resource_limit CONTINUE。**无 body**。
      *  非 submit → 不重试（一次决策不重放）。🔴 GATE-KIND GUARD: human/policy_ask 门 → 409 gate_not_resumable
-     *  （"continue" 绝不绕过人审, 那条路是 /decide）。owner 非属 → 404。 */
+     *  （"continue" 绝不绕过人审, 那条路是 /decide）。owner 非属 → 404。
+     *  🔴 [2400] HITL-13 前置:**checkpointStore 必须挂着** —— 先读 `capabilities().approvals`(见本文件顶注)。
+     *  另需 durable run store:无则 501 `capability.run_store_required`（`routes/approvals-assistant.ts:341`）。 */
     resume(taskId: string, opts?: {
         signal?: AbortSignal;
     }): Promise<AssistantTaskStatus>;
     /** §4c POST /v1/assistant/tasks/:id/plan_review（:id = taskId）—— PRE-ACTION plan_review 门的 3-state 决策。
      *  body = {decision, editedPlan?, reason?}。approve/edit/reject 全跑模型 → 计费。非 submit → 不重试。
      *  🔴 GATE-KIND GUARD: 非 plan_review 门 → 409 gate_not_plan_review。400: 坏/缺 decision; edit 缺非空 editedPlan;
-     *  approve/reject 带 editedPlan; reason 非串。owner 非属 → 404。 */
+     *  approve/reject 带 editedPlan; reason 非串。owner 非属 → 404。
+     *  🔴 [2400] HITL-13 前置:同 {@link AssistantResource.resume} —— checkpointStore（先读 `capabilities().approvals`）
+     *  + durable run store（无则 501 `capability.run_store_required`，`routes/approvals-assistant.ts:362`）。 */
     planReview(taskId: string, req: PlanReviewRequest, opts?: {
         signal?: AbortSignal;
     }): Promise<AssistantTaskStatus>;
     /** §4d POST /v1/assistant/tasks/:id/preempt（:id = taskId）—— 优雅 YIELD（跨副本让位, 与 runs.cancel 的 kill 相反）。
      *  **无 body**。202 {status}（terminal → 202 no-op）。非 submit → 不重试。NOT billable。
-     *  suspended → 409; RESOURCE_SUSPEND off → 501; owner 非属 → 404。 */
+     *  suspended → 409 `conflict.already_suspended`; owner 非属 → 404。
+     *  🔴 [2400] HITL-13 前置:本 verb 的 501 是**两与** —— `RESOURCE_SUSPEND=true` **且** checkpointStore 挂着
+     *  （`routes/approvals-assistant.ts:297`，`feature.preemption_disabled`；缺 run store 另有
+     *  `capability.run_store_required`）。先读 `capabilities().approvals` 判 store 那一半（见本文件顶注）。 */
     preempt(taskId: string, opts?: {
         signal?: AbortSignal;
     }): Promise<AssistantTaskStatus>;