@sema-agent/server 7.20.0 → 7.21.0-rc.1

package/dist/plugins/pg-session-storage.js

@@ -26,9 +26,9 @@ import { toIso } from "./sql-row-helpers.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
 import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, // 两孪生店同源(理由见 kernel 处顶注)
  } from "../session-sync-kernel.js";
-function isDupKey(err) {
-    return Boolean(err) && err.code === "23505"; // PG unique_violation
-}
+import { isPgUniqueViolation } from "./sql-errors.js";
+/** 判据属主 = `sql-errors.ts`(A-032 P1-①)。 */
+const isDupKey = isPgUniqueViolation;
 /** node-pg parses jsonb → object already; only strings need JSON.parse, everything else passes through. */
 function parseEntry(p) {
     return (typeof p === "string" ? JSON.parse(p) : p);

package/dist/plugins/run-store-sql.d.ts

@@ -14,7 +14,14 @@
  * ── Dialect deltas, kept EXPLICIT (never hidden behind an abstraction) ────────────────────────────────
  *   - `?` placeholders vs `$n` (transaction control itself is normalized by `SqlDriver`/`SqlTxConn` —
  *     mysql2's native begin/commit/rollback vs PG's statement form; see sql-driver.ts)
- *   - dup-key `ER_DUP_ENTRY` vs SQLSTATE `23505` (createRun's task_active claim race)
+ *   - dup-key classification (createRun's task_active claim race) — the PREDICATE has a single owner
+ *     (`sql-errors.ts`, A-032 P1-①); only the dialect DISPATCH is visible here
+ *
+ * ⚠️ The run ACTIVE-status word list written out in the `status IN (…)` / `NOT IN (…)` fragments below
+ * is the closed set owned by `store-contracts.ts` (`isTerminalRunStatus` / `isParkedRunStatus`). The SQL
+ * text stays literal ON PURPOSE (A12: both dialects readable side by side), so the tie is a PARITY GATE:
+ * `test/source-hygiene-gate.test.ts` → "A-032 P1-② run 活状态 SQL 字面 ↔ store-contracts 闭集属主 parity".
+ * core adding a TaskStatus member turns that gate red on every fragment here — update them in the same batch.
  *   - null-safe owner compare: `<=>` (TiDB) vs `IS NOT DISTINCT FROM` (PG) — a null-owner run still matches
  *     `owner=null` on both, single-DB-fleet defense-in-depth (see {@link requestCancel})
  *   - multi-table DELETE: `DELETE t FROM t JOIN j …` (TiDB) vs `DELETE FROM t USING j …` (PG)
@@ -36,6 +43,7 @@ import type { Pool as PgPool } from "pg";
 import { type UsageRow } from "../usage-analytics.js";
 import type { RunRecord, SessionSummary, RunEvent } from "./store-contracts.js";
 import { type SqlDriver } from "./sql-driver.js";
+import type { LedgerEventType } from "../trace/ledger-events.js";
 export type { RunRecord, SessionSummary, RunEvent } from "./store-contracts.js";
 /** Dual-dialect async run registry + event log. See the file header for the dialect-delta ledger. */
 export declare class SqlRunStore {
@@ -43,7 +51,8 @@ export declare class SqlRunStore {
     constructor(db: SqlDriver);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
-    /** mysql2 names the dup-key `ER_DUP_ENTRY`; PG raises SQLSTATE `23505`. */
+    /** Dup-key classification — single owner in `sql-errors.ts` (A-032 P1-①; the old local form read
+     *  only mysql2's string `code`, so an error carrying just `errno` fell through the claim-race arm). */
     private isDupKey;
     /** JSON column binding: TiDB stores the string verbatim; PG goes through the protocol-safe envelope
      *  (a raw NUL byte in an event payload would otherwise throw 22P05 mid-write). */
@@ -97,7 +106,7 @@ export declare class SqlRunStore {
     heartbeat(taskId: string, owner: string | null): Promise<void>;
     /** Append one event. A single INSERT — `updated_at` (liveness) is owned by `heartbeat`, so there
      *  is no second statement to keep atomic here. */
-    appendEvent(taskId: string, seq: number, type: string, data: unknown): Promise<void>;
+    appendEvent(taskId: string, seq: number, type: LedgerEventType, data: unknown): Promise<void>;
     /** Highest event seq for a task (0 if none). Lets a resumed leg CONTINUE the durable event log past the
      *  suspend (core 1.70 `resumeStream`) — the suspend wrote events 1..K, the resume appends from K+1 without
      *  colliding on the (task_id, seq) PK. */

package/dist/plugins/run-store-sql.js

@@ -3,6 +3,7 @@ import { escapeLike } from "./sql-escape.js";
 import { pgSanitizeText } from "./pg-safe-json.js";
 import { parseJsonLenient as parseJson, toIso as iso } from "./sql-row-helpers.js";
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
+import { isDupKeyError } from "./sql-errors.js";
 /** Dual-dialect async run registry + event log. See the file header for the dialect-delta ledger. */
 export class SqlRunStore {
     db;
@@ -13,10 +14,10 @@ export class SqlRunStore {
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
-    /** mysql2 names the dup-key `ER_DUP_ENTRY`; PG raises SQLSTATE `23505`. */
+    /** Dup-key classification — single owner in `sql-errors.ts` (A-032 P1-①; the old local form read
+     *  only mysql2's string `code`, so an error carrying just `errno` fell through the claim-race arm). */
     isDupKey(err) {
-        const code = err?.code;
-        return Boolean(err) && (this.db.dialect === "tidb" ? code === "ER_DUP_ENTRY" : code === "23505");
+        return isDupKeyError(this.db.dialect, err);
     }
     /** JSON column binding: TiDB stores the string verbatim; PG goes through the protocol-safe envelope
      *  (a raw NUL byte in an event payload would otherwise throw 22P05 mid-write). */

package/dist/plugins/session-policy-store-sql.d.ts

@@ -14,6 +14,7 @@ export declare class SqlSessionPolicyStore implements SessionPolicyStore {
     constructor(db: SqlDriver);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
+    /** 判据属主 = `sql-errors.ts`(A-032 P1-①;本站点旧形已是并集形,收编后语义不变)。 */
     private isDupKey;
     /** Read the stored rules for (session, principal-owner); null when none (parity with InMemory). */
     getRules(sessionId: string, principal?: string): Promise<StoredSessionRules | null>;

package/dist/plugins/session-policy-store-sql.js

@@ -43,6 +43,7 @@ import { createHash } from "node:crypto";
 import { loosenReasons, SessionPolicyError, normalizeRules, stripRev } from "@sema-agent/core";
 import { pgHasUnstorable } from "./pg-safe-json.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
+import { isDupKeyError } from "./sql-errors.js";
 /** `session_policy.policy_key` 的**唯一铸造点**(core 复合键的 sha256)。
  *
  *  🔴 导出而不是让收编腿再抄一份(clay 宪法「schema 单一属主禁复制」):design/183 form b 的身份重绑要
@@ -61,10 +62,9 @@ export class SqlSessionPolicyStore {
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
+    /** 判据属主 = `sql-errors.ts`(A-032 P1-①;本站点旧形已是并集形,收编后语义不变)。 */
     isDupKey(e) {
-        return this.db.dialect === "tidb"
-            ? e?.code === "ER_DUP_ENTRY" || e?.errno === 1062
-            : e?.code === "23505";
+        return isDupKeyError(this.db.dialect, e);
     }
     /** Read the stored rules for (session, principal-owner); null when none (parity with InMemory). */
     async getRules(sessionId, principal) {

package/dist/plugins/shared-memory-store-sql.js

@@ -1,16 +1,10 @@
 import { SHARED_MEMORY_READ_CAP_BYTES, SharedMemoryStoreError, } from "@sema-agent/core";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
-/** 唯一键冲突的方言判别(approval-ask/checkpoint 同一对常量)——mysql2 挂 `errno`,node-pg 挂 SQLSTATE。
+import { isDupKeyError } from "./sql-errors.js";
+/** 唯一键冲突的方言判别 —— 判据属主 = `sql-errors.ts`(A-032 P1-①:本站点原是全仓唯一的硬化形,
+ *  收编时把它**升格成属主**,其余六处按它对齐;`Reflect.get` 走原型链的理由见属主头注)。
  *  只用来把并发登记撞 PK 翻成一句人话,不让驱动错误对象漏给调用方。 */
-const DUP_ENTRY = 1062; // MySQL/TiDB ER_DUP_ENTRY
-const PG_UNIQUE_VIOLATION = "23505";
-function isDupKey(dialect, err) {
-    if (err === null || typeof err !== "object")
-        return false;
-    // Reflect.get (not a spread): driver error classes carry these on the PROTOTYPE chain in some
-    // versions, and `{...err}` would silently miss them — a missed dup-key leaks the raw driver object.
-    return dialect === "tidb" ? Number(Reflect.get(err, "errno")) === DUP_ENTRY : String(Reflect.get(err, "code")) === PG_UNIQUE_VIOLATION;
-}
+const isDupKey = isDupKeyError;
 /** Per-org plane state (`connecting` / `unavailable` / `connected`). One row per org scope. */
 export const SHARED_MEMORY_SCOPE_TABLE = "shared_memory_scope";
 /** The model-facing store registry: one row per browsable library. */

package/dist/plugins/sql-driver.d.ts

@@ -16,9 +16,11 @@
  *     `CAST(? AS JSON)` vs `$n::jsonb`, `INSERT IGNORE` vs `ON CONFLICT DO NOTHING`, `<=>` vs
  *     `IS NOT DISTINCT FROM`, VARBINARY vs `COLLATE "C"` — every one of these stays written out at
  *     the call site so a reader sees BOTH statements side by side (the real-DB suites are the oracle).
- *   - error classification: `ER_DUP_ENTRY`/errno 1062 vs SQLSTATE `23505`, and WHICH unique key
- *     collided (mysql2 `sqlMessage` text vs pg `err.constraint`) — those live with the store that
- *     needs them, because the discrimination rule is store-specific, not driver-generic.
+ *   - WHICH unique key collided (mysql2 `sqlMessage` text vs pg `err.constraint`) — that lives with
+ *     the store that needs it, because the attribution rule is store-specific, not driver-generic.
+ *     ⚠️ The dup-key predicate ITSELF is NOT store-specific and no longer lives at the call sites:
+ *     `sql-errors.ts` owns it (A-032 P1-①; 7+ hand-rolled copies had drifted into three different
+ *     recognition sets, so the same driver error got opposite verdicts in different stores).
  *   - per-query timeouts: mysql2 takes `{sql, timeout}` while node-pg takes a `QueryConfig` with
  *     `query_timeout`. The counter family (write-behind-counter.ts) needs those and keeps its own
  *     exec; this seam stays on the plain (sql, params) form.
@@ -58,8 +60,8 @@
  * WHAT MUST STAY EXPLICIT (never parameterized away)
  *   placeholders (?/$n) · upsert form (ON DUPLICATE vs ON CONFLICT) · JSON casts (CAST(? AS JSON) /
  *   $n::jsonb) · null-safe compare (<=> vs IS NOT DISTINCT FROM) AND its placeholder-arity fallout ·
- *   key-column byte semantics (VARBINARY vs COLLATE "C") · isolation/txn verbs · error classification
- *   (ER_DUP_ENTRY/errno vs SQLSTATE, sqlMessage vs err.constraint) · PG-only protocol-byte handling
+ *   key-column byte semantics (VARBINARY vs COLLATE "C") · isolation/txn verbs · dup-key ATTRIBUTION
+ *   (sqlMessage vs err.constraint; the dup-key predicate itself = `sql-errors.ts`) · PG-only protocol-byte handling
  *   (pgSafeJsonStringify / pgProtocolJsonStringify / pgSanitizeText / pgHasUnstorable) · DDL. Each arm's
  *   BEHAVIOR (what pgSafeJsonStringify/pgProtocolJsonStringify actually do to the bytes) stays written out
  *   in `pg-safe-json.ts`, untouched — `dialectJsonEncoder`/`dialectProtocolJsonEncoder` below (design/158

package/dist/plugins/sql-errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * SQL 驱动错误的**方言判别**——「这是不是唯一键冲突」的单一属主(A-032 P1-①,病族
+ * single-semantic-multi-site-drift)。`sql-escape.ts` / `sql-row-helpers.ts` / `store-contracts.ts`
+ * 的同级叶子:零 store 逻辑、零驱动依赖(不 import mysql2/pg),纯谓词。
+ *
+ * ## 为什么必须只有一份
+ * 收编前这条谓词在 src/ 手铸 ≥7 处,而且**识别集互相漂移**:一半站点只认 `code === "ER_DUP_ENTRY"`,
+ * 一半只认 `errno === 1062`,少数两者都认。同一个驱动错误因此在不同店里得到相反判决——漏判的代价
+ * 不是"少一句人话",而是 typed 契约错误(`checkpoint.already_exists` / `agent_record.already_exists` /
+ * `idempotency_conflict`)退化成**裸驱动错误对象**上抛,调用方按错误码分流的那条腿整条静默失效。
+ *
+ * ## 识别集 = 两个归因键的**并集**(刻意)
+ * mysql2 对同一条 `ER_DUP_ENTRY` 同时挂 `code`(errno 的字符串名)与 `errno`(数字),两者是**同一
+ * 件事的两种写法**,任一在场即可判定 —— 认并集不会造出假阳性,而认单键会漏掉任何只保留另一个键的
+ * 形(驱动版本差异、代理/包装层、序列化往返)。这正是收编前两个真漏判的成因,门钉在
+ * `test/sql-dup-key-single-source.test.ts`。
+ *
+ * ## 为什么是 `Reflect.get` 而不是属性访问/展开
+ * 驱动错误类在某些版本把这两个键挂在**原型链**上:`{...err}` 只拷自有可枚举键,会**静默**丢掉它们,
+ * 于是一次 dup 变成一个裸驱动对象漏给调用方。`Reflect.get` 与属性访问一样走原型链,写成 `Reflect.get`
+ * 是把"必须走原型链"这件事写在码面上(收编前唯一的硬化形 `shared-memory-store-sql.ts` 即此形)。
+ *
+ * ## 本模块**不**管的事(与 `sql-driver.ts` 头注的分工一致)
+ * 「撞的是**哪一个** UNIQUE 键」留在店内:mysql2 把键名写进 `sqlMessage` 文本、node-pg 写进
+ * `err.constraint`,而怎么按键名分诊(良性重发 vs 必须重试的竞态)是 store-specific 的判别规则,
+ * 不是驱动通用的。先例:`image-bake-store-sql.ts` 的 `dupKeyName`。
+ */
+import type { SqlDialect } from "./sql-driver.js";
+/** MySQL/TiDB `ER_DUP_ENTRY` 的数字 errno。 */
+export declare const MYSQL_ER_DUP_ENTRY_ERRNO = 1062;
+/** MySQL/TiDB `ER_DUP_ENTRY` 的字符串错误码(mysql2 的 `code`)。 */
+export declare const MYSQL_ER_DUP_ENTRY_CODE = "ER_DUP_ENTRY";
+/** PostgreSQL `unique_violation` 的 SQLSTATE。 */
+export declare const PG_UNIQUE_VIOLATION_SQLSTATE = "23505";
+/** MySQL/TiDB 的唯一键冲突:`code === "ER_DUP_ENTRY"` **或** `errno === 1062`(同一件事的两种写法)。 */
+export declare function isMysqlDupKeyError(err: unknown): boolean;
+/** PostgreSQL 的唯一键冲突:SQLSTATE `23505`(node-pg 挂在 `code` 上)。 */
+export declare function isPgUniqueViolation(err: unknown): boolean;
+/** 方言分派口——双方言店的调用形(`isDupKeyError(this.db.dialect, e)`)。 */
+export declare function isDupKeyError(dialect: SqlDialect, err: unknown): boolean;
+//# sourceMappingURL=sql-errors.d.ts.map

package/dist/plugins/sql-errors.js

@@ -0,0 +1,25 @@
+/** MySQL/TiDB `ER_DUP_ENTRY` 的数字 errno。 */
+export const MYSQL_ER_DUP_ENTRY_ERRNO = 1062;
+/** MySQL/TiDB `ER_DUP_ENTRY` 的字符串错误码(mysql2 的 `code`)。 */
+export const MYSQL_ER_DUP_ENTRY_CODE = "ER_DUP_ENTRY";
+/** PostgreSQL `unique_violation` 的 SQLSTATE。 */
+export const PG_UNIQUE_VIOLATION_SQLSTATE = "23505";
+/** 非对象(null / undefined / 字符串 / 数字)一律否——谓词自身绝不成为新的失败源。 */
+function keyOf(err, key) {
+    if (err === null || typeof err !== "object")
+        return undefined;
+    return Reflect.get(err, key);
+}
+/** MySQL/TiDB 的唯一键冲突:`code === "ER_DUP_ENTRY"` **或** `errno === 1062`(同一件事的两种写法)。 */
+export function isMysqlDupKeyError(err) {
+    return String(keyOf(err, "code")) === MYSQL_ER_DUP_ENTRY_CODE || Number(keyOf(err, "errno")) === MYSQL_ER_DUP_ENTRY_ERRNO;
+}
+/** PostgreSQL 的唯一键冲突:SQLSTATE `23505`(node-pg 挂在 `code` 上)。 */
+export function isPgUniqueViolation(err) {
+    return String(keyOf(err, "code")) === PG_UNIQUE_VIOLATION_SQLSTATE;
+}
+/** 方言分派口——双方言店的调用形(`isDupKeyError(this.db.dialect, e)`)。 */
+export function isDupKeyError(dialect, err) {
+    return dialect === "tidb" ? isMysqlDupKeyError(err) : isPgUniqueViolation(err);
+}
+//# sourceMappingURL=sql-errors.js.map

package/dist/plugins/tidb-session-storage.js

@@ -1,9 +1,9 @@
 import { emitLeafAdvance } from "../session-leaf-bus.js";
 import { BaseSessionStorage, SessionError, leafIdAfterEntry, normalizePromptEpoch, } from "@sema-agent/core";
 import { toIso } from "./sql-row-helpers.js";
-function isDupKey(err) {
-    return Boolean(err) && err.code === "ER_DUP_ENTRY";
-}
+import { isMysqlDupKeyError } from "./sql-errors.js";
+/** 判据属主 = `sql-errors.ts`(A-032 P1-①;旧形只认 `code`,只带 errno 的驱动错误漏判)。 */
+const isDupKey = isMysqlDupKeyError;
 /**
  * TiDB-backed {@link BaseSessionStorage} — the durable L1 event log for one session.
  *

package/dist/plugins/workflow-run-store-sql.js

@@ -1,6 +1,7 @@
 import { summarizeWorkflowRun, isTerminalWorkflowStatus, WorkflowRunStoreError } from "@sema-agent/core";
 import { foldKeyFamily, MAX_PENDING_PER_SESSION, PURGE_FENCE_MS, SERVED_FENCE_MS, } from "../orchestration/workflow-completion-inbox.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
+import { isDupKeyError } from "./sql-errors.js";
 /** Row cap guard: a run blob beyond this is NOT stored on update (the prior revision stays) — TiDB's
  *  ~6 MiB txn-entry limit would otherwise throw the (best-effort) progress write into the workflow loop.
  *  `put` (create, small) still throws on a real failure. Mirrors the journal's oversize skip-degrade. */
@@ -49,10 +50,9 @@ export class SqlWorkflowRunStore {
             await this.db.query(this.q("INSERT INTO workflow_run (id, scope, status, run, rev, created_at_ms, ended_at_ms) VALUES (?,?,?,?,?,?,?)", "INSERT INTO workflow_run (id, scope, status, run, rev, created_at_ms, ended_at_ms) VALUES ($1,$2,$3,$4,$5,$6,$7)"), [id, run.scope, run.status, JSON.stringify(stored), stored.rev, run.createdAt, run.endedAt ?? null]);
         }
         catch (e) {
-            // create-once error every backend throws (contract) — dup-key classification is dialect-specific:
-            // TiDB's errno-string ER_DUP_ENTRY vs PG's SQLSTATE 23505.
-            const isDupKey = this.db.dialect === "tidb" ? e.code === "ER_DUP_ENTRY" : e.code === "23505";
-            if (isDupKey) {
+            // create-once error every backend throws (contract) — the dialect classification has a single
+            // owner (`sql-errors.ts`, A-032 P1-①); the old local form read only mysql2's string `code`.
+            if (isDupKeyError(this.db.dialect, e)) {
                 throw new WorkflowRunStoreError("workflow_run.already_exists", "workflow run id already exists");
             }
             throw e;

package/dist/run-local.js

@@ -72,6 +72,7 @@ import { memoryEngineBackendFor, memorySpecForRequest } from "./memory-scope.js"
 import { createMemorySyncRunner, createMemorySyncTransport } from "./memory-sync-client.js";
 import { buildPricing, cappedCeiling, createTracer } from "./budget.js";
 import { createSharedRunnerDeps } from "./boot/runner-deps.js";
+import { createGovernanceSeams } from "./boot/governance-seams.js";
 import { createOrgMemoryAdmissionWiring } from "./boot/org-memory.js";
 import { createPermissionDeniedMeter } from "./observability/tool-trace.js";
 import { createKeyResolver } from "./key-resolver.js";
@@ -580,8 +581,22 @@ export async function runLocal(argv, deps = {}) {
      *  · `sharedMemoryStores`:**undefined** —— 供给面只有 SQL 形(`store-backend.ts` 明写:单机造 file 形
      *    等于给一个人的部署做「团队共享」,能力面会因此说谎)。
      */
+    // design/170 件B/C/D(#252):三个部署治理座席 —— 本地形与 server 形**同一只装配口**。为什么本地形也要
+    // 有:`COMPLIANCE_PROFILE` / `LOCKED_CONFIG_KEYS` / `RETENTION_MAX_AGE_DAYS` 是从同一份本地 `.env` 读出来
+    // 的,一个写下了档位的用户在 `sema` 与本机 HTTP 服务上必须得到同一个答案(两条腿对同一份配置两套行为
+    // 正是本仓在册的病族)。三键未配 = 三座席缺席 = 本腿逐字零变化。
+    const governanceSeams = createGovernanceSeams({
+        config,
+        logger,
+        retentionStores: [
+            { name: "sessionStore", store: sessionStore },
+            { name: "checkpointStore", store: fileBackend.checkpointStore },
+            { name: "toolResultStore", store: fileBackend.toolResultStore },
+        ],
+    });
     const sharedRunnerDeps = createSharedRunnerDeps({
         config,
+        governanceSeams,
         logger, // #240②:onNotice 席(共享基座键,本地形同席——结构化通告落同一 logger)
         // 交接件⑤:commit 尾注署名座进**共享基座** ⇒ 主 runner 与 subRunner 同源。
         // [931]① clay 拍:run-local = Sema 品牌本地形态,commit 尾注接 Sema 署名(core 1.300 缺省已翻转不署)。

package/dist/runs.js

@@ -555,40 +555,6 @@ approval) {
         // Thread the owning principal so the cost tracer attributes this run's spend (incl. council/team
         // sub-tasks) to the principal's cumulative quota — mirrors the synchronous path.
         const runBody = async () => {
-            if (verify !== undefined) {
-                // Developer-mode verification gate (1.44): multi-round (impl → adversarial verify → fix loop), not
-                // a stream — await the result and persist it terminal. The durable event log gets just the `done`
-                // (the verifier subtask runs on its own session). `result.verification` carries the verdict.
-                const result = await runWithVerification(runner, { ...spec, taskId, signal: cancelCtrl.signal }, verify);
-                await flush();
-                evictIfConflict(runner, spec.sessionId, result);
-                // A nested suspend under the verify gate is mapped by core to status:"failed" carrying the capability
-                // token — strip it before it touches the replayable log / run row (search [18] Q1b).
-                await flushPromptManifest(); // [998]②: the verify leg has no stream — persist the manifest before the terminal
-                const safe = await withModelUsage(stripCheckpointToken(result)); // E8: attach stats.modelUsage at terminal
-                await append("done", { result: safe });
-                reached = { kind: "done", result: safe };
-                await runStore.setTerminal(taskId, safe.status, safe, safe.errorMessage ?? null);
-                recordDone(safe, safe.status);
-                return;
-            }
-            if (cascade !== undefined) {
-                // Cascade (1.45): cheap→strong ladder; multi-attempt cold re-runs, not a stream. Persist terminal.
-                const result = await runCascade(runner, { ...spec, taskId, signal: cancelCtrl.signal }, cascade);
-                await flush();
-                evictIfConflict(runner, spec.sessionId, result);
-                await flushPromptManifest(); // [998]②: same no-stream posture as the verify leg above
-                const safe = await withModelUsage(stripCheckpointToken(result)); // see the verify branch; E8 modelUsage at terminal
-                await append("done", { result: safe });
-                reached = { kind: "done", result: safe };
-                await runStore.setTerminal(taskId, safe.status, safe, safe.errorMessage ?? null);
-                recordDone(safe, safe.status);
-                return;
-            }
-            // design/47 (mid-task steering): hold the live stream handle so POST /v1/runs/:id/steer can inject a steer via
-            // stream.steer() (drained at the next turn boundary). Only this plain-stream path is steerable — the verify/
-            // cascade branches above return a result, not a stream (parity with the preemptable registration). Deregistered
-            // in `finally`. Registering it AFTER the verify/cascade early-returns means those legs never enter the map.
             // core 1.154 nested-subagent live tree: opt into the forward sink — a subagent's task_progress lives in the
             // child run's ISOLATED stream (core's only emitter is parentToolCallId-gated and pushes onto the CHILD queue;
             // the top stream NEVER carries it), so this sink is the ONLY path a tick reaches the top-run consumers. 1.78
@@ -596,21 +562,52 @@ approval) {
             // forget — `++seq` is a sync increment so sink-vs-loop appends get unique seqs), not just the fleet bus —
             // previously no fleet bus wired ⇒ ticks dropped entirely, and the stream-switch task_progress case below was
             // forward-compat then — [2373]B-4:floor ^4.0.0 下它是热路径(腐注方向已翻转,勿按旧注当死支)。core swallow-guards a throwing sink.
+            // [3911] 定谳:per-agent tail 的**内容帧供给**由本腿 spec 的 forwardSubagentEvents 决定(core
+            // prepare-task 的 forward 门);缺席 ⇒ 那条流恒只有 task_progress。逐帧按**句柄**登记本腿的供给形,
+            // 让 tail 的 meta 帧如实声明(键为什么必须是句柄:SubagentTailBus.modeByHandle 顶注)。
+            //
+            // 🔴 **#253(core 5.33.0 #246 提货)起,这只 internals 在 verify/cascade 早返分支之前铸**:三条腿
+            // (verify 形 / cascade 形 / 普通流形)用**同一只**对象。5.32 及以前 core 的 `runWithVerification` /
+            // `runCascade` 签名里根本没有这一位,那两条腿因此对子代进度、活性打点、bg 终态通知**全盲**;5.33.0
+            // 开了尾可选 `internals` 座位并逐字转发给它驱动的每一条腿(实现腿/验证器腿/修复腿/每一级 rung),
+            // 于是这里只需要把既有供给链**接上去**,不新铸第二条链(黑盒判据见
+            // `test/issue190-status-wire-disclosure.test.ts` §4)。
+            // ⚠️ **`isolation` 一位永不传**:core 对 `internals.isolation` 在 verify/cascade 门上双相位响亮拒
+            // (`config.verify_internals_invalid` —— 这道门一次跑好几条腿,而 isolation 是 per-run 铸工作区),
+            // 本仓从不铸这一位,座位对象里也不许出现它。
+            const tailContentMode = spec.forwardSubagentEvents === true ? "on" : "progress_only";
             const fwdInternals = {
+                // #253:活性打点 —— 「只回结果」形没有事件循环,`recordTurnActivity` 此前只挂在 LedgerSink 的
+                // append 链上(那条链在 verify/cascade 腿上整段任务只响一次:终局 done)。core 的 onActivity 在
+                // 每次工具 start/end 同步回调,于是一条长跑的 verify 腿不再被 `GET /v1/runs/:id` 的
+                // `msSinceLastActivity` / 409 冲突体读成僵死。普通流形不经它(那条腿的打点在 sink 里,同一个函数,
+                // 重复打点无害但也无必要——本键对三腿一律在场,少一条判别分支)。
+                onActivity: () => recordTurnActivity(taskId),
                 onForwardEvent: (e) => {
                     fleetPublisher?.onForwardEvent(e);
                     // C1 (core 1.219): a delegated child's tool lifecycle + task_progress ticks persist through the SHARED
                     // sink (same whitelist+redact builders as the top stream — §E1, forwarded events are UNTRUSTED RAW;
                     // fire-and-forget with sync seq allocation). Rationale + the deliberate per-chunk-delta omission live
                     // on LedgerSink.onForwardEvent.
+                    //
+                    // 🔴 **别在这里加「腿结束就不落账」的围栏**(#253 施工期实测:加了当场打红 `runs-coverage` 的
+                    // [1840]§三定性钉)。那条钉是**取证结论**,不是习惯:`run_in_background` 收养形子代的**整个**
+                    // 生命周期都在父 run 终态之后,live events 流按设计 terminal break —— 帧照落账,消费端 done 后
+                    // 重拉即全见。撕掉 sink = 对那一族子代**真丢帧**(cli [1839] 轮②「子代内层零转发」的病因分析里
+                    // 写死了这一条)。codex 对抗复审 R2 [medium] 提的正是「终局后不该再落行」,**验真后驳回**:
+                    // 本仓已有属主裁定 + 复现器 + 防回归钉,不能因为一次静态复审把它反过来。
                     sink.onForwardEvent(e);
                     // S2 live tail(core 1.370 bgAgentId,[1520]{core}):bg 子代帧按句柄分发给 per-agent 订阅者
                     // (sync 腿 twin 在 http/server.ts)。hasSubscribers 快门=没人听不投影;投影一次 N 订阅者共享。
                     const bg = e.bgAgentId;
-                    if (bg !== undefined && defaultSubagentTailBus.hasSubscribers(bg)) {
-                        const f = projectTailFrame(e);
-                        if (f)
-                            defaultSubagentTailBus.publish(bg, f);
+                    if (bg !== undefined) {
+                        // 供给形登记在 hasSubscribers 快门**之前**:没人在听时也要学,否则晚开的 tail 读不到。
+                        defaultSubagentTailBus.noteHandleContentMode(bg, tailContentMode);
+                        if (defaultSubagentTailBus.hasSubscribers(bg)) {
+                            const f = projectTailFrame(e);
+                            if (f)
+                                defaultSubagentTailBus.publish(bg, f);
+                        }
                     }
                 },
                 // (durable half is the deployment's job): observe EVERY background
@@ -631,6 +628,9 @@ approval) {
                     if (n.task_type === "workflow")
                         return;
                     // S2 复审 #3(sync 腿同注):中途终态信号。
+                    // [3911] 终态即撤供给形登记:同一 a* 句柄可进入下一个**复活周期**,而新周期的宿主腿模式
+                    // 可能相反——不撤会把上一周期的答案报给新周期的首帧前窗口(理由全文见 forgetHandleContentMode)。
+                    defaultSubagentTailBus.forgetHandleContentMode(n.task_id);
                     if (defaultSubagentTailBus.hasSubscribers(n.task_id)) {
                         defaultSubagentTailBus.publish(n.task_id, { type: "task_settled", taskId: n.task_id, status: n.status, ...(typeof n.seq === "number" ? { seq: n.seq } : {}), ...(n.summary ? { summary: redactSecrets(n.summary) } : {}) });
                     }
@@ -678,6 +678,44 @@ approval) {
                     }
                     : {}),
             };
+            if (verify !== undefined) {
+                // Developer-mode verification gate (1.44): multi-round (impl → adversarial verify → fix loop), not
+                // a stream — await the result and persist it terminal. The durable event log gets just the `done`
+                // (the verifier subtask runs on its own session). `result.verification` carries the verdict.
+                // #253(core 5.33.0 #246):第 4 位 = 供给座席,core 逐字转发给实现腿 + 验证器腿 + 每一轮修复腿。
+                const result = await runWithVerification(runner, { ...spec, taskId, signal: cancelCtrl.signal }, verify, fwdInternals);
+                await flush();
+                evictIfConflict(runner, spec.sessionId, result);
+                // A nested suspend under the verify gate is mapped by core to status:"failed" carrying the capability
+                // token — strip it before it touches the replayable log / run row (search [18] Q1b).
+                await flushPromptManifest(); // [998]②: the verify leg has no stream — persist the manifest before the terminal
+                const safe = await withModelUsage(stripCheckpointToken(result)); // E8: attach stats.modelUsage at terminal
+                await append("done", { result: safe });
+                reached = { kind: "done", result: safe };
+                await runStore.setTerminal(taskId, safe.status, safe, safe.errorMessage ?? null);
+                recordDone(safe, safe.status);
+                return;
+            }
+            if (cascade !== undefined) {
+                // Cascade (1.45): cheap→strong ladder; multi-attempt cold re-runs, not a stream. Persist terminal.
+                // #253(core 5.33.0 #246):第 4 位 = 供给座席,core 逐字转发给**每一级 rung**(顺序跑,一只 sink
+                // 按梯序拼接收到各级的帧 —— core 的 ATTRIBUTION 注写明 ToolActivity 自身不带 rung 身份)。
+                const result = await runCascade(runner, { ...spec, taskId, signal: cancelCtrl.signal }, cascade, fwdInternals);
+                await flush();
+                evictIfConflict(runner, spec.sessionId, result);
+                await flushPromptManifest(); // [998]②: same no-stream posture as the verify leg above
+                const safe = await withModelUsage(stripCheckpointToken(result)); // see the verify branch; E8 modelUsage at terminal
+                await append("done", { result: safe });
+                reached = { kind: "done", result: safe };
+                await runStore.setTerminal(taskId, safe.status, safe, safe.errorMessage ?? null);
+                recordDone(safe, safe.status);
+                return;
+            }
+            // design/47 (mid-task steering): hold the live stream handle so POST /v1/runs/:id/steer can inject a steer via
+            // stream.steer() (drained at the next turn boundary). Only this plain-stream path is steerable — the verify/
+            // cascade branches above return a result, not a stream (parity with the preemptable registration). Deregistered
+            // in `finally`. Registering it AFTER the verify/cascade early-returns means those legs never enter the map.
+            // (供给座席 `fwdInternals` 已在本函数顶部铸好并被三条腿共用 —— 见那里的顶注。)
             const stream = runner.runTaskStream({ ...spec, taskId, signal: cancelCtrl.signal, preemptSignal: preemptCtrl.signal }, undefined, fwdInternals);
             steerableStreamRef = stream; // held for the finally's identity-guarded delete (1.78 review LOW)
             steerable?.set(taskId, stream);

package/dist/task-mcp.d.ts

@@ -22,7 +22,7 @@
  *     `runtimeCapsResolver`) is a DEFERRED v2.
  * When the gate is closed, a sent `mcpServers` is IGNORED (advertised via `capabilities.mcpInjection`).
  */
-import type { McpServerSpec } from "@sema-agent/core";
+import { type CompliancePosture, type LockedKey, type McpServerSpec } from "@sema-agent/core";
 /** Bound on caller-supplied servers (anti-DoS; a real local `.mcp.json` has a handful). */
 export declare const MAX_REQUEST_MCP_SERVERS = 32;
 /**
@@ -34,6 +34,8 @@ export declare const MAX_REQUEST_MCP_SERVERS = 32;
  */
 export declare function mcpInjectionHonored(config: {
     requirePrincipal?: boolean;
+    lockedConfigKeys?: readonly LockedKey[];
+    compliancePosture?: CompliancePosture;
 }): boolean;
 /**
  * Shape-check the raw `body.mcpServers`. `null` → a non-array (caller error; the route may 400). Otherwise the
@@ -43,6 +45,24 @@ export declare function validateRequestMcp(raw: unknown): {
     ok: McpServerSpec[];
     dropped: string[];
 } | null;
+/**
+ * design/170 件C §4.3 —— **同步**拒面:部署锁了 `mcp` 而请求仍带 `mcpServers` ⇒ 400 `config.locked_key`。
+ *
+ * 为什么在这里也拒一次(与 core 的 prepare 门不是「两处裁决」):设计稿把裁决点定在 server 治理层,
+ * core 的 preflight 执行的是**同一条**判据的引擎侧终局形。二者语义等价、位置不同 —— 一个请求根本不该
+ * 进 core 才发现自己被锁,而消费端拿到一条同步 4xx 比拿到一个跑起来又终态失败的任务可诊断得多。
+ *
+ * 判据是「请求**占位**」而不是「请求的值合不合法」:锁是两态的,占了就整拒,不静默丢(静默丢正是
+ * design/170 §2.3 讲的那种把判决变成探针的形)。键缺席 / 显式 `null` 都不是占位。
+ *
+ * ⚠️ **不看车道**:多租户腿本来就会忽略 body MCP(`mcpInjectionHonored` 关),但锁在场时忽略是错的
+ * 失败方向 —— operator 声明了「本部署不收任务自带 MCP」,那就该说出来,而不是安静地当没看见。
+ *
+ * ⚠️ **resume 腿同拒,这是刻意的**(与本仓「4xx 会砖存量 task」的一般姿势有意分歧):锁上之后,一条存量
+ * 任务的 body 里带着 mcpServers 就再也过不了 core 的 preflight —— 放它进去只会换来一个跑起来又终态失败的
+ * 任务。同样是失败,同步 400 至少是**立刻可诊断**的那一种,而且拒得出理由(锁在哪、怎么改)。
+ */
+export declare function assertRequestMcpUnlocked(bodyMcp: unknown, lockedKeys: ReadonlySet<LockedKey>): void;
 /**
  * Merge GATED per-request MCP servers OVER the deployment baseline (center/config). The baseline WINS on a name
  * clash — a caller can ADD servers but can never SHADOW a configured one (the security baseline is authoritative,
@@ -60,6 +80,7 @@ export declare function resolveRequestMcp(baseline: McpServerSpec[] | undefined,
         provider?: string;
     };
     requirePrincipal?: boolean;
+    lockedConfigKeys?: readonly LockedKey[];
 }, logger?: {
     info?(m: string, meta?: unknown): void;
     warn(m: string, meta?: unknown): void;

package/dist/task-mcp.js

@@ -1,3 +1,29 @@
+/**
+ * [TOC MCP seam, R3] — project the TOC client's local
+ * `.mcp.json` (`TaskRequest.mcpServers`) into the engine, so a `sema` run honors the user's own MCP servers
+ * (CC-parity "配置即用" local-first), instead of ONLY the center-config MCP. Mirrors the `cwd` seam (task-cwd.ts).
+ *
+ * 🔒 SECURITY — per-request MCP is the constitutional "untrusted-client tool injection" red line, because an MCP
+ * server is a TOOL SOURCE and an stdio transport is **arbitrary command execution**. The decisive fact (verified):
+ * core materializes stdio MCP with `StdioClientTransport`, which spawns the command as a child of **the WORKER
+ * (core's process), NOT the execution env** — so an stdio MCP runs on the worker host REGARDLESS of the exec lane
+ * (host/e2b/docker). Therefore the trust boundary is NOT "the host execution lane" (that's where the agent's TOOL
+ * CALLS run, irrelevant to MCP) — it is **"is the worker single-user, i.e. is the requester the super-admin?"** =
+ * `requirePrincipal !== true`. core's ruling (R3): the SERVICE is core's caller-trust-root; body→`TaskSpec.mcp` is a
+ * trust decision the service makes, never a passthrough.
+ *   - SINGLE-USER deployment (`requirePrincipal===false`): the requester IS the super-admin of their own worker, so
+ *     their `.mcp.json` is authoritative — exactly what CC does on the user's machine. This holds across EVERY
+ *     execution lane (host / E2B / k8s / local-docker), so a TOC user who switches execution local↔cloud keeps their
+ *     MCP honored seamlessly (TOC↔cloud is a spectrum, not a wall — clay 2026-06-29: TOB = single-user + people-mgmt).
+ *     The caller being the trust root, `toolAxes` (authoritative effect overrides) + `elicitation` are their own choices.
+ *   - MULTI-TENANT deployment (`requirePrincipal===true`): a tenant must NOT make the SHARED worker run an arbitrary
+ *     command (RCE) or connect to a body-chosen URL (SSRF). Gate CLOSED → body MCP ignored; the fleet gets MCP only
+ *     through center config refs. Per-principal http-remote injection (a center `allowMcpInjection` entitlement via
+ *     `runtimeCapsResolver`) is a DEFERRED v2.
+ * When the gate is closed, a sent `mcpServers` is IGNORED (advertised via `capabilities.mcpInjection`).
+ */
+import { resolveComplianceDenies } from "@sema-agent/core";
+import { HttpError } from "./security.js";
 /** Bound on caller-supplied servers (anti-DoS; a real local `.mcp.json` has a handful). */
 export const MAX_REQUEST_MCP_SERVERS = 32;
 /**
@@ -8,6 +34,21 @@ export const MAX_REQUEST_MCP_SERVERS = 32;
  * run an arbitrary command / connect to an arbitrary URL).
  */
 export function mcpInjectionHonored(config) {
+    // design/170 件C(codex 对抗复审 F2,验真后采纳):**锁也是这条轴的一票否决**。旧谓词只看租户轴,
+    // 于是「单用户 + `mcp` 锁」的部署会广告 `mcpInjection:true`,而每一个照此渲出 affordance 的调用方发过
+    // 来都吃 `config.locked_key` 400 —— 本仓 capabilities 面的立面承诺(「says yes ⟺ route works」)当场破。
+    // 判据合取在这里而不是在能力位那行,是因为这只谓词是**唯一**属主(能力位与请求腿都读它)。
+    if (config.lockedConfigKeys?.includes("mcp") === true)
+        return false;
+    // 件B 同族(R2-F2):合规档位禁了 `mcp_servers` 时,core 对**带 spec.mcp 的每一条腿**整拒 prepare
+    // (`config.compliance_denied`,亲核 prepare-task 的 compliance 段)。同样是「广告了却用不了」,同样一票否决。
+    //
+    // ⚠️ **刻意不 catch**(#191 门② SHAPE C 当场逮到的那一版已撤):`resolveComplianceDenies` 对闭集外的值
+    // 是 fail-loud 的,而这个档位在到这里之前已经被验过两遍(config 解析层 + boot 装配层),所以它在本站点
+    // 抛不出来。真抛了 = 有人绕过那两道门往 config 里塞了一个解析不了的档位 —— 那种时候**响亮**(路由 500)
+    // 才是对的方向,吞成一个布尔位等于让一台档位坏掉的部署继续对外广告能力位(安全轴禁静默兜底)。
+    if (config.compliancePosture !== undefined && resolveComplianceDenies(config.compliancePosture).has("mcp_servers"))
+        return false;
     return config.requirePrincipal !== true;
 }
 function isStringRecord(v) {
@@ -99,6 +140,32 @@ export function validateRequestMcp(raw) {
         dropped.push(`(+${raw.length - MAX_REQUEST_MCP_SERVERS} over cap of ${MAX_REQUEST_MCP_SERVERS})`);
     return { ok, dropped };
 }
+/**
+ * design/170 件C §4.3 —— **同步**拒面:部署锁了 `mcp` 而请求仍带 `mcpServers` ⇒ 400 `config.locked_key`。
+ *
+ * 为什么在这里也拒一次(与 core 的 prepare 门不是「两处裁决」):设计稿把裁决点定在 server 治理层,
+ * core 的 preflight 执行的是**同一条**判据的引擎侧终局形。二者语义等价、位置不同 —— 一个请求根本不该
+ * 进 core 才发现自己被锁,而消费端拿到一条同步 4xx 比拿到一个跑起来又终态失败的任务可诊断得多。
+ *
+ * 判据是「请求**占位**」而不是「请求的值合不合法」:锁是两态的,占了就整拒,不静默丢(静默丢正是
+ * design/170 §2.3 讲的那种把判决变成探针的形)。键缺席 / 显式 `null` 都不是占位。
+ *
+ * ⚠️ **不看车道**:多租户腿本来就会忽略 body MCP(`mcpInjectionHonored` 关),但锁在场时忽略是错的
+ * 失败方向 —— operator 声明了「本部署不收任务自带 MCP」,那就该说出来,而不是安静地当没看见。
+ *
+ * ⚠️ **resume 腿同拒,这是刻意的**(与本仓「4xx 会砖存量 task」的一般姿势有意分歧):锁上之后,一条存量
+ * 任务的 body 里带着 mcpServers 就再也过不了 core 的 preflight —— 放它进去只会换来一个跑起来又终态失败的
+ * 任务。同样是失败,同步 400 至少是**立刻可诊断**的那一种,而且拒得出理由(锁在哪、怎么改)。
+ */
+export function assertRequestMcpUnlocked(bodyMcp, lockedKeys) {
+    if (!lockedKeys.has("mcp"))
+        return;
+    if (bodyMcp === undefined || bodyMcp === null)
+        return;
+    throw new HttpError(400, "`mcpServers` is administratively locked by this deployment (locked key \"mcp\") — task-supplied MCP servers are refused; locks are config-time and there is no request-time unlock", {
+        code: "config.locked_key",
+    });
+}
 /**
  * Merge GATED per-request MCP servers OVER the deployment baseline (center/config). The baseline WINS on a name
  * clash — a caller can ADD servers but can never SHADOW a configured one (the security baseline is authoritative,
@@ -117,7 +184,10 @@ export function mergeRequestMcp(baseline, gated) {
  * unchanged. Logs an `mcp_injection_ignored` when a caller SENT servers a closed gate dropped (so the shell never
  * silently believes its `.mcp.json` took effect — it also reads `capabilities.mcpInjection`).
  */
-export function resolveRequestMcp(baseline, bodyMcp, config, logger) {
+export function resolveRequestMcp(baseline, bodyMcp, 
+// `lockedConfigKeys` 随 config 一并进(design/170 件C):`assertRequestMcpUnlocked` 已在腿首整拒,所以
+// 这里的 honored 判据在锁形下不可达 —— 保留它是纵深(判据只有一只谓词,不许两处各判一半)。
+config, logger) {
     if (bodyMcp === undefined || bodyMcp === null)
         return baseline;
     const honored = mcpInjectionHonored(config);