@sema-agent/client-core 0.5.0 → 0.7.0

package/dist/index.js

@@ -5,6 +5,22 @@
  * 沿革:@sema-agent/wire-cc-adapter 0.1.0 = seam 类型 + id 确定性派生 + 首批踩坑纯函数;
  * 0.1.2(#52a)= adapt() 管线首批(纯投影臂全落 + 壳态耦合臂投影成 ChromeEvent + 差分守卫);
  * 0.2.0 = 迁入 sema-client-core 独立仓并改名(旧 npm 名 deprecate 指本包);
+ * 0.7.0 = **B5 批**(设计稿 §3 B5):① **配对台账折回**([1857] —— 0.6.0 把 `notifiedRuns`/
+ *   `cardEnqueuedRuns` 放适配器实例,与清账/记账的另一半不共享前提 = 双卡/UI 零显示/模型二收,
+ *   本批整体折回 notifications.ts 的 module 台账);② **B/D/E 层搬入**(`toolResult.ts`:
+ *   structuredToToolUseResult 14 case + wireOutputToBody 3 臂 + E 层 4 臂),`adapt()` 从此
+ *   自己铸 `tool_result` 卡与两处开卡兜底;③ **structured 白名单吃现货**([1840]§一 30 项 ——
+ *   在场则 T11/T14 正则退位、T24 的 B 层惰性退位,缺席保回落,退位由**调用计数器**钉死);
+ *   ④ **T7 诚实缺席**(§8-4:不搬 mock 合成器,改 `_sema_degraded:'wire_carried_no_output'`)与
+ *   **T20 diff hunks 进包**(`diff/patch.ts`,本包**第一个** runtime dep `diff`)。
+ *   🆕 两个 chrome 臂:`bgshell_register`(#117a 判定在库、执行留宿主)· `task_ledger_sync{source:'structured'}`。
+ * 0.6.0 = **B4 批**(设计稿 §3 B4):A 层帧分派**收官**(第 14 臂 `task_progress` + 行绑定/
+ *   inline stats/alias/#6 常驻台账/SubagentStart/workflow lane 三级门 + `settlePanelTasks` 三处 sweep
+ *   全接线)· P0-2 tool label 侧信道补漏(0.5.0 真缺口)· **请求面合一**(`request/taskRequest.ts`:
+ *   三个构造器的字段集与合并语义收成一份,车道差异做成 `REQUEST_FIELD_MATRIX` 数据表)·
+ *   §8-2 构造点收编(`resolveWireAuth`)· §8-1 verb 门面接口定型(`ClientSliceLike` + `CLIENT_VERBS`,
+ *   **编译期**双向闭合门)· `CHROME_ARMS` 覆盖率出口 · 包级宿主装配 `installHost()`(settings/fs/
+ *   queue/timers 四口 + `hostPortMisses()` 自检)· `scratchpadWireCaps` 搬入(FsPort 端到端证明)。
  * 0.5.0 = **B3 批**(设计稿 §3 B3):`AdapterContext` 扩容(log/probe/signal/setTimer/clearTimer/
  *   coalesceIntervalMs,**只加可选位 = minor 不 BREAKING**)· 适配内核搬入(`adapter/types` 运行时
  *   半场 + `adapter/downstream` 三件 + `adapter/runStream`)· runStream **两条外向边切除**
@@ -29,9 +45,15 @@
  *   —— B2 新增:notifications.ts(11 个通知台账 + 队列 port + 两个 probe 槽)·
  *   agentsWireCaps.ts(prepare 缓存/投影闭包/一次性告警集)· liveModelCatalog.ts(目录 + refresher)·
  *   sessionModelLatch.ts(三个 latch)· ultracodeWireCaps.ts(sticky preset)。
+ *   —— B4 新增:scratchpadWireCaps.ts(`ensured` 建目录闩)· host.ts(宿主口装配 + miss 计数);
+ *   适配器**实例级**(非 module 级)新增 `firedSubagentStartHookTaskIds`——cli 那份是 module 级,
+ *   本包放实例级是**有意的**(多 session 宿主上 module 形会让两个会话互吞 SubagentStart,见 DIVERGENCE-6)。
  *   —— B3 新增:adapter/runStream.ts(`inFlightTurns` 计数,读口 `isRunStreamActive()`;
  *   两份实例 = 引擎滚动升级门恒读 false ⇒ **turn 中途热换引擎**,正是它当初要防的事)。
- * 🔴 **宿主装配**(B2 起本包有必须由宿主注入才完整的口):`installNotificationQueuePort()` ——
+ * 🔴 **宿主装配**——B4 起总入口是 `installHost({log,probe,queue,timers,settings,fs})`
+ *   (`installNotificationQueuePort()` 仍是队列的真源出口,`installHost({queue})` 直通它,两者不分裂);
+ *   自检口 `hostPortMisses()` 恒应为空对象,非空 = 有口漏装、对应的面已在静默失效。
+ *   —— B2 起的既有说明:`installNotificationQueuePort()` ——
  *   不装 = task-notification 投递静默丢失(`notificationQueuePortMisses()` 恒应为 0)。
  *   —— B3 新增(可选口,缺席 = 对应 UI 面在该宿主上是哑的,不是报错):`ctx.emitChrome`
  *   (runStream 的两条切边:statusline 真 usage / plan-review 审批卡)· `ctx.setTimer`
@@ -63,8 +85,8 @@ export * from './controlRouter.js';
 export * from './sseIdleTriage.js';
 export * from './engineWireSdk.js';
 export * from './classifierVerdictWire.js';
-// caps / wire 门族(17 个 *WireCaps —— 壳侧 hooksWireCaps / scratchpadWireCaps 因宿主耦合未搬,
-// 见 README 的 B2 记账)
+// caps / wire 门族(17 个 *WireCaps。B2 时 hooksWireCaps / scratchpadWireCaps 因宿主耦合未搬;
+// B4 已搬 scratchpadWireCaps(走 FsPort),hooksWireCaps 仍在壳里等 SettingsPort 接线 —— 见交接报告)
 export * from './agentsWireCaps.js';
 export * from './attachmentsWireCaps.js';
 export * from './clientContextWireCaps.js';
@@ -95,3 +117,26 @@ export * from './adapter/downstream/turnUsageToModelUsage.js';
 export * from './adapter/downstream/eventToSdkMessage.js';
 export * from './adapter/downstream/terminalToSdkResult.js';
 export * from './adapter/runStream.js';
+// ── B4 批:A 层帧分派收官 + 请求面合一 + 构造点收编(2026-07-27)────────────────────────────────
+// 请求面:三个构造器(seamQuery.toTaskRequest / seamQueryEngine / liveClient.toLiveRequest)
+// 的**字段集与合并语义**收成一份;车道差异做成 REQUEST_FIELD_MATRIX 数据表(gap:true = 判为漏)。
+export * from './request/taskRequest.js';
+export * from './clientSlice.js';
+// 包级宿主装配(per-turn 的 AdapterContext 之外的那一层:settings / fs / queue / timers)。
+// 🔴 `installNotificationQueuePort` 仍是队列的真源出口,`installHost({queue})` 只是直通它。
+export * from './host.js';
+// B2 判给 B4 的宿主耦合件之一(小的那件,同时是 FsPort 的端到端证明)。
+export * from './scratchpadWireCaps.js';
+// ── B5 批:工具结果卡 B/D/E 层 + T20 客户端 diff(2026-07-27)────────────────────────────────
+export * from './toolResult.js';
+export * from './diff/patch.js';
+// ── B5 批(B4 残项第一批):S/ 七件 headless / 部署旋钮 wire(2026-07-27)──────────────────────
+// 🔴 env 默认值从 `process.env` 换成 `hostEnv()`(本包零 process;Node 下是同一对象,
+//    壳侧「不传 env 参数」的调用点行为一字节不变 —— 等价性记账见 hostEnv.ts 头注)。
+export * from './sandboxWire.js';
+export * from './scenarioWire.js';
+export * from './finalVerifyWire.js';
+export * from './limitsWire.js';
+export * from './interactiveToolsWire.js';
+export * from './headlessPermissionModeWire.js';
+export * from './headlessReconnectWire.js';

package/dist/interactiveToolsWire.d.ts

@@ -0,0 +1,48 @@
+/**
+ * src/sema/interactiveToolsWire.ts — headless `-p` 的 TaskRequest.interactiveTools:false stamp
+ * ([909]B 件3,采 [911]② core 正解,2026-07-16)。
+ *
+ * WHY:core 1.296 起 TaskSpec 有 `interactiveTools?: boolean` 三态旋钮(dist/core/types.d.ts:241);
+ * prepare-task.js 两处消费:
+ *   :635 plan 门   `spec.enablePlanMode === true && spec.interactiveTools !== false`
+ *   :974 AskUserQuestion roster `interactiveTools === true || (interactiveTools !== false &&
+ *        (onQuestion !== undefined || durableQuestionFace))`
+ * ⇒ `-p` 无人值守姿势 stamp `false`,AskUserQuestion/plan 门从 roster【源头】全灭(模型压根看不到
+ * 该工具)= [909]A3(headless EnterPlanMode→park 弃 86% 预算)类事故的根治,比 [884]A1 的
+ * park→error 终帧防御纵深更靠前(现在根本不 park)。
+ *
+ * 语义(headlessPermissionModeWire 同点同型 wire):
+ *   · 仅 headless `-p` 车道(本模块只被 seamQueryEngine.ask import;交互 REPL 一根毛不动);
+ *   · 显式交互意图恒赢:CLI 无 --interactive-tools 类旗(gap-check 2026-07-16:上游 CC 2.1.207
+ *     与本壳 argv 面均无,不发明);既有旗里唯一表达「我要交互门」的是 `--permission-mode plan`
+ *     (plan 流程本身要 plan-review 交互)——该旗在场时不 stamp(维持引擎缺省判据);
+ *   · SEMA_HEADLESS_INTERACTIVE_TOOLS 部署旋钮(settings env 车道):true/1 = 不 stamp(回引擎
+ *     缺省判据),false/0 = 显式 stamp false(与缺省同效,显式垫);非法值一次性 warn + 回缺省;
+ *   · 缺省 = stamp false(无人值守正解);
+ *   · 旧 server 白名单 fail-soft:server resolveSpec 逐字段白名单拼 TaskSpec,未知 body 字段静默
+ *     忽略(limits wire 同款勘察结论)——本字段发了白发不炸。gap-check 实拆 server 1.210.0 dist:
+ *     resolveSpec(main.js:1233-)【不】读 body.interactiveTools ⇒ 需 server 半场补一行白名单,
+ *     壳先备(黑板记账)。
+ */
+import { type EnvLike } from './hostEnv.js';
+/** 部署旋钮 env 键名(settings.json env 块 → 1a-envseed → process.env 同车道)。 */
+export declare const HEADLESS_INTERACTIVE_TOOLS_ENV = "SEMA_HEADLESS_INTERACTIVE_TOOLS";
+export type InteractiveToolsResolution = {
+    /** 直接展开进 TaskRequest 的字段({} = 不 stamp)。 */
+    fields: {
+        interactiveTools?: false;
+    };
+    source: 'default' | 'env' | 'plan-flag';
+    /** 非法 env 值的告警文案(调用层一次性打 stderr)。 */
+    warning?: string;
+};
+/** argv 里是否显式要了 plan 交互意图(`--permission-mode plan` / `--permission-mode=plan`;
+ *  后出现者赢,commander 同语义;`--` 之后不是 flag)。 */
+export declare function planModeExplicitlyRequested(argv: readonly string[]): boolean;
+/**
+ * 解析 headless `-p` 的 interactiveTools stamp。纯函数除告警 latch。
+ * 调用方(seamQueryEngine.ask)live-gated:mock/pty 车道永不经过这里。
+ */
+export declare function resolveHeadlessInteractiveTools(argv: readonly string[], env?: EnvLike): InteractiveToolsResolution;
+/** 测试钩子:重置一次性告警 latch。 */
+export declare function _resetInteractiveToolsWireForTest(): void;

package/dist/interactiveToolsWire.js

@@ -0,0 +1,86 @@
+/**
+ * src/sema/interactiveToolsWire.ts — headless `-p` 的 TaskRequest.interactiveTools:false stamp
+ * ([909]B 件3,采 [911]② core 正解,2026-07-16)。
+ *
+ * WHY:core 1.296 起 TaskSpec 有 `interactiveTools?: boolean` 三态旋钮(dist/core/types.d.ts:241);
+ * prepare-task.js 两处消费:
+ *   :635 plan 门   `spec.enablePlanMode === true && spec.interactiveTools !== false`
+ *   :974 AskUserQuestion roster `interactiveTools === true || (interactiveTools !== false &&
+ *        (onQuestion !== undefined || durableQuestionFace))`
+ * ⇒ `-p` 无人值守姿势 stamp `false`,AskUserQuestion/plan 门从 roster【源头】全灭(模型压根看不到
+ * 该工具)= [909]A3(headless EnterPlanMode→park 弃 86% 预算)类事故的根治,比 [884]A1 的
+ * park→error 终帧防御纵深更靠前(现在根本不 park)。
+ *
+ * 语义(headlessPermissionModeWire 同点同型 wire):
+ *   · 仅 headless `-p` 车道(本模块只被 seamQueryEngine.ask import;交互 REPL 一根毛不动);
+ *   · 显式交互意图恒赢:CLI 无 --interactive-tools 类旗(gap-check 2026-07-16:上游 CC 2.1.207
+ *     与本壳 argv 面均无,不发明);既有旗里唯一表达「我要交互门」的是 `--permission-mode plan`
+ *     (plan 流程本身要 plan-review 交互)——该旗在场时不 stamp(维持引擎缺省判据);
+ *   · SEMA_HEADLESS_INTERACTIVE_TOOLS 部署旋钮(settings env 车道):true/1 = 不 stamp(回引擎
+ *     缺省判据),false/0 = 显式 stamp false(与缺省同效,显式垫);非法值一次性 warn + 回缺省;
+ *   · 缺省 = stamp false(无人值守正解);
+ *   · 旧 server 白名单 fail-soft:server resolveSpec 逐字段白名单拼 TaskSpec,未知 body 字段静默
+ *     忽略(limits wire 同款勘察结论)——本字段发了白发不炸。gap-check 实拆 server 1.210.0 dist:
+ *     resolveSpec(main.js:1233-)【不】读 body.interactiveTools ⇒ 需 server 半场补一行白名单,
+ *     壳先备(黑板记账)。
+ */
+import { hostEnv } from './hostEnv.js';
+/** 部署旋钮 env 键名(settings.json env 块 → 1a-envseed → process.env 同车道)。 */
+export const HEADLESS_INTERACTIVE_TOOLS_ENV = 'SEMA_HEADLESS_INTERACTIVE_TOOLS';
+/** argv 里是否显式要了 plan 交互意图(`--permission-mode plan` / `--permission-mode=plan`;
+ *  后出现者赢,commander 同语义;`--` 之后不是 flag)。 */
+export function planModeExplicitlyRequested(argv) {
+    let mode;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--permission-mode') {
+            const v = argv[i + 1];
+            if (typeof v === 'string' && !v.startsWith('-')) {
+                mode = v;
+                i++;
+            }
+        }
+        else if (a?.startsWith('--permission-mode=')) {
+            mode = a.slice('--permission-mode='.length);
+        }
+        else if (a === '--') {
+            break;
+        }
+    }
+    return mode === 'plan';
+}
+// 一次性告警 latch(-p 是 one-shot 进程;测试钩子可重置)
+let warnedInvalidEnv = false;
+/**
+ * 解析 headless `-p` 的 interactiveTools stamp。纯函数除告警 latch。
+ * 调用方(seamQueryEngine.ask)live-gated:mock/pty 车道永不经过这里。
+ */
+export function resolveHeadlessInteractiveTools(argv, env = hostEnv()) {
+    // 1) 显式交互意图恒赢:--permission-mode plan ⇒ 不 stamp(plan 流程要 plan-review 门)。
+    if (planModeExplicitlyRequested(argv)) {
+        return { fields: {}, source: 'plan-flag' };
+    }
+    // 2) 部署旋钮。
+    const raw = env[HEADLESS_INTERACTIVE_TOOLS_ENV]?.trim();
+    if (raw !== undefined && raw !== '') {
+        if (raw === 'true' || raw === '1')
+            return { fields: {}, source: 'env' }; // 回引擎缺省判据
+        if (raw === 'false' || raw === '0')
+            return { fields: { interactiveTools: false }, source: 'env' };
+        const resolution = {
+            fields: { interactiveTools: false },
+            source: 'default',
+        };
+        if (!warnedInvalidEnv) {
+            warnedInvalidEnv = true;
+            resolution.warning = `sema: ${HEADLESS_INTERACTIVE_TOOLS_ENV}="${raw}" is not a boolean (expected true/1/false/0) — ignoring it, headless -p keeps interactive tools OFF by default`;
+        }
+        return resolution;
+    }
+    // 3) 缺省:无人值守 stamp false(AskUserQuestion/plan 门 roster 源头全灭)。
+    return { fields: { interactiveTools: false }, source: 'default' };
+}
+/** 测试钩子:重置一次性告警 latch。 */
+export function _resetInteractiveToolsWireForTest() {
+    warnedInvalidEnv = false;
+}

