@sema-agent/server 7.150.0 → 7.152.0

package/dist/security.js

@@ -3,8 +3,10 @@ import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
 import { FACES, OWNERLESS_ORDINARY_CELL, ownerCellOf, ownerlessCellWithoutRead, qualsOf, recoveredSubject, visibleOn } from "./owner-faces.js";
 import { mintDurableOwnerKey, mintPerson, partsOf, personOf, scenarioNamed, subjectOf } from "./owner-brands.js";
 import { deletionHeadReadOf } from "./session-incarnation.js";
+import { isSessionKind, sessionKindFaceOf } from "./session-kind.js";
 import { memoryScopeFor } from "./memory-scope.js";
 import { verifyPrincipalJwt } from "./principal-jwt.js";
+import { engineScopeOfOwner } from "./engine-identity.js";
 import { fieldConflictFacts } from "./field-conflict.js";
 import { refusalReservedKeyMessage, refusalReservedKeyOf } from "./http/refusal-body.js";
 import { PRINCIPAL_MAX_BYTES, principalShapeProblem } from "./principal-shape.js";
@@ -33,6 +35,14 @@ export const ATTACH_ABSENT_MESSAGE = "requireExistingSession: session does not e
 function attachAbsentError() {
     return createCodedHttpError(404, "resume.session_not_found", ATTACH_ABSENT_MESSAGE);
 }
