@sema-agent/server 7.132.0 → 7.134.0

package/dist/sandbox-pkg-source.d.ts

@@ -14,7 +14,16 @@
  *
  * The marker `SEMA_PKG_SOURCE` always rides along: the image's pkg-source.sh hook (pod-start / profile.d)
  * materializes the file-bound pieces from it; images without the hook simply ignore it.
+ *
+ * ## One law: no URL that rides into the model-visible sandbox env carries userinfo
+ * Everything this module derives lands in the env of every sandbox process — including the ones the model drives
+ * (`env`, `printenv`) — so `https://user:pass@mirror/…` among the `custom` addresses would hand the deployment's
+ * package-source credential to the model. {@link customPkgSourceFromEnv} is the ONE reader of the six addresses and the
+ * one place that judges them: the shared URL-shape judge (`httpUrlFlaws`, the same one MEMORY_EMBEDDER_ENDPOINT /
+ * A2A_SERVE_URL answer to) says no ⇒ it throws, startup refuses. Never stripped, never rewritten, never forwarded
+ * quietly. The request face has no package-source address key at all (deployment face only).
  */
+import { type HttpUrlFlaw } from "@sema-agent/settings-schema";
 /** Explicit URLs for `custom` (RFC B: 极端情况出口). Read from the service process env (operator-trusted). */
 export interface CustomPkgSource {
     aptMirror?: string;
@@ -29,6 +38,15 @@ export interface CustomPkgSource {
  * profile (unset = byte-identical sandbox — the B5 backward-compat contract).
  */
 export declare function derivePkgSourceEnv(profile: string | undefined, custom?: CustomPkgSource): Record<string, string>;
-/** Read the `custom` explicit-URL set from the service process env (operator-trusted deployment config). */
+/**
+ * The refusal sentence for one address (pure data): the shared judge's rule words + the value's origin only
+ * ({@link buildHttpUrlRefusal}), then why it matters here and the two ways out. No byte of the credential can reach it.
+ */
+export declare function buildCustomPkgSourceRefusal(envName: string, raw: string, flaws: readonly HttpUrlFlaw[]): string;
+/**
+ * Read the `custom` explicit-URL set from the service process env (operator-trusted deployment config) — the ONE reader and
+ * the ONE judge of those six addresses (see the module header). An address the shared judge refuses (userinfo, or a shape
+ * that is not a parseable http(s) URL) throws {@link buildCustomPkgSourceRefusal}; empty / unset = not set.
+ */
 export declare function customPkgSourceFromEnv(env?: NodeJS.ProcessEnv): CustomPkgSource;
 //# sourceMappingURL=sandbox-pkg-source.d.ts.map

package/dist/sandbox-pkg-source.js

@@ -1,3 +1,5 @@
+import { httpUrlFlaws } from "@sema-agent/settings-schema";
+import { buildHttpUrlRefusal } from "./url-refusal.js";
 const GLOBAL_ENV = {
     PIP_INDEX_URL: "https://pypi.org/simple",
     UV_DEFAULT_INDEX: "https://pypi.org/simple",
@@ -43,14 +45,34 @@ 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 ` +
+        `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.`);
+}
 export function customPkgSourceFromEnv(env = process.env) {
-    return {
-        ...(env.SEMA_APT_MIRROR ? { aptMirror: env.SEMA_APT_MIRROR } : {}),
-        ...(env.SEMA_PIP_INDEX ? { pipIndex: env.SEMA_PIP_INDEX } : {}),
-        ...(env.SEMA_UV_INDEX ? { uvIndex: env.SEMA_UV_INDEX } : {}),
-        ...(env.SEMA_UV_PY_MIRROR ? { uvPyMirror: env.SEMA_UV_PY_MIRROR } : {}),
-        ...(env.SEMA_NPM_REGISTRY ? { npmRegistry: env.SEMA_NPM_REGISTRY } : {}),
-        ...(env.SEMA_NODE_MIRROR ? { nodeMirror: env.SEMA_NODE_MIRROR } : {}),
+    const addresses = {
+        aptMirror: ["SEMA_APT_MIRROR", env.SEMA_APT_MIRROR],
+        pipIndex: ["SEMA_PIP_INDEX", env.SEMA_PIP_INDEX],
+        uvIndex: ["SEMA_UV_INDEX", env.SEMA_UV_INDEX],
+        uvPyMirror: ["SEMA_UV_PY_MIRROR", env.SEMA_UV_PY_MIRROR],
+        npmRegistry: ["SEMA_NPM_REGISTRY", env.SEMA_NPM_REGISTRY],
+        nodeMirror: ["SEMA_NODE_MIRROR", env.SEMA_NODE_MIRROR],
     };
+    const out = {};
+    for (const field of Object.keys(addresses)) {
+        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));
+        out[field] = raw;
+    }
+    return out;
 }
 //# sourceMappingURL=sandbox-pkg-source.js.map

package/dist/sealed-key.d.ts

@@ -1,4 +1,5 @@
 import type { Logger } from "./observability/logger.js";
+import { type CheckpointCtxSealing } from "./http/checkpoint-ctx.js";
 /** Algorithm tag — MUST equal registry-core's `SEALED_BOX_ALG` (v1 sole value; a different alg on
  *  the wire is a loud per-model rejection in applyEffective, never a guess). */
 export declare const SEALED_KEY_ALG = "libsodium-sealedbox-x25519";
@@ -61,6 +62,36 @@ export declare function deriveKeyId(publicKeyRaw: Uint8Array): string;
  * zero loadable keys AND generation failed).
  */
 export declare function ensureSealedKeyStore(dir: string, logger?: Logger): Promise<SealedKeyStore>;
+declare const checkpointCtxKeyStoreBrand: unique symbol;
+/**
+ * 停驻行封签那一域的保管店(品牌型):读口与 {@link SealedKeyStore} 同形,型不同 —— {@link createCheckpointCtxSealing} 只收它,模型钥匙那只店交进去是 tsc 错
+ * (「两域并成一对钥匙」那条路在型面上关掉,不靠注释)。唯一铸点 = {@link ensureCheckpointCtxSealing} 建店处(经 {@link mintCheckpointCtxKeyStore});
+ * 品牌断言的普查在 `test/owner-gate-single-owner.test.ts` ⑤b。
+ */
+export type CheckpointCtxKeyStore = SealedKeyStore & {
+    readonly [checkpointCtxKeyStoreBrand]: true;
+};
+/**
+ * 停驻行封签器的**生产工厂**(起服 web-admin 运行时与嵌入方同调这一只):在 `sealedKeyDir`(`<数据根>/sealed-key`)之下的 {@link CHECKPOINT_CTX_KEY_SUBDIR}
+ * 建这一域自己的保管店(同一只 {@link ensureSealedKeyStore}:目录 0700、钥匙文件 0600、空目录生成一把、读不了的文件跳过不删),再交 {@link createCheckpointCtxSealing}。
+ * 钥匙只在这里读进内存(起服一次):进程运行中补进目录的钥匙文件要重启才认。
+ * 抛 = 这一域没有封签器(目录建不了 / 改不了权限,或钥匙文件公私不配对);调用方当「没有封签器」处置。
+ */
+export declare function ensureCheckpointCtxSealing(sealedKeyDir: string, logger?: Logger): Promise<CheckpointCtxSealing>;
+/**
+ * 停驻行凭据的**封签器**(S-1907;形与规则的属主 = `http/checkpoint-ctx.ts` 末段「凭据位密封」)—— 从**这一域自己的**保管店派生(生产 = {@link ensureCheckpointCtxSealing};
+ * 入参型 {@link CheckpointCtxKeyStore}:模型钥匙那只店进不来),信封是:封进密文的明文是 `JSON.stringify([CHECKPOINT_CTX_SEAL_ALG, sessionId, value])`。
+ *  · **封**:对着保管店**最新**那把公钥 `crypto_box_seal`(只用公钥);封签记下那把钥匙的 id。
+ *  · **开**:按封签上的 id **精确**选私钥(保管店的 `open`,不逐把试),再判信封:三元数组、首元是本信封的词、第二元是**这一行的会话 id**,交回第三元(封进去的 JSON 值,任何类型) ——
+ *    任何一条不成立 ⇒ 抛。域隔离由钥匙给(两域两对钥匙:模型钥匙的密文放进停驻行凭据位 ⇒ 这一域不持有那把钥匙;反过来停驻行的封签放进 `sealedApiKey` ⇒ 模型钥匙店不持有),
+ *    信封再给**行绑定**(别的会话那一行的封签搬过来开不开)与格式词 —— 持有本对象的那一层(HTTP 续跑腿)拿到的是「只开停驻行封签」的口;
+ *    私钥本身、保管目录、持有 id 列表照旧够不着(只多一个 `holds(id)`:开之前判「这把钥匙在不在本副本」,`key_not_held` 与 `unopenable` 分开报)。
+ *  · 错误句不带明文:信封解析失败只报「不是停驻行封签」(`JSON.parse` 的报错会嵌入输入片段 —— 那里可能是一只模型钥匙),保管店的错误句只说哪把钥匙 / 哪种失败。
+ * 前置条件:`store` 来自 {@link ensureSealedKeyStore}(它已等过 libsodium 就绪);没就绪 ⇒ 当场响亮抛,不造一只封不了的对象。
+ * **自检**:交出之前对最新那把钥匙封一只探针、再开回来 —— 开不回来(保管档里公私钥不配对:长度都对,装载照收)⇒ 当场抛。封得进、开不出的封签器比没有更坏:
+ * 起服的一次性迁移 M28 会用它把还读得懂的明文行换成谁都开不开的密文。调用方(web-admin 运行时)把这一抛当「没有封签器」处置 ⇒ 耐久审批在场的部署起服拒。
+ */
+export declare function createCheckpointCtxSealing(store: CheckpointCtxKeyStore): CheckpointCtxSealing;
 /**
  * Best-effort public-key registration with the web-admin (`POST /api/config/execution-keys`).
  *
@@ -86,4 +117,5 @@ export declare function reportExecutionPublicKey(opts: {
     /** Test seam. */
     fetchImpl?: typeof fetch;
 }): Promise<void>;
+export {};
 //# sourceMappingURL=sealed-key.d.ts.map

package/dist/sealed-key.js

@@ -6,6 +6,7 @@ import { buildDisplaySafeUrl } from "./trace/redact.js";
 import { createCenterCredentialSource } from "./center-credential.js";
 import { centerFetch } from "./web-admin-client/center-request.js";
 import { WEB_ADMIN_ENV } from "@sema-agent/settings-schema";
+import { CHECKPOINT_CTX_SEAL_ALG } from "./http/checkpoint-ctx.js";
 export const SEALED_KEY_ALG = "libsodium-sealedbox-x25519";
 const SEAL_OVERHEAD_BYTES = 48;
 const BASE64_STRICT = /^[A-Za-z0-9+/]+={0,2}$/;
@@ -70,7 +71,7 @@ export async function ensureSealedKeyStore(dir, logger) {
         await writeFile(path, JSON.stringify(record, null, 2) + "\n", { mode: 0o600 });
         await chmod(path, 0o600);
         keys.set(record.publicKeyId, { publicKey: kp.publicKey, privateKey: kp.privateKey, publicKeyB64, createdAt: record.createdAt });
-        logger?.info("sealed_key_generated", { publicKeyId: record.publicKeyId, publicKey: publicKeyB64, dir, note: "new X25519 sealed-box keypair — register the PUBLIC key with the registry (see sealed_key_public_key)" });
+        logger?.info("sealed_key_generated", { publicKeyId: record.publicKeyId, publicKey: publicKeyB64, dir, note: "new X25519 sealed-box keypair in this directory — the private key exists only here: keep the directory across restarts and identical on every replica that has to open what it sealed, and back it up as a private key" });
     }
     const latestEntry = [...keys.entries()].sort((a, b) => (a[1].createdAt < b[1].createdAt ? 1 : a[1].createdAt > b[1].createdAt ? -1 : a[0] < b[0] ? -1 : 1))[0];
     return {
@@ -88,6 +89,59 @@ export async function ensureSealedKeyStore(dir, logger) {
         },
     };
 }
+const CHECKPOINT_CTX_KEY_SUBDIR = "checkpoint-ctx-keys";
+function mintCheckpointCtxKeyStore(store) {
+    return store;
+}
+export async function ensureCheckpointCtxSealing(sealedKeyDir, logger) {
+    return createCheckpointCtxSealing(mintCheckpointCtxKeyStore(await ensureSealedKeyStore(join(sealedKeyDir, CHECKPOINT_CTX_KEY_SUBDIR), logger)));
+}
+export function createCheckpointCtxSealing(store) {
+    const sodium = _sodium;
+    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 sealing = createUncheckedCheckpointCtxSealing(store, publicKeyId, publicKey);
+    const probeSession = "sealed-key-self-test";
+    let roundTrip;
+    try {
+        roundTrip = sealing.open(sealing.seal(probeSession, probeSession), probeSession);
+    }
+    catch {
+        roundTrip = undefined;
+    }
+    if (roundTrip !== probeSession) {
+        throw new Error(`createCheckpointCtxSealing: self-test failed — a value sealed against the newest public key (publicKeyId "${publicKeyId}") does not open with the private key held under that id; the key file's public and private halves do not belong together. Refusing to hand out a sealer whose seals nobody can open`);
+    }
+    return sealing;
+}
+function createUncheckedCheckpointCtxSealing(store, publicKeyId, publicKey) {
+    const sodium = _sodium;
+    return {
+        seal: (value, sessionId) => ({
+            alg: CHECKPOINT_CTX_SEAL_ALG,
+            publicKeyId,
+            sealed: Buffer.from(sodium.crypto_box_seal(sodium.from_string(JSON.stringify([CHECKPOINT_CTX_SEAL_ALG, sessionId, value])), publicKey)).toString("base64"),
+        }),
+        holds: (id) => store.has(id),
+        open: (sealed, sessionId) => {
+            const plaintext = store.open(sealed.sealed, sealed.publicKeyId);
+            let envelope;
+            try {
+                envelope = JSON.parse(plaintext);
+            }
+            catch {
+                throw new Error("sealed value is not a checkpoint-context seal");
+            }
+            if (!Array.isArray(envelope) || envelope.length !== 3 || envelope[0] !== CHECKPOINT_CTX_SEAL_ALG)
+                throw new Error("sealed value is not a checkpoint-context seal");
+            if (envelope[1] !== sessionId)
+                throw new Error("sealed value was sealed for a different session's resume context");
+            return envelope[2];
+        },
+    };
+}
 export async function reportExecutionPublicKey(opts) {
     const { baseUrl, adminToken, key, notes, logger } = opts;
     const manual = (why) => {

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 {
@@ -41,7 +42,7 @@ export interface SessionListItem {
  * 而 `DELETE /v1/sessions/:id`(删整条会话)不在其中 —— 同一风险形、爆炸半径**更大**,却没门。
  *
  * 风险形逐字同源(守卫自己的注释):「无 service token + 未开 `ALLOW_UNAUTHED_WRITES`」这一形下
- * `sessionOwnerScopeForWrite` 判 fleet-wide ⇒ 集群内**任意**调用方可对**任意** session 动手。
+ * fleet 写档(`http/principal-gate.ts` 的 `fleetViewOf`,dev-open 臂)判 fleet-wide ⇒ 集群内**任意**调用方可对**任意** session 动手。
  * policy 腿担心的是「forged principal 能 tighten/DoS 一个会话的工具」;DELETE 直接把会话删掉。
  *
  * ⇒ 枚举改**族判定**:新增一条破坏性会话路由时自动落进门内,不必记得回来加白名单。
@@ -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,14 +115,19 @@ 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 主不产生跨租外泄。
  *
  * 🪦 墓碑注(与第一臂同源):这是两个表示法之间的**过渡承接**。存量随会话生命周期消亡后,本臂
  * 连同 {@link LEGACY_UNOWNED_AMNESTY_TENANT} 与几处调用点可**整删**,不留兼容层。
  *
- * ── 逐面判过、**刻意不放行**的三处(免得后人当遗漏再补一次)────────────────────────────────
+ * ── 同步族(`…/sync/*`:拉取 / 推送 / 开导入 / 导入第二阶段)──────────────────────────────────
+ *  同步族四口自 7.134.0 同走本臂(表态见 7.134.0 发车帖;三条件不变):属主门是 `http/routes/session-sync.ts` 的一只布尔 `mayTouch`,与 fork / 删除同一只谓词、同一对读法
+ *  (`sessionCallerOf` + `sessionOwnerCellOf`),不另立判据。这一族带破坏性的 import 腿,但单用户形下 `default` 是唯一用户,与已走本臂的删除同级,没有新增跨租风险;
+ *  多租形、非 `default` 主体、无主的 placed 行仍与不存在的会话同码同体。暂存句柄的归属不因本臂放宽(非 fleet 调用方只推自己开的暂存,fleet 调用方照旧可推任何一张)。
+ *
+ * ── 逐面判过、**刻意不放行**的两处(免得后人当遗漏再补一次)────────────────────────────────
  *  · `runOwnerOk` 三读面(head / audit 单读 / events):`owner === null` 那一支**本来就放行**
  *    (判据是 `owner !== null && principal !== owner`),不需要本臂。[ref] 帖文里「单读 404」一句
  *    经亲读实现行**不成立**,已加现状钉(session-head-probe.test.ts)锁住这个事实。
@@ -82,22 +136,19 @@ export declare const LEGACY_UNOWNED_AMNESTY_TENANT = "default";
  *    这把键,替它读写规则只能**猜**一个 principal(猜错 = 200 说已生效,其实没有哪条 run 读它)。已经存下的规则不受影响:
  *    它们存在当初那个属主的键下,那个 principal 的 run 照读照生效(7.119.0 前 local 后端重启即把属主忘掉,于是那些规则
  *    在跑、却读不到也删不掉 —— 修在属主落盘,不在放宽本门)。放宽它等于制造一条 fail-open,不在本臂辖域。
- *  · `…/sync/*`(PULL/PUSH/import):PULL 虽是只读、形同 workspace,但这一族**带一条破坏性 import 腿**
- *    (`isDestructiveSessionWrite` 明列),而 [ref]/[ref] 裁的是会话**读面与生命周期**四门。放宽一个
- *    写面族超出裁定射程 —— 要做另立一次表态,不在本臂里顺手带过。
  *
  * @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} 的**条件①③**半支 —— 只判「这个部署形 × 这个调用方」是否落在窄臂辖域内。
  *
  * 🔴 单独存在的唯一理由是**列表面**:`GET /v1/sessions` 的第三条件(`owner === null`)不在 JS 里判,
  * 它是 store 侧 `owner = ? OR owner IS NULL` 这一句 SQL 谓词 —— 三条件仍然齐,只是第三条件由 SQL 承载
  * (`listSessions({ owner, includeUnowned })` 的 `includeUnowned` 位即本函数的返回值)。
- * 单实体读/写点(fork/delete/workspace)**一律**用三条件齐的 {@link legacyUnownedSessionOk},不要用本函数。
+ * 单实体读/写点(fork/delete/同步族/workspace)**一律**用三条件齐的 {@link legacyUnownedSessionOk},不要用本函数。
  */
 export declare function legacyUnownedAmnestyOpen(requirePrincipal: boolean, gateOwner: string | null): boolean;
 export type OwnerAwareSessionStore = SessionStore & {
@@ -106,6 +157,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 +327,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 +394,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 +419,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,10 +27,23 @@
  *    `open` 面留白(#1077 形,见上)。
  *  · `not_found` —— 留白:每一面各有自己的「不存在」答法(404 `not_found.session` / 同步口的 `resume.session_not_found` /
  *    列表里的缺席),码位各不相同,不由本表统一。
- *  · `invalid_entry` / `invalid_fork_target` / `placement_refused` —— 留白:本仓今天没有一条 wire 口把它们作为自己的
- *    应答(它们在 core 的追加 / 分叉 / 放置面上抛,落进各站点既有的处置或通用 500)。给它们起名是另一件事、另一张票。
- *  · `storage` / `conflict` / `unknown` —— 留白:`conflict` 是 run 的写撞上真并发写,落成那条 run 的 `failed` 终局
- *    (`terminal.code: "conflict"`),提交腿不另作处置;`storage` / `unknown` 是故障类,通用 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)。给它们起名是另一件事、另一张票。
+ *  · `conflict` —— `import` 面 **409 `conflict`**(固定句 {@link STAGED_IMPORT_OWNER_CHANGED_SENTENCE});`open` 面留白。import 面上这个词只有一个来源:
+ *    暂存提交的属主 CAS(`session-sync-kernel.ts` 的 `StagedCommitOwnerChangedError`,三家店在提交事务里比「此刻的属主格 = 这次导入的门判过的那一格」,
+ *    不等 ⇒ 回滚)—— 码位与同族的提交期同步冲突(`SyncConflictError` ⇒ 409 `conflict`「sync conflict」)同一个,出路也相同:从第一阶段重来(重新过门)。
+ *    open 面上它是 run 的写撞上真并发写,落成那条 run 的 `failed` 终局(`terminal.code: "conflict"`),提交腿不另作处置。
+ *  · `storage` / `unknown` —— 留白:故障类,通用 500 就是它们今天的应答。
  *
  * core 给闭集加一个词 ⇒ 下面的 `switch` 编译红,由人裁定它在两面上的答复,而不是让它静默落进某个恰好存在的臂
  * ([ref] 词表纪律;同形先例 `session-policy-wire.ts` 的 `sessionPolicyErrorHttp`)。
@@ -45,14 +58,25 @@ export interface SessionErrorWire {
     readonly status: number;
     readonly errorCode: string;
     /**
-     * 固定句(缺席 = 发 core 的原句,过既有脱敏)。只有 import 面的 `invalid_session` 用它:core 导入门的原句点名的是
-     * 调用方日志里的条目 id / 父子关系,修前这一口就只回一句固定话(冻结在 `test/api-error-text-freeze.test.ts` 的
-     * 常量锚格),本批逐字不改。
+     * 固定句(缺席 = 发 core 的原句,过既有脱敏)。import 面的三行用它(`invalid_session` / `placement_refused` / `conflict`):店与引擎的原句
+     * 点名条目 id / 会话 id / 引擎内部词,wire 上只回一句固定话(各自冻结在 `test/api-error-text-freeze.test.ts` 的常量锚格)。
      */
     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";
+/**
+ * import 面 `conflict` 的固定句:暂存提交时会话的属主格已不是开暂存时门判过的那一格(另一副本在导入流式进行期间删建 / 认领 / 新建了它),提交事务回滚。
+ * 不发店的原句(它点名会话 id);固定句只说发生了什么与出路(冻结在 `test/api-error-text-freeze.test.ts` 的常量锚格)。
+ */
+export declare const STAGED_IMPORT_OWNER_CHANGED_SENTENCE = "session owner changed while the import streamed; nothing was imported \u2014 start the sync again";
 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,18 +1,25 @@
 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";
+export const STAGED_IMPORT_OWNER_CHANGED_SENTENCE = "session owner changed while the import streamed; nothing was imported — start the sync again";
 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 } };
+const STAGED_IMPORT_OWNER_CHANGED = { status: 409, errorCode: "conflict", sentence: STAGED_IMPORT_OWNER_CHANGED_SENTENCE };
 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 "conflict":
+            return face === "import" ? STAGED_IMPORT_OWNER_CHANGED : undefined;
         case "not_found":
         case "invalid_entry":
         case "invalid_fork_target":
-        case "placement_refused":
         case "storage":
-        case "conflict":
         case "unknown":
             return undefined;
         default: {