@sema-agent/server 7.149.0 → 7.151.0

package/dist/server-secret-env.js

@@ -1,17 +1,20 @@
 import { declareWithheldEnv, hostChildEnv, inheritEnvPolicyProblem, inheritedHostEnv } from "@sema-agent/core";
-import { CONFIG_CATALOG } from "./config-catalog.js";
+import { BAKE_RUNNER_CREDENTIAL_ENV, CONFIG_CATALOG } from "./config-catalog.js";
 import { parseApprovalHmacKeys, parseServiceAuthTokens } from "./auth-keys.js";
 import { ENV_NAME_ALLOWLIST_KNOB_NAMES } from "./env-name-allowlist-knobs.js";
 import { recordOwnCredentialValueNotWithheld, recordSecretEnvScrub } from "./observability/secret-env-scrub.js";
-export const CATALOG_SECRET_ENV_NAMES = new Set(CONFIG_CATALOG.filter((spec) => spec.type === "secret").map((spec) => spec.name));
+const CREDENTIAL_FORM_OF = new Map([
+    ...CONFIG_CATALOG.flatMap((spec) => (spec.credentialForm === undefined ? [] : [[spec.name, spec.credentialForm]])),
+    ...Object.entries(BAKE_RUNNER_CREDENTIAL_ENV),
+]);
+export const CREDENTIAL_ENV_NAMES = new Set([...CREDENTIAL_FORM_OF.keys()].sort());
 const NO_MODEL_ENTRIES = Object.freeze({});
 export function serverWithheldEnvNames(modelApiKeyEnv = NO_MODEL_ENTRIES) {
-    return [...new Set([...CATALOG_SECRET_ENV_NAMES, ...ENV_NAME_ALLOWLIST_KNOB_NAMES, ...Object.values(modelApiKeyEnv)])].sort();
+    return [...new Set([...CREDENTIAL_ENV_NAMES, ...ENV_NAME_ALLOWLIST_KNOB_NAMES, ...Object.values(modelApiKeyEnv)])].sort();
 }
 export function serverCredentialValueSources(modelApiKeyEnv = NO_MODEL_ENTRIES) {
-    return [...new Set([...CATALOG_SECRET_ENV_NAMES, ...Object.values(modelApiKeyEnv)])].sort();
+    return [...new Set([...CREDENTIAL_ENV_NAMES, ...Object.values(modelApiKeyEnv)])].sort();
 }