+export const SESSION_KIND_MISMATCH_MESSAGE = "this session already exists with a different session kind — a session's kind is written once, when the session is created, and never changes; send the same sessionKind the session was created with, omit sessionKind to run the session as it is, or start a new session";
+function sessionKindMismatch(rowKind) {
+    return createCodedHttpError(409, "conflict.session_kind_mismatch", SESSION_KIND_MISMATCH_MESSAGE, rowKind === undefined ? undefined : { sessionKind: rowKind });
+}
+export const SESSION_KIND_UNRECORDABLE_MESSAGE = "sessionKind requires a session store that records a session's kind and ages such sessions out (DB_BACKEND=mysql|pg|local) — this deployment cannot, so the session would be created as a top-level conversation; capabilities.sessionKinds lists the kinds a deployment accepts";
+function sessionKindUnrecordable() {
+    return createCodedHttpError(400, "request.precondition_unmet", SESSION_KIND_UNRECORDABLE_MESSAGE);
+}
 export async function sessionOwnerCellOf(store, sessionId, owner) {
     if (owner !== null)
         return ownerCellOf(owner);
@@ -122,13 +132,25 @@ export function createAuthorizer(config, sessionStore, logger) {
     };
     const birthFace = birthFaceOf(sessionStore);
     const withdrawFace = withdrawFaceOf(sessionStore);
-    const registerNew = async (id, owner, register, onBirth) => {
-        if (birthFace === undefined || withdrawFace === undefined)
+    const kindFace = sessionKindFaceOf(sessionStore);
+    const registerNew = async (id, owner, kind, register, onBirth) => {
+        if (kind !== undefined && birthFace === undefined)
+            throw sessionKindUnrecordable();
+        if (birthFace === undefined || (withdrawFace === undefined && kind === undefined))
             return register(id, owner);
-        const receipt = await birthFace.registerWithReceipt(id, owner);
-        if (receipt.minted !== undefined)
+        const receipt = await birthFace.registerWithReceipt(id, owner, kind);
+        if (receipt.minted !== undefined && withdrawFace !== undefined)
             onBirth?.(receipt.minted, withdrawFace);
     };
+    const judgeKind = async (id, wanted, judged, subject) => {
+        if (kindFace === undefined)
+            throw sessionKindUnrecordable();
+        const reading = await kindFace.sessionKindOf(id);
+        if (reading === undefined || judged === undefined || reading.incarnation !== judged.incarnation)
+            throw attachRefused("not_visible", subject);
+        if (reading.kind !== wanted)
+            throw sessionKindMismatch(reading.kind);
+    };
     return async ({ req, body, onBirth }) => {
         const subject = verifiedSubject(req, config);
         if (config.requirePrincipal && !subject) {
@@ -142,6 +164,7 @@ export function createAuthorizer(config, sessionStore, logger) {
             projectId = body.projectId.toLowerCase();
         }
         const requireExisting = body.requireExistingSession === true;
+        const kind = isSessionKind(body.sessionKind) ? body.sessionKind : undefined;
         const headOf = deletionHeadReadOf(sessionStore);
         let head;
         const readOwner = headOf === undefined ? undefined : async (id) => {
@@ -159,7 +182,7 @@ export function createAuthorizer(config, sessionStore, logger) {
                         throw attachRefused("missing", subject);
                     }
                     if (register) {
-                        await registerNew(requested, subject ?? null, register, onBirth);
+                        await registerNew(requested, subject ?? null, kind, register, onBirth);
                         owner = await readOwner(requested);
                     }
                     else if (config.requirePrincipal) {
@@ -170,11 +193,18 @@ export function createAuthorizer(config, sessionStore, logger) {
                     const claimCaller = claimCallerOf(subject, config);
                     if (!visibleOn("session.attach", qualsOf(claimCaller, await sessionCellFor("session.attach", claimCaller, sessionStore, requested, owner))))
                         throw attachRefused("not_visible", subject);
+                    if (kind !== undefined)
+                        await judgeKind(requested, kind, head, subject);
+                }
+                else if (kind !== undefined) {
+                    throw register ? attachRefused("missing", subject) : sessionKindUnrecordable();
                 }
             }
             else if (config.requirePrincipal) {
                 throw new HttpError(403, "session reuse needs an owner-aware session store on a multi-tenant deployment: this worker's session store cannot attest who owns a session, so a sessionId cannot be authorized — including one this worker itself minted a moment ago (without a register seam it was never recorded as yours). Configure a durable session backend (SESSION_BACKEND), or omit sessionId on every turn to start fresh.");
             }
+            if (!readOwner && kind !== undefined)
+                throw sessionKindUnrecordable();
             sessionId = requested;
         }
         else {
@@ -183,9 +213,13 @@ export function createAuthorizer(config, sessionStore, logger) {
             }
             sessionId = uuidv7();
             if (register)
-                await registerNew(sessionId, subject ?? null, register, onBirth);
+                await registerNew(sessionId, subject ?? null, kind, register, onBirth);
+            else if (kind !== undefined)
+                throw sessionKindUnrecordable();
             if (readOwner)
                 await readOwner(sessionId);
+            if (kind !== undefined)
+                await judgeKind(sessionId, kind, head, subject);
         }
         return { subject, sessionId, memoryScope: memoryScopeFor(config, subject === undefined ? undefined : personOf(subject), projectId), resolvedProjectId: projectId, ...(head === undefined ? {} : { head }) };
     };
@@ -223,7 +257,7 @@ export function subjectWidthExceeded(subject) {
 export const CHECKPOINT_PUBLIC_SCOPE = "_";
 export const BACKGROUND_REGISTRY_ANON_SCOPE = "default";
 export function backgroundScopesForCheckpointScope(scope) {
-    return scope === CHECKPOINT_PUBLIC_SCOPE ? [CHECKPOINT_PUBLIC_SCOPE, BACKGROUND_REGISTRY_ANON_SCOPE] : [scope];
+    return scope === CHECKPOINT_PUBLIC_SCOPE ? [CHECKPOINT_PUBLIC_SCOPE, BACKGROUND_REGISTRY_ANON_SCOPE] : [engineScopeOfOwner(scope)];
 }
 export const encodeCheckpointScope = (subject) => subject ?? CHECKPOINT_PUBLIC_SCOPE;
 export const decodeCheckpointScope = (scope) => (scope === CHECKPOINT_PUBLIC_SCOPE ? undefined : mintDurableOwnerKey(scope));

package/dist/sema-config-dir.d.ts

@@ -30,7 +30,8 @@ export declare function provisionSemaConfigDir(config: {
  * (与记忆根那一判共用同一只规范形,那一判的失败方向是多报,这一判的是漏报;如实披露)。
  * 句子只描述位置关系,后果限定在引擎**缺省**写保护表上:用 `WRITE_PROTECTED_TABLE_REPLACE` 去掉那一行的部署不受影响(这一行不读那张表),可忽略它。
  *
- * 规范形读不出(盘上竞态:探完到取值之间目录被挪走 / 搜索权限被收)⇒ 披露面不得把起服打死:响亮报另一行 `sema_config_root_workspace_check_unavailable`(类名 + 机器码),起服照常。
+ * 规范形读不出(两边路径上有一段没有搜索权限 / 链接成环,或盘上竞态:探完到取值之间目录被挪走 / 搜索权限被收)⇒ 不给位置结论(看不见的一段不当成「还不存在」),
+ * 披露面也不得把起服打死:响亮报另一行 `sema_config_root_workspace_check_unavailable`(类名 + 机器码),起服照常。
  * 位置:HTTP 服务在装配第 2 段执行车道合成之后(读的是合成后的车道与工作区底),`run-local` 在工作区定下之后 —— 车道在这两处才定形,所以不与 {@link provisionSemaConfigDir} 同一拍。
  */
 export declare function announceConfigRootEnclosingWorkspace(config: {

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

@@ -18,7 +18,8 @@
  * `ADB_VENDOR_KEYS` / `AWS_SECRET_ACCESS_KEY` 一类,实测)。三个继承词只在引擎一处判:
  *  · `"all"` = 整份环境 **减** 本进程声明的自有凭据名;`"scrub"`(缺省)= 形状剥 ∪ 该名单;`[names]` = 严格白名单,点到名单中的名 ⇒ 引擎响亮拒
  *    (`inheritEnvPolicyProblem`:构造时与 spawn 时两格都拒,拒句带名;本仓不自判 withheld、不留第二读法)。
- *  · 名单 = 配置目录(`config-catalog.ts`)全部 `type:"secret"` 名 ∪ 名单型旋钮名(`env-name-allowlist-knobs.ts`,其原文可能夹着被错展开的令牌)∪ **生效配置
+ *  · 名单 = 本包凭据类变量名({@link CREDENTIAL_ENV_NAMES}:配置目录(`config-catalog.ts`)全部 `type:"secret"` 名 ∪ bake-runner 进程自己的凭据名 `BAKE_RUNNER_CREDENTIAL_ENV`
+ *    —— 目录只装服务进程读的 env,runner 的 bearer 不是目录行)∪ 名单型旋钮名(`env-name-allowlist-knobs.ts`,其原文可能夹着被错展开的令牌)∪ **生效配置
  *    模型条目的 `apiKeyEnv`**(key-resolver 取凭据的那张表 `config.modelApiKeyEnv` 的值 —— 本进程消费的凭据变量名,条目由中心热应用新增 / 改名),
  *    **机器派生**、不手抄、不按「归谁消费」切({@link serverWithheldEnvNames} 一处)。声明两个时机、同一只 {@link declareServerWithheldEnv}:起服第一步(三个进程入口:
  *    `boot/stage-01-config.ts` / `run-local.ts` / `bake-runner/main.ts`,在任何执行环境构造与 spawn 之前 —— 声明先于构造才有构造时拒;此时没有生效配置 = 空表),
@@ -29,9 +30,10 @@
  *    `loadConfig()` 的**声明前提**({@link ownCredentialDeclarationRefusal}:起服表的名没全扣 ⇒ `loadConfig` 抛,拒句点名 {@link declareServerWithheldEnv} —— 「先声明」不再只是入口里的位置契约,
  *    不经入口直接调 `loadConfig` 的进程〔包根嵌入方 / bench / 探针脚本〕得先声明,声明对它们才不是空的)与能力词 `inherit_env.own_credentials_withheld` 在本进程的事实
  *    {@link ownCredentialsWithheld}(当前生效配置应声明的名全被扣;活配置经 {@link bindOwnCredentialsConfig} 在 `loadConfig()` 之后绑一次;未绑 / 没扣 ⇒ false)。
- *  · **值臂**(core 7.52.0 [ref]):声明是一张表 `{ names, values }`。`values` = 本进程持有凭据的变量(目录 secret 名 ∪ 模型条目 `apiKeyEnv`,{@link serverCredentialValueSources})
- *    此刻装着的**每一枚**本服务凭据 —— 颗粒按本服务读这只变量的那一只解析器定(目录行的 `credentialForm`:整值总在内,`SERVICE_AUTH_TOKENS` 另加每一枚令牌、
- *    `APPROVAL_HMAC_KEYS` 另加每一把钥;{@link credentialsHeldBy})—— 引擎按整串比,所以一枚令牌换了个变量名放着与原变量同扣,部分重叠 / 前后缀不同的值不扣。
+ *  · **值臂**(core 7.52.0 [ref]):声明是一张表 `{ names, values }`。`values` = 本包凭据类变量(本包凭据类变量名 ∪ 模型条目 `apiKeyEnv`,{@link serverCredentialValueSources})
+ *    此刻装着的**每一枚**本服务凭据 —— 颗粒按本服务读这只变量的那一只解析器定(行的 `credentialForm`:装着凭据值的颗粒整值总在内,`SERVICE_AUTH_TOKENS` 另加每一枚令牌、
+ *    `APPROVAL_HMAC_KEYS` 另加每一把钥;名单型旋钮的颗粒 `name-list` 是零枚 —— 原文是变量名单,不是凭据;一只变量有几个读者就取几个读法的并集 —— 模型条目的 `apiKeyEnv` 指着它 ⇒
+ *    key-resolver 把它整值读成一枚,哪怕它是一行名单型旋钮;{@link credentialsHeldBy})—— 引擎按整串比,所以一枚令牌换了个变量名放着与原变量同扣,部分重叠 / 前后缀不同的值不扣。
  *    逐枚交给引擎的同一只判;引擎判「不是凭据值」的那一枚不扣、名照扣、不拒启、点名那个变量一次。能力词 `inherit_env.own_credential_values_withheld` 的事实 = {@link ownCredentialValuesWithheld}(位真 ⇔ 值臂每一枚都真扣)。
  *    「这个变量是不是本服务的凭据」(名是,或值是)只有一只读法 {@link ownCredentialVariable}(判官 = 引擎此刻的声明):名单型旋钮的解析器与声明增长时的重判都问它。
  *  · 调用方显式传入的 env(`cfg.env` / 单次命令的 `env` / 沙箱的点名放回)不是继承,照旧原样叠在组合结果之上 —— 那是适配器自己的凭据通道。
@@ -54,19 +56,19 @@
 import { type InheritEnvPolicy, type SecretEnvFinding } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
 import { type SecretEnvScrubSite } from "./observability/secret-env-scrub.js";
-/** 配置目录里 `type:"secret"` 的 env 名(按目录原文 —— 引擎按平台比名:POSIX 逐字、Windows 不分大小写,本仓不再另折叠)。 */
-export declare const CATALOG_SECRET_ENV_NAMES: ReadonlySet<string>;
+/** 本包凭据类变量名({@link CREDENTIAL_FORM_OF} 的键;排序只为读数稳定)。 */
+export declare const CREDENTIAL_ENV_NAMES: ReadonlySet<string>;
 /** 生效配置模型条目 name → `apiKeyEnv`(变量**名**,值从本进程 env 取)—— `ServiceConfig.modelApiKeyEnv` 的形,key-resolver 读凭据的那张表。 */
 export type ModelApiKeyEnvTable = Readonly<Record<string, string>>;
 /**
- * 本进程的自有凭据名(机器派生,三臂一处:目录 secret 名 ∪ 名单型旋钮名 ∪ `modelApiKeyEnv` 表的值;排序只为读数稳定)。纯函数:给哪张表就答哪张表的应声明
+ * 本进程的自有凭据名(机器派生,三臂一处:本包凭据类变量名 ∪ 名单型旋钮名 ∪ `modelApiKeyEnv` 表的值;排序只为读数稳定)。纯函数:给哪张表就答哪张表的应声明
  * 集合 —— 声明时给候选表、能力位给活表,同一只派生。名字按原文交引擎(目录臂同形),不在本仓折叠大小写。
  */
 export declare function serverWithheldEnvNames(modelApiKeyEnv?: ModelApiKeyEnvTable): readonly string[];
 /**
- * 本进程**持有凭据值**的变量名(值臂的来源;core 7.52.0 [ref]):目录 secret 名 ∪ 模型条目 `apiKeyEnv` 的值 —— 名单与值臂两臂同一张表派生,只少不在目录里的名单型旋钮名
- * (今天 = bake-runner 进程的 `BAKE_ENV_ALLOW`);目录里的名单型旋钮行是 secret 行,原文按凭据类整值对待(行上 `credentialForm: "whole"`)。每个来源装着几枚凭据
- * 由目录行的颗粒定({@link credentialsHeldBy})。纯函数,排序只为读数稳定。
+ * 本进程的**凭据类变量**名:本包凭据类变量名 ∪ 模型条目 `apiKeyEnv` 的值 —— 名单与值臂两臂同一张表派生,只少不在那张表里的名单型旋钮名(今天 = bake-runner 进程的
+ * `BAKE_ENV_ALLOW`)。两个读者问同一张:值臂按每只的颗粒读出它此刻装着的凭据值({@link credentialsHeldBy};名单型旋钮的颗粒 `name-list` ⇒ 零枚,名照扣),
+ * 请求 `settings.env` 的凭据判据按名拒(`task-settings.ts` `settingsEnvCredentialIssue`)。纯函数,排序只为读数稳定。
  */
 export declare function serverCredentialValueSources(modelApiKeyEnv?: ModelApiKeyEnvTable): readonly string[];
 /**

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-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` 的那一位收到它本身(同一只错误对象,码与句子原样 ——

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) {

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