package/dist/limitsWire.d.ts

@@ -0,0 +1,89 @@
+/**
+ * src/sema/limitsWire.ts — headless `-p` run-limits wire (TB2.0 反馈批 E · P2-3-b, 2026-07-15):
+ * expose the engine's REQUEST-LEVEL pacing limits on the headless `-p` path via `TaskRequest.limits`.
+ * The server accepts `limits:{timeoutSec?,maxOutputTokens?,maxTurns?}` since 1.196.0 (positive-integer
+ * 400 gate, board [857]) and feeds the EXISTING pacing machinery (deadlineNudge / callCapByDeadline /
+ * gracefulFinalize) — the shell simply never stamped the field. This module is the CLI face.
+ *
+ * TWO FLAGS, TWO ALIGNMENT BUCKETS:
+ *  · `--deadline <sec>`   → limits.timeoutSec. Upstream CC 2.1.207 has NO deadline flag (nearest kin:
+ *    --max-turns / --task-budget / --max-budget-usd) → SUPERSET, help copy says so.
+ *  · `--max-turns <n>`    → limits.maxTurns. Upstream CC 2.1.207 HAS `--max-turns` (source 199676 /
+ *    793380) → ALIGNMENT-GAP fill: the flag was already registered (main.tsx CC-inherited surface) and
+ *    drove the local query loop, but the seam path executes turns ENGINE-side — this wire finally
+ *    carries the cap to where the turns actually run.
+ *
+ * PRECEDENCE per knob (flag > settings > none), scenarioWire 三件套同款:
+ *  a) explicit flag                                   → strict validation, FAIL-LOUD on an invalid
+ *     value (integer domain below; a mis-typed pacing bound must not quietly run unbounded).
+ *  b) settings env lane (settings.json `env` block → 1a-envseed → process.env):
+ *     `SEMA_HEADLESS_DEADLINE_SEC` / `SEMA_HEADLESS_MAX_TURNS` → SILENT degrade on an invalid value
+ *     (spec'd 静默降级 — a settings typo must never brick every headless run; unlike scenarioWire we
+ *     don't even warn, per the batch-E triage shape. SEMA_DEBUG surfaces the drop for diagnosis).
+ *  c) neither                                          → NO stamp = today's behaviour, verbatim.
+ *
+ * DOMAINS (integer, inclusive): timeoutSec 30..86400 · maxTurns 1..1000.
+ *
+ * VERSION GATE (triage risk ③ — an OLD server SILENTLY SWALLOWS unknown body fields, worse than not
+ * shipping): the self-spawned engine is release-pinned ≥1.197.0 so the dev/release lanes are safe by
+ * construction; but a user-supplied SEMA_ENGINE_URL may point at an older engine. When the user
+ * EXPLICITLY passed a flag (env-lane defaults stay quiet) and SEMA_ENGINE_URL is in play, the caller
+ * probes `${baseUrl}/health` (the engine self-describes `version` since 1.96) and prints ONE honest
+ * stderr line when version <1.196.0 — the request still goes out unchanged (warn, don't block).
+ * Unreachable /health or an unparsable version stays silent (can't confirm staleness — fail-soft).
+ */
+import { type EnvLike } from './hostEnv.js';
+/** Settings-lane env knobs (settings.json `env` block → 1a-envseed → process.env). */
+export declare const HEADLESS_DEADLINE_ENV = "SEMA_HEADLESS_DEADLINE_SEC";
+export declare const HEADLESS_MAX_TURNS_ENV = "SEMA_HEADLESS_MAX_TURNS";
+/** Integer domains (inclusive). timeoutSec: 30s..24h; maxTurns: 1..1000. */
+export declare const DEADLINE_SEC_MIN = 30;
+export declare const DEADLINE_SEC_MAX = 86400;
+export declare const MAX_TURNS_MIN = 1;
+export declare const MAX_TURNS_MAX = 1000;
+/** First server version whose /v1/tasks|/v1/tasks/stream accept body.limits (board [857]). */
+export declare const LIMITS_WIRE_MIN_ENGINE: readonly [number, number, number];
+export interface HeadlessLimits {
+    timeoutSec?: number;
+    maxTurns?: number;
+}
+export type LimitsParseResult = {
+    ok: true;
+    limits?: HeadlessLimits;
+    flaggedFlags: string[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Parse `--deadline` + `--max-turns` out of an argv slice. No flags ⇒ `{ok:true}` with no limits.
+ * Repeated flag ⇒ LAST wins (commander convention). Missing value / non-integer / out-of-domain ⇒
+ * fail-LOUD parse error (never a silent default — same stance as `--scenario`/`--sandbox`).
+ * `flaggedFlags` names the flags that EXPLICITLY contributed (the version-gate probe trigger).
+ */
+export declare function parseLimitsArgv(argv: string[]): LimitsParseResult;
+/**
+ * The settings-lane defaults. SILENT degrade on a bad value (batch-E triage shape — stricter than
+ * scenarioWire's warn-and-ignore: these are pacing hints, and a settings typo must neither brick nor
+ * spam every headless run). SEMA_DEBUG surfaces the drop.
+ */
+export declare function headlessLimitsFromEnv(env?: EnvLike): HeadlessLimits | undefined;
+/**
+ * Resolve the limits for a headless `-p` submit: explicit flags > settings env defaults > none
+ * (= no stamp, today's behaviour). Merge is PER-KNOB: `--deadline 300` + SEMA_HEADLESS_MAX_TURNS=50
+ * yields {timeoutSec:300, maxTurns:50}. Flag parse errors propagate fail-loud; the caller exits.
+ */
+export declare function limitsForPrint(argv: string[], env?: EnvLike): LimitsParseResult;
+/** True when the engine version string satisfies the limits-wire minimum (≥1.196.0). Unparsable ⇒ false. */
+export declare function versionSupportsLimits(v: string | undefined): boolean;
+/**
+ * Version-gate probe (triage risk ③): GET `${baseUrl}/health`, read `version`, and return ONE honest
+ * stderr line when the engine is confirmed <1.196.0 — the caller prints it and SENDS ANYWAY (the old
+ * server drops the field server-side; warn, don't block). Returns undefined when the engine is new
+ * enough, unreachable, or self-describes no parsable version (can't confirm staleness — fail-soft
+ * silent; the release-pinned self-spawn lane never even reaches this probe).
+ */
+export declare function engineLimitsSupportWarning(baseUrl: string, flaggedFlags: string[], opts?: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<string | undefined>;

package/dist/limitsWire.js

@@ -0,0 +1,225 @@
+/**
+ * src/sema/limitsWire.ts — headless `-p` run-limits wire (TB2.0 反馈批 E · P2-3-b, 2026-07-15):
+ * expose the engine's REQUEST-LEVEL pacing limits on the headless `-p` path via `TaskRequest.limits`.
+ * The server accepts `limits:{timeoutSec?,maxOutputTokens?,maxTurns?}` since 1.196.0 (positive-integer
+ * 400 gate, board [857]) and feeds the EXISTING pacing machinery (deadlineNudge / callCapByDeadline /
+ * gracefulFinalize) — the shell simply never stamped the field. This module is the CLI face.
+ *
+ * TWO FLAGS, TWO ALIGNMENT BUCKETS:
+ *  · `--deadline <sec>`   → limits.timeoutSec. Upstream CC 2.1.207 has NO deadline flag (nearest kin:
+ *    --max-turns / --task-budget / --max-budget-usd) → SUPERSET, help copy says so.
+ *  · `--max-turns <n>`    → limits.maxTurns. Upstream CC 2.1.207 HAS `--max-turns` (source 199676 /
+ *    793380) → ALIGNMENT-GAP fill: the flag was already registered (main.tsx CC-inherited surface) and
+ *    drove the local query loop, but the seam path executes turns ENGINE-side — this wire finally
+ *    carries the cap to where the turns actually run.
+ *
+ * PRECEDENCE per knob (flag > settings > none), scenarioWire 三件套同款:
+ *  a) explicit flag                                   → strict validation, FAIL-LOUD on an invalid
+ *     value (integer domain below; a mis-typed pacing bound must not quietly run unbounded).
+ *  b) settings env lane (settings.json `env` block → 1a-envseed → process.env):
+ *     `SEMA_HEADLESS_DEADLINE_SEC` / `SEMA_HEADLESS_MAX_TURNS` → SILENT degrade on an invalid value
+ *     (spec'd 静默降级 — a settings typo must never brick every headless run; unlike scenarioWire we
+ *     don't even warn, per the batch-E triage shape. SEMA_DEBUG surfaces the drop for diagnosis).
+ *  c) neither                                          → NO stamp = today's behaviour, verbatim.
+ *
+ * DOMAINS (integer, inclusive): timeoutSec 30..86400 · maxTurns 1..1000.
+ *
+ * VERSION GATE (triage risk ③ — an OLD server SILENTLY SWALLOWS unknown body fields, worse than not
+ * shipping): the self-spawned engine is release-pinned ≥1.197.0 so the dev/release lanes are safe by
+ * construction; but a user-supplied SEMA_ENGINE_URL may point at an older engine. When the user
+ * EXPLICITLY passed a flag (env-lane defaults stay quiet) and SEMA_ENGINE_URL is in play, the caller
+ * probes `${baseUrl}/health` (the engine self-describes `version` since 1.96) and prints ONE honest
+ * stderr line when version <1.196.0 — the request still goes out unchanged (warn, don't block).
+ * Unreachable /health or an unparsable version stays silent (can't confirm staleness — fail-soft).
+ */
+import { hostEnv } from './hostEnv.js';
+/** Settings-lane env knobs (settings.json `env` block → 1a-envseed → process.env). */
+export const HEADLESS_DEADLINE_ENV = 'SEMA_HEADLESS_DEADLINE_SEC';
+export const HEADLESS_MAX_TURNS_ENV = 'SEMA_HEADLESS_MAX_TURNS';
+/** Integer domains (inclusive). timeoutSec: 30s..24h; maxTurns: 1..1000. */
+export const DEADLINE_SEC_MIN = 30;
+export const DEADLINE_SEC_MAX = 86_400;
+export const MAX_TURNS_MIN = 1;
+export const MAX_TURNS_MAX = 1_000;
+/** First server version whose /v1/tasks|/v1/tasks/stream accept body.limits (board [857]). */
+export const LIMITS_WIRE_MIN_ENGINE = [1, 196, 0];
+const DEADLINE_USAGE = `sema: --deadline expects a whole number of seconds between ${DEADLINE_SEC_MIN} and ${DEADLINE_SEC_MAX}.\n` +
+    '  --deadline <sec>     soft wall-clock budget for this run (sema superset — no upstream equivalent):\n' +
+    '                       the engine paces itself (nudges + call caps) and finalizes gracefully near the deadline\n' +
+    '  (no flag)            no deadline — today\'s behaviour';
+const MAX_TURNS_USAGE = `sema: --max-turns expects a whole number of turns between ${MAX_TURNS_MIN} and ${MAX_TURNS_MAX}.\n` +
+    '  --max-turns <n>      maximum number of agentic turns for this run (upstream-aligned flag,\n' +
+    '                       enforced engine-side on the sema seam)\n' +
+    '  (no flag)            no turn cap — today\'s behaviour';
+/** STRICT integer shape for explicit flag values: ASCII digits only (no sign/decimal/exponent/space). */
+const INT_RE = /^\d+$/;
+/**
+ * Pull the LAST value of a `--name <v>` / `--name=<v>` flag out of an argv slice (everything before a
+ * bare `--` — positionals are never flags; scenarioWire 纪律). Returns:
+ *   {present:false}                 — flag absent
+ *   {present:true, raw}             — flag present with a value token
+ *   {present:true, raw:undefined}   — flag present but the value is missing/flag-shaped (fail-loud at caller)
+ */
+function lastFlagValue(argv, name) {
+    const eq = `${name}=`;
+    let present = false;
+    let raw;
+    let valueMissing = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--')
+            break; // positionals — never flags
+        if (a === name) {
+            present = true;
+            const nxt = argv[i + 1];
+            if (nxt === undefined || nxt.startsWith('-')) {
+                // note: a NEGATIVE number would look flag-shaped too — the domains are all-positive, so the
+                // fail-loud usage hint is the right answer for `--deadline -5` as well.
+                valueMissing = true;
+                raw = undefined;
+                continue;
+            }
+            valueMissing = false;
+            raw = nxt;
+            i++; // consume the value token
+        }
+        else if (a.startsWith(eq)) {
+            present = true;
+            valueMissing = false;
+            raw = a.slice(eq.length);
+        }
+    }
+    if (present && (valueMissing || raw === undefined))
+        return { present: true };
+    return present ? { present: true, raw } : { present: false };
+}
+/** Validate a RAW flag value against an inclusive integer domain. Returns the number or null. */
+function parseIntInDomain(raw, min, max) {
+    const v = raw.trim();
+    if (!INT_RE.test(v))
+        return null;
+    const n = Number(v);
+    if (!Number.isSafeInteger(n) || n < min || n > max)
+        return null;
+    return n;
+}
+/**
+ * Parse `--deadline` + `--max-turns` out of an argv slice. No flags ⇒ `{ok:true}` with no limits.
+ * Repeated flag ⇒ LAST wins (commander convention). Missing value / non-integer / out-of-domain ⇒
+ * fail-LOUD parse error (never a silent default — same stance as `--scenario`/`--sandbox`).
+ * `flaggedFlags` names the flags that EXPLICITLY contributed (the version-gate probe trigger).
+ */
+export function parseLimitsArgv(argv) {
+    const limits = {};
+    const flaggedFlags = [];
+    const dl = lastFlagValue(argv, '--deadline');
+    if (dl.present) {
+        const n = dl.raw !== undefined ? parseIntInDomain(dl.raw, DEADLINE_SEC_MIN, DEADLINE_SEC_MAX) : null;
+        if (n === null)
+            return { ok: false, error: DEADLINE_USAGE };
+        limits.timeoutSec = n;
+        flaggedFlags.push('--deadline');
+    }
+    const mt = lastFlagValue(argv, '--max-turns');
+    if (mt.present) {
+        const n = mt.raw !== undefined ? parseIntInDomain(mt.raw, MAX_TURNS_MIN, MAX_TURNS_MAX) : null;
+        if (n === null)
+            return { ok: false, error: MAX_TURNS_USAGE };
+        limits.maxTurns = n;
+        flaggedFlags.push('--max-turns');
+    }
+    return {
+        ok: true,
+        ...(flaggedFlags.length > 0 ? { limits } : {}),
+        flaggedFlags,
+    };
+}
+/**
+ * The settings-lane defaults. SILENT degrade on a bad value (batch-E triage shape — stricter than
+ * scenarioWire's warn-and-ignore: these are pacing hints, and a settings typo must neither brick nor
+ * spam every headless run). SEMA_DEBUG surfaces the drop.
+ */
+export function headlessLimitsFromEnv(env = hostEnv()) {
+    const out = {};
+    const dl = env[HEADLESS_DEADLINE_ENV]?.trim();
+    if (dl) {
+        const n = parseIntInDomain(dl, DEADLINE_SEC_MIN, DEADLINE_SEC_MAX);
+        if (n !== null)
+            out.timeoutSec = n;
+        else if (env.SEMA_DEBUG) {
+            // eslint-disable-next-line no-console
+            console.error(`[sema] ${HEADLESS_DEADLINE_ENV}="${dl}" is not an integer in ${DEADLINE_SEC_MIN}..${DEADLINE_SEC_MAX} — ignoring the settings default`);
+        }
+    }
+    const mt = env[HEADLESS_MAX_TURNS_ENV]?.trim();
+    if (mt) {
+        const n = parseIntInDomain(mt, MAX_TURNS_MIN, MAX_TURNS_MAX);
+        if (n !== null)
+            out.maxTurns = n;
+        else if (env.SEMA_DEBUG) {
+            // eslint-disable-next-line no-console
+            console.error(`[sema] ${HEADLESS_MAX_TURNS_ENV}="${mt}" is not an integer in ${MAX_TURNS_MIN}..${MAX_TURNS_MAX} — ignoring the settings default`);
+        }
+    }
+    return out.timeoutSec !== undefined || out.maxTurns !== undefined ? out : undefined;
+}
+/**
+ * Resolve the limits for a headless `-p` submit: explicit flags > settings env defaults > none
+ * (= no stamp, today's behaviour). Merge is PER-KNOB: `--deadline 300` + SEMA_HEADLESS_MAX_TURNS=50
+ * yields {timeoutSec:300, maxTurns:50}. Flag parse errors propagate fail-loud; the caller exits.
+ */
+export function limitsForPrint(argv, env = hostEnv()) {
+    const parsed = parseLimitsArgv(argv);
+    if (!parsed.ok)
+        return parsed;
+    const fromEnv = headlessLimitsFromEnv(env);
+    const merged = { ...(fromEnv ?? {}), ...(parsed.limits ?? {}) };
+    const any = merged.timeoutSec !== undefined || merged.maxTurns !== undefined;
+    return { ok: true, ...(any ? { limits: merged } : {}), flaggedFlags: parsed.flaggedFlags };
+}
+/** True when the engine version string satisfies the limits-wire minimum (≥1.196.0). Unparsable ⇒ false. */
+export function versionSupportsLimits(v) {
+    const m = v ? /^(\d+)\.(\d+)\.(\d+)/.exec(v) : null;
+    if (!m)
+        return false;
+    const [a, b, c] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const [ma, mb, mc] = LIMITS_WIRE_MIN_ENGINE;
+    if (a !== ma)
+        return a > ma;
+    if (b !== mb)
+        return b > mb;
+    return c >= mc;
+}
+/**
+ * Version-gate probe (triage risk ③): GET `${baseUrl}/health`, read `version`, and return ONE honest
+ * stderr line when the engine is confirmed <1.196.0 — the caller prints it and SENDS ANYWAY (the old
+ * server drops the field server-side; warn, don't block). Returns undefined when the engine is new
+ * enough, unreachable, or self-describes no parsable version (can't confirm staleness — fail-soft
+ * silent; the release-pinned self-spawn lane never even reaches this probe).
+ */
+export async function engineLimitsSupportWarning(baseUrl, flaggedFlags, opts) {
+    const fetchImpl = opts?.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts?.timeoutMs ?? 1500);
+    try {
+        const res = await fetchImpl(`${baseUrl.replace(/\/+$/, '')}/health`, {
+            method: 'GET',
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        const version = typeof body?.version === 'string' ? body.version : undefined;
+        // No version field = pre-1.96 engine — definitely older than 1.196.0, warn honestly.
+        if (versionSupportsLimits(version))
+            return undefined;
+        const flags = flaggedFlags.length > 0 ? flaggedFlags.join('/') : '--deadline/--max-turns';
+        return `[sema] engine ${version ?? '(unversioned, pre-1.96)'} does not support ${flags} (needs ≥1.196.0); the flag will be ignored by the engine`;
+    }
+    catch {
+        return undefined; // unreachable/timeout — cannot confirm staleness, stay silent
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/notifications.d.ts

@@ -90,6 +90,13 @@ export declare function dropQueuedNotificationsForRun(taskId: string): number;
  * steer-inject 的 task_notification 帧)即预标记,Channel A 对同 runId 的补发直接丢弃。
  */
 export declare function markEngineWorkflowNotified(runId: string): void;
+/** 跨通道去重的**读**口(适配器 workflow_complete 臂的发射门;cli 同域)。 */
+export declare function isEngineWorkflowNotified(runId: string): boolean;
+/** 「这个 run 的完成卡已入队」的**写**口(cli 侧等价物 = 两个 enqueue 函数内的 `cardEnqueuedRunIds.add`)。 */
+export declare function noteWorkflowCompletionCardEnqueued(runId: string): void;
+/** 台账序列化面(`exportLedger`)—— 只读快照,顺序 = 插入序。 */
+export declare function listNotifiedRuns(): string[];
+export declare function listWorkflowCompletionCardsEnqueued(): string[];
 export declare function isWorkflowCompletionCardEnqueued(runId: string): boolean;
 type WorkflowStatusProbe = (runId: string) => Promise<{
     terminal: boolean;

package/dist/notifications.js

@@ -215,6 +215,38 @@ export function markEngineWorkflowNotified(runId) {
     if (outstandingRuns.delete(runId))
         notifyOutstanding();
 }
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+// B5 ①(0.7.0)—— **配对台账折回**([1857];记忆 paired-mechanisms-must-share-premise)。
+// 0.6.0 把 `notifiedRuns` / `cardEnqueuedRuns` 放在**适配器实例**上,而与它们配对的另一半全在
+// 本模块的 module 台账上:清账的 `dropQueuedNotificationsForRun`、记账的
+// `enqueueBgChildNotification` / `enqueueEngineWorkflowNotification`、以及 idle watcher 那条
+// (壳根本拦不到的调用点)。两半前提不共享 = 四个方向同时错:
+//   ① module 记过账 ⇒ 实例不知道 ⇒ 推送帧渲第二张卡(双卡)
+//   ② 宿主回钩写实例、drop 清 module ⇒ 实例只增不减 ⇒ 那一行永不上屏(a0110e88 复发)
+//   ③④ 跨通道去重两向失效 ⇒ 同一完成二次喂模型
+// 修法 = 台账**整体**回到 module(与 cli 的 module 级 Set 逐字同域),适配器只经下面这四个口读写;
+// 实例上只留 `renderedNotifications`(渲染去重,天然 per-session)与 `firedSubagentStartHookTaskIds`
+// (DIVERGENCE-6 有意的实例级)。
+// 🔴 多 session 宿主(web 一个页面两个会话)上本对台账是**进程级共享**的 —— 这与 cli 一致,
+//   且必须如此:队列 port、idle watcher、outstanding 药丸也都是进程级的,台账单独 per-session
+//   就又造出一对「前提不共享」的机制。
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+/** 跨通道去重的**读**口(适配器 workflow_complete 臂的发射门;cli 同域)。 */
+export function isEngineWorkflowNotified(runId) {
+    return notifiedRunIds.has(runId);
+}
+/** 「这个 run 的完成卡已入队」的**写**口(cli 侧等价物 = 两个 enqueue 函数内的 `cardEnqueuedRunIds.add`)。 */
+export function noteWorkflowCompletionCardEnqueued(runId) {
+    if (runId.length > 0)
+        cardEnqueuedRunIds.add(runId);
+}
+/** 台账序列化面(`exportLedger`)—— 只读快照,顺序 = 插入序。 */
+export function listNotifiedRuns() {
+    return [...notifiedRunIds];
+}
+export function listWorkflowCompletionCardsEnqueued() {
+    return [...cardEnqueuedRunIds];
+}
 /** 双通道「完成卡」去重(clay dogfood 2026-07-19 双通知案):与 notifiedRunIds(模型通知去重,
  *  external mark 也写它)**分键**——本集只由 probe 合成 enqueue 写入(workflow+bg agent 两族,
  *  对抗复审§1:bg 合成不写此集时 probe 先到→后到推送帧仍渲第二张卡)、只由推送帧渲染前读,