-const CREDENTIAL_FORM_OF = new Map(CONFIG_CATALOG.flatMap((spec) => (spec.credentialForm === undefined ? [] : [[spec.name, spec.credentialForm]])));
 const DROPPED_KEYS_TOLD_BY_LOAD_CONFIG = () => { };
 function credentialsIn(form, raw) {
     switch (form) {
@@ -21,6 +24,8 @@ function credentialsIn(form, raw) {
             return [raw, ...Object.keys(parseServiceAuthTokens(raw))];
         case "key-set":
             return [raw, ...parseApprovalHmacKeys(raw, DROPPED_KEYS_TOLD_BY_LOAD_CONFIG).map((k) => k.key)];
+        case "name-list":
+            return [];
         default: {
             const unreachable = form;
             throw new Error(`unhandled secret credential form: ${String(unreachable)}`);
@@ -32,15 +37,17 @@ let beforeLast;
 const valueRefusalAnnounced = new Set();
 let liveConfig;
 const envValueOf = (name) => process.env[name];
-function credentialsHeldBy(source) {
+function credentialsHeldBy(source, keyEnvs) {
     const raw = envValueOf(source);
     if (raw === undefined || raw === "")
         return [];
-    return [...new Set(credentialsIn(CREDENTIAL_FORM_OF.get(source) ?? "whole", raw))].filter((v) => v !== "");
+    const row = CREDENTIAL_FORM_OF.get(source);
+    const read = [...(row === undefined ? [] : credentialsIn(row, raw)), ...(keyEnvs.has(source) ? credentialsIn("whole", raw) : [])];
+    return [...new Set(read)].filter((v) => v !== "");
 }
-function heldValues(held) {
+function heldValues(held, keyEnvs) {
     return [...held].flatMap(([source, at]) => {
-        const all = credentialsHeldBy(source);
+        const all = credentialsHeldBy(source, keyEnvs);
         return [...at].flatMap((i) => {
             const value = all[i];
             return value === undefined ? [] : [value];
@@ -49,16 +56,17 @@ function heldValues(held) {
 }
 export function declareServerWithheldEnv(modelApiKeyEnv = NO_MODEL_ENTRIES) {
     const names = [...new Set([...(declared?.names ?? []), ...serverWithheldEnvNames(modelApiKeyEnv)])].sort();
+    const keyEnvs = new Set([...(declared?.keyEnvs ?? []), ...Object.values(modelApiKeyEnv)]);
     const held = new Map(declared?.held ?? []);
-    declareWithheldEnv({ names, values: heldValues(held) });
+    declareWithheldEnv({ names, values: heldValues(held, keyEnvs) });
     for (const source of serverCredentialValueSources(modelApiKeyEnv)) {
         const at = new Set(held.get(source) ?? []);
         let refusal;
-        credentialsHeldBy(source).forEach((_, i) => {
+        credentialsHeldBy(source, keyEnvs).forEach((_, i) => {
             if (at.has(i))
                 return;
             try {
-                declareWithheldEnv({ names, values: heldValues(new Map(held).set(source, new Set([...at, i]))) });
+                declareWithheldEnv({ names, values: heldValues(new Map(held).set(source, new Set([...at, i])), keyEnvs) });
                 at.add(i);
                 held.set(source, new Set(at));
             }
@@ -72,11 +80,11 @@ export function declareServerWithheldEnv(modelApiKeyEnv = NO_MODEL_ENTRIES) {
         }
     }
     beforeLast = declared;
-    declared = { names: new Set(names), held };
+    declared = { names: new Set(names), held, keyEnvs };
     return names;
 }
 export function withdrawServerWithheldEnv() {
-    declareWithheldEnv({ names: [...(beforeLast?.names ?? [])], values: heldValues(beforeLast?.held ?? new Map()) });
+    declareWithheldEnv({ names: [...(beforeLast?.names ?? [])], values: heldValues(beforeLast?.held ?? new Map(), beforeLast?.keyEnvs ?? new Set()) });
     declared = beforeLast;
 }
 export function bindOwnCredentialsConfig(config) {
@@ -102,7 +110,8 @@ export function ownCredentialValuesWithheld() {
     if (declared === undefined || liveConfig === undefined)
         return false;
     const held = declared.held;
-    return serverCredentialValueSources(liveConfig.modelApiKeyEnv).every((source) => (held.get(source)?.size ?? 0) === credentialsHeldBy(source).length);
+    const keyEnvs = new Set([...declared.keyEnvs, ...Object.values(liveConfig.modelApiKeyEnv)]);
+    return serverCredentialValueSources(liveConfig.modelApiKeyEnv).every((source) => (held.get(source)?.size ?? 0) === credentialsHeldBy(source, keyEnvs).length);
 }
 export function ownCredentialVariable(name) {
     if (inheritEnvPolicyProblem([name]) !== undefined)

package/dist/session-agent.d.ts

@@ -5,7 +5,7 @@
  * 店原样记下,首写不可变。三只持久会话店都存:SQL 两孪生在 `session_meta` 的 `placement_*` 列(`plugins/session-placement.ts` 的 `placementFromRow`),
  * local 后端(7.141.0 起)在会话存档行头(core 文件 repo)。读口是店的 `placementOf`(一行 PK 探针;店不交它 = 不存元组)。
  *
- * 读者(同一只读口 {@link readSessionAgent}、同一只投影 {@link sessionAgentOf},逐值同答):
+ * 读者(同一只读口 —— 属主存取器的 `readSessionAgent`(`http/owner-access.ts`:店的行读只在存取器里)—— 同一只投影 {@link sessionAgentOf},逐值同答):
  *  · 会话视图 `GET /v1/sessions/:id` 体顶层的 `agent`(视图读才付探针;探针抛 ⇒ 视图读响亮失败,`boot/session-faces.ts`);
  *  · 运维审批队列 `GET /v1/approvals` 的停驻行(`pending[]` 的 `checkpoint` 族)与 `/v1/approvals/stream` 的 `pending` 帧:行的身份就是它那只会话
  *    (决断口 `/v1/approvals/:sessionId/decide`),行上的 `agent` = 同一只会话在视图上的 `agent`;一行读不出 ⇒ 只这一行缺键、F 类兜底计数
@@ -26,15 +26,6 @@ export interface SessionAgent {
     parentSessionId?: string;
     rootSessionId?: string;
 }
-/** 交委派元组读口的会话店面(本仓三只持久会话店与缓存包装层都交;内存店不交)。 */
-export interface PlacementReadingSessionStore {
-    readonly placementOf?: (sessionId: string) => Promise<SessionPlacementRecord | undefined>;
-}
 /** {@link SessionAgent} 的唯一投影:店答出的委派元组 → `agent` 的值;`undefined`(普通会话 / 店没有这一面)⇒ 调用方不铸键。 */
 export declare function sessionAgentOf(placement: SessionPlacementRecord | undefined): SessionAgent | undefined;
-/**
- * `agent` 的**唯一读口**:店的 `placementOf` 一读 → {@link sessionAgentOf}。店不交 `placementOf` ⇒ `undefined`(这台部署不存元组,不探)。
- * 探针抛 ⇒ 原样上抛 —— 读不出怎么说归读者(视图读响亮失败;队列只缺那一行的键并计数),本函数不替任何一面把故障说成「不是子代」。
- */
-export declare function readSessionAgent(store: PlacementReadingSessionStore | undefined, sessionId: string): Promise<SessionAgent | undefined>;
 //# sourceMappingURL=session-agent.d.ts.map

package/dist/session-agent.js

@@ -7,10 +7,4 @@ export function sessionAgentOf(placement) {
         ...(placement.rootSessionId !== undefined ? { rootSessionId: placement.rootSessionId } : {}),
     };
 }
-export async function readSessionAgent(store, sessionId) {
-    const placementOf = store?.placementOf;
-    if (placementOf === undefined)
-        return undefined;
-    return sessionAgentOf(await placementOf.call(store, sessionId));
-}
 //# sourceMappingURL=session-agent.js.map

package/dist/session-bindings.d.ts

@@ -0,0 +1,82 @@
+/**
+ * **会话绑定** —— 一次提交写在会话上的三格进程内事实(工作目录 · shell 环境 · 继承策略;host / device 工厂在 run 起跑那一拍按会话键现读)的唯一律。
+ *
+ * ## 律
+ * 会话绑定是**被受理的 run** 的事实,不是请求的事实:
+ *  · **判在写之前** —— 装配器(`boot/resolve-spec.ts`)只判、只算这条腿要写的那一份({@link SessionBindings},随部署事实 `LegFacts.sessionBindings` 走);
+ *    工作目录那一格 = 这条腿**跑在**的那一枚(请求带的 ?? 项目继承来的 ?? 会话上已登记的),装配器自己的读者(hooks 的工作目录、真任务根、写门基准、组合腿的根)
+ *    与起跑时的工厂读的是同一枚 —— 提交点把它原样写进会话,装配读与起跑读之间别的提交的写改不了这条腿的落点;
+ *  · **一个写点** —— run 认领之后、起跑之前的唯一提交点 {@link commitLegBindings}(四个认领点:流式提交 / 同步提交 / durable 建行腿 / 续跑驱动腿;
+ *    类级机器门 `test/inherit-env-request-key.test.ts`)。装配器之后、认领之前的一切拒(装配期的拒、路由层的建行 409 / placement / 续跑输入 / 起跑前复核)零写;
+ *  · **写在判之后的,同一只撤回** —— 写了之后才收场 `refused` 的提交(引擎零工作的拒、受理之前取消)由提交出口(`submission-exit.ts`)按本次的回执撤回;
+ *    受理 / record 的落定。登记簿记的是「已落定的底 + 还没落定的各笔(按提交序)」,三张表恒是它的物化:撤回只抽掉这一笔、重新物化 —— 别的提交的写原样、原序,
+ *    两笔都被撤就回到底(不会把一笔被拒的写当成另一笔的「写之前」还原回来);围栏清过 / 会话删过 ⇒ 回执一笔不动。
+ *    行判撤的提交另由出口按住客清掉全部条目(与 `DELETE` 同一组,既有)。没有出口座的腿(续跑驱动腿 · 后台建行腿:认领即 record)写即落定。
+ *
+ * 一条被拒的提交因此不留任何它写下的会话绑定 —— 请求自带的 `cwd`、项目继承来的第一条 `folder`、`settings.env`、`inheritEnv` 同一条律,
+ * 与会话行(提交出口)、请求形的拒(`request-form.ts`,在铸点之前答)同一个「拒后零残留」。
+ *
+ * ## 三格的缺席语义(各自原样)
+ *  · `cwd`:缺席 = 这条腿没有工作目录(请求没带、没继承、会话上也没登记)⇒ 不动;
+ *  · `shellEnv`:缺席 = 不动(粘住上一条受理的 —— 壳每条请求重发,粘住无害;装配器不读这一格);
+ *  · `inheritEnv`:缺席 = 清(缺省清洗 —— 粘住 = 替一个没说话的请求放宽凭据面;理由在 `boot/execution-env.ts` 的登记簿注)。
+ *  装配器没铸事实(嵌入方自带的装配器)⇒ 按「什么都没要」写:`inheritEnv` 清、其余不动(安全轴 fail-closed 的那一侧)。
+ *
+ * ## 残余(如实)
+ *  · 登记簿仍按**会话**键控、工厂在起跑那一刻现读(core 的执行环境工厂上下文只带 sessionId / taskId,没有 per-run 座):有 run 店的部署上认领串行化同会话的 run,
+ *    「写 → 读」落在同一条认领窗里;没有 run 店的部署上同会话并发受理的两条 run 仍是「最后写者赢」。
+ *  · 续跑腿没有提交出口:它在 markResuming 赢之后写**那条停驻任务自己**盘上的值(不是别的请求的);core 的 pre-CAS 守卫在那之后才拒的续跑照样留着它,
+ *    下一条受理的 run 照写覆盖。
+ *  · 登记簿是每副本进程内的(围栏与清除只在处理该请求的副本上发生),见 `createSessionScopedRegistries` 头注。
+ */
+import type { TaskInheritEnv } from "./request-value-closure.js";
+/** 一条腿要写在会话上的绑定(装配器判出的那一份;提交点原样写)。缺席语义见本文件头注。 */
+export interface SessionBindings {
+    /** 这条腿跑在的工作目录(请求带的 ?? 项目继承来的 ?? 会话上已登记的;前两者只在车道能力 `callerCwd` 成立且是宿主绝对路径时算数)。缺席 = 不动。 */
+    readonly cwd?: string;
+    /** 请求的 `settings.env`(只在 `callerCwd` 成立时在场)。缺席 = 不动。 */
+    readonly shellEnv?: Readonly<Record<string, string>>;
+    /** 请求的 `inheritEnv`(装配器判过值形 / 车道 / 射程)。缺席 = 清。 */
+    readonly inheritEnv?: TaskInheritEnv;
+}
+/**
+ * 三格的**唯一铸法**:在场(≠ `undefined`)的格才出键,缺席的格不出键。本函数只答「缺席 = 没有这个键」,不替任何一格选缺省 —— 每一格缺席读作什么见上面头注,由各读者按那一条读。
+ * 三个调用点同用:装配器算这条腿的绑定(`boot/resolve-spec.ts`)、登记簿读一份当下的三格、登记簿把一笔写叠在一份读数之上(`boot/execution-env.ts`)。
+ * 此前各写一遍三条件展开,`inheritEnv` 这个键在三处各被拼一次;现在这个键的属性字面量在 src 只此一处(类级门 `test/secret-env-scrub-host-legs.test.ts` 的 [ref] 格数的就是它)。
+ * `shellEnv` 的型随调用点(装配器交只读的、登记簿的表里是可变的)。
+ */
+export declare function bindingsOf<E extends Readonly<Record<string, string>>>(cwd: string | undefined, shellEnv: E | undefined, inheritEnv: TaskInheritEnv | undefined): {
+    readonly cwd?: string;
+    readonly shellEnv?: E;
+    readonly inheritEnv?: TaskInheritEnv;
+};
+/** 一笔提交的回执(撤回 / 落定只认这一笔)。 */
+export interface SessionBindingReceipt {
+    readonly sessionId: string;
+    /** 这一笔的回执号。 */
+    readonly token: symbol;
+}
+/** 登记簿的写座(`boot/execution-env.ts` `createSessionScopedRegistries` 铸;HTTP 面经 `ServiceDeps.sessionBindings` 拿到)。 */
+export interface SessionBindingSeat {
+    /** 写一笔(唯一调用者 = {@link commitLegBindings}),交回回执。 */
+    commitSessionBindings(sessionId: string, bindings: SessionBindings): SessionBindingReceipt;
+    /** 撤回一笔:这一笔还没落定 ⇒ 抽掉它、三格重新物化(别的提交的写原样)、答 `true`;否则(已落定 / 已撤 / 清过)一笔不动、答 `false`。 */
+    withdrawSessionBindings(receipt: SessionBindingReceipt): boolean;
+    /** 落定一笔(这次提交被受理 / 交给了它自己的耐久 run):此后不可撤。已撤 / 清过 ⇒ 答 `false`。 */
+    settleSessionBindings(receipt: SessionBindingReceipt): boolean;
+}
+/** 提交点读的那一面:写座(缺席 = 夹具 / 嵌入方没接登记簿 ⇒ no-op)。 */
+export interface LegBindingsCommitCtx {
+    readonly sessionBindings?: SessionBindingSeat | undefined;
+}
+/** 提交出口收回执的那一面(`submission-exit.ts` 的 `SubmissionSeat.noteBindings`):收场 `refused` ⇒ 撤回,`accepted` / `record` ⇒ 落定。 */
+export interface BindingReceiptSink {
+    noteBindings(receipt: SessionBindingReceipt, face: Pick<SessionBindingSeat, "withdrawSessionBindings" | "settleSessionBindings">): void;
+}
+/**
+ * **唯一提交点**:在 run 认领(与执行放置、续跑输入、起跑前复核)之后、起跑之前调一次 —— 把这条腿的绑定写进它的根会话,回执交给这次提交的出口座
+ * (同步 / 流式两条提交腿:收场定撤还是落定);`exit` 缺席(续跑驱动腿没有座;后台建行腿认领即 record,之后不再有拒)⇒ 写即落定。
+ * `bindings` 缺席(装配器没铸事实)⇒ 按「什么都没要」写。
+ */
+export declare function commitLegBindings(ctx: LegBindingsCommitCtx, exit: BindingReceiptSink | undefined, sessionId: string, bindings: SessionBindings | undefined): void;
+//# sourceMappingURL=session-bindings.d.ts.map

package/dist/session-bindings.js

@@ -0,0 +1,18 @@
+export function bindingsOf(cwd, shellEnv, inheritEnv) {
+    return {
+        ...(cwd !== undefined ? { cwd } : {}),
+        ...(shellEnv !== undefined ? { shellEnv } : {}),
+        ...(inheritEnv !== undefined ? { inheritEnv } : {}),
+    };
+}
+export function commitLegBindings(ctx, exit, sessionId, bindings) {
+    const seat = ctx.sessionBindings;
+    if (seat === undefined)
+        return;
+    const receipt = seat.commitSessionBindings(sessionId, bindings ?? {});
+    if (exit !== undefined)
+        exit.noteBindings(receipt, seat);
+    else
+        seat.settleSessionBindings(receipt);
+}
+//# sourceMappingURL=session-bindings.js.map

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

@@ -89,8 +89,8 @@ export type RetireSessionChildrenOutcome = {
 };
 /**
  * 一只会话的**引擎租户分区** —— **唯一一处取**:以它为根的后台子代、它的后台 shell、它的会话信箱盒,都登记在这一分区(删除门、换绑 / 导入两门、结清口、
- * 删除协调器的信箱腿与 shell 收割腿、删后收尾的丢箱同读;属主串本身不是 scope)。引擎按任务规格的身份格登记,所以这里读的是**引擎交界**
- * (`engine-identity.ts` 的 `taskSpecIdentityOf`)从会话属主恢复出的那一格:没带场景的会话 = 属主(逐字节同改前);带场景的会话(属主 `_scn:<场景>:<人>`)=
+ * 删除协调器的信箱腿与 shell 收割腿、删后收尾的丢箱同读;属主串本身不是 scope)。引擎按任务规格的身份格登记,所以这里读的是**引擎身份那一格**
+ * (`engine-identity.ts` 的 `engineScopeOfOwner`,唯一换算):没带场景的会话 = 属主(逐字节同改前);带场景的会话(属主 `_scn:<场景>:<人>`)=
  * 引擎登记时用的那一个值(今天是人)—— 按属主串去枚举 / 退役 / 收割会打到一个空分区。无主 ⇒ `"default"`。
  */
 export declare function sessionTenantScope(owner: string | null): string;

package/dist/session-children-retire.js

@@ -1,13 +1,9 @@
-import { partsOf } from "./owner-brands.js";
-import { recoveredSubject } from "./owner-faces.js";
-import { taskSpecIdentityOf } from "./engine-identity.js";
+import { engineScopeOfOwner } from "./engine-identity.js";
 import { expireCardUnderStoredScope } from "./card-settle-stored-scope.js";
 export const RETIRE_MAX_ROUNDS = 6;
 const RETIRE_BACKOFF_MS = [0, 25, 50, 100, 200, 400];
 export function sessionTenantScope(owner) {
-    if (owner === null)
-        return "default";
-    return taskSpecIdentityOf(partsOf(recoveredSubject(owner))).principal ?? "default";
+    return engineScopeOfOwner(owner);
 }
 async function liveChildren(deps, rootSessionId, scope) {
     const out = new Map();

package/dist/session-deletion.d.ts

@@ -20,6 +20,7 @@
  *    持有者已死的在删行,重发的 DELETE 同样是接管。
  * 持久面:SQL = 旁表 `session_ext.deleting_token`(列属主 `plugins/session-ext-table.ts`);local = 会话元数据边档那一格的 `deleting`。
  */
+import type { SessionKind } from "./session-kind.js";
 /** 围栏的回执:这一次删除的令牌 + 被删的那一位住客的化身(空间回收的键;存量行没有化身 ⇒ `undefined`)。 */
 export interface SessionDeletionTicket {
     readonly token: string;
@@ -36,10 +37,24 @@ export interface PendingSessionDeletion {
  * (某腿失败 / 被接管)—— 死的;`elsewhere` = 不是本进程铸的(上一个进程 / 别的副本)。
  */
 export type DeletionHolder = "running" | "ended" | "elsewhere";
-/** 围栏的选项:`holder` = 令牌持有者在哪(协调器的在飞表);`expect` = 只接管这一只令牌(收尾者;活行 / 别的令牌 ⇒ `undefined`)。 */
+/**
+ * 老化的条件(会话种类的律在 `session-kind.ts`;唯一调用者 = 维护拍的老化腿 `boot/session-age-out.ts`):候选读只挑人,**判官是围栏根行锁里的这一判** ——
+ * 对一只**活**行,锁住根行之后、写令牌之前再判:住客仍是候选读到的那一位(`incarnation`:候选读之后同 id 被删并重登记的新住客不被碰)∧ 种类仍是 `kind`
+ * ∧ 最后活动仍早于 `idleBefore`(候选读之后一次 run / 追加 / 收场把它推前 ⇒ 不删)∧ 当下没有活引用(在跑的 run 的认领 —— 围栏本来就判 —— / 待决的检查点 /
+ * 在跑或停驻的后台子代以它为会话 · 父 · 根 / 它发起的在跑 workflow;SQL 两孪生与托管留存同读一只谓词)∧ 所在域不在保全中(SQL:托管留存的保全行锁)。
+ * 任一不成立 ⇒ 回滚、`undefined`,一个字节不写。在删行(一次失败的删除撂下的)照常按持有者判接管 —— 它已经在删,不回到活。
+ * 条件与收尾者的 `expect` 同位:一只围栏、一个可选条件,不是第二条删除路;`DELETE /v1/sessions/:id` 不带它。
+ */
+export interface SessionAgeOutExpectation {
+    readonly incarnation: string | undefined;
+    readonly kind: SessionKind;
+    readonly idleBefore: Date;
+}
+/** 围栏的选项:`holder` = 令牌持有者在哪(协调器的在飞表);`expect` = 只接管这一只令牌(收尾者;活行 / 别的令牌 ⇒ `undefined`);`ageOut` = 老化的锁内条件({@link SessionAgeOutExpectation})。 */
 export interface SessionDeletionFenceOptions {
     readonly holder: (token: string) => DeletionHolder;
     readonly expect?: string;
+    readonly ageOut?: SessionAgeOutExpectation;
 }
 /** 围栏的答复:回执(本次立了 / 接管了)· `inProgress`(一次仍可能活着的删除持有这一行 —— 不接管)· `undefined`(行不在 / 属主不是这一位 / 收尾者的令牌对不上)。 */
 export type SessionDeletionFenceAnswer = SessionDeletionTicket | {

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

@@ -42,8 +42,8 @@
  *    (请求 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`,三家店在提交事务里比「此刻的属主格 = 这次导入的门判过的那一格」,
+ *  · `conflict` —— `import` 面 **409 `conflict`**(固定句 {@link STAGED_IMPORT_OCCUPANT_CHANGED_SENTENCE});`open` 面留白。按码映射时 import 面上这个词只有一个来源:
+ *    暂存提交的住客 CAS(`session-sync-kernel.ts` 的 `StagedCommitOccupantChangedError`,三家店在提交事务里比「此刻的行 = 这次导入的门判过的那一位住客」(属主 ∧ 化身),
  *    不等 ⇒ 回滚)—— 码位与同族的提交期同步冲突(`SyncConflictError` ⇒ 409 `conflict`「sync conflict」)同一个,出路也相同:从第一阶段重来(重新过门)。
  *    本服务自铸的同码具名拒 {@link StampedSessionArchiveError}(local 店:存档仍带更早版本写下的属主戳)不按码映射 —— 出路不同(重来照样撞),它有**自己的 wire 码**:
  *    由 {@link sessionErrorWireOf} 按**型**先认:两面同答 409 `conflict.session_archive_stamped` + 固定句 {@link STAMPED_SESSION_ARCHIVE_SENTENCE}(与上一句的属主变更拒同状态、不同码:
@@ -90,7 +90,7 @@ export declare const PLACED_SESSION_SENTENCE = "this session holds a delegated a
  * 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 const STAGED_IMPORT_OCCUPANT_CHANGED_SENTENCE = "session changed hands while the import streamed (deleted, re-created or re-owned); nothing was imported \u2014 start the sync again";
 /**
  * local 店的具名拒(唯一铸点 `plugins/local-session-store.ts` 的 `assertArchiveAnonymous`):这只会话的引擎存档仍带更早版本写下的属主戳(一次性迁移 M33 改写不了它,或数据根跳过了带这次迁移的版本)
  * ⇒ 不在它上面造新存档(fork),也不原地换它的日志(改日志的推送,含第一阶段对 fork / stale 的早拒);零写。`SessionError.code` 是 core 闭集的 `conflict`;句子(给运维日志,点名会话 id)归本错,

package/dist/session-error-wire.js

@@ -2,7 +2,7 @@ import { SessionError } from "@sema-agent/core";
 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";
+export const STAGED_IMPORT_OCCUPANT_CHANGED_SENTENCE = "session changed hands while the import streamed (deleted, re-created or re-owned); nothing was imported — start the sync again";
 export class StampedSessionArchiveError extends SessionError {
     sessionId;
     constructor(sessionId) {
@@ -23,7 +23,7 @@ export const STAMPED_SESSION_ARCHIVE_SENTENCE = "this session's stored archive s
 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, facts: { placement_kind: PLACEMENT_KIND } };
-const STAGED_IMPORT_OWNER_CHANGED = { status: 409, errorCode: "conflict", sentence: STAGED_IMPORT_OWNER_CHANGED_SENTENCE };
+const STAGED_IMPORT_OCCUPANT_CHANGED = { status: 409, errorCode: "conflict", sentence: STAGED_IMPORT_OCCUPANT_CHANGED_SENTENCE };
 const STAMPED_SESSION_ARCHIVE = { status: 409, errorCode: "conflict.session_archive_stamped", sentence: STAMPED_SESSION_ARCHIVE_SENTENCE };
 export function sessionErrorWireOf(e, face) {
     return e instanceof StampedSessionArchiveError ? STAMPED_SESSION_ARCHIVE : sessionErrorHttp(e.code, face);
@@ -44,7 +44,7 @@ export function sessionErrorHttp(code, face) {
         case "placement_refused":
             return face === "import" ? SESSION_PLACED : undefined;
         case "conflict":
-            return face === "import" ? STAGED_IMPORT_OWNER_CHANGED : undefined;
+            return face === "import" ? STAGED_IMPORT_OCCUPANT_CHANGED : undefined;
         case "not_found":
         case "invalid_entry":
         case "invalid_fork_target":

package/dist/session-incarnation.d.ts

@@ -73,6 +73,8 @@ export declare function incarnationLogPrefix(incarnation: string): string;
  * 把其中每一只化身形的串截成 {@link incarnationLogPrefix}(前 8 位 + `…`)。规则只有一条:完整令牌不进日志正文;前 8 位留着对账。
  */
 export declare function redactIncarnations(text: string): string;
+/** {@link SessionIncarnationMissingError} 的码(读到空化身的那一拒;k8s 车道按它把住客读拒分成立定的一形)。 */
+export declare const SESSION_INCARNATION_MISSING = "session.incarnation_missing";
 /**
  * 会话行在、化身却是空的 —— 响亮拒(头注「读到空化身」一条)。具名类型:调用方按类型认它,不按文案。
  * 文案不带任何令牌(本来就是空的),只点名会话 id 与出路。
@@ -100,6 +102,14 @@ export declare function incarnationFromCell(sessionId: string, cell: unknown, em
 /** 一行原始列 → {@link SessionFace}(属主 + 一只令牌)的唯一口:化身那一格经 {@link incarnationFromCell} 的 `refuse` 读法(空 ⇒ 响亮拒)。
  *  按 id 的读者经 {@link sessionFaceOfHead};批量来源读(一次性迁移 M23 窗内的回填扫描)与 staged 换装的回读直接从行列经它。 */
 export declare function sessionFaceFromRow(sessionId: string, owner: string | null, incarnation: unknown): SessionFace;
+/**
+ * 门承认的那一位住客在门后读的半途不再占着这只 id(删了、或删后同 id 被重建 —— 包括同一属主)。会话同步的拉取流在每页交出之前复判住客,不是那一位 ⇒ 抛它,
+ * 流在那里结束、不写尾行(客户端读作截断,重拉)—— 从不交出别一代住客的条目。不上 wire(流头已发,状态码改不了),只落一行运维 info。
+ */
+export declare class SessionOccupantChangedError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
 /**
  * 头的叶子那一格读不出 —— 会话**内容**读不出时的那只故障(local 店:会话存档读不出,例如存档首行的会话头坏了;行上的属主与住客照样读得出)。
  * {@link headFromRow} 收它:头照答属主与住客,叶子那一格带着这只故障,读 `leafId` 的那一位收到它本身(同一只错误对象,码与句子原样 ——
@@ -129,14 +139,28 @@ export declare function sessionFaceOfHead(sessionId: string, head: SessionHead):
 export declare function sessionFaceOfHead(sessionId: string, head: SessionHead | undefined): SessionFace | undefined;
 /**
  * 「这只会话店有没有按 id 读(`headOf`)」—— 全仓**只判这一处**:授权口、各路由的属主门、能力位、起服门、k8s 工作区空间的每 run 读与
- * 一次性迁移 M23(窗内)的回填读的都是这一只返回值。缺席 = 店没有实装 `headOf`(读不出属主 / 住客 / 叶子,调用方各按自己的 fail-closed 臂处置)。
+ * 一次性迁移 M23(窗内)的回填读的都是这一只判({@link headReadOf} 的在不在 = 它)。缺席 = 店没有实装 `headOf`(读不出属主 / 住客 / 叶子,调用方各按自己的 fail-closed 臂处置)。
+ * 收的是任意店形(路由层的封住视图也行:在不在照判,读口在型上调不了 —— 带属主的行只经属主存取器读,`http/owner-access.ts`)。
  */
-export declare function headReadOf(store: object | undefined): HeadRead | undefined;
+export declare function headReadPresent(store: {
+    readonly headOf?: unknown;
+} | undefined): boolean;
+/** 会话店的按 id 读(绑好宿主的那一只;店没有 ⇒ `undefined`)。路由层的封住视图在这里读不出读口(封住的那一格型是 `undefined`,类型墙,`route-ctx.ts` 的 `RouteDeps`)。 */
+export declare function headReadOf(store: {
+    readonly headOf?: HeadRead;
+} | undefined): HeadRead | undefined;
 /**
  * 删除门(`DELETE /v1/sessions/:id` 的属主门 + 协调器的化身围栏)的头读 —— **只判这一处**:店交了 `deletionHeadOf`(删除已开始、还没收完的那一行也答得出属主与住客;local)⇒ 它;
- * 否则 ⇒ {@link headReadOf}(删除是一个事务的店,没有删到一半的行)。缺席 = 店没有按 id 读。
+ * 否则 ⇒ {@link headReadOf}(删除是一个事务的店,没有删到一半的行)。缺席 = 店没有按 id 读。同 {@link headReadOf}:只收值上交读口的店形。
  */
-export declare function deletionHeadReadOf(store: object | undefined): HeadRead | undefined;
+export declare function deletionHeadReadOf(store: {
+    readonly deletionHeadOf?: HeadRead;
+    readonly headOf: HeadRead;
+}): HeadRead;
+export declare function deletionHeadReadOf(store: {
+    readonly deletionHeadOf?: HeadRead;
+    readonly headOf?: HeadRead;
+} | undefined): HeadRead | undefined;
 /** 换装沿用的行格(化身 + fork 键):{@link carriedRowCells} 的答案。`forkKey: null` = 没有可沿用的键(新建行 / 行上本来没有)。 */
 export interface CarriedRowCells {
     readonly incarnation: string;

package/dist/session-incarnation.js

@@ -12,9 +12,10 @@ const INCARNATION_TOKEN_SHAPE = /[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9
 export function redactIncarnations(text) {
     return text.replace(INCARNATION_TOKEN_SHAPE, (token) => `${incarnationLogPrefix(token)}…`);
 }
+export const SESSION_INCARNATION_MISSING = "session.incarnation_missing";
 export class SessionIncarnationMissingError extends Error {
     sessionId;
-    code = "session.incarnation_missing";
+    code = SESSION_INCARNATION_MISSING;
     constructor(sessionId) {
         super(`session ${sessionId} has no incarnation token: every session row is minted one when it is created. An empty value means a write path ` +
             `that did not mint one, a hand-edited row, or a database upgraded from before 7.104.0 straight to a version after 7.135.x (a boot of any ` +
@@ -41,6 +42,14 @@ export function incarnationFromCell(sessionId, cell, empty = "refuse") {
 export function sessionFaceFromRow(sessionId, owner, incarnation) {
     return { owner, incarnation: incarnationFromCell(sessionId, incarnation) };
 }
+export class SessionOccupantChangedError extends Error {
+    sessionId;
+    constructor(sessionId) {
+        super(`session ${sessionId}: the occupant the gate admitted no longer holds this id — the stream ends here`);
+        this.sessionId = sessionId;
+        this.name = "SessionOccupantChangedError";
+    }
+}
 export class UnreadableLeaf {
     fault;
     constructor(fault) {
@@ -66,9 +75,12 @@ export function leafOfAdmittedHead(head) {
 export function sessionFaceOfHead(sessionId, head) {
     return head === undefined ? undefined : sessionFaceFromRow(sessionId, head.owner, head.incarnation);
 }
+export function headReadPresent(store) {
+    return typeof store?.headOf === "function";
+}
 export function headReadOf(store) {
     const read = store?.headOf;
-    return typeof read === "function" ? read.bind(store) : undefined;
+    return headReadPresent(store) ? read.bind(store) : undefined;
 }
 export function deletionHeadReadOf(store) {
     const read = store?.deletionHeadOf;

package/dist/session-kind.d.ts

@@ -0,0 +1,57 @@
+/**
+ * **会话种类 `sessionKind`** —— 一只会话是不是用户的顶层对话,是它出生那一笔写下的一个事实(规则只写在这里一次;三只会话店、授权口、列表口、能力面与老化腿同读)。
+ *
+ * ## 律
+ *  · 闭集 {@link SESSION_KINDS};**缺席 = 顶层对话**(存量行、老壳建的行、fork / 同步导入 / run-local / 定时与 A2A 起的会话恒缺席 —— 缺席不存缺省词,顶层只有一种拼法)。
+ *  · **只有建这只会话的那一次提交写它**(提交体 `sessionKind`,授权口登记新行的那一笔:SQL = 建行事务里的建行钩、local = 建行那一笔格写),此后终身不改 ——
+ *    没有改写它的写口;整段换装就地改写同一行(种类随行),删后同 id 重登记是新住客(无种类)。
+ *  · 它只决定两件事:**会话枚举的缺省视图列不列它**(列表与 peer 目录读同一只 lister 的同一只视图 {@link sessionKindListed};缺省视图 = 无种类,
+ *    `?sessionKind=<词>` = 只列那一种)与**它按哪只视界老化**(有种类 ⇒ 最后活动之后 `BG_AGENT_RETENTION_MS`、无活引用时由维护拍删)。
+ *  · 按 id 的每一口读写、属主判、执行放置、同步 / fork / 删除对它与对任何会话是同一句话:种类不是资格、不是面、不是访问谓词。
+ *
+ * ## 与委派分区不是一件事
+ * core 的委派分区(`session_meta.placement_*`,placed 行)是引擎写的、不是列表面的行、不能当执行根;种类是客户端经提交写的、是列表面的行(缺省视图不列)、可以当执行根。
+ * 两个事实答两个问题,一个推不出另一个;「列不列」这一问的读者只有一只(lister 的视图谓词)。
+ */
+/** 会话种类的闭集(**顺序 = 拒句里的列举顺序**;加一个词 = 判它在缺省视图里列不列、按哪只视界老化,并逐处过编译)。 */
+export declare const SESSION_KINDS: readonly ["sidechain"];
+/** 一只会话的种类(缺席 = 顶层对话)。 */
+export type SessionKind = (typeof SESSION_KINDS)[number];
+/** 值是不是闭集里的一个词(判的是 wire 值 / 行上那一格的形;表外 ⇒ 不是)。 */
+export declare function isSessionKind(v: unknown): v is SessionKind;
+/**
+ * 🔴 **视图谓词的唯一判法**(local 店的 lister 与老化候选面同调;SQL 两孪生的同一句是 `plugins/session-store-sql.ts` 的 `sessionKindSql`):
+ * 一行进一只视图 ⇔ 行上的种类**等于**视图的种类(两边缺席相等 —— 缺省视图只列无种类的行)。
+ */
+export declare function sessionKindListed(rowKind: SessionKind | undefined, view: SessionKind | undefined): boolean;
+/** 按 id 读种类的答案:读到它时行上的住客(化身那一格,按 `absent` 读)与种类(缺席 = 顶层)。`undefined`(整只)= 没有这只会话。 */
+export interface SessionKindReading {
+    readonly incarnation: string | undefined;
+    readonly kind: SessionKind | undefined;
+}
+/** 会话店的按 id 种类读(三只持久店都交;包装层原样转发)。 */
+export interface SessionKindFace {
+    sessionKindOf(sessionId: string): Promise<SessionKindReading | undefined>;
+}
+/** 店上的种类读(没有 ⇒ `undefined`:这台部署记不了种类 —— 能力位 `sessionKinds` 为空、带键提交 400)。 */
+export declare function sessionKindFaceOf(store: unknown): SessionKindFace | undefined;
+/** 行上那一格 → 种类(SQL 列 / local 格的唯一解码):闭集里的词 ⇒ 它;NULL / 缺 ⇒ 缺席;别的值 ⇒ 响亮抛(手改库 / 将来的词落到旧构建上 —— 不猜成顶层)。 */
+export declare function sessionKindFromCell(sessionId: string, cell: unknown): SessionKind | undefined;
+/** 老化候选面的一行(候选读只挑人,判官是删除围栏根行锁里的那一判 —— `session-deletion.ts` 的 `SessionAgeOutExpectation`)。 */
+export interface IdleSession {
+    readonly sessionId: string;
+    /** 行上的属主(删除协调器按它走)。 */
+    readonly owner: string | null;
+    /** 读到它时行上的住客(围栏比它:候选读之后同 id 被删并重登记的新住客不被碰)。 */
+    readonly incarnation: string | undefined;
+    /** 最后活动(ISO;SQL `updated_at`,local 新近标记 —— 与列表行的 `lastActivityAt` 同一读法)。 */
+    readonly lastActivityAt: string;
+}
+/** 老化候选面的续页键(`(lastActivityAt, sessionId)` 升序:最老先出)。 */
+export interface IdleSessionCursor {
+    readonly lastActivityAt: string;
+    readonly sessionId: string;
+}
+/** 老化候选面的序:最老先出(`(lastActivityAt, sessionId)` 升序 —— SQL 两孪生的 `ORDER BY` 与 local 店的排序同读这一判)。 */
+export declare function idleSessionAfter(row: IdleSessionCursor, cursor: IdleSessionCursor | undefined): boolean;
+//# sourceMappingURL=session-kind.d.ts.map

package/dist/session-kind.js

@@ -0,0 +1,22 @@
+export const SESSION_KINDS = ["sidechain"];
+export function isSessionKind(v) {
+    return typeof v === "string" && SESSION_KINDS.includes(v);
+}
+export function sessionKindListed(rowKind, view) {
+    return rowKind === view;
+}
+export function sessionKindFaceOf(store) {
+    const s = store;
+    return typeof s?.sessionKindOf === "function" ? { sessionKindOf: s.sessionKindOf.bind(s) } : undefined;
+}
+export function sessionKindFromCell(sessionId, cell) {
+    if (cell === null || cell === undefined)
+        return undefined;
+    if (isSessionKind(cell))
+        return cell;
+    throw new Error(`session ${sessionId} carries a session kind this build does not know (${JSON.stringify(String(cell).slice(0, 32))}) — refusing to read it as a top-level session; a newer build wrote it, or the row was edited by hand`);
+}
+export function idleSessionAfter(row, cursor) {
+    return cursor === undefined || row.lastActivityAt > cursor.lastActivityAt || (row.lastActivityAt === cursor.lastActivityAt && row.sessionId > cursor.sessionId);
+}
+//# sourceMappingURL=session-kind.js.map

package/dist/session-notify-door.d.ts

@@ -9,7 +9,7 @@
  *    别的抛 = 活流刚收尾的竞态 ⇒ 落空闲臂。
  *  · **空闲**:这只会话的完成收件箱(`externalNotificationInboxEntry`,external 键域;脱敏 / 限长在入箱口内)⇒ 下次开流排空成 `task_notification` 帧。
  *    部署没有收件箱 ⇒ 如实交回 `no_inbox`(调用方各自答:HTTP 门 501,引擎完成告警)。
- *  · **复核住客**:两臂的投递动作(注入 / 入箱)之前**紧邻**一次头读,与目标的住客比 —— 判官是仓里那一只 `sameOccupant`(`execution-placement.ts`:属主 ∧ 化身,
+ *  · **复核住客**:两臂的投递动作(注入 / 入箱)之前**紧邻**一次头读,与目标的住客比(读与判在属主存取器的 `occupantRecheckOf`)—— 判官是仓里那一只 `sameOccupant`(`execution-placement.ts`:属主 ∧ 化身,
  *    写口与执行上下文解析器判的也是它):不在 ⇒ `withdrawn: gone`;两样里任一样变了 ⇒ `withdrawn: replaced`。会话店不铸化身(嵌入方自建的店)时两侧都没有令牌,
  *    判官只剩属主那一半:属主没变 ⇒ 投,变了 ⇒ 撤回。这一读是动作之前的最后一次让出:判活读(及活臂刚收尾时的那次注入)都在它前面 ——
  *    令牌永不复用,此刻还是那一位 ⇒ 判活读那一刻也是那一位 ⇒ 判出的 run 是它的 run。
@@ -33,7 +33,7 @@
 import type { ExternalNotificationInput, SessionHead, SubagentToolOptions, TaskStream } from "@sema-agent/core";
 import { type WorkflowCompletionInbox } from "./orchestration/workflow-completion-inbox.js";
 import type { DelegationRootWitness } from "./delegated-session-owner.js";
-import type { HeadRead } from "./session-incarnation.js";
+import type { OwnerAwareSessionStore } from "./security.js";
 import type { Logger } from "./observability/logger.js";
 /** 门的一次投递结局(闭集;调用方 `switch` 穷尽)。 */
 export type SessionNotifyOutcome = {
@@ -74,8 +74,8 @@ export interface SessionNotifyDoorIo {
     /** 本副本持活 core 流的腿(taskId → 流)。 */
     readonly liveRuns: ReadonlyMap<string, Pick<TaskStream, "notify">>;
     readonly inbox: WorkflowCompletionInbox | undefined;
-    /** 会话店的按 id 头读(复核住客的那一读)。店没有 ⇒ `undefined`:调用方先判(路由 501;后台完成 relay 照交,门响亮抛 ⇒ relay 告警)。 */
-    readonly headOf: HeadRead | undefined;
+    /** 会话店(复核住客的那一读只经属主存取器)。店没有按 id 头读 ⇒ 调用方先判(路由 501;后台完成 relay 照交,门响亮抛 ⇒ relay 告警)。 */
+    readonly sessionStorage: Pick<OwnerAwareSessionStore, "headOf"> | undefined;
 }
 export declare function createSessionNotifyDoor(io: SessionNotifyDoorIo): SessionNotifyDoor;
 /** 委派工具挂载期的完成 sink 的型(取自 core 的选项型,不手抄)。 */

package/dist/session-notify-door.js

@@ -1,14 +1,13 @@
 import { externalNotificationInboxEntry } from "./orchestration/workflow-completion-inbox.js";
-import { sameOccupant } from "./execution-placement.js";
+import { occupantRecheckOf } from "./http/owner-access.js";
 import { recordFailOpen } from "./observability/fail-open.js";
 export function createSessionNotifyDoor(io) {
+    const occupantNow = occupantRecheckOf(io.sessionStorage);
     async function recheck(target) {
-        if (io.headOf === undefined)
+        if (occupantNow === undefined)
             throw new Error("session notify door: the session store has no head read (headOf); the occupant cannot be re-checked before delivery");
-        const head = await io.headOf(target.sessionId);
-        if (head === undefined)
-            return { delivery: "withdrawn", reason: "gone" };
-        return sameOccupant(target.occupant, head) ? undefined : { delivery: "withdrawn", reason: "replaced" };
+        const verdict = await occupantNow(target.sessionId, target.occupant);
+        return verdict === "same" ? undefined : { delivery: "withdrawn", reason: verdict };
     }
     return {
         async deliver(target, event) {