@sema-agent/server 7.134.0 → 7.136.0

package/dist/sandbox-pkg-source.js

@@ -1,5 +1,5 @@
-import { httpUrlFlaws } from "@sema-agent/settings-schema";
-import { buildHttpUrlRefusal } from "./url-refusal.js";
+import { findUrlCredential, httpUrlFlaws } from "@sema-agent/settings-schema";
+import { buildHttpUrlRefusal, buildUrlCredentialRefusal } from "./url-refusal.js";
 const GLOBAL_ENV = {
     PIP_INDEX_URL: "https://pypi.org/simple",
     UV_DEFAULT_INDEX: "https://pypi.org/simple",
@@ -45,14 +45,17 @@ export function derivePkgSourceEnv(profile, custom) {
             return { SEMA_PKG_SOURCE: profile };
     }
 }
-export function buildCustomPkgSourceRefusal(envName, raw, flaws) {
-    return (`${buildHttpUrlRefusal(envName, raw, flaws)} — with SANDBOX_PKG_SOURCE=custom this address is written verbatim into the environment of every sandbox ` +
-        `(e2b VM / k8s pod), where any process the model can run reads it back with \`env\`; an address that carries userinfo, or whose shape cannot be judged ` +
+export function buildCustomPkgSourceRefusal(envName, raw, problem) {
+    const head = problem === "not-http-url" ? buildHttpUrlRefusal(envName, raw, ["not-http-url"]) : buildUrlCredentialRefusal(envName, raw, problem);
+    const drop = problem !== "not-http-url" && problem.reason === "url_credential_param" ? `drop the "${problem.name}" parameter` : "drop the userinfo";
+    return (`${head} — with SANDBOX_PKG_SOURCE=custom this address is written verbatim into the environment of every sandbox ` +
+        `(e2b VM / k8s pod), where any process the model can run reads it back with \`env\`; an address that carries a credential (userinfo, or a query / fragment ` +
+        `parameter named like one — the names the service's log redactor treats as credentials), or whose shape cannot be judged ` +
         `credential-free (not http(s)://host[:port][/path], or containing a backslash — the URL standard reads it as "/", package managers do not), would hand ` +
         `the deployment's package-source credential to the model, so the server refuses to start rather than forward or rewrite it. ` +
         `Way out: (1) set ${envName} to the credential-free address and give the package manager its credential through its own channel — a token variable ` +
         `named in the lane's name list (E2B_SANDBOX_ENV / K8S_SANDBOX_ENV; naming it accepts that every process in the sandbox, the model included, can read it) ` +
-        `or a credential file baked into the sandbox image; (2) if the source needs no authentication, drop the userinfo.`);
+        `or a credential file baked into the sandbox image; (2) if the source needs no authentication, ${drop}.`);
 }
 export function customPkgSourceFromEnv(env = process.env) {
     const addresses = {
@@ -68,9 +71,11 @@ export function customPkgSourceFromEnv(env = process.env) {
         const [name, raw] = addresses[field];
         if (!raw)
             continue;
-        const flaws = raw.includes("\\") ? ["not-http-url"] : httpUrlFlaws(raw, ["userinfo"]);
-        if (flaws.length > 0)
-            throw new Error(buildCustomPkgSourceRefusal(name, raw, flaws));
+        if (raw.includes("\\") || httpUrlFlaws(raw, []).length > 0)
+            throw new Error(buildCustomPkgSourceRefusal(name, raw, "not-http-url"));
+        const credential = findUrlCredential(raw);
+        if (credential !== undefined)
+            throw new Error(buildCustomPkgSourceRefusal(name, raw, credential));
         out[field] = raw;
     }
     return out;

package/dist/sealed-key.d.ts

@@ -15,7 +15,7 @@ export interface SealedKeyOpener {
     open(ciphertextB64: string, publicKeyId: string): string;
 }
 /**
- * S-737 —— the store's **discovery-safe face**: ONLY the newest public key. This is what the HTTP layer is handed
+ * [ref] —— the store's **discovery-safe face**: ONLY the newest public key. This is what the HTTP layer is handed
  * (`ServiceDeps.sealedKeyPublic` → `GET /v1/capabilities` `sealedKey`) — never the whole store — so private-key
  * material, the custody path and the held-id list are structurally unreachable from that layer (not merely
  * "not read"). Built from a live store by {@link buildSealedKeyPublicFace}, which copies out `latest` alone.
@@ -37,7 +37,7 @@ export interface SealedKeyStore extends SealedKeyOpener, SealedKeyPublicFace {
  *  reachable through it, whatever the caller later casts it to). Plain data ⇒ `build*`. */
 export declare function buildSealedKeyPublicFace(store: SealedKeyPublicFace): SealedKeyPublicFace;
 /**
- * S-737 —— the `GET /v1/capabilities` `sealedKey` segment: exactly three keys — the algorithm (the pinned v1
+ * [ref] —— the `GET /v1/capabilities` `sealedKey` segment: exactly three keys — the algorithm (the pinned v1
  * {@link SEALED_KEY_ALG}, never a hand-copied literal), the id to write into `sealedApiKey.publicKeyId`, and the
  * base64 X25519 public key to `crypto_box_seal` against. `createdAt` is deliberately NOT projected (it answers
  * nothing a sealer needs; the wire keeps to the three keys the contract names).
@@ -54,6 +54,25 @@ export declare function projectSealedKeyCapability(face: SealedKeyPublicFace | u
 /** Default id = fingerprint of the RAW public-key bytes: `exec-<sha256(pk)[0..12) hex>`.
  *  Deterministic → regenerating the id from the same key file is stable across boots. */
 export declare function deriveKeyId(publicKeyRaw: Uint8Array): string;
+/** {@link judgeSealedKeyPublicKey} 的拒因(闭集)。 */
+export type SealedKeyPublicKeyFlaw = "non_canonical_base64" | "bad_length" | "small_order";
+/** 公钥判官的拒(类型化;`flaw` 闭集)。公钥是公开材料,句子里点名它无妨;从不带私钥 / 密文。 */
+export declare class SealedKeyPublicKeyRefusedError extends Error {
+    readonly flaw: SealedKeyPublicKeyFlaw;
+    constructor(flaw: SealedKeyPublicKeyFlaw);
+}
+/**
+ * **X25519 公钥的唯一判官** —— 保管店装载({@link ensureSealedKeyStore},每份钥匙文件)、向中心登记({@link reportExecutionPublicKey})、
+ * 封之前({@link createCheckpointCtxSealing},对着最新那把)三处同读这一只;过了交回原始 32 字节,不过抛 {@link SealedKeyPublicKeyRefusedError}。
+ *  1. **规范 base64**:解出来的字节再编码回去必须逐字等于原串 —— 一句话盖住字母表、补齐、填充位三件(一把钥匙只有一种写法);
+ *  2. **32 字节**;
+ *  3. **不是小阶点**:对 {@link SMALL_ORDER_PROBE_SCALAR} 做 `crypto_scalarmult`,结果全零 ⇔ 小阶(libsodium 此时不交结果、抛 `weak public key`)。
+ * 判法取「标量乘结果全零」而不是手抄小阶点表:与 noble 同一判(`x25519.getSharedSecret` 零结果即抛,包侧 `bad_public_key` 读的就是它)、
+ * 就是 RFC 7748 §6.1 要求的那一检;非规范编码(p、p+1)与第 255 位置位的写法由 X25519 自己的约化 / 掩位盖住,不必逐个列;
+ * 高位别名(第 255 位置位、掩掉后是同一个非小阶点)照收 —— 两边同口径。依赖已在树里(libsodium),不新增一张要人维护的表。
+ * 前置:libsodium 已就绪(三处调用方都先等过它);没就绪 ⇒ 当场抛普通错误(不是判决)。
+ */
+export declare function judgeSealedKeyPublicKey(publicKeyB64: string): Uint8Array;
 /**
  * Load every keypair under `dir` (creating dir + ONE fresh keypair when none exist) and return the
  * custody store. Invalid/corrupt files are skipped with a warn (they may be an OLD format or a
@@ -79,7 +98,7 @@ export type CheckpointCtxKeyStore = SealedKeyStore & {
  */
 export declare function ensureCheckpointCtxSealing(sealedKeyDir: string, logger?: Logger): Promise<CheckpointCtxSealing>;
 /**
- * 停驻行凭据的**封签器**(S-1907;形与规则的属主 = `http/checkpoint-ctx.ts` 末段「凭据位密封」)—— 从**这一域自己的**保管店派生(生产 = {@link ensureCheckpointCtxSealing};
+ * 停驻行凭据的**封签器**([ref];形与规则的属主 = `http/checkpoint-ctx.ts` 末段「凭据位密封」)—— 从**这一域自己的**保管店派生(生产 = {@link ensureCheckpointCtxSealing};
  * 入参型 {@link CheckpointCtxKeyStore}:模型钥匙那只店进不来),信封是:封进密文的明文是 `JSON.stringify([CHECKPOINT_CTX_SEAL_ALG, sessionId, value])`。
  *  · **封**:对着保管店**最新**那把公钥 `crypto_box_seal`(只用公钥);封签记下那把钥匙的 id。
  *  · **开**:按封签上的 id **精确**选私钥(保管店的 `open`,不逐把试),再判信封:三元数组、首元是本信封的词、第二元是**这一行的会话 id**,交回第三元(封进去的 JSON 值,任何类型) ——

package/dist/sealed-key.js

@@ -27,6 +27,37 @@ function b64ToBytes(b64, what) {
         throw new Error(`${what}: not valid base64`);
     return new Uint8Array(Buffer.from(b64, "base64"));
 }
+export class SealedKeyPublicKeyRefusedError extends Error {
+    flaw;
+    constructor(flaw) {
+        super(`sealed-key public key refused (${flaw}): ${SEALED_KEY_PUBLIC_KEY_FLAW_TEXT[flaw]}`);
+        this.name = "SealedKeyPublicKeyRefusedError";
+        this.flaw = flaw;
+    }
+}
+const SEALED_KEY_PUBLIC_KEY_FLAW_TEXT = {
+    non_canonical_base64: "not the canonical standard-base64 spelling of 32 bytes (alphabet A-Z a-z 0-9 + /, `=` padding, zero padding bits)",
+    bad_length: "does not decode to 32 bytes",
+    small_order: "an X25519 small-order point — anything sealed against it can be opened without the private key",
+};
+const SMALL_ORDER_PROBE_SCALAR = new Uint8Array(32).fill(7);
+export function judgeSealedKeyPublicKey(publicKeyB64) {
+    const sodium = _sodium;
+    if (typeof sodium.crypto_scalarmult !== "function")
+        throw new Error("judgeSealedKeyPublicKey: libsodium is not initialized — await its ready promise first");
+    const bytes = new Uint8Array(Buffer.from(publicKeyB64, "base64"));
+    if (Buffer.from(bytes).toString("base64") !== publicKeyB64)
+        throw new SealedKeyPublicKeyRefusedError("non_canonical_base64");
+    if (bytes.length !== sodium.crypto_box_PUBLICKEYBYTES)
+        throw new SealedKeyPublicKeyRefusedError("bad_length");
+    try {
+        sodium.crypto_scalarmult(SMALL_ORDER_PROBE_SCALAR, bytes);
+    }
+    catch {
+        throw new SealedKeyPublicKeyRefusedError("small_order");
+    }
+    return bytes;
+}
 export async function ensureSealedKeyStore(dir, logger) {
     await _sodium.ready;
     const sodium = _sodium;
@@ -40,9 +71,9 @@ export async function ensureSealedKeyStore(dir, logger) {
             if (raw.alg !== SEALED_KEY_ALG || typeof raw.publicKey !== "string" || typeof raw.privateKey !== "string" || typeof raw.publicKeyId !== "string") {
                 throw new Error("missing/unsupported fields");
             }
-            const publicKey = b64ToBytes(raw.publicKey, "publicKey");
+            const publicKey = judgeSealedKeyPublicKey(raw.publicKey);
             const privateKey = b64ToBytes(raw.privateKey, "privateKey");
-            if (publicKey.length !== sodium.crypto_box_PUBLICKEYBYTES || privateKey.length !== sodium.crypto_box_SECRETKEYBYTES)
+            if (privateKey.length !== sodium.crypto_box_SECRETKEYBYTES)
                 throw new Error("bad key length");
             if (name !== `${raw.publicKeyId}.json`)
                 logger?.warn("sealed_key_filename_drift", { file: name, publicKeyId: raw.publicKeyId, note: "content publicKeyId wins; rename the file to silence this" });
@@ -53,7 +84,7 @@ export async function ensureSealedKeyStore(dir, logger) {
             keys.set(raw.publicKeyId, { publicKey, privateKey, publicKeyB64: raw.publicKey, createdAt: typeof raw.createdAt === "string" ? raw.createdAt : "" });
         }
         catch (err) {
-            logger?.warn("sealed_key_file_unreadable", { file: path, errKind: err instanceof Error ? err.name : "unknown", note: "skipped (NOT deleted) — ciphertexts sealed for this key will fail loud per-model" });
+            logger?.warn("sealed_key_file_unreadable", { file: path, errKind: err instanceof Error ? err.name : "unknown", ...(err instanceof SealedKeyPublicKeyRefusedError ? { flaw: err.flaw } : {}), note: "skipped (NOT deleted) — ciphertexts sealed for this key will fail loud per-model" });
         }
     }
     if (keys.size === 0) {
@@ -101,7 +132,7 @@ export function createCheckpointCtxSealing(store) {
     if (typeof sodium.crypto_box_seal !== "function")
         throw new Error("createCheckpointCtxSealing: libsodium is not initialized — build the store with ensureSealedKeyStore() first");
     const { publicKeyId } = store.latest;
-    const publicKey = b64ToBytes(store.latest.publicKey, "publicKey");
+    const publicKey = judgeSealedKeyPublicKey(store.latest.publicKey);
     const sealing = createUncheckedCheckpointCtxSealing(store, publicKeyId, publicKey);
     const probeSession = "sealed-key-self-test";
     let roundTrip;
@@ -144,6 +175,18 @@ function createUncheckedCheckpointCtxSealing(store, publicKeyId, publicKey) {
 }
 export async function reportExecutionPublicKey(opts) {
     const { baseUrl, adminToken, key, notes, logger } = opts;
+    await _sodium.ready;
+    try {
+        judgeSealedKeyPublicKey(key.publicKey);
+    }
+    catch (err) {
+        logger?.warn("sealed_key_public_key_refused", {
+            publicKeyId: key.publicKeyId,
+            ...(err instanceof SealedKeyPublicKeyRefusedError ? { flaw: err.flaw } : { errKind: err instanceof Error ? err.name : "unknown" }),
+            note: "this public key is not registered with the center and not printed for manual registration — fix or remove the key file in the sealed-key directory and restart",
+        });
+        return;
+    }
     const manual = (why) => {
         logger?.warn("sealed_key_public_key", {
             publicKeyId: key.publicKeyId,

package/dist/security.d.ts

@@ -1,9 +1,10 @@
 import type { IncomingMessage } from "node:http";
 import { type SessionPlacementRecord, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
+import { type DeploymentShapeInput } from "./deployment-shape.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 SessionFace } 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
@@ -19,7 +20,7 @@ export interface SessionListItem {
     /** K-5c (shell §K): the latest run's task_id — the shell's one-hop live-tail re-attach anchor on resume. */
     lastRunId: string | null;
     /** [ref]([ref]/[ref]):the LATEST run's **engine run id**(`TaskResult.runId`)when known —— OMIT-when-absent,
-     *  恒不铸 null。所有 lister(SQL 双生、local 会话店 —— 它的 run 店是必填位)从 latest run 的 `result` JSON 提取(终局与 park 时写、认领续跑即清空 —— S-173
+     *  恒不铸 null。所有 lister(SQL 双生、local 会话店 —— 它的 run 店是必填位)从 latest run 的 `result` JSON 提取(终局与 park 时写、认领续跑即清空 —— [ref]
      *  ⇒ 在跑 latest 键诚实缺席)。
      *  读法一致:缺席 = 「此行无已知 engine runId」,禁读成其它含义。⚠️ 与 `lastRunId`(= latest run 的 **task_id**)
      *  是两条身份轴,命名对齐 core `SessionStoreSummary.lastTaskRunId`。wire:additive 键零投影透传
@@ -55,7 +56,7 @@ export declare function isDestructiveSessionWrite(method: string, url: string):
 declare const principalBrand: unique symbol;
 declare const durableOwnerKeyBrand: unique symbol;
 /**
- * 🔴 **两个 owner 不是同一个东西**(S-487 RH-3,类型事实):
+ * 🔴 **两个 owner 不是同一个东西**([ref] RH-3,类型事实):
  *  · {@link Principal} —— **这次请求**验过的调用方身份。铸点闭集:`http/principal-gate.ts` 的 `gatedPrincipal`(验身份的那一只),以及属主存取器
  *    (`http/owner-access.ts`)里一只「上游已验」的适配口(调用方身份经一只纯串结构转手过来的腿 —— 第二期随那只结构带品牌而删);
  *  · {@link DurableOwnerKey} —— **行上 / 存储键里**落下的属主(run 行、会话行的 `owner` 列)。铸点闭集:属主存取器读行处与 {@link sessionOwnerCellOf}。
@@ -73,7 +74,7 @@ export declare function mintPrincipal(verified: string): Principal;
 /** {@link DurableOwnerKey} 的铸造口(只在铸点闭集里调,见上)。 */
 export declare function mintDurableOwnerKey(persisted: string): DurableOwnerKey;
 /**
- * 会话行属主门读的那一格(S-1770):有主的行只有属主;**无主的行**另带「它是不是委派子代的 placed 行」(店的 `placementOf` 答,{@link sessionOwnerCellOf} 读;
+ * 会话行属主门读的那一格([ref]):有主的行只有属主;**无主的行**另带「它是不是委派子代的 placed 行」(店的 `placementOf` 答,{@link sessionOwnerCellOf} 读;
  * 不实现 placement 的店没有 placed 行)。`placed` 只在无主时存在 —— 有主的行属主门不看它。
  */
 export type SessionOwnerCell = {
@@ -89,7 +90,7 @@ export interface SessionCaller {
     readonly fleet: boolean;
 }
 /**
- * 🔴 **会话行属主门上「无主行放行」臂的唯一判据**(S-1770 读面律;会话面谓词 `sessionOwnerReadable`、fork / 删除 / 同步族的存量互认臂 {@link legacyUnownedSessionOk}、
+ * 🔴 **会话行属主门上「无主行放行」臂的唯一判据**([ref] 读面律;会话面谓词 `sessionOwnerReadable`、fork / 删除 / 同步族的存量互认臂 {@link legacyUnownedSessionOk}、
  * 审批豁免面、notify 面的无主臂都经它,不各写一份):
  *  · 无主的**普通**会话行 ⇒ 成立(各臂照它自己的其余条件);
  *  · 无主的 **placed** 行(委派子代:属主 = 委派树根的属主,`delegated-session-owner.ts`)⇒ 只对 **fleet 调用方**成立({@link SessionCaller}:dev-open 部署上的任何调用方,
@@ -114,7 +115,7 @@ export declare const LEGACY_UNOWNED_AMNESTY_TENANT = "default";
  * fleet 面与 run 读面天然连续,面1/面2 零施工)。
  *
  * 🔒 **三条件缺一不放行**(与第一臂同源,不是兼容臂):
- *   ① 单机形 `!requirePrincipal` —— 多租部署本臂**死路**(header 必到、键必具名);
+ *   ① 单机形(部署形表行 `multiTenant` 不成立)—— 多租部署本臂**死路**(header 必到、键必具名);
  *   ② 存量行恰为无主 `owner === null`、且不是委派子代的 placed 行(无主臂的唯一判据 {@link ownerlessRowOpen})—— 任何具名 owner 的行不受影响;
  *   ③ 调用方恰为 `default` 主 —— 非 default 的具名主对无主行仍走原门(404 / deleted:false)。
  * 反向风险有界:①限定的单机形本就单用户,把无主行判给 default 主不产生跨租外泄。
@@ -137,11 +138,11 @@ export declare const LEGACY_UNOWNED_AMNESTY_TENANT = "default";
  *    它们存在当初那个属主的键下,那个 principal 的 run 照读照生效(7.119.0 前 local 后端重启即把属主忘掉,于是那些规则
  *    在跑、却读不到也删不掉 —— 修在属主落盘,不在放宽本门)。放宽它等于制造一条 fail-open,不在本臂辖域。
  *
- * @param requirePrincipal `config.requirePrincipal`(条件①)
+ * @param deployment 部署形(条件①;读表行 `multiTenant`)
  * @param caller 调用方(条件③ 读它验过的主体;fleet-wide 面不经本臂)
- * @param cell 存量行那一格(条件②:无主,且经无主臂的唯一判据 {@link ownerlessRowOpen} —— 无主的委派子代 placed 行不在本臂,S-1770)
+ * @param cell 存量行那一格(条件②:无主,且经无主臂的唯一判据 {@link ownerlessRowOpen} —— 无主的委派子代 placed 行不在本臂,[ref])
  */
-export declare function legacyUnownedSessionOk(requirePrincipal: boolean, caller: SessionCaller, cell: SessionOwnerCell): boolean;
+export declare function legacyUnownedSessionOk(deployment: DeploymentShapeInput<"principal">, caller: SessionCaller, cell: SessionOwnerCell): boolean;
 /**
  * {@link legacyUnownedSessionOk} 的**条件①③**半支 —— 只判「这个部署形 × 这个调用方」是否落在窄臂辖域内。
  *
@@ -150,14 +151,18 @@ export declare function legacyUnownedSessionOk(requirePrincipal: boolean, caller
  * (`listSessions({ owner, includeUnowned })` 的 `includeUnowned` 位即本函数的返回值)。
  * 单实体读/写点(fork/delete/同步族/workspace)**一律**用三条件齐的 {@link legacyUnownedSessionOk},不要用本函数。
  */
-export declare function legacyUnownedAmnestyOpen(requirePrincipal: boolean, gateOwner: string | null): boolean;
+export declare function legacyUnownedAmnestyOpen(deployment: DeploymentShapeInput<"principal">, gateOwner: string | null): boolean;
+/**
+ * 本仓会话店的面 = core `SessionStore` + 本仓的行面(登记 / 列表 / 换装 / 同步……)。
+ * 🔴 **按 id 读一行只有一只**:core 的 `headOf(id)`(`{ owner, incarnation, leafId }`,同一行一次读;core 7.55.0 [ref] S2)。
+ * 属主 = `headOf(id)?.owner`、住客 = 头的 `incarnation`(比较用 core `compareOccupants`,拿令牌去写用 `sessionFaceOfHead`)、叶子 = 头的 `leafId`
+ * —— 此前本面另有五只按 id 读(`ownerOf` / `incarnationOf` / `sessionFaceOf` / `getHead` / `getLeafId`),全部退役;规则在 `src/session-incarnation.ts` 头注,
+ * 「店有没有这只读」只判 `headReadOf` 一处。
+ */
 export type OwnerAwareSessionStore = SessionStore & {
-    ownerOf?: (sessionId: string) => Promise<string | null | undefined>;
-    /** S-790 / S-506([ref] §2)—— 属主 + **化身**一次读(`undefined` = 无此会话;行在而化身为空 ⇒ 响亮拒)。规则的唯一属主
-     *  是 `src/session-incarnation.ts`。只关心属主的消费点照旧读 `ownerOf`;判「这还是不是同一位住客」的读它。 */
-    sessionFaceOf?: SessionFaceReader;
+    /** 属主登记(core `SessionStore.register` 的契约:对没有行的 id 建行并记下属主,首写赢;对已有的行什么都不做)。读回走 `headOf`。 */
     register?: (sessionId: string, owner: string | null) => Promise<void>;
-    /** S-1770 委派继承律的**认领口** —— 只在记录委派树的店上(SQL 两店,只命中 placed 行;local 店没有):判断时读到的那一位住客仍是无主的 placed 行 ⇒ 写 `owner`,
+    /** [ref] 委派继承律的**认领口** —— 只在记录委派树的店上(SQL 两店,只命中 placed 行;local 店没有):判断时读到的那一位住客仍是无主的 placed 行 ⇒ 写 `owner`,
      *  返回是否写成(只 CAS 子行自己)。唯一调用方 = 停驻挂点的 `settleDelegatedOwner`(`delegated-session-owner.ts`;M23 走同一句 SQL);规则写在那个模块。 */
     claimOwnerless?: OwnerlessClaim;
     /** [ref] placed 分区的元组读口(店的既有读口,一行 PK 读;`undefined` = 普通会话或无此行)。店不交它 = 不实现 placement = 没有 placed 行(local 店)。两个读者:
@@ -184,23 +189,15 @@ export type OwnerAwareSessionStore = SessionStore & {
     sessionSummaryOf?: (sessionId: string) => Promise<SessionListItem | undefined>;
     /** The session row's writable bits (`title` / `pinned`) — the ONLY writer of a user-set title or pin (`title: null` clears it back
      *  to the automatic title; the auto-titler's `setTitleIfNull` fills a NULL title only; the law of the two writers is written in
-     *  `session-row.ts`). **Written on the occupant the caller verified, and only on it**: `face` is the {@link sessionFaceOf} read
+     *  `session-row.ts`). **Written on the occupant the caller verified, and only on it**: `face` is the live occupant (`sessionFaceOfHead` over the `headOf` read)
      *  the caller's gate judged; the write and the read-back are both conditioned on that occupant's incarnation (the same law as
      *  the parked decide leg's two reads, `session-incarnation.ts`). Answers that occupant's list row after the write
      *  ({@link sessionSummaryOf}'s projection); `undefined` = no list row for that occupant (deleted, re-registered by anyone in the
      *  meantime, or a placed session) — nothing was written. A failed write throws. */
     patchSessionMeta?: (sessionId: string, patch: SessionRowPatch, face: SessionFace) => Promise<SessionListItem | undefined>;
-    /** E17 — fork a session's whole history to a NEW session owned by `owner`; null if the source is unknown. */
+    /** E17 — fork a session's whole history to a NEW session; null if the source is unknown. The fork row records `owner` when it is a
+     *  string, else (`null`) the SOURCE row's owner — a copy of an owned history is never anonymous (core `SessionStore.fork`, 7.55.0 S2). */
     fork?: (sourceId: string, owner: string | null) => Promise<string | null>;
-    /** E18 — the session's current leaf `SessionTreeEntry.id` (a cache-bypassing single read), so the resume-at
-     *  turn-capture can pair it with the turn's message eventId. null when the session has no leaf / does not exist. */
-    getLeafId?: (sessionId: string) => Promise<string | null>;
-    /** [ref] 六轮复审:owner+leafId 单行原子快照(SSE watch 探针租户围栏读;两独立读在 delete/reclaim
-     *  缝里可拼出混世代组合)。undefined=无此会话。 */
-    getHead?: (sessionId: string) => Promise<{
-        owner: string | null;
-        leafId: string | null;
-    } | undefined>;
     /** E21 — purge a session's conversation history (session_meta/session_event); idempotent (false if absent).
      *  `owner` is the single-DB-fleet null-safe SQL owner guard on `session_meta.owner` (defense-in-depth — the
      *  route already owner-gates; this pins the DELETE to the authenticated tenant so even a buggy gate can't purge

package/dist/security.js

@@ -1,4 +1,6 @@
 import { uuidv7, PROJECT_ID_REGEX } from "@sema-agent/core";
+import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
+import { headReadOf } from "./session-incarnation.js";
 import { memoryScopeFor } from "./memory-scope.js";
 import { verifyPrincipalJwt } from "./principal-jwt.js";
 import { fieldConflictFacts } from "./field-conflict.js";
@@ -30,11 +32,11 @@ export async function sessionOwnerCellOf(store, sessionId, owner) {
     return { owner: null, placed: placementOf !== undefined && (await placementOf.call(store, sessionId)) !== undefined };
 }
 export const LEGACY_UNOWNED_AMNESTY_TENANT = "default";
-export function legacyUnownedSessionOk(requirePrincipal, caller, cell) {
-    return legacyUnownedAmnestyOpen(requirePrincipal, caller.principal ?? null) && ownerlessRowOpen(cell, caller);
+export function legacyUnownedSessionOk(deployment, caller, cell) {
+    return legacyUnownedAmnestyOpen(deployment, caller.principal ?? null) && ownerlessRowOpen(cell, caller);
 }
-export function legacyUnownedAmnestyOpen(requirePrincipal, gateOwner) {
-    return !requirePrincipal && gateOwner === LEGACY_UNOWNED_AMNESTY_TENANT;
+export function legacyUnownedAmnestyOpen(deployment, gateOwner) {
+    return !DEPLOYMENT_SHAPE_PREDICATES.multiTenant.holds(deployment) && gateOwner === LEGACY_UNOWNED_AMNESTY_TENANT;
 }
 const UUIDV7_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 export function isUuidV7(s) {
@@ -80,20 +82,21 @@ export function createAuthorizer(config, sessionStore) {
             projectId = body.projectId.toLowerCase();
         }
         const requireExisting = body.requireExistingSession === true;
-        const ownerOf = sessionStore.ownerOf?.bind(sessionStore);
+        const headOf = headReadOf(sessionStore);
+        const readOwner = headOf === undefined ? undefined : async (id) => (await headOf(id))?.owner;
         const register = sessionStore.register?.bind(sessionStore);
         const requested = typeof body.sessionId === "string" && body.sessionId ? body.sessionId : undefined;
         let sessionId;
         if (requested) {
-            if (ownerOf) {
-                let owner = await ownerOf(requested);
+            if (readOwner) {
+                let owner = await readOwner(requested);
                 if (owner === undefined) {
                     if (requireExisting) {
                         throw createCodedHttpError(404, "resume.session_not_found", "requireExistingSession: session does not exist (resume.session_not_found)");
                     }
                     if (register) {
                         await register(requested, principal ?? null);
-                        owner = await ownerOf(requested);
+                        owner = await readOwner(requested);
                     }
                     else if (config.requirePrincipal) {
                         throw new HttpError(403, "cannot claim a caller-supplied sessionId on a multi-tenant deployment: this worker's session store cannot record session ownership, so the id would stay unowned and the next caller could attach to it. Configure a durable session backend (SESSION_BACKEND), or omit sessionId to start a new session.");
@@ -101,7 +104,7 @@ export function createAuthorizer(config, sessionStore) {
                 }
                 else if (owner === null && principal !== undefined && !config.requirePrincipal && register) {
                     await register(requested, principal);
-                    owner = await ownerOf(requested);
+                    owner = await readOwner(requested);
                 }
                 const legacyShellOwner = !config.requirePrincipal && owner === "anon:shell-live" && principal === undefined;
                 if (!legacyShellOwner && owner != null && owner !== principal) {

package/dist/server-secret-env.d.ts

@@ -1,14 +1,14 @@
 /**
- * 宿主子进程 env 的**唯一组合点**(7.103.0 起,S-684 残余按类收口)+ 本进程**自有凭据名的唯一声明点**(7.129.0 起,core 7.51.1)。
+ * 宿主子进程 env 的**唯一组合点**(7.103.0 起,[ref] 残余按类收口)+ 本进程**自有凭据名的唯一声明点**(7.129.0 起,core 7.51.1)。
  *
  * ## 病(沿革)
- * 7.99.0 合并复审 F7(web-admin [ref] 实测;安全轴;DEBTS S-684):core 的形状剥(`*_KEY` / `*_TOKEN` …)认不出本仓自己的凭据键
+ * 7.99.0 合并复审 F7(web-admin [ref] 实测;安全轴;DEBTS [ref]):core 的形状剥(`*_KEY` / `*_TOKEN` …)认不出本仓自己的凭据键
  * (`SERVICE_AUTH_TOKENS` / `APPROVAL_HMAC_KEYS` / `OTEL_EXPORTER_OTLP_HEADERS`)⇒ 本仓在 `scrub` 腿上另加目录臂按名剥。7.129.0(web-client
  * 实测):目录臂只在 `scrub` 腿施,`inheritEnv:"all"` 是 `{ ...process.env }` 零剥除、`[names]` 点到目录 secret 名照放 —— 单用户 host 上 cli 交互 lane
  * 每次提交发 `"all"`,引擎自己的 `SERVICE_AUTH_TOKEN(S)` / `APPROVAL_HMAC_KEYS` / `MODEL_API_KEY` 逐字进模型 shell,模型一条 `curl` 可自批自己的 HITL 卡。
  * 病根是本仓自判三个继承词、而只在其中一个词上减自有凭据。
  *
- * ## 律(一句;core #1753 定,本仓只传事实、不判)
+ * ## 律(一句;core [ref] 定,本仓只传事实、不判)
  * 本包任何进程在宿主上 spawn 的子进程:env = 引擎 `inheritedHostEnv(policy, findings)` ∪ 部署方点名放回的键(只在运维真可能要传东西的腿上有旋钮),
  * 剥掉的键经一个登记过的 `SecretEnvScrubSite` 留痕(现场按**腿**命名);git 腿再叠 git 自己的两件({@link gitSubprocessEnv})。射程 = **每一条**宿主腿:
  * src 里每一只值引 `node:child_process` 的文件都是登记腿、其中每一次起子进程都显式交组合出的 env(普查门在 `test/secret-env-scrub-host-legs.test.ts`)。
@@ -28,13 +28,13 @@
  *    抛同路)。能力词 `inherit_env.own_credentials_withheld` 在本进程的事实 =
  *    {@link ownCredentialsWithheld}:最近一次成功声明的集合 ⊇ 当前生效配置应声明的集合(活配置经 {@link bindOwnCredentialsConfig} 在 `loadConfig()` 之后绑一次;
  *    未绑 / 未声明 ⇒ false,事实读不到应声明集合就不答 true)。
- *  · **值臂**(core 7.52.0 #1754):声明是一张表 `{ names, values }`。`values` = 本进程持有凭据的变量此刻的值(目录 secret 名 ∪ 模型条目 `apiKeyEnv`,{@link serverCredentialValueSources}),
+ *  · **值臂**(core 7.52.0 [ref]):声明是一张表 `{ 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,一只谓词各处用)
+ * ## 点名放行([ref] / [ref],一只谓词各处用)
  * {@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` 同名选项同义,点到自有凭据名即拒),不经本谓词。
@@ -57,7 +57,7 @@ export type ModelApiKeyEnvTable = Readonly<Record<string, string>>;
  */
 export declare function serverWithheldEnvNames(modelApiKeyEnv?: ModelApiKeyEnvTable): readonly string[];
 /**
- * 本进程**持有凭据值**的变量名(值臂的来源;core 7.52.0 #1754):目录 secret 名 ∪ 模型条目 `apiKeyEnv` 的值 —— 名单与值臂两臂同一张表派生,只少名单型旋钮名(它们的值是
+ * 本进程**持有凭据值**的变量名(值臂的来源;core 7.52.0 [ref]):目录 secret 名 ∪ 模型条目 `apiKeyEnv` 的值 —— 名单与值臂两臂同一张表派生,只少名单型旋钮名(它们的值是
  * 一张变量名单,不是凭据)。纯函数,排序只为读数稳定。
  */
 export declare function serverCredentialValueSources(modelApiKeyEnv?: ModelApiKeyEnvTable): readonly string[];
@@ -111,7 +111,7 @@ export interface HostSubprocessEnvRequest {
  * 调用时机 = 每次要交 env 时现算一次(`process.env` 在本仓是 boot 期输入,各次同值;计数因此是「每组合一次」)。
  * 引擎对坏策略 / 点到自有凭据名的白名单在这里**抛**(spawn 时的拒是不变量;构造时的拒由各构造点自己先问 `inheritEnvPolicyProblem`)。
  *
- * 🔴 **git 的 env 配置族与代理变量一族只有 core 一只写手**:core 7.35.0 #1201(S-877)起它们是 core 的**豁免族** —— `GIT_CONFIG_COUNT` / `GIT_CONFIG_PARAMETERS` /
+ * 🔴 **git 的 env 配置族与代理变量一族只有 core 一只写手**:core 7.35.0 [ref]([ref])起它们是 core 的**豁免族** —— `GIT_CONFIG_COUNT` / `GIT_CONFIG_PARAMETERS` /
  * `GIT_CONFIG_KEY_<数字>` / `GIT_CONFIG_VALUE_<数字>`(大写)与 `http(s)_proxy` / `all_proxy` / `no_proxy` / `npm_config_*proxy` …(任意大小写),名与值都不读、
  * **原样交出,凭据在内**(部署面:凭据不放本进程 env —— `docs/DEPLOY-PREREQS.md`)。本仓不重判;本进程自有凭据名单不含这两族的名字
  * (钉:`test/secret-env-git-config-pair.test.ts`「一只写手」格)。
@@ -120,7 +120,7 @@ export interface HostSubprocessEnvRequest {
 export declare function hostSubprocessEnv(o: HostSubprocessEnvRequest): NodeJS.ProcessEnv;
 /**
  * {@link hostSubprocessEnv} 的**组合本体**(不披露、不计数)—— 同一只组合,两个入口:真要交给子进程的现场经 `hostSubprocessEnv`(组合 + 披露);
- * 只想知道「子进程**会**拿到什么」的读者(core 7.49.0 #1554:host 车道的 `ExecutionEnv.cdPath` 要报子进程真拿到的 `CDPATH`)读这一只 ——
+ * 只想知道「子进程**会**拿到什么」的读者(core 7.49.0 [ref]:host 车道的 `ExecutionEnv.cdPath` 要报子进程真拿到的 `CDPATH`)读这一只 ——
  * 既不另写一份组合(第二份会漂),也不把一次没发生的 spawn 记进剥除计数。`findings` 是组合点自己的收集器(引擎把形状臂与自有凭据臂的每一条扣下都推进去)。
  */
 export declare function composeHostSubprocessEnv(o: Omit<HostSubprocessEnvRequest, "site">, findings?: SecretEnvFinding[]): NodeJS.ProcessEnv;
@@ -143,10 +143,10 @@ export declare function gitSubprocessEnv(o: {
     isolateConfig: boolean;
 }): NodeJS.ProcessEnv;
 /**
- * S-699 —— **点名放行**的唯一谓词:从 `env` 里把 `names` 点到的键**原样**取出(值逐字,空串照带;源里没有的名不产生
+ * [ref] —— **点名放行**的唯一谓词:从 `env` 里把 `names` 点到的键**原样**取出(值逐字,空串照带;源里没有的名不产生
  * 条目)。密钥形的键点到了也照取 —— 点名即部署方显式承担;要不要在这之上再叠别的基底,是调用方的事(见文件头「点名放行」节)。
  * 纯函数,不留痕:点名放回的键不是剥除,不进 `secret_env_scrubbed` 的键表与计数。
- * 返回形 `Record<string, string>`(S-713):只装源里在的键,值恒是字符串 —— 沙箱两腿(`sandboxEnv` / docker `env`)要的正是这个形,
+ * 返回形 `Record<string, string>`([ref]):只装源里在的键,值恒是字符串 —— 沙箱两腿(`sandboxEnv` / docker `env`)要的正是这个形,
  * 不必在调用点再过滤一遍 `undefined`。
  */
 export declare function allowlistedEnv(names: readonly string[], env: NodeJS.ProcessEnv): Record<string, string>;

package/dist/session-children-retire.d.ts

@@ -1,5 +1,5 @@
 /**
- * S-790 件B([ref] §3)—— **删会话带走以它为根的后台子代**:一只会话被删,以它为根的子代跟着结束 —— parked 的作废
+ * [ref] 件B([ref] §3)—— **删会话带走以它为根的后台子代**:一只会话被删,以它为根的子代跟着结束 —— parked 的作废
  * (行转终态,审批卡随之离开待决面),在跑的停掉。**这件事做完,才删会话元数据**(调用方:`boot/session-faces.ts` 的删除协调器)。
  *
  * ## 两步、两种失败,类型上分开(合并复审 gpt-6 腿 [high] 之后的形,裁定 2026-09-28)

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

@@ -1,19 +1,19 @@
 /**
- * 🔴 **core `SessionError` 闭集 → HTTP 的唯一映射**(S-612,server 7.104.0;设计稿 [ref] §2.1)。
+ * 🔴 **core `SessionError` 闭集 → HTTP 的唯一映射**([ref],server 7.104.0;设计稿 [ref] §2.1)。
  *
  * ## 为什么要一只属主
  * 修前 wire 上只有**一处**认得 `SessionError` 的码:`http/routes/session-sync.ts` 的暂存导入腿把 `invalid_session`
- * 手写成 422。其余每一条路都把它交给全局兜底 ⇒ `500 internal.error "internal error"`,码丢。core 7.30.0(#1041)
+ * 手写成 422。其余每一条路都把它交给全局兜底 ⇒ `500 internal.error "internal error"`,码丢。core 7.30.0([ref])
  * 给文件会话店铸了 `corrupt_session`(存档没有会话头 ⇒ 这只会话唤不醒),而它在 wire 上一个名字都没有
- * (真跑读数见 S-612 收车档 §0:冷启动时三条提交口与每一条经归属探针 / 读存档碰到它的口都答 500 `internal.error`;
+ * (真跑读数见 [ref] 收车档 §0:冷启动时三条提交口与每一条经归属探针 / 读存档碰到它的口都答 500 `internal.error`;
  * owner 已知时同步口是 200 + failed 体、并照常走计费收尾)。
  *
  * ## 为什么多一个 `face` 参数(而不是单参)
  * core 的 `invalid_session` 是**同词两义**(亲读 dist:`engine/session/import-validate.js` 的导入门拒调用方交来的
- * 日志,`engine/session/storage-base.js` 的建树 / 走根拒**已存**日志里指向缺席条目的叶子或祖先 —— 后者即 core #1077)。
+ * 日志,`engine/session/storage-base.js` 的建树 / 走根拒**已存**日志里指向缺席条目的叶子或祖先 —— 后者即 core [ref])。
  * 本仓对它的成文义是前者(调用方的日志没过校验 ⇒ 422),而后者今天在打开会话的各口上答的是通用 500 / 同步口
- * 200 + failed(S-612 的 3b 负控格钉住这一形,#1077 落地后按 core 的新码再对一次)。单参签名装不下这件事:要么
- * 打开面的每个消费点都写一句 `code === "corrupt_session"` 特判,要么把 #1077 形从今天的应答改成「你交的日志坏了」。
+ * 200 + failed([ref] 的 3b 负控格钉住这一形,[ref] 落地后按 core 的新码再对一次)。单参签名装不下这件事:要么
+ * 打开面的每个消费点都写一句 `code === "corrupt_session"` 特判,要么把 [ref] 形从今天的应答改成「你交的日志坏了」。
  * ⇒ 面是映射的一维,写进属主,不散在消费点。
  *  · `"open"`   —— 为某只会话**打开它已存的日志**(提交各腿的引擎 prepare、鉴权门的归属探针、直接读会话的口);
  *  · `"import"` —— 校验 / 写入**调用方交来的**日志(2c session-sync 的暂存导入)。
@@ -24,7 +24,7 @@
  *    原样上 wire,契约既有立场:不为上游码铸孪生码)。三种会话后端同词:文件店由 core 铸,两只 SQL 店由
  *    `plugins/session-event-payload.ts` 铸(坏的 `session_event.payload` 行)。
  *  · `invalid_session` —— `import` 面 **422 `invalid_entries`**(修前 session-sync 的那一行,码位 / 状态逐字不变);
- *    `open` 面留白(#1077 形,见上)。
+ *    `open` 面留白([ref] 形,见上)。
  *  · `not_found` —— 留白:每一面各有自己的「不存在」答法(404 `not_found.session` / 同步口的 `resume.session_not_found` /
  *    列表里的缺席),码位各不相同,不由本表统一。
  *  · `placement_refused` —— `import` 面 **409 `conflict.session_placed`**(机读位 `detail.placement_kind`,固定句);`open` 面留白。