@sema-agent/server 7.131.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/server-secret-env.d.ts

@@ -10,7 +10,12 @@
  *
  * ## 律(一句;core #1753 定,本仓只传事实、不判)
  * 本包任何进程在宿主上 spawn 的子进程:env = 引擎 `inheritedHostEnv(policy, findings)` ∪ 部署方点名放回的键(只在运维真可能要传东西的腿上有旋钮),
- * 剥掉的键经一个登记过的 `SecretEnvScrubSite` 留痕;git 腿再叠 git 自己的两件({@link gitSubprocessEnv})。三个继承词只在引擎一处判:
+ * 剥掉的键经一个登记过的 `SecretEnvScrubSite` 留痕(现场按**腿**命名);git 腿再叠 git 自己的两件({@link gitSubprocessEnv})。射程 = **每一条**宿主腿:
+ * src 里每一只值引 `node:child_process` 的文件都是登记腿、其中每一次起子进程都显式交组合出的 env(普查门在 `test/secret-env-scrub-host-legs.test.ts`)。
+ * 腿的继承词是调用点的事实,按「子进程里跑的是谁选的代码」定:模型命令(host shell,交任务自己的词)/ 仓里的钩子与凭据助手(三条 git 腿)/ 执行仓代码的
+ * 语言服务器 / 配方脚本 ⇒ 形状剥 `"scrub"`;请求带来的 settings hooks 命令 ⇒ 严格名单(引擎的 `[names]` 臂);部署方装在宿主上的 CLI(`docker` / `adb`,命令本身
+ * 在容器 / 设备里跑、那边的 env 由 `-e` 显式给)⇒ `"all"` —— 只扣本服务自有凭据,CLI 与它的凭据助手 / 插件要读的生态变量照交(形状剥会剥
+ * `ADB_VENDOR_KEYS` / `AWS_SECRET_ACCESS_KEY` 一类,实测)。三个继承词只在引擎一处判:
  *  · `"all"` = 整份环境 **减** 本进程声明的自有凭据名;`"scrub"`(缺省)= 形状剥 ∪ 该名单;`[names]` = 严格白名单,点到名单中的名 ⇒ 引擎响亮拒
  *    (`inheritEnvPolicyProblem`:构造时与 spawn 时两格都拒,拒句带名;本仓不自判 withheld、不留第二读法)。
  *  · 名单 = 配置目录(`config-catalog.ts`)全部 `type:"secret"` 名 ∪ 名单型旋钮名(`env-name-allowlist-knobs.ts`,其原文可能夹着被错展开的令牌)∪ **生效配置
@@ -23,17 +28,21 @@
  *    抛同路)。能力词 `inherit_env.own_credentials_withheld` 在本进程的事实 =
  *    {@link ownCredentialsWithheld}:最近一次成功声明的集合 ⊇ 当前生效配置应声明的集合(活配置经 {@link bindOwnCredentialsConfig} 在 `loadConfig()` 之后绑一次;
  *    未绑 / 未声明 ⇒ false,事实读不到应声明集合就不答 true)。
