@sema-agent/server 7.132.0 → 7.133.0

package/dist/security.d.ts

@@ -1,10 +1,11 @@
 import type { IncomingMessage } from "node:http";
-import { type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
+import { type SessionPlacementRecord, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
 import type { TaskRequestBody } from "./http/wire-types.js";
 import type { StagingHandle } from "./session-sync-kernel.js";
 import type { SessionFace, SessionFaceReader } from "./session-incarnation.js";
 import type { SessionRowPatch } from "./session-row.js";
+import { type OwnerlessClaim } from "./delegated-session-owner.js";
 /** One row of the session-list projection (CC /resume picker) — the durable session abstraction's enumeration
  *  output (§0.5). Mirrors {@link RunStore}'s shipped `SessionSummary` shape so the wire response is unchanged. */
 export interface SessionListItem {
@@ -51,6 +52,54 @@ export interface SessionListItem {
  * 不含读面,也不含 `POST /v1/tasks` 那条提交腿 —— 它有自己的同族门(别重复拦,双拦会让错误归因变糊)。
  */
 export declare function isDestructiveSessionWrite(method: string, url: string): boolean;
+declare const principalBrand: unique symbol;
+declare const durableOwnerKeyBrand: unique symbol;
+/**
+ * 🔴 **两个 owner 不是同一个东西**(S-487 RH-3,类型事实):
+ *  · {@link Principal} —— **这次请求**验过的调用方身份。铸点闭集:`http/principal-gate.ts` 的 `gatedPrincipal`(验身份的那一只),以及属主存取器
+ *    (`http/owner-access.ts`)里一只「上游已验」的适配口(调用方身份经一只纯串结构转手过来的腿 —— 第二期随那只结构带品牌而删);
+ *  · {@link DurableOwnerKey} —— **行上 / 存储键里**落下的属主(run 行、会话行的 `owner` 列)。铸点闭集:属主存取器读行处与 {@link sessionOwnerCellOf}。
+ * 两者互不可赋、裸 `string` 两者都不可赋;「这个调用方读得到这一行吗」的判官(`runOwnerReadable`)签名两参各带一个品牌,对调即编译红。
+ * 铸点按文件计数钉在 `test/owner-gate-single-owner.test.ts` 的品牌铸点普查格里:多一处铸点 = 门红。
+ */
+export type Principal = string & {
+    readonly [principalBrand]: true;
+};
+export type DurableOwnerKey = string & {
+    readonly [durableOwnerKeyBrand]: true;
+};
+/** {@link Principal} 的铸造口(只在铸点闭集里调,见上)。 */
+export declare function mintPrincipal(verified: string): Principal;
+/** {@link DurableOwnerKey} 的铸造口(只在铸点闭集里调,见上)。 */
+export declare function mintDurableOwnerKey(persisted: string): DurableOwnerKey;
+/**
+ * 会话行属主门读的那一格(S-1770):有主的行只有属主;**无主的行**另带「它是不是委派子代的 placed 行」(店的 `placementOf` 答,{@link sessionOwnerCellOf} 读;
+ * 不实现 placement 的店没有 placed 行)。`placed` 只在无主时存在 —— 有主的行属主门不看它。
+ */
+export type SessionOwnerCell = {
+    readonly owner: DurableOwnerKey;
+} | {
+    readonly owner: null;
+    readonly placed: boolean;
+};
+/** 会话行属主门的调用方:验过的主体(`gatedPrincipal`)+ 它是不是 **fleet 调用方**(dev-open 部署上的任何调用方,或出示了这台部署的 service 凭据、
+ *  不报主体的调用方)。唯一铸点 `http/principal-gate.ts` 的 `sessionCallerOf`。 */
+export interface SessionCaller {
+    readonly principal: Principal | undefined;
+    readonly fleet: boolean;
+}
+/**
+ * 🔴 **会话行属主门上「无主行放行」臂的唯一判据**(S-1770 读面律;会话面谓词 `sessionOwnerReadable`、fork / 删除的存量互认臂 {@link legacyUnownedSessionOk}、
+ * 审批豁免面、notify 面的无主臂都经它,不各写一份):
+ *  · 无主的**普通**会话行 ⇒ 成立(各臂照它自己的其余条件);
+ *  · 无主的 **placed** 行(委派子代:属主 = 委派树根的属主,`delegated-session-owner.ts`)⇒ 只对 **fleet 调用方**成立({@link SessionCaller}:dev-open 部署上的任何调用方,
+ *    或出示了 service 凭据、不报主体的调用方 —— 只配 token 的单用户部署、BFF 的系统调用)。任何具名主体(含经 BFF 代发的)与没有 service 凭据的无身份调用方都不成立:
+ *    这一行要么属于一棵无身份调用方的树,要么属主还没定下(升级前写下、回填还没判出 / 判断时来源还没有属主)—— 后者把它当公共行,就是把别人那棵树的子代转录交给拿到 id 的人。
+ *  · 有主的行 ⇒ 不在本臂。
+ */
+export declare function ownerlessRowOpen(cell: SessionOwnerCell, caller: SessionCaller): boolean;
+/** 读一只会话行的 {@link SessionOwnerCell}:无主时问一次店的 `placementOf`(既有读口;店不交它 = 不实现 placement = 没有 placed 行)。`owner` = 调用点那一读。 */
+export declare function sessionOwnerCellOf(store: Pick<OwnerAwareSessionStore, "placementOf"> | undefined, sessionId: string, owner: string | null): Promise<SessionOwnerCell>;
 /** [ref] 窄互认第二臂的租户键字面量 —— 单机形下 core 写侧 `spec.principal ?? "default"` 铸出的那一个,
  *  也是壳 [ref]G1 翻面后随请求带的那一个。**不是哨兵**([ref] 措辞):它是单机形的真租户键。 */
 export declare const LEGACY_UNOWNED_AMNESTY_TENANT = "default";
@@ -66,7 +115,7 @@ export declare const LEGACY_UNOWNED_AMNESTY_TENANT = "default";
  *
  * 🔒 **三条件缺一不放行**(与第一臂同源,不是兼容臂):
  *   ① 单机形 `!requirePrincipal` —— 多租部署本臂**死路**(header 必到、键必具名);
- *   ② 存量行恰为无主 `owner === null` —— 任何具名 owner 的行不受影响;
+ *   ② 存量行恰为无主 `owner === null`、且不是委派子代的 placed 行(无主臂的唯一判据 {@link ownerlessRowOpen})—— 任何具名 owner 的行不受影响;
  *   ③ 调用方恰为 `default` 主 —— 非 default 的具名主对无主行仍走原门(404 / deleted:false)。
  * 反向风险有界:①限定的单机形本就单用户,把无主行判给 default 主不产生跨租外泄。
  *
@@ -87,10 +136,10 @@ export declare const LEGACY_UNOWNED_AMNESTY_TENANT = "default";
  *    写面族超出裁定射程 —— 要做另立一次表态,不在本臂里顺手带过。
  *
  * @param requirePrincipal `config.requirePrincipal`(条件①)
- * @param gateOwner `sessionOwnerScope(ForWrite)` 判出的**已验证**主(条件③;fleet-wide 面不经本臂)
- * @param owner 存量行的 owner 列(条件②)
+ * @param caller 调用方(条件③ 读它验过的主体;fleet-wide 面不经本臂)
+ * @param cell 存量行那一格(条件②:无主,且经无主臂的唯一判据 {@link ownerlessRowOpen} —— 无主的委派子代 placed 行不在本臂,S-1770)
  */
-export declare function legacyUnownedSessionOk(requirePrincipal: boolean, gateOwner: string | null, owner: string | null): boolean;
+export declare function legacyUnownedSessionOk(requirePrincipal: boolean, caller: SessionCaller, cell: SessionOwnerCell): boolean;
 /**
  * {@link legacyUnownedSessionOk} 的**条件①③**半支 —— 只判「这个部署形 × 这个调用方」是否落在窄臂辖域内。
  *
@@ -106,6 +155,13 @@ export type OwnerAwareSessionStore = SessionStore & {
      *  是 `src/session-incarnation.ts`。只关心属主的消费点照旧读 `ownerOf`;判「这还是不是同一位住客」的读它。 */
     sessionFaceOf?: SessionFaceReader;
     register?: (sessionId: string, owner: string | null) => Promise<void>;
+    /** S-1770 委派继承律的**认领口** —— 只在记录委派树的店上(SQL 两店,只命中 placed 行;local 店没有):判断时读到的那一位住客仍是无主的 placed 行 ⇒ 写 `owner`,
+     *  返回是否写成(只 CAS 子行自己)。唯一调用方 = 停驻挂点的 `settleDelegatedOwner`(`delegated-session-owner.ts`;M23 走同一句 SQL);规则写在那个模块。 */
+    claimOwnerless?: OwnerlessClaim;
+    /** [ref] placed 分区的元组读口(店的既有读口,一行 PK 读;`undefined` = 普通会话或无此行)。店不交它 = 不实现 placement = 没有 placed 行(local 店)。两个读者:
+     *  ① 会话面的属主门只在属主为 NULL 时读它一次(无主的 placed 行不是公共行,`http/principal-gate.ts` 的 `sessionOwnerCellOf`);
+     *  ② 会话视图读它投影体顶层 `agent` 键(`audit.ts` 的 `sessionAgentOf`,只在视图读上付):店没有这一面 ⇒ 键缺席,读面不凭别处另铸子代身份。 */
+    placementOf?: (sessionId: string) => Promise<SessionPlacementRecord | undefined>;
     /** E16 — enumerate the caller's sessions (owner-filtered on the session store's OWN owner column).
      *  `includeUnowned` = [ref] 窄互认第二臂的**第三条件**(`owner IS NULL`)的 SQL 承载位:置真时
      *  谓词放宽为 `owner = ? OR owner IS NULL`。只在 `owner` 在场时有意义(路由已判①③);`owner` 缺席
@@ -269,24 +325,39 @@ export declare function createAuthorizer(config: ServiceConfig, sessionStore: Ow
  *     SendUserFile ledger scope + the /v1/sendfile-links fleet-wide default; the resource-suspend isolation
  *     key), `"_leader"` merges with the leader durable-approval owner scope (a tenant so named could list/
  *     decide internal leader approvals), `"_leader-…"` with the leader resource-suspend scope family, and
- *     `"__none__"` with the missing-principal placeholder scope on the decide/pending gates.
+ *     `"__none__"` with the missing-principal read placeholder of the approval queue faces (≤ 7.132.x replicas).
  *   - length > 190 is REJECTED: every scope/owner column the principal lands in VERBATIM is VARCHAR(190)
  *     (sendfile_link.scope, approval.owner/scope, memory-engine scope, rate-limit keys, …) — an over-long
  *     principal would truncate/500 at the INSERT and split one identity into two.
  *  Throws a typed 400 `HttpError` (the HTTP layer maps it); the message names the rule (a reserved identifier /
  *  the length cap), never a secret and never the internal scope's semantics. */
 export declare const PRINCIPAL_MAX_LENGTH = 190;
+/**
+ * 一个被受理的主体串最多占多少个 UTF-8 字节 —— 按**字节**计宽的身份列(TiDB `VARBINARY(n)`)的列宽**唯一来源**(派生,不手抄第二个数)。
+ * {@link PRINCIPAL_MAX_LENGTH} 数的是 UTF-16 码元(`string.length`),一个码元最坏落 3 个 UTF-8 字节:BMP 字符 3 字节;代理对 4 字节 / 2 码元;
+ * 孤代理按 U+FFFD 编,3 字节。按**字符**计宽的列(`VARCHAR(n)`:TiDB utf8mb4 / PG 都数码点)直接用 {@link PRINCIPAL_MAX_LENGTH} —— 码点数 ≤ 码元数。
+ */
+export declare const PRINCIPAL_MAX_UTF8_BYTES: number;
 /** 修1 — the SINGLE registry of internal sentinel/scope identifiers a tenant principal must never equal.
  *  🔴 新增内部 sentinel scope 必须在此登记(精确值加 RESERVED_PRINCIPALS,前缀族加
  *  RESERVED_PRINCIPAL_PREFIXES),否则 assertPrincipalShape 会放行同名租户 = 与内部 scope 行合流的超范围面。
  *  Current entries (where each is minted): `"_"` = single-user/anonymous sentinel (checkpoint/sendfile/
- *  resource-suspend scope family); `"__none__"` = missing-principal placeholder on the decide/pending gates
- *  (http/server.ts `principal ?? "__none__"`); `"_leader"` = leader durable-approval scope
+ *  resource-suspend scope family); `"__none__"` = the missing-principal read placeholder of the approval
+ *  queue faces up to 7.132.x (7.133.0 reads the anonymous group `"_"` instead; still reserved because a 7.132.x replica in the same
+ *  rolling upgrade lists that scope for anonymous callers, so a tenant by that name would merge with them there); `"_leader"` = leader durable-approval scope
  *  (src/leader/wire.ts); prefix `"_leader-"` = the leader resource-suspend scope family
- *  (`_leader-resource-<workerId>`, src/leader/wire.ts). NB the prefix REQUIRES the hyphen — a tenant named
+ *  (`_leader-resource-<workerId>`, src/leader/wire.ts); prefix `"_orphan:"` = the owner written on a delegated session whose
+ *  delegation ancestors are gone (`_orphan:<sessionId>`, src/delegated-session-owner.ts) — a caller allowed to authenticate as it
+ *  would read that transcript. NB the `_leader-` prefix REQUIRES the hyphen — a tenant named
  *  `_leaderX` collides with nothing internal and stays valid (boundary pinned by test). */
 export declare const RESERVED_PRINCIPALS: readonly string[];
 export declare const RESERVED_PRINCIPAL_PREFIXES: readonly string[];
+/** The principal-shape rule as a VERDICT (the one judge; {@link assertPrincipalShape} is its throwing reader). `undefined` = a
+ *  principal may carry this string; otherwise which rule it breaks. A reader that only needs "can this string be anyone?" (the
+ *  organization delivery gate's recipient: a string that breaks the rule is nobody, refused with the same bytes as an unknown
+ *  principal) reads the verdict instead of catching the throw. */
+export type PrincipalShapeProblem = "reserved" | "too_long";
+export declare function principalShapeProblem(principal: string): PrincipalShapeProblem | undefined;
 export declare function assertPrincipalShape(principal: string): void;
 /** The checkpoint `scope` column's single-user/anonymous sentinel — the same "_" documented above
  *  ({@link RESERVED_PRINCIPALS}) as the checkpoint/sendfile/resource-suspend scope family's shared value.
@@ -321,6 +392,10 @@ export declare const encodeCheckpointScope: (principal: string | null | undefine
 /** Decode a checkpoint `scope` column value back to a principal — {@link CHECKPOINT_PUBLIC_SCOPE} maps to
  *  `undefined` (no principal), everything else passes through verbatim. */
 export declare const decodeCheckpointScope: (scope: string) => string | undefined;
+/** A checkpoint `scope` value read as the **owner column** of the rows it governs (run rows, live / crash asks): {@link CHECKPOINT_PUBLIC_SCOPE}
+ *  ⇒ `null` (the null-owner rows: tasks submitted without a principal), everything else verbatim. The one translation from the approval faces'
+ *  scope to an owner filter — stores filter on the owner column and never recognize `"_"` themselves. */
+export declare const ownerOfCheckpointScope: (scope: string) => string | null;
 /** Read the authenticated principal from the trusted header. Never from the body. */
 export declare function principalFrom(req: IncomingMessage, config: ServiceConfig): string | undefined;
 /** Header carrying the crypto-verified principal JWT on a direct-door worker (the issuer signs it; the worker only
@@ -342,5 +417,8 @@ export declare function setSsoPrincipal(req: IncomingMessage, principal: string)
 export declare function ssoVerifiedPrincipal(req: IncomingMessage): string | undefined;
 export declare function setSsoScope(req: IncomingMessage, scope: string): void;
 export declare function ssoVerifiedScope(req: IncomingMessage): string | undefined;
+export declare function setSsoRole(req: IncomingMessage, role: string): void;
+export declare function ssoVerifiedRole(req: IncomingMessage): string | undefined;
 export declare function verifiedPrincipal(req: IncomingMessage, config: ServiceConfig): string | undefined;
+export {};
 //# sourceMappingURL=security.d.ts.map

package/dist/security.js

@@ -1,6 +1,8 @@
 import { uuidv7, PROJECT_ID_REGEX } from "@sema-agent/core";
 import { memoryScopeFor } from "./memory-scope.js";
 import { verifyPrincipalJwt } from "./principal-jwt.js";
+import { fieldConflictFacts } from "./field-conflict.js";
+import { ORPHAN_SESSION_OWNER_PREFIX } from "./delegated-session-owner.js";
 export function isDestructiveSessionWrite(method, url) {
     if (method === "DELETE")
         return /^\/v1\/sessions\/[^/]+$/.test(url);
@@ -10,9 +12,26 @@ export function isDestructiveSessionWrite(method, url) {
         return /^\/v1\/sessions\/[^/]+\/(sync\/import|fork|memory\/erase)$/.test(url);
     return false;
 }
+export function mintPrincipal(verified) {
+    return verified;
+}
+export function mintDurableOwnerKey(persisted) {
+    return persisted;
+}
+export function ownerlessRowOpen(cell, caller) {
+    if (cell.owner !== null)
+        return false;
+    return !cell.placed || caller.fleet;
+}
+export async function sessionOwnerCellOf(store, sessionId, owner) {
+    if (owner !== null)
+        return { owner: mintDurableOwnerKey(owner) };
+    const placementOf = store?.placementOf;
+    return { owner: null, placed: placementOf !== undefined && (await placementOf.call(store, sessionId)) !== undefined };
+}
 export const LEGACY_UNOWNED_AMNESTY_TENANT = "default";
-export function legacyUnownedSessionOk(requirePrincipal, gateOwner, owner) {
-    return owner === null && legacyUnownedAmnestyOpen(requirePrincipal, gateOwner);
+export function legacyUnownedSessionOk(requirePrincipal, caller, cell) {
+    return legacyUnownedAmnestyOpen(requirePrincipal, caller.principal ?? null) && ownerlessRowOpen(cell, caller);
 }
 export function legacyUnownedAmnestyOpen(requirePrincipal, gateOwner) {
     return !requirePrincipal && gateOwner === LEGACY_UNOWNED_AMNESTY_TENANT;
@@ -98,7 +117,7 @@ export function createAuthorizer(config, sessionStore) {
         }
         else {
             if (requireExisting) {
-                throw createCodedHttpError(422, "request.field_conflict", "requireExistingSession requires a sessionId — there is no existing session to resume");
+                throw createCodedHttpError(422, "request.field_conflict", "requireExistingSession requires a sessionId — there is no existing session to resume", fieldConflictFacts("existing_session", ["requireExistingSession", "sessionId"]));
             }
             sessionId = uuidv7();
             if (register)
@@ -108,14 +127,29 @@ export function createAuthorizer(config, sessionStore) {
     };
 }
 export const PRINCIPAL_MAX_LENGTH = 190;
+export const PRINCIPAL_MAX_UTF8_BYTES = PRINCIPAL_MAX_LENGTH * 3;
 export const RESERVED_PRINCIPALS = ["_", "__none__", "_leader"];
-export const RESERVED_PRINCIPAL_PREFIXES = ["_leader-"];
+export const RESERVED_PRINCIPAL_PREFIXES = ["_leader-", ORPHAN_SESSION_OWNER_PREFIX];
+export function principalShapeProblem(principal) {
+    if (RESERVED_PRINCIPALS.includes(principal) || RESERVED_PRINCIPAL_PREFIXES.some((p) => principal.startsWith(p)))
+        return "reserved";
+    if (principal.length > PRINCIPAL_MAX_LENGTH)
+        return "too_long";
+    return undefined;
+}
 export function assertPrincipalShape(principal) {
-    if (RESERVED_PRINCIPALS.includes(principal) || RESERVED_PRINCIPAL_PREFIXES.some((p) => principal.startsWith(p))) {
-        throw new HttpError(400, `principal ${JSON.stringify(principal)} is reserved (an internal scope sentinel) — authenticate with a real tenant identifier`, { code: "principal_reserved" });
-    }
-    if (principal.length > PRINCIPAL_MAX_LENGTH) {
-        throw new HttpError(400, `principal exceeds ${PRINCIPAL_MAX_LENGTH} characters (the scope-column width every store pins, e.g. sendfile_link.scope VARCHAR(190)); got ${principal.length}`, { code: "principal_too_long" });
+    const problem = principalShapeProblem(principal);
+    switch (problem) {
+        case undefined:
+            return;
+        case "reserved":
+            throw new HttpError(400, `principal ${JSON.stringify(principal)} is reserved (an internal scope sentinel) — authenticate with a real tenant identifier`, { code: "principal_reserved" });
+        case "too_long":
+            throw new HttpError(400, `principal exceeds ${PRINCIPAL_MAX_LENGTH} characters (the scope-column width every store pins, e.g. sendfile_link.scope VARCHAR(190)); got ${principal.length}`, { code: "principal_too_long" });
+        default: {
+            const unknownProblem = problem;
+            throw new Error(`assertPrincipalShape: unknown problem ${String(unknownProblem)}`);
+        }
     }
 }
 export const CHECKPOINT_PUBLIC_SCOPE = "_";
@@ -125,6 +159,7 @@ export function backgroundScopesForCheckpointScope(scope) {
 }
 export const encodeCheckpointScope = (principal) => principal ?? CHECKPOINT_PUBLIC_SCOPE;
 export const decodeCheckpointScope = (scope) => (scope === CHECKPOINT_PUBLIC_SCOPE ? undefined : scope);
+export const ownerOfCheckpointScope = (scope) => decodeCheckpointScope(scope) ?? null;
 export function principalFrom(req, config) {
     if (!config.principalHeader)
         return undefined;
@@ -153,6 +188,14 @@ export function ssoVerifiedScope(req) {
     const v = req[SSO_SCOPE];
     return typeof v === "string" && v.length > 0 ? v : undefined;
 }
+const SSO_ROLES = new WeakMap();
+export function setSsoRole(req, role) {
+    SSO_ROLES.set(req, role);
+}
+export function ssoVerifiedRole(req) {
+    const v = SSO_ROLES.get(req);
+    return v !== undefined && v.length > 0 ? v : undefined;
+}
 export function verifiedPrincipal(req, config) {
     const sso = ssoVerifiedPrincipal(req);
     if (sso) {

package/dist/session-error-wire.d.ts

@@ -27,8 +27,18 @@
  *    `open` 面留白(#1077 形,见上)。
  *  · `not_found` —— 留白:每一面各有自己的「不存在」答法(404 `not_found.session` / 同步口的 `resume.session_not_found` /
  *    列表里的缺席),码位各不相同,不由本表统一。
- *  · `invalid_entry` / `invalid_fork_target` / `placement_refused` —— 留白:本仓今天没有一条 wire 口把它们作为自己的
- *    应答(它们在 core 的追加 / 分叉 / 放置面上抛,落进各站点既有的处置或通用 500)。给它们起名是另一件事、另一张票。
+ *  · `placement_refused` —— `import` 面 **409 `conflict.session_placed`**(机读位 `detail.placement_kind`,固定句);`open` 面留白。
+ *    同一个词在两面上说的不是同一件事:import 面只有「会话同步往一只**分区会话**(委派子代的转录)上写」一个来源
+ *    (SQL 两店的整段换装 / 暂存提交门:目标 id 的 `placement_kind` 在场 ⇒ 不适用),调用方没做错格式、是**目标**不收这种写;
+ *    open 面上同一个词还含「声明了分区的创建撞上了分区外 / 异组的行」两形(core `TtlSessionStore.assertPlacementAdmission` 的后两条),
+ *    那不是「目标是分区会话」。而 run 终局上它是引擎词汇(`terminal.code`),原样随 failed 体走 —— 若在这里分诊成 409,
+ *    体上的 `errorCode` 仍是引擎词 `placement_refused`,一个状态两个名字。所以 open 面留白,`invalid_session` 是同形先例。
+ *    409 的语义:目标会话**状态**不收这种写(重试同一个 id 同一结果;换一个会话 id 推)—— 与 `conflict.session_ownerless` / `conflict.session_children_alive` 同族。
+ *    `detail.placement_kind` 是**常量**,不是从错误里读的:core 的 `SessionError` 只带 `code` 与句子,不带种类;今天分区种类闭集只有
+ *    `"subagent"` 一个词,所以常量就是事实。core 给 `SessionPlacementRecord["kind"]` 加第二个词 ⇒ 下面的守卫编译红,由人裁定种类从哪儿读
+ *    (请求 core 把种类放进错误,而不是在这里解析句子)。
+ *  · `invalid_entry` / `invalid_fork_target` —— 留白:本仓今天没有一条 wire 口把它们作为自己的
+ *    应答(它们在 core 的追加 / 分叉面上抛,落进各站点既有的处置或通用 500)。给它们起名是另一件事、另一张票。
  *  · `storage` / `conflict` / `unknown` —— 留白:`conflict` 是 run 的写撞上真并发写,落成那条 run 的 `failed` 终局
  *    (`terminal.code: "conflict"`),提交腿不另作处置;`storage` / `unknown` 是故障类,通用 500 就是它们今天的应答。
  *
@@ -50,9 +60,16 @@ export interface SessionErrorWire {
      * 常量锚格),本批逐字不改。
      */
     readonly sentence?: string;
+    /** 机读事实(体顶层的 `detail` 键;缺席 = 体里不带这个键)。只有 import 面的 `placement_refused` 用它:`{ placement_kind }`。 */
+    readonly detail?: Readonly<Record<string, string>>;
 }
 /** import 面 `invalid_session` 的固定句(修前 session-sync 暂存导入腿那一行的原文)。 */
 export declare const STAGED_IMPORT_INVALID_SENTENCE = "staged session log failed validation";
+/**
+ * import 面 `placement_refused` 的固定句:wire 上不发引擎原句 —— 两家 SQL 店的原句不同(措辞各自铸),都点名会话 id 与引擎内部词
+ * (「placement partition」「delegation transcript」);固定句只说调用方能做什么(冻结在 `test/api-error-text-freeze.test.ts` 的常量锚格)。
+ */
+export declare const PLACED_SESSION_SENTENCE = "this session holds a delegated agent's transcript, so session sync cannot overwrite it; sync into a different session id";
 export declare function sessionErrorHttp(code: SessionErrorCode, face: SessionErrorFace): SessionErrorWire | undefined;
 export declare function isSessionErrorCode(code: string): code is SessionErrorCode;
 //# sourceMappingURL=session-error-wire.d.ts.map

package/dist/session-error-wire.js

@@ -1,16 +1,20 @@
 export const STAGED_IMPORT_INVALID_SENTENCE = "staged session log failed validation";
+export const PLACED_SESSION_SENTENCE = "this session holds a delegated agent's transcript, so session sync cannot overwrite it; sync into a different session id";
+const PLACEMENT_KIND = "subagent";
 const CORRUPT_SESSION = { status: 500, errorCode: "corrupt_session" };
 const INVALID_ENTRIES = { status: 422, errorCode: "invalid_entries", sentence: STAGED_IMPORT_INVALID_SENTENCE };
+const SESSION_PLACED = { status: 409, errorCode: "conflict.session_placed", sentence: PLACED_SESSION_SENTENCE, detail: { placement_kind: PLACEMENT_KIND } };
 export function sessionErrorHttp(code, face) {
     switch (code) {
         case "corrupt_session":
             return CORRUPT_SESSION;
         case "invalid_session":
             return face === "import" ? INVALID_ENTRIES : undefined;
+        case "placement_refused":
+            return face === "import" ? SESSION_PLACED : undefined;
         case "not_found":
         case "invalid_entry":
         case "invalid_fork_target":
-        case "placement_refused":
         case "storage":
         case "conflict":
         case "unknown":

package/dist/session-titled-frame.d.ts

@@ -0,0 +1,33 @@
+/**
+ * **会话标题帧 `session_titled`** —— 标题器把标题写进会话行**之后**,在**这条 run 的活流**上自铸的一帧(契约 §4a-ttl)。
+ *
+ * ## 为什么有这一帧
+ * 标题器是 fire-and-forget:run 被引擎受理之后才起、在 run 跑的同时生成,写成时那条 run 的流往往还开着。此前写成只落行
+ * (`setTitleIfNull`)+ 一行运维日志 —— wire 上零通知,端上(桌面 / web 座位)只能在首轮之后有界轮询读会话行。
+ * 这一帧把「标题写成了」交给已经在 tail 这条流的人,轮询可以删。
+ *
+ * ## 律(一条)
+ * **只活不存**:会话行是标题的唯一真源,本帧只是「行刚刚变了」的活通知 —— 不落账本(`GET /v1/runs/:id/events` 回放读不出它)、
+ * 不进任何重放面;冷启动 / 多窗口 / 断线重连读会话行(`GET /v1/sessions` 的列表行 `title`;`/v1/sessions/:id/head` 只带 `leafId`,不是标题的读面)。因此:
+ *  · 读者 = **这条 run 的流读者**,与会话行的读权同一(流是提交这条 run 的人开的,会话行归同一个人);
+ *  · 只有持活流的腿才收得到(今天 = `POST /v1/tasks/stream`);同步 JSON 腿 / durable 后台腿没有活流 ⇒ 这一帧结构上不存在,读行;
+ *  · 流已经走到终帧(`done`)或连接已断 ⇒ 丢弃(终帧是流的最后一帧);
+ *  · `PATCH /v1/sessions/:id` 的改名 / 置顶不经标题器 ⇒ 不发(调用方自知);用户清空标题后下一次提交由标题器重填,那一次重填照发(例外:本进程里此前为这个会话生成失败 / 回空过 —— 标题器不再为它重试,直到进程重启)。
+ *
+ * ## 谁铸
+ * 唯一铸点 = {@link buildSessionTitledFrame},唯一调用方 = `session-titler.ts`(落行成功的那一支,实参 = 落进行里的**同一个**标题 ——
+ * 已脱敏、已清洗;帧上的标题与行上的标题是一个值,不从模型原文另铸)。键集登记在 `trace/self-minted-wire.ts` 的 `sessionTitledFrameKey`
+ * (成员集 `satisfies Record<keyof SessionTitledFrame, …>`:加一个键而登记没跟 ⇒ tsc 红)。
+ *
+ * 帧上没有 `eventId` ⇒ SSE 不发 `id:` 行(契约 §0.6「无锚不发行」):它不是引擎的内容帧,没有续流位置可言。
+ */
+/** 标题帧的形 —— 键集就是这个接口的键(登记表按 `keyof` 绑定)。 */
+export interface SessionTitledFrame {
+    readonly type: "session_titled";
+    readonly sessionId: string;
+    /** 落进会话行的那个标题(已过标题器的脱敏与清洗,≤ `TITLE_MAX_CHARS` 个字符)。 */
+    readonly title: string;
+}
+/** 唯一铸点:纯数据,无行为。 */
+export declare function buildSessionTitledFrame(sessionId: string, title: string): SessionTitledFrame;
+//# sourceMappingURL=session-titled-frame.d.ts.map

package/dist/session-titled-frame.js

@@ -0,0 +1,4 @@
+export function buildSessionTitledFrame(sessionId, title) {
+    return { type: "session_titled", sessionId, title };
+}
+//# sourceMappingURL=session-titled-frame.js.map

package/dist/session-titler.d.ts

@@ -13,6 +13,11 @@
  * cheap-model one-liner via the deployment's hookLlm face (summarize role → MODEL_CHEAP_ID when configured, else the
  * main model; bounded + timed out).
  *
+ * WRITE-AFTER NOTICE: the title that lands is announced to the run that triggered it — `maybeTitle`'s `onTitled` hands the
+ * seat (`run-acceptance.ts`) the one `session_titled` frame (`session-titled-frame.ts`, contract §4a-ttl) built from the
+ * SAME string the row now holds; the seat forwards it to the live stream when the leg has one. Live-only: the row is the
+ * truth, nothing else stores the frame.
+ *
  * FAILURE POSTURE: everything is best-effort — a generation/store failure logs and leaves title null (the
  * list falls back to objectivePreview). The fail-open tag it leaves names the CAUSE FAMILY (one tag, one family):
  * the llm face's failure CODE picks it (`failOpenTagFor`), never the error's wording. An in-process pending set dedupes concurrent submits on the same
@@ -20,6 +25,7 @@
  * call at worst, and exactly one title lands).
  */
 import type { HookLlmFailureCode } from "./hooks/hook-runner.js";
+import { type SessionTitledFrame } from "./session-titled-frame.js";
 export interface SessionTitlerDeps {
     /** Secret scrub applied to the RAW llm text before sanitize/persist (workflow audit 2026-07-13: the
      *  objective may carry a pasted secret and the model can echo it into the title — titles are persisted,
@@ -58,7 +64,9 @@ export interface SessionTitlerDeps {
 export interface SessionTitler {
     /** Fire-and-forget: maybe generate + persist a title for this session. Never throws, never blocks the caller. */
     /** `model`([ref]②)= 本 turn 真实驱动的模型——带上则标题 hook 同链路,不再裸落 env 缺省。 */
-    maybeTitle(sessionId: string, objective: string, model?: string): void;
+    /** `onTitled` = 这一次调用**自己**把标题写成之后(`setTitleIfNull` 落行)交出的活通知(`session_titled` 帧,契约 §4a-ttl):只在落行的那一支调用恰一次 ——
+     *  已有标题 / 竞态输了 / 模型失败 / 空标题 / 这个会话已有一次在飞的调用,都不调。回调同步执行、**不许抛**;抛了也不影响已落行的标题(见下 `frame_failed`)。 */
+    maybeTitle(sessionId: string, objective: string, model?: string, onTitled?: (frame: SessionTitledFrame) => void): void;
 }
 export declare const TITLE_MAX_CHARS = 80;
 /** Single line, control chars stripped, hard cap; surrounding quotes (a common LLM tic) trimmed. */

package/dist/session-titler.js

@@ -1,7 +1,8 @@
-import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
+import { stripControlAndBidi } from "@sema-agent/settings-schema";
 import { recordFailOpen } from "./observability/fail-open.js";
 import { redactSecrets } from "./trace/redact.js";
 import { userAuthoredText } from "./user-authored-text.js";
+import { buildSessionTitledFrame } from "./session-titled-frame.js";
 export const TITLE_MAX_CHARS = 80;
 const OBJECTIVE_SNIPPET_CHARS = 600;
 const LLM_TIMEOUT_MS = 15_000;
@@ -29,7 +30,7 @@ function failOpenTagFor(code) {
     }
 }
 export function sanitizeTitle(raw) {
-    const oneLine = raw.replace(/[\r\n]+/g, " ").replace(CONTROL_AND_BIDI_STRIP_RE, "").trim();
+    const oneLine = stripControlAndBidi(raw.replace(/[\r\n]+/g, " ")).trim();
     const unquoted = oneLine.replace(/^["'「『]+/, "").replace(/["'」』]+$/, "").trim();
     return unquoted.length > TITLE_MAX_CHARS ? `${unquoted.slice(0, TITLE_MAX_CHARS - 1)}…` : unquoted;
 }
@@ -45,8 +46,9 @@ export function buildTitlePrompt(objective) {
 }
 export function createSessionTitler(deps) {
     const seen = new Set();
+    const redactedError = (error) => redactSecrets(error);
     const logFailure = (sessionId, error, code) => {
-        const safe = redactSecrets(error);
+        const safe = redactedError(error);
         deps.logger?.debug?.("session_title_failed", { sessionId, error: safe.slice(0, 200) });
         recordFailOpen(failOpenTagFor(code), safe.slice(0, FAIL_CAUSE_KEY_CHARS));
     };
@@ -55,7 +57,7 @@ export function createSessionTitler(deps) {
         .then((state) => ({ state, unreadable: false }))
         .catch(() => ({ state: continueWord, unreadable: true }));
     return {
-        maybeTitle(sessionId, objective, model) {
+        maybeTitle(sessionId, objective, model, onTitled) {
             if (!sessionId || !userAuthoredText(objective))
                 return;
             if (seen.has(sessionId))
@@ -104,6 +106,15 @@ export function createSessionTitler(deps) {
                 seen.delete(sessionId);
                 deps.metrics?.inc("session_title_total", { outcome: "set" });
                 deps.logger?.info?.("session_titled", { sessionId, titleChars: title.length });
+                if (onTitled) {
+                    try {
+                        onTitled(buildSessionTitledFrame(sessionId, title));
+                    }
+                    catch (e) {
+                        deps.metrics?.inc("session_title_total", { outcome: "frame_failed" });
+                        deps.logger?.warn?.("session_titled_frame_failed", { sessionId, error: redactedError(String(e)).slice(0, 200) });
+                    }
+                }
             })().catch((e) => {
                 deps.metrics?.inc("session_title_total", { outcome: "error" });
                 logFailure(sessionId, String(e));

package/dist/spec-fields.js

@@ -1,6 +1,6 @@
 import { isThinkingLevel } from "@sema-agent/core";
 import { taskWallClockSec } from "./task-workflow.js";
-import { isAbsoluteHostPath } from "@sema-agent/settings-schema";
+import { ABSOLUTE_HOST_PATH_MAX, isAbsoluteHostPath } from "@sema-agent/settings-schema";
 import { ruleEntryListShapeOk, skillToolListsOverCap } from "./rule-entry-list.js";
 import { describeLimit, limitFacts, limitRefusal } from "./limit-refusal.js";
 import { quotedCallerText } from "./caller-text-echo.js";
@@ -110,6 +110,23 @@ const skillOk = (s) => {
     }
     return true;
 };
+const skillsLimit = (v) => {
+    if (!Array.isArray(v))
+        return undefined;
+    const j = v.findIndex((s) => !skillOk(s));
+    const s = j < 0 ? undefined : v[j];
+    if (!plainObject(s))
+        return undefined;
+    const content = s["content"];
+    const baseDir = s["baseDir"];
+    if (typeof content === "string" && content.length > MAX_AGENT_SKILL_CONTENT_CHARS) {
+        return { sub: `[${j}].content`, measure: "characters", count: content.length, cap: MAX_AGENT_SKILL_CONTENT_CHARS, keepShapeSentence: true };
+    }
+    if (typeof baseDir === "string" && baseDir.length > ABSOLUTE_HOST_PATH_MAX) {
+        return { sub: `[${j}].baseDir`, measure: "characters", count: baseDir.length, cap: ABSOLUTE_HOST_PATH_MAX, keepShapeSentence: true };
+    }
+    return undefined;
+};
 const memoryOk = (v) => {
     if (!plainObject(v))
         return false;
@@ -140,6 +157,7 @@ const TASK_AGENT_FIELD_SHAPES = {
     skills: {
         desc: "an array of { name, description, content } skill objects (optional allowedTools/disallowedTools/files/baseDir; allowedTools/disallowedTools are arrays of strings; files entries need { path, content }; baseDir must be an absolute path with no \"..\" segment) — no count cap; the engine renders the listing within its own byte budget",
         ok: (v) => Array.isArray(v) && v.every(skillOk),
+        limit: skillsLimit,
     },
     background: { desc: "a boolean", ok: (v) => typeof v === "boolean" },
     isolation: { desc: '"worktree"', ok: (v) => v === "worktree" },
@@ -180,7 +198,8 @@ export function taskAgentIssue(item) {
         if (hit === undefined)
             return { message: `agent.${k} must be ${shape.desc}` };
         const rel = `${k}${hit.sub}`;
-        return { message: describeLimit(`agent.${rel}`, hit.measure, hit.count, hit.cap), limit: { rel, measure: hit.measure, count: hit.count, cap: hit.cap } };
+        const limit = { rel, measure: hit.measure, count: hit.count, cap: hit.cap };
+        return hit.keepShapeSentence === true ? { message: `agent.${k} must be ${shape.desc}`, limit } : { message: describeLimit(`agent.${rel}`, hit.measure, hit.count, hit.cap), limit };
     }
     return null;
 }

package/dist/sql-engine-posture.d.ts

@@ -60,7 +60,9 @@ export interface SqlEngineCapability {
 }
 /**
  * Boot 期建立引擎事实:借一条池连接(初始化随之跑),再原样归还。返回本池的**引擎读口**(驱动本身:方言 + 活的 `facts`)—— 事实由
- * 驱动持有,重连后它会被下一次初始化刷新,快照会说谎;方言与事实同出这一只,写入要装进的墙(`sqlWallsOf`)只读它。
+ * 驱动持有,重连后它会被下一次初始化刷新,快照会说谎;方言与事实同出这一只,写入要装进的墙(`sqlWallsOf`)只读它。读到的是**最近一次初始化的那条连接**的事实:隔离级 / 事务模式每条连接
+ * 同钉同验,所以就是池的事实;包墙 `maxPacketBytes` 是会话值、随连接不同,这里只是那一条连接的读数(池见过的最新读数 —— 只在有连接初始化时才更新,DBA 调了全局值之后、下一条连接初始化之前它仍是旧值;
+ * 运维读面与提交受理口的提前一跑读它),终判读将要执行写入的那条连接自己的读数(`sql-driver.ts` `connectJudged`)。
  *
  * 抛出 = 拒启:连接初始化拒绝了这个后端(TiDB 乐观模式设不成悲观、隔离级复核不符、服务器太旧读不出
  * `@@transaction_isolation`)。这条错**刻意不吞** —— 本仓所有 `FOR UPDATE` 判据都以它为前提。

package/dist/task-cwd.d.ts

@@ -34,7 +34,7 @@ export declare function cwdHonored(config: {
 }): boolean;
 /**
  * S-377 —— 「**工具跑的那台机器**就是本进程这台吗」。回答的是一个**文件系统同一性**问题,不是权限问题:
- * server 盘上的一条绝对路径(出厂 `SKILLS_DIR` 下某个技能自己的目录)对模型的工具**有没有意义**。
+ * server 盘上的一条绝对路径(出厂 `SKILLS_DIR` 下、或中心 plugin 缓存里某个技能自己的目录)对模型的工具**有没有意义**。
  *
  * 判据 = 能力表两位的合取 {@link handsOnWorkerFilePlane}(`coreRemoteExecutionEnv ∧ hostFilePlane`,都读表,
  * 本函数不手写任何车道词):

package/dist/task-mcp.d.ts

@@ -159,12 +159,12 @@ export interface RequestMcpRefusal {
  *  ③ **身份头的键组合**(`principalHeader` 与 `assertionHeader` 同设 / `assertionHeader` 非串)⇒ {@link requestEntryIdentityRefusal}(同设那一句对契约包解析期原句逐字)。
  *  ④ **受理键的值** ⇒ 逐键问判官表 {@link ENTRY_KEY_JUDGES},`400 request.field_invalid`,拒句点名 `mcpServers[i].<键路径>`、server 名与**该键判官的原因句**({@link entryFieldRefusal})。
  *     判官**就是读器用的那一只**,不是第二份:`toolAxes` = 引擎根导出的 `readMcpToolAxes`;`toolFaces` = `readMcpToolFaces`;`contentOrigin` = `isContentOriginWord`;`source` = `isMcpSourceLabel`;
- *     `name` = `isUsableWireName`;`allowTools` / `transport.args` = {@link isStringArray};`transport.env` / `headers` = {@link readPlainStringRecord};`elicitation` = {@link isElicitationFlag};
- *     `transport` 的硬字段(`kind` / `command` / `url`)与软字段(`args` / `env` / `headers` / `principalHeader`)= {@link readRequestTransport}(读器投影 transport 的那一只函数,门读它报的 `lost`)。
+ *     `name` = `isUsableWireName`;`allowTools` / `transport.args` = {@link isStringArray};`transport.env` / `headers` = 契约包读器 {@link readRequestMcpTransport} 的纯数据记录读法;`elicitation` = {@link isElicitationFlag};
+ *     `transport` 的硬字段(`kind` / `command` / `url`)与软字段(`args` / `env` / `headers` / `principalHeader`)= {@link readRequestMcpTransport}(读器投影 transport 的那一只函数,门读它报的 `lost`;读器在契约包,本仓只据 `lost[0]` 拒、据 `lost` 在重放腿逐处点名)。
  *     判官只在引擎里、包根没给读口的键(今天只有 `startupTimeoutMs`)不在这里判,原样过境、由引擎在拨号时按 server 拒(不写第二份判据;到货读口即换)。
  * 于是判官受理的条目,读器({@link normalizeServer})交回的就是申报本身(只差判官自己的合法归一:空容器 / `skillScopeEligible:false` 折成缺席、`toolAxes` 取引擎的拷贝)——
  * 探测口拨的那一份因此就是提交腿会挂的那一份,不另比一遍(另比就是第二只回答者)。唯一按门分的后果是「声明了 `assertionHeader`」这一个事实(引擎尚无座,
- * 承载、不发送):新提交照挂 + 运维 info,探测口整条拒 —— 判据是同一只谓词 `declaresMcpAssertionHeader`,不是第二份判法(见 `readMcpProbeBody`)。
+ * 承载、不发送):新提交照挂 + 运维 info,探测口整条拒 —— 判据是同一只谓词 `specWithholdsMcpAssertionHeader`(开关 `MCP_ASSERTION_HEADER_SENT` 假时「声明了」即「被扣下」),不是第二份判法(见 `readMcpProbeBody`)。
  *
  * ## 射程
  * 纯值域、与租户车道无关(一个写坏的请求在哪条车道上都是写坏的;多租户腿本来就忽略整只数组,告诉调用方「你写错了」只多不少)。