@sema-agent/server 7.133.0 → 7.135.0

package/dist/runs.js

@@ -141,8 +141,22 @@ export function zeroWorkRefusalFacts(terminal, admissionReadings = []) {
     const c = cause;
     return c.kind === "coded" && c.detail !== undefined ? { detail: c.detail } : {};
 }
+const RETRY_CLASS_WORDS = { transient: true, terminal: true };
+function engineRetryClassOf(terminal) {
+    if (terminal.kind !== "failed")
+        return undefined;
+    const cause = terminal.detail;
+    if (cause === null || typeof cause !== "object")
+        return undefined;
+    const c = cause;
+    if (c.kind !== "coded" || c.detail === null || typeof c.detail !== "object")
+        return undefined;
+    const word = c.detail.permanence;
+    return typeof word === "string" && Object.hasOwn(RETRY_CLASS_WORDS, word) ? word : undefined;
+}
 export async function releaseKeyIfZeroWorkRefusal(runStore, taskId, result) {
-    if (syncRefusalHttpStatus(result) !== undefined)
+    const zeroWork = result.stats.turns === 0 && result.stats.tokens === 0;
+    if (syncRefusalHttpStatus(result) !== undefined || (zeroWork && engineRetryClassOf(result.terminal) === "transient"))
         await runStore.releaseIdemKey(taskId);
 }
 export function createPromptCommitReader() {
@@ -271,12 +285,13 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         windowMarginMs: approval?.windowMarginMs ?? 0,
         ...(typeof spec.limits?.maxWalltimeMs === "number" ? { legWalltimeMs: spec.limits.maxWalltimeMs } : {}),
         nowMonotonicMs: performance.now(),
+        declaredFamilies: approval?.declaredFamilies ?? new Set(),
     });
     const legDeadlineMonotonic = approvalLeg.legDeadlineMonotonic;
     if (approval) {
         const coordinator = approval.coordinator;
-        spec.onAsk = approvalLeg.windowZero
-            ? coordinator.boundUnattendedAsk({ owner: elicitOwner ?? owner, taskId, ...(spec.sessionId ? { sessionId: spec.sessionId } : {}) })
+        spec.onAsk = approvalLeg.unattended
+            ? coordinator.boundUnattendedAsk({ owner: elicitOwner ?? owner, taskId, ...(spec.sessionId ? { sessionId: spec.sessionId } : {}) }, approvalLeg.unattended)
             : coordinator.boundAsk({
                 owner: elicitOwner ?? owner,
                 taskId,
@@ -504,7 +519,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             const withQuestion = () => question
                 ? question.runWithContext({ taskId, owner: elicitOwner ?? owner, emit: questionEmit, abortSignal: cancelCtrl.signal }, withElicit)
                 : withElicit();
-            const withApproval = () => approval && approvalLeg.active && !approvalLeg.windowZero
+            const withApproval = () => approval && approvalLeg.active && approvalLeg.unattended === undefined
                 ? approval.coordinator.runWithContext({
                     taskId,
                     owner: elicitOwner ?? owner,

package/dist/runtime-caps-resolver.d.ts

@@ -27,7 +27,7 @@
  *                        显式 opt-in 极性，且 [ref] 起本侧传的是三态 org deny 位，见 toCoreRuntimeCaps 头注）
  *  · `bypassPermissions` — `dist/core/mode-policy.js` 的模式折叠（请求 `bypassPermissions` ∧ 本位 `=== false` ⇒ 这条腿跑在
  *                        `default`、发 `config.permission_mode_unavailable{by:"operator_deny"}`、回执 `foldedBy:"operator_deny"`）；
- *                        deny 形，缺席 = 不阻。S-900 D2 起由 center 的 `allowBypassPermissions` 写（此前本仓零写点）
+ *                        deny 形，缺席 = 不阻。[ref] D2 起由 center 的 `allowBypassPermissions` 写（此前本仓零写点）
  *  · `allowMemoryOptOut` — prepare-memory.js `resolveCaptureEntitlementFresh`（+prepare-task.js
  *                        的 value/faulted 投影）；**极性反转，但只在 `open` 姿态下**——判决全表在
  *                        `dist/core/runner/memory-capture-optout.js` 的 `adjudicateCaptureOptOut`，按
@@ -38,7 +38,7 @@
  *                          （拒由分「answered false」与「verdict absent / resolver fault」两句）
  *                        · `"capture-required"`:4-12 **完全不看本 verdict**（逐字「resolver-independent」），恒拒
  * center 的键里只有 `allowUltracode` 被 DROP（下文）；center 的其余每一键都在 {@link toCoreRuntimeCaps} 的处置表里，
- * settings-schema 加一键而这里没处置 ⇒ tsc 红（S-900 D2 之前 `allowBypassPermissions` / `allowAutoMode` 两键就是这样被静默丢掉的）。
+ * settings-schema 加一键而这里没处置 ⇒ tsc 红（[ref] D2 之前 `allowBypassPermissions` / `allowAutoMode` 两键就是这样被静默丢掉的）。
  *
  * It pulls the PER-PRINCIPAL entitlement from center's `GET /api/config/effective?principal=` (via
  * {@link fetchPrincipalCaps}). center has ALREADY pre-resolved the tighten-only intersection (fleet defaults ∩
@@ -55,7 +55,7 @@
  * ⚠️ [ref]① 纠失实：这段曾写作「降级为 `{ allowWorkflows: false }`」，与真码不符 —— 真铸点在本文件
  * `load()` 的 catch 臂（搜 `Caps face FAIL CLOSED`），逐字是上行那几键：`allowFork` 自提货批就在，
  * `autoMode` 由 [ref] / core [ref] 同车加入（org deny 位不能因一次抖动在 denyTtl 窗内抬起），`bypassPermissions`
- * 由 S-900 D2 加入（同一条律：center 可能已经拒了的 bypass 不能因一次抖动放出来；core 自己的 resolver-throw 降级臂
+ * 由 [ref] D2 加入（同一条律：center 可能已经拒了的 bypass 不能因一次抖动放出来；core 自己的 resolver-throw 降级臂
  * 铸的也是这四位拒，`dist/core/runner/prepare-caps-and-workflow.js`）。
  * 🔒 **四只放大位以外的那三键刻意不铸**：`forceDurableGate` 同上（强挂人在环会搞死无人值守的 run）；
  * `allowObservers` 是 `=== true` opt-in，缺席已等于关；`allowMemoryOptOut` 是隐私轴的 FAULT-TRANSIT 契约
@@ -70,7 +70,7 @@
  * also carries `allowUltracode` (a shell/UX reasoning-tier cap the engine has no primitive for), which we DROP —
  * this seam feeds the ENGINE, and `allowUltracode` is enforced at the service settings-resolution layer, not here.
  * center's two MODE kill-switches are NOT dropped: `allowBypassPermissions:false` ⇒ `bypassPermissions:false`,
- * `allowAutoMode:false` ⇒ the same auto deny bit `autoMode:false` writes (S-900 D2 — a mode's every refusal is an engine
+ * `allowAutoMode:false` ⇒ the same auto deny bit `autoMode:false` writes ([ref] D2 — a mode's every refusal is an engine
  * deny bit; the engine folds, announces and reports it on `wiring_manifest.permissionMode`).
  */
 import type { RuntimeCaps } from "@sema-agent/core";
@@ -83,7 +83,7 @@ import { type Logger } from "./observability/logger.js";
 /** test-only: reset the once-per-process trace so each test observes a fresh "first hit". */
 export declare function resetExecutionLaneDefaultTraceForTest(): void;
 export interface EntitlementsResolverOpts {
-    /** S-651:中心端点(基址 + 凭证**来源**;每次抓取取一次值,不持有启动快照)。 */
+    /** [ref]:中心端点(基址 + 凭证**来源**;每次抓取取一次值,不持有启动快照)。 */
     center: CenterEndpoint;
     /** This worker's name (`SEMA_WEB_ADMIN_WORKER`), passed as `?worker=` so a worker-scoped `wpt_<self>` token can
      *  resolve its OWN worker's principal caps (caps-only); harmless on a full token (the caps value
@@ -126,7 +126,7 @@ export interface EntitlementsResolverOpts {
  *  镜像)。core 武装式 = `spec.permissionMode === "auto" ∧ deps.autoMode !== undefined ∧ runtimeCaps?.autoMode !== false`(core 7.34.0 起;此前意图座是退役的 `autoModeRequested`)
  *  ——「用户开 + org 拒」极性(此前是 `=== true` 的「org 授予」极性,无 center 的本地部署零授予路径 ⇒ auto 永不
  *  武装,真实用户诊断的病根)。
- *  ([ref]① 的历史:npm 7.2.0 不含 [ref]、是旧「org 授予」极性,本仓曾用安装包探针分臂;S-877 / core 7.34.0 起引擎只剩
+ *  ([ref]① 的历史:npm 7.2.0 不含 [ref]、是旧「org 授予」极性,本仓曾用安装包探针分臂;[ref] / core 7.34.0 起引擎只剩
  *  上面这一种极性,探针随 7.106.0 退役 —— 本仓精确钉的 core 恒是它。)
  *  所以**缺键=不写键**在这条轴上是行为承重的:补一个 false 就是替 org 说了一句它没说的 deny。[ref]B-6a:registry-core 0.13.0 已把 autoMode 收进 EntitlementRuntimeCaps——类型直读。 */
 export declare function toCoreRuntimeCaps(ent: EntitlementRuntimeCaps | null | undefined): RuntimeCaps | undefined;

package/dist/runtime-governance.d.ts

@@ -64,13 +64,13 @@ export declare function validateCommandRules(rules: CommandRule[]): string[];
  * Either way the result only ever ADDS asks/denies — composed onto the baseline via `combinePolicies`
  * (deny-wins) by {@link applyRuntimeGovernance}, so it is tighten-only.
  *
- * 🔴 **S-958:返回叶,不在这里折**(改名自 `compileCommandPolicy`,修前返回 blocklist 形里 `combinePolicies(coarseDeny, askList)` 的
+ * 🔴 **[ref]:返回叶,不在这里折**(改名自 `compileCommandPolicy`,修前返回 blocklist 形里 `combinePolicies(coarseDeny, askList)` 的
  * 一只折叠)。复合命令(`a && b`、管道、`;`)上两只叶都按「解析不了 ⇒ 问」问 ⇒ 那只折叠带出 `foldedAskClasses`,而治理层随后要给每只
- * ask 盖部署出身 —— 盖在折叠的输出上就是展开一只 core 担保过身份的对象(core #1266 7.39.0 按名拒)。叶交出去,由
+ * ask 盖部署出身 —— 盖在折叠的输出上就是展开一只 core 担保过身份的对象(core [ref] 7.39.0 按名拒)。叶交出去,由
  * {@link applyRuntimeGovernance} 逐叶盖位、折**一次**:本函数不知道出身这件事,治理层只有一个折叠点。 (Assumes commands are pre-validated by
  * {@link validateCommandRules}; an un-matchable command here is simply inert, never a parse error.)
  *
- * 🔴 **S-496:词表外的 `decision` 折 `deny`,不折 `ask`。** {@link validateCommandRules} 的头注写下的那条
+ * 🔴 **[ref]:词表外的 `decision` 折 `deny`,不折 `ask`。** {@link validateCommandRules} 的头注写下的那条
  * 后果(「域外的 `decision` 穿过本函数的三元链落到 ASK,静默把一条 intended deny 弱化掉」)此前只靠
  * **调用方记得先校验**挡着 —— 而本函数在 `resolve-spec` 里是逐请求现调的,`config.commandPolicy` 的来路
  * (center hot apply / 本地 `config.d/governance.json` / LKG / 测试直塞)不止一条。现在闭集在本函数**内部**
@@ -213,7 +213,7 @@ export interface GovernancePosture {
  * ⚠️ 残留(双向失真的窄在场向 + 根治路径)与「只收窄」的那一个裁决读者,都登记在
  * {@link governanceMandatesShellGateAlways} 的顶注,别在这里复述。
  *
- * 🔴 **形状档的 ask 刻意不标**(S-877 起它不再是一个档位词:core 7.34.0 把形状档装在**每一种模式**的全权 shell 上,
+ * 🔴 **形状档的 ask 刻意不标**([ref] 起它不再是一个档位词:core 7.34.0 把形状档装在**每一种模式**的全权 shell 上,
  * 行上的 `shellGateDoctrine` 只在运维地板 `"always"` 铸门时出现):形状档的一次 shell ask 出自引擎自己的判断,
  * 也可能叠着 `APPROVAL_REQUIRE` 这类别的门,行上无从分辨 —— 与活卡腿同一条「宁缺毋假」纪律。
  *
@@ -230,7 +230,7 @@ export interface GovernancePosture {
  * (checkpoint → ask)今天**没有读口**:两条 list 读口都硬过滤 `state='STREAM_PENDING'`,而 park 完的行是
  * `PARKED`;唯一精确的连接键是 ask 行上的 `gate_token`,要按它反查得给店加一个新读口(SQL 面 = 双库集成
  * 门)。派生 `deriveAskId(...)` 也不行:它吃 `legKey`(= 上一腿 resume token 的摘要)、`parentToolCallId` 与这一问的
- * 类集(S-944);前两维从 checkpoint 行推不出来,类集在 park 行上老行缺席、续跑不补 —— 二腿/子代/老行形上会算出一个
+ * 类集([ref]);前两维从 checkpoint 行推不出来,类集在 park 行上老行缺席、续跑不补 —— 二腿/子代/老行形上会算出一个
  * **错**的 id —— 在「等的谁」这条通道上,错 id 比缺席坏得多(`http/active-run-conflict.ts` 的 `resumeEntryForGate` 的 default 臂是同一条纪律)。故诚实缺席。
  */
 export declare function governanceOriginOf(gate: {
@@ -253,14 +253,14 @@ export declare function governanceOriginOf(gate: {
  * (task-settings deriveSettingsPolicy 的 default/auto/acceptEdits 三臂)让一个**部署级 tighten-only 旋钮
  * 的生死由客户端表态在场性决定**:body 无 settings/permissionMode(cli print/headless 腿按设计不 stamp)
  * ⇒ 旋钮静默失效(clay 实机 Monitor 案「门根本没铸」);bypassPermissions 一句话掀掉部署闸;非 host lane
- * fsWriteGate wiring 不建 ⇒ 沙箱 lane 全失效。governance 层与 autonomy 同拍施加后三者全闭。S-877 起地板只有
+ * fsWriteGate wiring 不建 ⇒ 沙箱 lane 全失效。governance 层与 autonomy 同拍施加后三者全闭。[ref] 起地板只有
  * `"always"` 一个词,合成退化成在场性(两个来源同词),不再有秩比较。
  *
  * [ref]([ref] issue #29,**邻仓 test AI 的 46 格真机矩阵**实证——不是本仓的钉,别到本仓文件里数 46;
  * 本仓的类级门是 test/operator-knob-client-posture-matrix.test.ts 的 旋钮×表态×lane 矩阵):
  * `SENSITIVE_WRITE_PATTERNS` 是 [ref] 那次搬家漏下的兄弟旋钮——同一个病灶原样复发在 sensitive-path
  * DENY 腿上(唯一合成点在 deriveSettingsPolicy 的 fsWriteGate 闭包,bypassPermissions/键缺席/settings
- * 整缺席三形整条腿不建)。同方修:调用方(resolve-spec)把 operator 守卫集预铸成 `sensitivePathLayers`(叶;S-958 起不再是
+ * 整缺席三形整条腿不建)。同方修:调用方(resolve-spec)把 operator 守卫集预铸成 `sensitivePathLayers`(叶;[ref] 起不再是
  * 一只预折的策略,见下段)从这里**无条件施加**——它只在守卫段上产 deny(core 语义 deny/"safety"),对其余目标返回的是
  * `action:"allow"`(**不是**「无意见」这种第三态:core 的 ToolPolicy 没有弃权值。它在
  * `combinePolicies` 的 deny/ask 优先折叠里不构成一票,所以在**折叠语境**下等价于弃权;若日后有人把
@@ -269,7 +269,7 @@ export declare function governanceOriginOf(gate: {
  * 只组合不构造:裁决 env 的 lane 分形(host 真 fs / 沙箱 deferred 代理)是 resolve-spec 的属主知识,
  * governance 层不重复它。
  *
- * 🔴 **S-958(core #1266 7.39.0)—— 治理层只有一个折叠点**:两种输入都交**叶**(`compileCommandPolicyLayers` 的那几只、
+ * 🔴 **[ref](core [ref] 7.39.0)—— 治理层只有一个折叠点**:两种输入都交**叶**(`compileCommandPolicyLayers` 的那几只、
  * `sensitivePathLayers` 的那几只),本函数对每一片叶各盖一次部署出身(`createDeploymentAuthoredPolicy`),再交 core
  * `combinePolicies` 折一次;折叠是最外层,输出经标记观察器原物交回。修前是「先折、再在折叠输出上展开盖位」——折叠带出
  * `foldedAskClasses` 时交给 core 的是副本,7.39.0 起按名拒(工具不跑、无卡)。
@@ -278,7 +278,7 @@ export declare function applyRuntimeGovernance(base: TaskSpec, governance: {
     autonomy?: Autonomy;
     commandPolicy?: CommandRule[];
     manualModeShellGate?: ShellGateDoctrine;
-    /** 守卫集的**叶**(`deployment-governance.ts` `createDeploymentGovernanceInputs` 预铸;S-958 起是叶的列表,不是一只预折的策略)。
+    /** 守卫集的**叶**(`deployment-governance.ts` `createDeploymentGovernanceInputs` 预铸;[ref] 起是叶的列表,不是一只预折的策略)。
      *  空列表与缺席同义。 */
     sensitivePathLayers?: readonly ToolPolicy[];
     /** [ref]/[ref] `governanceForced` 的标记表(缺省 = **当前 run 腿的 ALS 表**,见

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

@@ -1,29 +1,4 @@
-/**
- * RFC B5/B4 抽象点② (sema-internal server/docs/design/ENV-SELECT-AND-REGION-SOURCE.md): the deployment-region package-source →
- * sandbox env derivation. ENV-FIRST: pod/sandbox env OVERRIDES the image's baked `ENV` (k8s container env wins
- * over image config and is visible to every exec'd process; e2b sandboxEnv likewise) — so the env-overridable
- * ecosystem pieces (pip/uv/npm/corepack/go/rustup/flutter/playwright/nuget) switch region on EXISTING images,
- * no rebake needed. Only the file-bound pieces (apt sources, /etc/gemrc, composer global config, cargo
- * config.toml) still need the in-image `pkg-source.sh` hook (rebaked images; bake prep chowns those files).
- *
- * Profiles:
- *   cn      → inject only the SEMA_PKG_SOURCE marker (the pool's images bake the CN set as their defaults).
- *   global  → official endpoints for every env-overridable ecosystem (overrides the baked CN ENV values).
- *   custom  → SEMA_* explicit URLs (from the service process env) forwarded verbatim + mapped onto the same
- *             ecosystem variables where a mapping is unambiguous (apt has no env form — hook-only).
- *
- * 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";
+import { type UrlCredential } from "./url-credential.js";
 /** Explicit URLs for `custom` (RFC B: 极端情况出口). Read from the service process env (operator-trusted). */
 export interface CustomPkgSource {
     aptMirror?: string;
@@ -38,15 +13,18 @@ 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>;
+/** 一只地址的毛病:形判不出(不是层级式 http(s) URL,或含反斜杠 —— 本座位律),或带凭据(共用判官的一处命中)。 */
+export type PkgSourceAddressProblem = "not-http-url" | UrlCredential;
 /**
- * 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.
+ * The refusal sentence for one address (pure data): the shared judges' rule sentence + the value's origin only
+ * ({@link buildHttpUrlRefusal} / {@link buildUrlCredentialRefusal}), 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;
+export declare function buildCustomPkgSourceRefusal(envName: string, raw: string, problem: PkgSourceAddressProblem): 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.
+ * the ONE judge of those six addresses (see the module header). An address the shared judges refuse (a shape that is not a
+ * parseable http(s) URL, or a credential: userinfo / a credential-named parameter) 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,5 +1,6 @@
 import { httpUrlFlaws } from "@sema-agent/settings-schema";
-import { buildHttpUrlRefusal } from "./url-refusal.js";
+import { buildHttpUrlRefusal, buildUrlCredentialRefusal } from "./url-refusal.js";
+import { findUrlCredential } from "./url-credential.js";
 const GLOBAL_ENV = {
     PIP_INDEX_URL: "https://pypi.org/simple",
     UV_DEFAULT_INDEX: "https://pypi.org/simple",
@@ -45,14 +46,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 +72,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

@@ -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";
@@ -14,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.
@@ -36,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).
@@ -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>;
+/**
+ * 停驻行凭据的**封签器**([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 值,任何类型) ——
+ *    任何一条不成立 ⇒ 抛。域隔离由钥匙给(两域两对钥匙:模型钥匙的密文放进停驻行凭据位 ⇒ 这一域不持有那把钥匙;反过来停驻行的封签放进 `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,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 键零投影透传
@@ -42,7 +43,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 直接把会话删掉。
  *
  * ⇒ 枚举改**族判定**:新增一条破坏性会话路由时自动落进门内,不必记得回来加白名单。
@@ -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 主不产生跨租外泄。
@@ -122,7 +123,12 @@ export declare const LEGACY_UNOWNED_AMNESTY_TENANT = "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)锁住这个事实。
@@ -131,31 +137,32 @@ 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 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} 的**条件①③**半支 —— 只判「这个部署形 × 这个调用方」是否落在窄臂辖域内。
  *
  * 🔴 单独存在的唯一理由是**列表面**:`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(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 declare function legacyUnownedAmnestyOpen(requirePrincipal: boolean, gateOwner: string | null): boolean;
 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 店)。两个读者:
@@ -182,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