- *  · 调用方显式传入的 env(`cfg.env` / 单次命令的 `env` / 语言服务器与沙箱的点名放回)不是继承,照旧原样叠在组合结果之上 —— 那是适配器自己的凭据通道。
- * 各腿只调 {@link hostSubprocessEnv} / {@link gitSubprocessEnv} —— 不许再有内联拼装、不许再有 `{ ...process.env }`、不许本仓再判任何一个继承词
- * (类级门在 `test/secret-env-scrub-host-legs.test.ts`)。
+ *  · **值臂**(core 7.52.0 #1754):声明是一张表 `{ names, values }`。`values` = 本进程持有凭据的变量此刻的值(目录 secret 名 ∪ 模型条目 `apiKeyEnv`,{@link serverCredentialValueSources}),
+ *    逐个交给引擎的同一只判;引擎判「不是凭据值」的那一个不扣、名照扣、不拒启、点名一次。能力词 `inherit_env.own_credential_values_withheld` 的事实 = {@link ownCredentialValuesWithheld}(位真 ⇔ 值臂真扣)。
+ *  · 调用方显式传入的 env(`cfg.env` / 单次命令的 `env` / 沙箱的点名放回)不是继承,照旧原样叠在组合结果之上 —— 那是适配器自己的凭据通道。
+ * 各腿只调 {@link hostSubprocessEnv} / {@link gitSubprocessEnv} —— 不许再有内联拼装、不许再有 `{ ...process.env }`、不许本仓再判任何一个继承词、不许起子进程不交 env
+ * (类级门与普查门在 `test/secret-env-scrub-host-legs.test.ts`)。
  *
  * ## 点名放行(S-699 / S-713,一只谓词各处用)
- * {@link allowlistedEnv} 是本仓「一张名单点到哪些 env 键,就把它们从源 env **原样**交给子进程」的唯一实现。调用:{@link hostSubprocessEnv}(剥后放回形:
- * 本地语言服务器的 `LSP_ENV_ALLOW`、bake-runner 的 `BAKE_ENV_ALLOW`)、沙箱带外 env 的 `E2B_SANDBOX_ENV` / `DOCKER_SANDBOX_ENV` / `K8S_SANDBOX_ENV`(`config.ts`)。
+ * {@link allowlistedEnv} 是本仓「一张名单点到哪些 env 键,就把它们从源 env **原样**交给沙箱」的唯一实现。调用:沙箱带外 env 的 `E2B_SANDBOX_ENV` / `DOCKER_SANDBOX_ENV` /
+ * `K8S_SANDBOX_ENV`(`config.ts`)与名单解析器的「在不在」判。宿主子进程的剥后放回(`LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`)不经它 —— 那是引擎的严格名单臂(上一段)。
  * host shell 的 `inheritEnv:[names]`(hermetic 形)7.129.0 起由引擎读(与 core `NodeExecutionEnv` 同名选项同义,点到自有凭据名即拒),不经本谓词。
  * 名单型旋钮的**名单**另由 `config.ts` 的同一只解析器 `parseEnvNameAllowlist` 判形(形错拒启 / 源里没有的名按序号 warn),本函数只管取值。
  * 「点名」在各处同义:点到的键原样带值(空串值照带),密钥形也照过(点名 = 部署方显式承担);源里没有的名不产生条目。
- * ⚠️ 已知边界(不在本函数修):`LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW` 点到自有凭据名会把它放回语言服务器 / 配方脚本(剥后放回形在引擎的减法之上);解析器今天只拒名单型旋钮名。
+ * 剥后放回形(`LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`)的放回本身也经引擎:{@link composeHostSubprocessEnv} 把名单交引擎的严格名单臂(`inheritedHostEnv([names])`)叠在
+ * 继承结果之上 ⇒ 点到本服务自有凭据名 = 引擎抛(spawn 时;起服时解析器 `parseEnvNameAllowlist` 按表列 `channel` 已用同一只判 `inheritEnvPolicyProblem` 拒过),
+ * 点到的变量值是本服务凭据的副本 = 引擎扣下。本仓不另判。
  */
 import { type InheritEnvPolicy, type SecretEnvFinding } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
@@ -48,27 +57,44 @@ export type ModelApiKeyEnvTable = Readonly<Record<string, string>>;
  */
 export declare function serverWithheldEnvNames(modelApiKeyEnv?: ModelApiKeyEnvTable): readonly string[];
 /**
- * 🔴 **唯一声明点**:把本进程自有凭据名向引擎声明(core `declareWithheldEnv`;重声明即替换,从下一次 spawn 起生效)。`modelApiKeyEnv` = 这一次要并进名单的模型条目表
- * (起服第一步 = 空表;换代 = 候选表),名单 = 此前声明过的 ∪ 这张表的应声明集合 —— 名单只随**落地**的世代增长:落地过的名不再退出(改名 / 删条目之后它的值仍在
- * 本进程 env 里),没落地的候选不留痕(旧世代在 CAS 处就拒、不到这里;换装拒 ⇒ {@link withdrawServerWithheldEnv})。引擎对坏形名 / 运行时回填名(`PATH` / `HOME` /
- * `USER` …)响亮抛且声明保持原状 —— 本函数不接住:起服那次抛 = 拒启;换代那次抛 = 候选整拒(`applyEffective` 抛,与 stage 抛同路)。返回声明的名单(只名、不值)。
+ * 本进程**持有凭据值**的变量名(值臂的来源;core 7.52.0 #1754):目录 secret 名 ∪ 模型条目 `apiKeyEnv` 的值 —— 名单与值臂两臂同一张表派生,只少名单型旋钮名(它们的值是
+ * 一张变量名单,不是凭据)。纯函数,排序只为读数稳定。
+ */
+export declare function serverCredentialValueSources(modelApiKeyEnv?: ModelApiKeyEnvTable): readonly string[];
+/**
+ * 🔴 **唯一声明点**:把本进程自有凭据向引擎声明(core 7.52.0 `declareWithheldEnv({ names, values })`;重声明即整表替换,从下一次 spawn 起生效)。`modelApiKeyEnv` = 这一次要并进的
+ * 模型条目表(起服第一步 = 空表;换代 = 候选表)。两臂都只随**落地**的世代增长(落地过的名 / 值来源不退出:本进程 env 是 boot 期输入;没落地的候选不留痕 ——
+ * 换装拒 ⇒ {@link withdrawServerWithheldEnv})。
+ *  · **名臂**:此前声明过的 ∪ 这张表的 {@link serverWithheldEnvNames}。引擎对坏形名 / 运行时回填名(`PATH` / `HOME` …)响亮抛且声明保持原状 —— 本函数不接住:
+ *    起服那次抛 = 拒启;换代那次抛 = 候选整拒(`applyEffective` 抛,与 stage 抛同路)。第一次交表带着名臂与**此前已收下的值**(引擎收过、env 不变 ⇒ 同值照收),
+ *    所以这一次抛只可能是名的问题。
+ *  · **值臂**:{@link serverCredentialValueSources} 的每一个变量此刻在 env 里的值,逐个交给引擎**同一只**判(不另写「什么算凭据值」的第二份判据):引擎收下 ⇒ 记进值臂;
+ *    引擎拒(不是凭据值:空白 / 占位词 / 一个字符重复 / 不足 8 字符;或它是每个子进程都会拿到的变量的值)⇒ 这一个值不扣、名照扣、**不拒启**(与引擎自己的收值口
+ *    `holdOwnCredentialValues` 同一姿势:不收 + 说一次),`console.warn` 点名那个变量一次(引擎的拒句从不回显值;本句也不),能力位 `inherit_env.own_credential_values_withheld`
+ *    因此答 false(位真 ⇔ 值臂真扣)。引擎拒一个值时声明保持上一份,所以逐个交表的中间态都是上一份的超集。
+ * 返回声明的名单(只名、不值)。
  */
 export declare function declareServerWithheldEnv(modelApiKeyEnv?: ModelApiKeyEnvTable): readonly string[];
 /**
- * 席位拒 ⇒ 撤回最近一次声明(回到它之前的集合):`applyEffective` 在 Runner 换装抛时调,紧跟着那一次 {@link declareServerWithheldEnv} —— 没落地的候选不留痕。
- * 退回去的集合是引擎之前接受过的(判名确定)⇒ 不抛;连撤两次是同一个结果(幂等)。
+ * 席位拒 ⇒ 撤回最近一次声明(两臂一起回到它之前的那一份):`applyEffective` 在 Runner 换装抛时调,紧跟着那一次 {@link declareServerWithheldEnv} —— 没落地的候选不留痕。
+ * 退回去的那一份是引擎之前接受过的(名确定、值来源的值随 env 不变)⇒ 不抛;连撤两次是同一个结果(幂等)。
  */
 export declare function withdrawServerWithheldEnv(): void;
 /** 把活配置交给能力位读(stage-01 / run-local 在 `loadConfig()` 之后各一次;读的是 `config.modelApiKeyEnv` 这个**属性**,commit 整表重赋值之后看到的就是新表)。 */
 export declare function bindOwnCredentialsConfig(config: Pick<ServiceConfig, "modelApiKeyEnv">): void;
 /**
- * 能力词 `inherit_env.own_credentials_withheld` 在本进程的事实:最近一次成功声明的集合 ⊇ 当前生效配置应声明的集合。是一次比较,不是「声明过」的旗 ——
+ * 能力词 `inherit_env.own_credentials_withheld` 在本进程的事实:最近一次成功声明的名单 ⊇ 当前生效配置应声明的名单。是一次比较,不是「声明过」的旗 ——
  * 活表若被谁绕过声明写了新名,这里立刻 false(位不替流程担保)。没绑活配置 / 没声明过 ⇒ false(fail-closed)。
  */
 export declare function ownCredentialsWithheld(): boolean;
-/** 测试缝:撤回声明(引擎侧重声明为空)、忘掉声明集合(含撤回格)与活配置;生产代码从不调它。 */
+/**
+ * 能力词 `inherit_env.own_credential_values_withheld`(core 7.52.0)在本进程的事实:当前生效配置的每一个凭据值来源({@link serverCredentialValueSources}),只要它此刻在 env 里
+ * 有值,那个值都已交进值臂、被引擎收下。位真 ⇔ 值臂真扣:一个值被引擎判「扣不了」⇒ false;env 里没有值的来源没有东西可扣,不影响事实。没绑活配置 / 没声明过 ⇒ false。
+ */
+export declare function ownCredentialValuesWithheld(): boolean;
+/** 测试缝:撤回声明(引擎侧重声明为空表)、忘掉两份声明镜像、点名记账与活配置;生产代码从不调它。 */
 export declare function __resetServerWithheldEnvForTest(): void;
-/** 一条宿主腿要什么:现场(留痕)、继承策略(缺省 `"scrub"`;只有模型可驱动的 host shell 交非缺省词)、部署方点名放回的键。 */
+/** 一条宿主腿要什么:现场(留痕)、继承策略(缺省 `"scrub"`;按头注「腿的继承词」一条由调用点定)、部署方点名放回的键。 */
 export interface HostSubprocessEnvRequest {
     readonly site: SecretEnvScrubSite;
     readonly policy?: InheritEnvPolicy | undefined;
@@ -78,8 +104,8 @@ export interface HostSubprocessEnvRequest {
  * 🔴 **宿主子进程 env 的唯一组合**:{@link composeHostSubprocessEnv} + 留痕。**没有按原样交给子进程**的名字(剥掉的)经 `site` 留痕;点名放回的键取回源值,
  * 不是剥除,不计数、不披露。源 env 恒为本进程 env(引擎只读 `process.env`,本仓没有第二个源)。
  *
- * 六条宿主腿都只经它(直接或经 {@link gitSubprocessEnv}):host shell(三个继承词原样交给 `policy`)、project-memory / center-plugins / leader 三条 git 腿、
- * 本地语言服务器、bake-runner 的每一只子进程组。`allow` 只在**有部署级出路**的现场非空(今天 = `LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`,
+ * 九条宿主腿都只经它(直接或经 {@link gitSubprocessEnv}):host shell(三个继承词原样交给 `policy`)、project-memory / center-plugins / leader 三条 git 腿、
+ * 本地语言服务器、bake-runner 的每一只子进程组、local-docker 与 adb 两条 CLI 腿(`"all"`)、settings hooks 的命令腿(严格名单)。`allow` 只在**有部署级出路**的现场非空(今天 = `LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`,
  * 它们的现场在 `SECRET_ENV_SCRUB_SITES` 里登记了 `remedy`,披露行因此是 warn + 放行名单 + 出路句);其余现场传 `[]`。
  * 返回 `NodeJS.ProcessEnv` 形(值可能是 `undefined` 的键本来就不会进子进程);调用方显式要交的键(`LC_ALL`、`cfg.env` …)叠在它之上。
  * 调用时机 = 每次要交 env 时现算一次(`process.env` 在本仓是 boot 期输入,各次同值;计数因此是「每组合一次」)。

package/dist/server-secret-env.js

@@ -7,18 +7,42 @@ const NO_MODEL_ENTRIES = Object.freeze({});
 export function serverWithheldEnvNames(modelApiKeyEnv = NO_MODEL_ENTRIES) {
     return [...new Set([...CATALOG_SECRET_ENV_NAMES, ...ENV_NAME_ALLOWLIST_KNOB_NAMES, ...Object.values(modelApiKeyEnv)])].sort();
 }
+export function serverCredentialValueSources(modelApiKeyEnv = NO_MODEL_ENTRIES) {
+    return [...new Set([...CATALOG_SECRET_ENV_NAMES, ...Object.values(modelApiKeyEnv)])].sort();
+}
 let declared;
 let beforeLast;
+const valueRefusalAnnounced = new Set();
 let liveConfig;
+const envValueOf = (name) => process.env[name];
+const valuesOf = (sources) => [...sources].map(envValueOf).filter((v) => typeof v === "string" && v !== "");
 export function declareServerWithheldEnv(modelApiKeyEnv = NO_MODEL_ENTRIES) {
-    const names = [...new Set([...(declared ?? []), ...serverWithheldEnvNames(modelApiKeyEnv)])].sort();
-    declareWithheldEnv(names);
+    const names = [...new Set([...(declared?.names ?? []), ...serverWithheldEnvNames(modelApiKeyEnv)])].sort();
+    const kept = [...(declared?.valueSources ?? [])];
+    declareWithheldEnv({ names, values: valuesOf(kept) });
+    const valueSources = new Set(kept);
+    for (const source of serverCredentialValueSources(modelApiKeyEnv)) {
+        if (valueSources.has(source) || valuesOf([source]).length === 0)
+            continue;
+        try {
+            declareWithheldEnv({ names, values: valuesOf([...valueSources, source]) });
+            valueSources.add(source);
+        }
+        catch (e) {
+            if (!valueRefusalAnnounced.has(source)) {
+                valueRefusalAnnounced.add(source);
+                console.warn(`[sema-server] own credential ${source}: its value is not withheld by value from spawned children — the engine refused it (${e instanceof Error ? e.message : String(e)}); ` +
+                    "the variable name is still withheld under every inheritEnv policy, but a variable holding the same string under another name is not, and GET /v1/capabilities answers inherit_env.own_credential_values_withheld: false. " +
+                    "Give it a real credential value (at least 8 characters, not a placeholder) to withhold copies of it too.");
+            }
+        }
+    }
     beforeLast = declared;
-    declared = new Set(names);
+    declared = { names: new Set(names), valueSources };
     return names;
 }
 export function withdrawServerWithheldEnv() {
-    declareWithheldEnv([...(beforeLast ?? [])]);
+    declareWithheldEnv({ names: [...(beforeLast?.names ?? [])], values: valuesOf(beforeLast?.valueSources ?? []) });
     declared = beforeLast;
 }
 export function bindOwnCredentialsConfig(config) {
@@ -27,23 +51,40 @@ export function bindOwnCredentialsConfig(config) {
 export function ownCredentialsWithheld() {
     if (declared === undefined || liveConfig === undefined)
         return false;
-    const own = declared;
+    const own = declared.names;
     return serverWithheldEnvNames(liveConfig.modelApiKeyEnv).every((name) => own.has(name));
 }
+export function ownCredentialValuesWithheld() {
+    if (declared === undefined || liveConfig === undefined)
+        return false;
+    const own = declared.valueSources;
+    return serverCredentialValueSources(liveConfig.modelApiKeyEnv).every((source) => own.has(source) || valuesOf([source]).length === 0);
+}
 export function __resetServerWithheldEnvForTest() {
-    declareWithheldEnv([]);
+    declareWithheldEnv({ names: [], values: [] });
     declared = undefined;
     beforeLast = undefined;
     liveConfig = undefined;
+    valueRefusalAnnounced.clear();
 }
 export function hostSubprocessEnv(o) {
     const findings = [];
     const composed = composeHostSubprocessEnv(o, findings);
-    recordSecretEnvScrub(o.site, findings.filter((f) => composed[f.key] !== process.env[f.key]), o.allow);
+    const disclosed = [];
+    const seen = new Set();
+    for (const f of findings) {
+        const k = `${f.key}=${f.kind}`;
+        if (composed[f.key] === envValueOf(f.key) || seen.has(k))
+            continue;
+        seen.add(k);
+        disclosed.push(f);
+    }
+    recordSecretEnvScrub(o.site, disclosed, o.allow);
     return composed;
 }
 export function composeHostSubprocessEnv(o, findings = []) {
-    return { ...inheritedHostEnv(o.policy ?? "scrub", findings), ...allowlistedEnv(o.allow, process.env) };
+    const putBack = o.allow.length > 0 ? inheritedHostEnv([...o.allow], findings) : {};
+    return { ...inheritedHostEnv(o.policy ?? "scrub", findings), ...putBack };
 }
 export function gitSubprocessEnv(o) {
     return {

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-incarnation.d.ts

@@ -61,10 +61,19 @@ export declare class SessionIncarnationMissingError extends Error {
     constructor(sessionId: string);
 }
 /**
- * 行上化身那一格的**唯一解码**(三只店的 `sessionFaceOf` 与 SQL 两店 wake 带出的会话元数据都经它 —— 空值判据只写这一处)。
- * 不是非空字符串 ⇒ {@link SessionIncarnationMissingError}。
+ * 空化身那一格怎么读 —— {@link incarnationFromCell} 的参数(一只解码,两种**显式**读法;不是两只函数):
+ *  · `refuse`(缺省,读口):一位活住客必须有令牌 ⇒ 空 / 非串 = {@link SessionIncarnationMissingError}(响亮拒,不当通配);
+ *  · `absent`:调用方问的是「这一格里有没有一只令牌」,空 / 非串的答案是**没有**(`undefined`)—— 会话树删除时的空间键
+ *    (没有令牌 = 没有空间,不回收缓存卷)与整段换装的沿用判据(没有令牌 = 铸一只新的)。
  */
-export declare function incarnationFromCell(sessionId: string, cell: unknown): string;
+export type EmptyIncarnationReading = "refuse" | "absent";
+/**
+ * 行上化身那一格的**唯一解码**(三只店的 `sessionFaceOf`、SQL 两店 wake 带出的会话元数据、留存删除的空间键、整段换装的沿用判据都经它 ——
+ * 「是不是一只令牌」只判这一处)。非空字符串 ⇒ 那只令牌;否则按 `empty`({@link EmptyIncarnationReading}):缺省 `refuse` ⇒
+ * {@link SessionIncarnationMissingError},`absent` ⇒ `undefined`。
+ */
+export declare function incarnationFromCell(sessionId: string, cell: unknown, empty?: "refuse"): string;
+export declare function incarnationFromCell(sessionId: string, cell: unknown, empty: "absent"): string | undefined;
 /** 店把一行原始列读成 {@link SessionFace} 的唯一口(三只店共用;化身那一格经 {@link incarnationFromCell})。 */
 export declare function sessionFaceFromRow(sessionId: string, owner: string | null, incarnation: unknown): SessionFace;
 /** 按 id 读住客(core `SessionStore.incarnationOf` 的形):`undefined` = 没有这只会话;读抛 = 读故障,不是答案。 */
@@ -81,9 +90,10 @@ export declare function incarnationReadOf(store: Pick<SessionStore, "incarnation
 export declare function sessionFaceReadOf(store: object | undefined): SessionFaceReader | undefined;
 /**
  * session-sync **整段换装**(replace)时化身的去留 —— 三只店共用的一句判据:换装删掉再插回的是**同一位住客**的那一行
- * (删除带属主门),所以行在、属主相同、化身非空 ⇒ 沿用;行不在(这是一次新建)或还是空的存量形 ⇒ 铸一只新的。
+ * (删除带属主门),所以行在、属主相同、那一格里有一只令牌(唯一解码 {@link incarnationFromCell} 的 `absent` 读法)⇒ 沿用;
+ * 行不在(这是一次新建)或还是空的存量形 ⇒ 铸一只新的。
  */
-export declare function carriedIncarnation(prior: {
+export declare function carriedIncarnation(sessionId: string, prior: {
     owner?: unknown;
     incarnation?: unknown;
 } | undefined, owner: string | null): string;