@sema-agent/server 7.147.0 → 7.148.0

package/dist/security.js

@@ -1,10 +1,14 @@
-import { uuidv7, PROJECT_ID_REGEX, principalNameOf } from "@sema-agent/core";
+import { uuidv7, PROJECT_ID_REGEX, SessionError, buildCrossSessionEnvelope, encodePeerAddress, CrossSessionCodecError } from "@sema-agent/core";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
-import { headReadOf } from "./session-incarnation.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 { memoryScopeFor } from "./memory-scope.js";
 import { verifyPrincipalJwt } from "./principal-jwt.js";
 import { fieldConflictFacts } from "./field-conflict.js";
-import { ORPHAN_SESSION_OWNER_PREFIX } from "./delegated-session-owner.js";
+import { refusalReservedKeyMessage, refusalReservedKeyOf } from "./http/refusal-body.js";
+import { PRINCIPAL_MAX_BYTES, principalShapeProblem } from "./principal-shape.js";
+import { birthFaceOf, withdrawFaceOf } from "./plugins/session-birth.js";
 import { NOT_A_PRINCIPAL_NAME } from "./plugins/session-ownership.js";
 export function isDestructiveSessionWrite(method, url) {
     if (method === "DELETE")
@@ -15,37 +19,66 @@ export function isDestructiveSessionWrite(method, url) {
         return /^\/v1\/sessions\/[^/]+\/(sync\/import|fork|memory\/erase)$/.test(url);
     return false;
 }
-export function mintPrincipal(verified) {
-    return verified;
-}
-export function mintDurableOwnerKey(persisted) {
-    return persisted;
+export function claimCallerOf(subject, config) {
+    return {
+        subject,
+        operator: false,
+        fleet: undefined,
+        traceRead: false,
+        principalRequired: DEPLOYMENT_SHAPE_PREDICATES.principalRequired.holds(config),
+        multiTenant: DEPLOYMENT_SHAPE_PREDICATES.multiTenant.holds(config),
+    };
 }
-export function ownerlessRowOpen(cell, caller) {
-    if (cell.owner !== null)
-        return false;
-    return !cell.placed || caller.fleet;
+export const ATTACH_ABSENT_MESSAGE = "requireExistingSession: session does not exist (resume.session_not_found)";
+function attachAbsentError() {
+    return createCodedHttpError(404, "resume.session_not_found", ATTACH_ABSENT_MESSAGE);
 }
 export async function sessionOwnerCellOf(store, sessionId, owner) {
     if (owner !== null)
-        return { owner: mintDurableOwnerKey(owner) };
+        return ownerCellOf(owner);
     const placementOf = store?.placementOf;
     return { owner: null, placed: placementOf !== undefined && (await placementOf.call(store, sessionId)) !== undefined };
 }
-export const LEGACY_UNOWNED_AMNESTY_TENANT = "default";
-export function legacyUnownedSessionOk(deployment, caller, cell) {
-    return legacyUnownedAmnestyOpen(deployment, caller.principal ?? null) && ownerlessRowOpen(cell, caller);
+export async function sessionCellFor(face, caller, store, sessionId, owner) {
+    if (owner !== null)
+        return sessionOwnerCellOf(store, sessionId, owner);
+    const unread = ownerlessCellWithoutRead(face, caller);
+    if (unread !== undefined)
+        return unread;
+    try {
+        return await sessionOwnerCellOf(store, sessionId, null);
+    }
+    catch (e) {
+        if (FACES[face].placementUnreadable === "ordinary" && archiveUnreadable(e))
+            return OWNERLESS_ORDINARY_CELL;
+        throw e;
+    }
 }
-export function legacyUnownedAmnestyOpen(deployment, gateOwner) {
-    return !DEPLOYMENT_SHAPE_PREDICATES.multiTenant.holds(deployment) && gateOwner === LEGACY_UNOWNED_AMNESTY_TENANT;
+function archiveUnreadable(e) {
+    if (!(e instanceof SessionError))
+        return false;
+    const code = e.code;
+    switch (code) {
+        case "corrupt_session":
+        case "invalid_session":
+            return true;
+        case "not_found":
+        case "invalid_entry":
+        case "invalid_fork_target":
+        case "storage":
+        case "conflict":
+        case "placement_refused":
+        case "unknown":
+            return false;
+        default: {
+            const unknownCode = code;
+            throw new Error(`archiveUnreadable: unknown SessionError code ${String(unknownCode)}`);
+        }
+    }
 }
-export const LEGACY_SHELL_SENTINEL_OWNER = "anon:shell-live";
-export function sameSessionOwner(deployment, rowOwner, principal) {
-    if (rowOwner === principal)
-        return true;
-    if (rowOwner === null)
-        return legacyUnownedAmnestyOpen(deployment, principal);
-    return !DEPLOYMENT_SHAPE_PREDICATES.principalRequired.holds(deployment) && rowOwner === LEGACY_SHELL_SENTINEL_OWNER && principal === null;
+export function sameSessionOwner(deployment, rowOwner, occupant) {
+    const quals = qualsOf(claimCallerOf(recoveredSubject(occupant), deployment), ownerCellOf(rowOwner));
+    return rowOwner === null ? occupant === null || quals.has("j4") : quals.has("owner");
 }
 const UUIDV7_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 export function isUuidV7(s) {
@@ -65,6 +98,11 @@ export class HttpError extends Error {
     code;
     extra;
     constructor(status, message, opts) {
+        if (opts?.extra !== undefined) {
+            const reserved = refusalReservedKeyOf(opts.extra);
+            if (reserved !== undefined)
+                throw new TypeError(refusalReservedKeyMessage(opts.code ?? `HTTP ${status}`, reserved));
+        }
         super(message);
         this.status = status;
         this.name = "HttpError";
@@ -77,10 +115,23 @@ export class HttpError extends Error {
 export function createCodedHttpError(status, errorCode, message, extra) {
     return new HttpError(status, message, extra === undefined ? { code: errorCode } : { code: errorCode, extra });
 }
-export function createAuthorizer(config, sessionStore) {
-    return async ({ req, body }) => {
-        const principal = verifiedPrincipal(req, config);
-        if (config.requirePrincipal && !principal) {
+export function createAuthorizer(config, sessionStore, logger) {
+    const attachRefused = (reason, subject) => {
+        logger?.info("owner_gate_refused", { policyFace: "session.attach", reason, principalPresent: subject !== undefined });
+        return attachAbsentError();
+    };
+    const birthFace = birthFaceOf(sessionStore);
+    const withdrawFace = withdrawFaceOf(sessionStore);
+    const registerNew = async (id, owner, register, onBirth) => {
+        if (birthFace === undefined || withdrawFace === undefined)
+            return register(id, owner);
+        const receipt = await birthFace.registerWithReceipt(id, owner);
+        if (receipt.minted !== undefined)
+            onBirth?.(receipt.minted, withdrawFace);
+    };
+    return async ({ req, body, onBirth }) => {
+        const subject = verifiedSubject(req, config);
+        if (config.requirePrincipal && !subject) {
             throw new HttpError(401, `missing principal header '${config.principalHeader}'`);
         }
         let projectId;
@@ -91,7 +142,7 @@ export function createAuthorizer(config, sessionStore) {
             projectId = body.projectId.toLowerCase();
         }
         const requireExisting = body.requireExistingSession === true;
-        const headOf = headReadOf(sessionStore);
+        const headOf = deletionHeadReadOf(sessionStore);
         let head;
         const readOwner = headOf === undefined ? undefined : async (id) => {
             head = await headOf(id);
@@ -105,24 +156,20 @@ export function createAuthorizer(config, sessionStore) {
                 let owner = await readOwner(requested);
                 if (owner === undefined) {
                     if (requireExisting) {
-                        throw createCodedHttpError(404, "resume.session_not_found", "requireExistingSession: session does not exist (resume.session_not_found)");
+                        throw attachRefused("missing", subject);
                     }
                     if (register) {
-                        await register(requested, principal ?? null);
+                        await registerNew(requested, subject ?? null, register, onBirth);
                         owner = await readOwner(requested);
                     }
                     else if (config.requirePrincipal) {
                         throw new HttpError(403, "cannot claim a caller-supplied sessionId on a multi-tenant deployment: this worker's session store cannot record session ownership, so the id would stay unowned and the next caller could attach to it. Configure a durable session backend (SESSION_BACKEND), or omit sessionId to start a new session.");
                     }
                 }
-                else if (owner === null && principal !== undefined && !config.requirePrincipal && register) {
-                    await register(requested, principal);
-                    owner = await readOwner(requested);
-                }
-                if (owner != null && !sameSessionOwner(config, owner, principal ?? null)) {
-                    throw principal
-                        ? new HttpError(403, "session does not belong to this principal")
-                        : new HttpError(401, `session is principal-owned; missing principal header '${config.principalHeader}'`);
+                if (owner !== undefined) {
+                    const claimCaller = claimCallerOf(subject, config);
+                    if (!visibleOn("session.attach", qualsOf(claimCaller, await sessionCellFor("session.attach", claimCaller, sessionStore, requested, owner))))
+                        throw attachRefused("not_visible", subject);
                 }
             }
             else if (config.requirePrincipal) {
@@ -136,26 +183,13 @@ export function createAuthorizer(config, sessionStore) {
             }
             sessionId = uuidv7();
             if (register)
-                await register(sessionId, principal ?? null);
+                await registerNew(sessionId, subject ?? null, register, onBirth);
             if (readOwner)
                 await readOwner(sessionId);
         }
-        return { principal, sessionId, memoryScope: memoryScopeFor(config, principal, projectId), resolvedProjectId: projectId, ...(head === undefined ? {} : { head }) };
+        return { subject, sessionId, memoryScope: memoryScopeFor(config, subject === undefined ? undefined : personOf(subject), projectId), resolvedProjectId: projectId, ...(head === undefined ? {} : { head }) };
     };
 }
-export const PRINCIPAL_MAX_LENGTH = 190;
-export const PRINCIPAL_MAX_UTF8_BYTES = PRINCIPAL_MAX_LENGTH * 3;
-export const RESERVED_PRINCIPALS = ["_", "__none__", "_leader"];
-export const RESERVED_PRINCIPAL_PREFIXES = ["_leader-", ORPHAN_SESSION_OWNER_PREFIX];
-export function principalShapeProblem(principal) {
-    if (principalNameOf(principal) === undefined)
-        return "not_a_name";
-    if (RESERVED_PRINCIPALS.includes(principal) || RESERVED_PRINCIPAL_PREFIXES.some((p) => principal.startsWith(p)))
-        return "reserved";
-    if (principal.length > PRINCIPAL_MAX_LENGTH)
-        return "too_long";
-    return undefined;
-}
 export function assertPrincipalShape(principal) {
     const problem = principalShapeProblem(principal);
     switch (problem) {
@@ -166,21 +200,44 @@ export function assertPrincipalShape(principal) {
         case "reserved":
             throw createCodedHttpError(400, "principal_reserved", `principal ${JSON.stringify(principal)} is reserved (an internal scope sentinel) — authenticate with a real tenant identifier`);
         case "too_long":
-            throw createCodedHttpError(400, "principal_too_long", `principal exceeds ${PRINCIPAL_MAX_LENGTH} characters (the scope-column width every store pins, e.g. sendfile_link.scope VARCHAR(190)); got ${principal.length}`);
+            throw createCodedHttpError(400, "principal_too_long", `principal exceeds ${PRINCIPAL_MAX_BYTES} UTF-8 bytes (the identity-column width every store pins, e.g. sendfile_link.scope VARCHAR(190), mailbox.scope_key VARBINARY(190)); got ${Buffer.byteLength(principal, "utf8")}`);
         default: {
             const unknownProblem = problem;
             throw new Error(`assertPrincipalShape: unknown problem ${String(unknownProblem)}`);
         }
     }
 }
+export const CROSS_SESSION_FROM_SCOPE_MAX_ENCODED = 190;
+export const SUBJECT_ENCODED_BUDGET = CROSS_SESSION_FROM_SCOPE_MAX_ENCODED;
+export function subjectWidthExceeded(subject) {
+    try {
+        buildCrossSessionEnvelope({ from: encodePeerAddress("width-probe"), fromScope: subject }, "");
+        return false;
+    }
+    catch (e) {
+        if (e instanceof CrossSessionCodecError && e.code === "cross_session.invalid_from_scope")
+            return true;
+        throw e;
+    }
+}
 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];
 }
-export const encodeCheckpointScope = (principal) => principal ?? CHECKPOINT_PUBLIC_SCOPE;
-export const decodeCheckpointScope = (scope) => (scope === CHECKPOINT_PUBLIC_SCOPE ? undefined : scope);
+export const encodeCheckpointScope = (subject) => subject ?? CHECKPOINT_PUBLIC_SCOPE;
+export const decodeCheckpointScope = (scope) => (scope === CHECKPOINT_PUBLIC_SCOPE ? undefined : mintDurableOwnerKey(scope));
 export const ownerOfCheckpointScope = (scope) => decodeCheckpointScope(scope) ?? null;
+export const checkpointPartsOf = (scope) => {
+    const key = decodeCheckpointScope(scope);
+    return key === undefined ? undefined : partsOf(key);
+};
+export function scopeCellOf(scope) {
+    if (typeof scope !== "string")
+        return undefined;
+    const owner = decodeCheckpointScope(scope);
+    return owner === undefined ? OWNERLESS_ORDINARY_CELL : { owner };
+}
 export function principalFrom(req, config) {
     if (!config.principalHeader)
         return undefined;
@@ -225,7 +282,54 @@ export function ssoVerifiedPrincipalInc(req) {
     const v = SSO_PRINCIPAL_INCS.get(req);
     return v !== undefined && v.length > 0 ? v : undefined;
 }
-export function verifiedPrincipal(req, config) {
+export function verifiedPerson(req, config) {
+    const verified = verifiedIdentity(req, config);
+    return verified === undefined ? undefined : mintPerson(verified);
+}
+export const SCENARIO_HEADER = "x-agent-scenario";
+export function scenarioHeaderOf(req) {
+    const raw = req.headers[SCENARIO_HEADER];
+    return (Array.isArray(raw) ? raw[0] : raw)?.trim() || undefined;
+}
+export function scenarioWithoutPrincipalError() {
+    return createCodedHttpError(400, "request.scenario_without_principal", `the ${SCENARIO_HEADER} header selects a partition inside a verified person, but this request carries no verified principal — authenticate the person, or drop the header`);
+}
+export function scenarioHeaderUnknownError(name, known) {
+    return createCodedHttpError(400, "scenario_unknown", `unknown scenario ${JSON.stringify(name)} in the ${SCENARIO_HEADER} header — it is not a scenario of this deployment`, known === undefined ? undefined : { known: [...known] });
+}
+const REQUEST_SUBJECTS = new WeakMap();
+export function verifiedSubject(req, config) {
+    let memo = REQUEST_SUBJECTS.get(req);
+    if (memo === undefined) {
+        try {
+            memo = { subject: judgeRequestSubject(req, config) };
+        }
+        catch (error) {
+            memo = { error };
+        }
+        REQUEST_SUBJECTS.set(req, memo);
+    }
+    if ("error" in memo)
+        throw memo.error;
+    return memo.subject;
+}
+function judgeRequestSubject(req, config) {
+    const person = verifiedPerson(req, config);
+    const raw = scenarioHeaderOf(req);
+    if (raw === undefined)
+        return person === undefined ? undefined : subjectOf(person);
+    if (person === undefined)
+        throw scenarioWithoutPrincipalError();
+    const scenario = scenarioNamed(raw);
+    if (scenario === undefined)
+        throw scenarioHeaderUnknownError(raw, undefined);
+    const subject = subjectOf(person, scenario);
+    if (subjectWidthExceeded(subject)) {
+        throw createCodedHttpError(400, "principal_too_long", `principal plus the ${SCENARIO_HEADER} scenario exceeds ${SUBJECT_ENCODED_BUDGET} characters once percent-encoded (the narrowest face the subject lands in: the cross-session envelope from-scope) — use a shorter principal or scenario name`);
+    }
+    return subject;
+}
+function verifiedIdentity(req, config) {
     const sso = ssoVerifiedPrincipal(req);
     if (sso) {
         assertPrincipalShape(sso);

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

@@ -1,4 +1,6 @@
+import { type DeploymentShapeInput } from "./deployment-shape.js";
 import type { Logger } from "./observability/logger.js";
+import type { LaunchWorkspace } from "./task-cwd.js";
 /** 部署声明的配置根(绝对路径);没声明 ⇒ `undefined`;空串 ⇒ 抛(起服拒,句子点名变量与出路)。纯读 env,不碰文件。**只有 `loadConfig` 调它**
  *  (结果 = 配置席 `agentConfigDir`);别的读者读那一席。 */
 export declare function declaredSemaConfigDir(env?: NodeJS.ProcessEnv): string | undefined;
@@ -16,4 +18,22 @@ export declare function configRootOf(config: {
 export declare function provisionSemaConfigDir(config: {
     readonly agentConfigDir?: string;
 }, logger: Pick<Logger, "warn">): void;
+/**
+ * 起服的**公告动作**(每个入口一次):配置根就是工作区、或是工作区的祖先 ⇒ warn 恰一行 `sema_config_root_encloses_workspace`;不相交(含配置根在工作区之内)⇒ 零行。**不拒启、不改任何行为。**
+ *
+ * 为什么要说:引擎缺省写保护表的 `.sema` 行在声明的配置根下同样守,根**之内**任何路径的写都过 `write_protection` 一问(allow 规则清不掉、`acceptEdits` 不放、无人值守腿直接拒)——
+ * 配置根是工作区的祖先时,工作区里每一次写都出这一张卡,而此前起服与首条任务零行。能不能用仍只有引擎一个判官,本服务只把这个构造说出来,不判、不铸拒句。
+ *
+ * 判法:配置根({@link configRootOf})与工作区({@link LaunchWorkspace},读链唯一属主 `task-cwd.ts` 的 `launchWorkspaceOf`)各取一次规范形后,`pathIsWithin(配置根, 工作区)`(含相等);两侧同一只规范形座。
+ * 读数里的两条路径是**原样拼写**(运维认得出来的那两条)。手不在本机盘上的车道(部署形表行 `sandboxPathAdjudication`:工具跑在沙箱 / 远程)不判 —— 那里的工作区不是本进程这台机的盘。
+ * 看不见的一半(随包文档如实写):请求体里按任务给的 `cwd` 起服时不可知,不在读链里;规范形对**尚不存在**的尾巴只比字串、不折大小写 —— 大小写不敏感的盘上,两个只差大小写且尾巴都还不存在的拼写读成两处,这一行会漏报
+ * (与记忆根那一判共用同一只规范形,那一判的失败方向是多报,这一判的是漏报;如实披露)。
+ * 句子只描述位置关系,后果限定在引擎**缺省**写保护表上:用 `WRITE_PROTECTED_TABLE_REPLACE` 去掉那一行的部署不受影响(这一行不读那张表),可忽略它。
+ *
+ * 规范形读不出(盘上竞态:探完到取值之间目录被挪走 / 搜索权限被收)⇒ 披露面不得把起服打死:响亮报另一行 `sema_config_root_workspace_check_unavailable`(类名 + 机器码),起服照常。
+ * 位置:HTTP 服务在装配第 2 段执行车道合成之后(读的是合成后的车道与工作区底),`run-local` 在工作区定下之后 —— 车道在这两处才定形,所以不与 {@link provisionSemaConfigDir} 同一拍。
+ */
+export declare function announceConfigRootEnclosingWorkspace(config: {
+    readonly agentConfigDir?: string;
+} & DeploymentShapeInput<"lane">, logger: Pick<Logger, "warn">, workspace: LaunchWorkspace, canonical?: (p: string) => string): void;
 //# sourceMappingURL=sema-config-dir.d.ts.map

package/dist/sema-config-dir.js

@@ -1,6 +1,9 @@
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { ensureDir } from "@sema-agent/core";
+import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
+import { canonicalPathOf, pathIsWithin } from "./memory-scope.js";
+import { errorCodeOf, errorKindOf } from "./observability/err-text.js";
 export function declaredSemaConfigDir(env = process.env) {
     const raw = env.SEMA_CONFIG_DIR;
     if (raw === undefined)
@@ -30,4 +33,26 @@ export function provisionSemaConfigDir(config, logger) {
         });
     }
 }
+export function announceConfigRootEnclosingWorkspace(config, logger, workspace, canonical = canonicalPathOf) {
+    if (DEPLOYMENT_SHAPE_PREDICATES.sandboxPathAdjudication.holds(config))
+        return;
+    const configRoot = configRootOf(config);
+    try {
+        if (!pathIsWithin(configRoot, workspace.dir, canonical))
+            return;
+    }
+    catch (e) {
+        logger.warn("sema_config_root_workspace_check_unavailable", { configRoot, workspace: workspace.dir, workspaceFrom: workspace.from, errorKind: errorKindOf(e), errorCode: errorCodeOf(e) });
+        return;
+    }
+    logger.warn("sema_config_root_encloses_workspace", {
+        configRoot,
+        workspace: workspace.dir,
+        workspaceFrom: workspace.from,
+        note: "The configuration root (配置根, SEMA_CONFIG_DIR; default ~/.sema) is the workspace (工作区) itself or one of its ancestors. With the engine's default write-protection table, every file the agent writes " +
+            "inside it goes through a write-protection prompt that allow rules cannot clear, and unattended runs are refused (a deployment that replaced or disabled that table with WRITE_PROTECTED_TABLE_REPLACE " +
+            "is not affected and can ignore this line: it only reports where the two directories sit). This line changes nothing. Point SEMA_CONFIG_DIR at a dedicated directory outside the workspace " +
+            "(unset it to use ~/.sema).",
+    });
+}
 //# sourceMappingURL=sema-config-dir.js.map

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

@@ -25,9 +25,10 @@
  *    与每次生效配置换代(`web-admin-client/apply-effective.ts` 本体:CAS 之后、Runner 换装与 commit 之前 —— 声明先于席位,旧世代不声明)。名单只随**落地**的世代
  *    增长(本进程 env 是 boot 期输入:一个名字一旦指过本进程的凭据,条目改名 / 删掉之后它的值仍在 env 里 ⇒ 落地过的名不退出;没落地的候选不留痕 —— 名单重判命中 / 换装拒 ⇒
  *    {@link withdrawServerWithheldEnv} 撤回到换代前的集合)。声明失败(坏形名 / 运行时回填名)⇒ 引擎抛且声明保持原状:起服那次 = 拒启,换代那次 = 候选整拒(与 stage
- *    抛同路)。能力词 `inherit_env.own_credentials_withheld` 在本进程的事实 =
- *    {@link ownCredentialsWithheld}:最近一次成功声明的集合 ⊇ 当前生效配置应声明的集合(活配置经 {@link bindOwnCredentialsConfig} 在 `loadConfig()` 之后绑一次;
- *    未绑 / 未声明 ⇒ false,事实读不到应声明集合就不答 true)。
+ *    抛同路)。「引擎扣没扣这些名」只有一只读法 {@link ownCredentialNamesNotWithheld}(问引擎本尊的判官,不读本文件的镜像),两个读者:
+ *    `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}),
  *    逐个交给引擎的同一只判;引擎判「不是凭据值」的那一个不扣、名照扣、不拒启、点名一次。能力词 `inherit_env.own_credential_values_withheld` 的事实 = {@link ownCredentialValuesWithheld}(位真 ⇔ 值臂真扣)。
  *  · 调用方显式传入的 env(`cfg.env` / 单次命令的 `env` / 沙箱的点名放回)不是继承,照旧原样叠在组合结果之上 —— 那是适配器自己的凭据通道。
@@ -92,8 +93,23 @@ export declare function withdrawServerWithheldEnv(): void;
 /** 把活配置交给能力位读(stage-01 / run-local 在 `loadConfig()` 之后各一次;读的是 `config.modelApiKeyEnv` 这个**属性**,commit 整表重赋值之后看到的就是新表)。 */
 export declare function bindOwnCredentialsConfig(config: Pick<ServiceConfig, "modelApiKeyEnv">): void;
 /**
- * 能力词 `inherit_env.own_credentials_withheld` 在本进程的事实:最近一次成功声明的名单 ⊇ 当前生效配置应声明的名单。是一次比较,不是「声明过」的旗 ——
- * 活表若被谁绕过声明写了新名,这里立刻 false(位不替流程担保)。没绑活配置 / 没声明过 ⇒ false(fail-closed)。
+ * 「引擎此刻扣不扣这些名」的**唯一读法**:给哪张表就判哪张表的应声明集合({@link serverWithheldEnvNames}),答引擎此刻**没有**扣下的那些名(空 = 全扣)。
+ * 读引擎本尊的判官 `inheritEnvPolicyProblem`(名单解析器 ② 判「点到本服务自有凭据名」问的同一只;按平台比名),不读本文件的镜像 `declared` ——
+ * 镜像只是声明口的写者状态(并集 / 深度 1 撤回),答「扣没扣」的只有引擎:引擎的声明是进程级的(换一份模块图、镜像归零,它照在)。两个读者:
+ * `loadConfig` 的声明前提({@link ownCredentialDeclarationRefusal},起服表 = 空表)与能力位({@link ownCredentialsWithheld},活表)。
+ */
+export declare function ownCredentialNamesNotWithheld(modelApiKeyEnv?: ModelApiKeyEnvTable): readonly string[];
+/**
+ * 🔴 `loadConfig()` 的前提:本进程的自有凭据名(起服表 = 目录 secret 名 ∪ 名单型旋钮名)此刻全被引擎扣下 —— 否则拒因(句子只写这一处),满足 ⇒ `undefined`。
+ * 名单型旋钮的自有凭据判与每一条宿主腿的扣留都读引擎此刻的声明;声明为空时判官恒答「合法」⇒ 名单点到本服务凭据照收、宿主子进程照拿,零声响。
+ * 三个进程入口第一步就声明(stage-01 / run-local 先于 `loadConfig()`,bake-runner 先于它自己的 env 读),所以本服务起服序里这句永远不出现;
+ * 它说给不经入口直接调 `loadConfig()` 的进程听(包根的嵌入方、bench、探针脚本):出路一步 —— 先调包根的 {@link declareServerWithheldEnv}。
+ * 回显的是变量**名**(不是值)。
+ */
+export declare function ownCredentialDeclarationRefusal(): string | undefined;
+/**
+ * 能力词 `inherit_env.own_credentials_withheld` 在本进程的事实:当前生效配置应声明的每一个名,引擎此刻都扣着({@link ownCredentialNamesNotWithheld} 为空)。
+ * 是一次比较,不是「声明过」的旗 —— 活表若被谁绕过声明写了新名,这里立刻 false(位不替流程担保)。没绑活配置 / 引擎没扣 ⇒ false(fail-closed)。
  */
 export declare function ownCredentialsWithheld(): boolean;
 /**

package/dist/server-secret-env.js

@@ -1,4 +1,4 @@
-import { declareWithheldEnv, hostChildEnv, inheritedHostEnv } from "@sema-agent/core";
+import { declareWithheldEnv, hostChildEnv, inheritEnvPolicyProblem, inheritedHostEnv } from "@sema-agent/core";
 import { CONFIG_CATALOG } from "./config-catalog.js";
 import { ENV_NAME_ALLOWLIST_KNOB_NAMES } from "./env-name-allowlist-knobs.js";
 import { recordOwnCredentialValueNotWithheld, recordSecretEnvScrub } from "./observability/secret-env-scrub.js";
@@ -46,11 +46,21 @@ export function withdrawServerWithheldEnv() {
 export function bindOwnCredentialsConfig(config) {
     liveConfig = config;
 }
+export function ownCredentialNamesNotWithheld(modelApiKeyEnv = NO_MODEL_ENTRIES) {
+    return serverWithheldEnvNames(modelApiKeyEnv).filter((name) => inheritEnvPolicyProblem([name]) === undefined);
+}
+export function ownCredentialDeclarationRefusal() {
+    const missing = ownCredentialNamesNotWithheld();
+    if (missing.length === 0)
+        return undefined;
+    return (`loadConfig(): this process has not declared its own credentials to the engine (${missing.length} of ${serverWithheldEnvNames().length} names are not withheld, e.g. ${missing[0]}) — ` +
+        "call declareServerWithheldEnv() (package root) once before loadConfig(), before any execution environment is built or any child process is started. " +
+        "Without it the name-list knobs' own-credential refusal and the withholding on every host child process read an empty declaration and let this service's credentials through.");
+}
 export function ownCredentialsWithheld() {
-    if (declared === undefined || liveConfig === undefined)
+    if (liveConfig === undefined)
         return false;
-    const own = declared.names;
-    return serverWithheldEnvNames(liveConfig.modelApiKeyEnv).every((name) => own.has(name));
+    return ownCredentialNamesNotWithheld(liveConfig.modelApiKeyEnv).length === 0;
 }
 export function ownCredentialValuesWithheld() {
     if (declared === undefined || liveConfig === undefined)

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

@@ -14,7 +14,7 @@
  *
  * ## 动词(core 板 [ref] ⑧⑨ 给定;本车第零步探针 `test/core-probe-parked-stop-root-access.test.ts` 真跑证实)
  *  · 枚举 = `agentStore.listBySession(scope, 根会话)`(耐久行,锚 = 行的 session / parent / root 任一),并上本进程登记表里的
- *    `activeDelegationHandles(scope, 根会话)`(没接耐久店的部署只有这一半)。scope 轴由调用方给(协调器:会话行的 `owner ?? "default"`)。
+ *    `activeDelegationHandles(scope, 根会话)`(没接耐久店的部署只有这一半)。scope 轴由调用方给(唯一派生 {@link sessionTenantScope})。
  *  · **parked** 行 ⇒ `checkpointStore.expire(token, 卡自己的 scope)`(与 core 自己的本进程仲裁器同一只 CAS)+
  *    `registry.reconcileParkedAgents(stores, scope)` ⇒ 行 `failed`(stoppedBy `system`)、卡离开待决面。任何副本上都做得到 ⇒ 预检把它
  *    算作可达(前提是本部署有 checkpoint 店)。
@@ -31,7 +31,7 @@
  * 能在树活着时改根放置 / 住客的三门 —— 删除(`boot/session-faces.ts`)、换绑(`routes/devices.ts`)、导入(`routes/session-sync.ts`)—— 与显式结清口
  * `POST /v1/sessions/:id/children/retire`(`routes/background.ts`)都只经这里:**观察**只有 {@link probeSessionChildren}(同一次枚举交出活子代句柄
  * `liveChildren` 与不可达的那几只),**结清**只有 {@link retireSessionChildren}(结果交首轮观察到的句柄 `observed`);scope 只有一处取
- * {@link sessionChildrenScope}(会话属主 `owner ?? "default"`)。wire 上的 `children` / `remaining` 一律经名册的 id 投影出门。
+ * {@link sessionTenantScope}(会话的引擎租户分区)。wire 上的 `children` / `remaining` 一律经名册的 id 投影出门。
  * 子代半是**写前一次观察**:子代登记在 core 的后台子代店,写者的事务装不进这一读(认领半才是写事务内那一读,`execution-placement-sql.ts` 头注)。
  *
  * ## 循环(有上界)
@@ -85,10 +85,12 @@ export type RetireSessionChildrenOutcome = {
     readonly remainingHandles: readonly string[];
 };
 /**
- * 以一只根会话为根的后台子代在哪个 scope 分区里枚举 —— **唯一一处取**:会话属主 `owner ?? "default"`(删除门、换绑 / 导入两门、结清口同读;
- * 子代按 run 的 principal 登记、与会话属主不同源的那一形是既有缺陷,修在这里一处)。
+ * 一只会话的**引擎租户分区** —— **唯一一处取**:以它为根的后台子代、它的后台 shell、它的会话信箱盒,都登记在这一分区(删除门、换绑 / 导入两门、结清口、
+ * 删除协调器的信箱腿与 shell 收割腿、删后收尾的丢箱同读;属主串本身不是 scope)。引擎按任务规格的身份格登记,所以这里读的是**引擎交界**
+ * (`engine-identity.ts` 的 `taskSpecIdentityOf`)从会话属主恢复出的那一格:没带场景的会话 = 属主(逐字节同改前);带场景的会话(属主 `_scn:<场景>:<人>`)=
+ * 引擎登记时用的那一个值(今天是人)—— 按属主串去枚举 / 退役 / 收割会打到一个空分区。无主 ⇒ `"default"`。
  */
-export declare function sessionChildrenScope(owner: string | null): string;
+export declare function sessionTenantScope(owner: string | null): string;
 /**
  * **可达性预检**(零写;协调器在任何破坏性步骤之前调)。parked 行在有 checkpoint 店时可达(expire + reconcile 在任何副本上都成);
  * running 行除非 {@link runsOnAnotherReplica} 都可达(`getAccessibleTask` / `agentStore.get` 都是纯读,不动任何东西)。

package/dist/session-children-retire.js

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

package/dist/session-deletion.d.ts

@@ -0,0 +1,88 @@
+/**
+ * **会话的三态:活 → 在删 → 没了**(删会话 × 提交只赢一个的律;规则只写在这里一次,三只会话店与删除协调器同读)。
+ *
+ * ## 律
+ * 一只会话行此刻是三态之一:
+ *  · **活** —— 接受一切读写;
+ *  · **在删** —— 一次删除已经在根行锁里判过「没有在跑的 run、属主是调用方」并立了围栏(写下自己的**删除尝试令牌**),还没删完。在删由持令牌的那一次删除**独占**:
+ *    删除门之外的一切读者与写者把它读作「行不在」(头读、列表、认领点的规则 L、登记 —— 撞上即「已存在」,不新建);认领落不下,于是删除级联的每一腿都只作用在一只
+ *    不会再起回合的会话上;
+ *  · **没了** —— 行删掉了;同 id 的下一次登记是新住客。
+ * 在删**不回到活**(没有放弃删除的臂:子代可达性预检在围栏之前,终刀失败只会重试)⇒ 围栏之后立的外部围栏(会话盒墓碑)不会挡错一只活会话。
+ *
+ * ## 谁写、谁读
+ *  · 围栏(活 → 在删 / 在删 → 在删 = 接管已死的那一次、换令牌)= {@link SessionDeletionFace.fence}:删除路**唯一**的认领判;一次仍可能活着的删除持有的行**不接管**
+ *    (答「在删中」)—— 否则陈旧尝试与接管者交错、接管者删完而同 id 重登记之后,陈旧尝试的下一腿会落在新住客身上;
+ *  · 终刀(在删 → 没了)= 删净一只会话的**执行体**(`src/session-erase.ts`;SQL = 执行器的 `eraseSession`,local = 会话店的删除锁节 `deleteSession(id, owner, token, legs)`):
+ *    根行锁里比属主、判「这一行处于本令牌的在删态」(判官 `judgeSessionWrite` 的 `erase` 词),不是 ⇒ 一行不删;是 ⇒ 同一个事务 / 锁节删完会话挂靠的全部行、行最后删;
+ *  · 执行体之前的每一步进程面动作(不在根行锁里)之前,协调器问 {@link SessionDeletionFace.holds}:令牌被换了(另一次删除接管)⇒ 这次尝试就此停,答「被接管」;
+ *  · 唯一收尾者 = 删除协调器:起服装配完之后按 {@link SessionDeletionFace.pending} 逐只再跑一遍(= 接管**那一只令牌**:读到之后那一次删完、同 id 重登记的新行不被碰);
+ *    持有者已死的在删行,重发的 DELETE 同样是接管。
+ * 持久面:SQL = 旁表 `session_ext.deleting_token`(列属主 `plugins/session-ext-table.ts`);local = 会话元数据边档那一格的 `deleting`。
+ */
+/** 围栏的回执:这一次删除的令牌 + 被删的那一位住客的化身(空间回收的键;存量行没有化身 ⇒ `undefined`)。 */
+export interface SessionDeletionTicket {
+    readonly token: string;
+    readonly incarnation: string | undefined;
+}
+/** 此刻处于在删态的一行(收尾者的输入):它的 id、属主与持有它的令牌(收尾按这一位属主、**只接管这一只令牌**再跑一遍协调器)。 */
+export interface PendingSessionDeletion {
+    readonly sessionId: string;
+    readonly owner: string | null;
+    readonly token: string;
+}
+/**
+ * 一只在删令牌的持有者此刻在哪(协调器答,它记得本进程铸过的每一只令牌):`running` = 本进程里那一次删除还在跑;`ended` = 本进程里那一次已经结束而没删完
+ * (某腿失败 / 被接管)—— 死的;`elsewhere` = 不是本进程铸的(上一个进程 / 别的副本)。
+ */
+export type DeletionHolder = "running" | "ended" | "elsewhere";
+/** 围栏的选项:`holder` = 令牌持有者在哪(协调器的在飞表);`expect` = 只接管这一只令牌(收尾者;活行 / 别的令牌 ⇒ `undefined`)。 */
+export interface SessionDeletionFenceOptions {
+    readonly holder: (token: string) => DeletionHolder;
+    readonly expect?: string;
+}
+/** 围栏的答复:回执(本次立了 / 接管了)· `inProgress`(一次仍可能活着的删除持有这一行 —— 不接管)· `undefined`(行不在 / 属主不是这一位 / 收尾者的令牌对不上)。 */
+export type SessionDeletionFenceAnswer = SessionDeletionTicket | {
+    readonly inProgress: true;
+} | undefined;
+/**
+ * 别的进程里一次删除的令牌**多久之后**才可以被接管(SQL 多副本:另一副本上那一次删除可能还活着,本进程看不见它)—— 令牌是 uuidv7,它的时刻就是那一次尝试的起点。
+ * 一次删除的各腿通常几秒内跑完(子代停止有轮次上界、后台 shell 的硬杀宽限是秒级);十分钟之后仍未删完的读作那一次已死(崩溃 / 进程被杀)。
+ * 如实的边:一次活着却卡过十分钟的删除会被接管,它此后的每一腿之前读到令牌已换、就此停 —— 两腿之间的那一拍是披露的残余(`src/boot/session-faces.ts` 的协调器注)。
+ * local 数据根独占(一个数据根恒一个进程),别的进程的令牌一律是死的 ⇒ 不读这只数。
+ */
+export declare const CROSS_PROCESS_TAKEOVER_AFTER_MS: number;
+/** 一只令牌(uuidv7)的铸造时刻(ms;读不出 ⇒ `undefined`,读者按「刚铸」处置 —— 不接管)。 */
+export declare function deletionTokenMintedAt(token: string): number | undefined;
+/** 会话店的删除面(三只会话店各一只实现,暖缓存包装原样转发;一只能力位 —— 三个动词同在或同缺)。 */
+export interface SessionDeletionFace {
+    /**
+     * 立围栏:根行锁里 ——
+     *  · 活行 ∧ 属主是 `owner`(字面相等,`null` 与 `null` 相等)∧ 不带 `expect` ⇒ 判认领(在 ⇒ 抛 `SessionActiveRunError`,一个字节不写)、写新令牌;
+     *  · 在删行 ∧ 属主等 ∧(不带 `expect` 或持有的就是它)⇒ 持有它的那一次**仍可能活着**(`holder` 答 `running`;SQL 另加:答 `elsewhere` 而令牌铸于
+     *    {@link CROSS_PROCESS_TAKEOVER_AFTER_MS} 之内 —— 别的副本上那一次可能还在跑)⇒ `{ inProgress }`(不接管、不写);否则(那一次已死)⇒ **接管**:换新令牌
+     *    (在删期间认领落不下,不再判);带 `expect` 而持有的不是它 ⇒ `undefined`;
+     *  · 行不在 / 属主不等 / 带 `expect` 而这一行是活的 ⇒ `undefined`(一个字节不写)—— 收尾者永远不把一只活行送进在删。
+     */
+    fence(sessionId: string, owner: string | null, opts: SessionDeletionFenceOptions): Promise<SessionDeletionFenceAnswer>;
+    /** `token` 此刻仍是这只会话的在删令牌(无锁一读;行不在 / 活 / 别的令牌 ⇒ `false`)。 */
+    holds(sessionId: string, token: string): Promise<boolean>;
+    /** 此刻处于在删态的全部行(按 id 排序)。 */
+    pending(): Promise<readonly PendingSessionDeletion[]>;
+}
+/**
+ * 删除协调器的结局(`DELETE /v1/sessions/:id` 读它,一形一句):
+ *  · `{ deleted: true }` —— 这一次删完了(终刀删掉了行);`{ deleted: false }` —— 门验过之后行已不在 / 不是这一位的(什么都没删);
+ *  · `{ active }` —— 围栏判到认领(409 `conflict.session_active_run`,一字节没写);`{ childrenAlive }` —— 子代预检拒(409 `conflict.session_children_alive`,一字节没写);
+ *  · `{ inProgress: true }` —— 同一只会话的另一次删除持有它(仍在跑,或接管了这一次)—— 409 `conflict.session_deleting`,由那一次删完;这次请求不再删任何东西。
+ */
+export type SessionPurgeOutcome = {
+    readonly deleted: boolean;
+} | {
+    readonly active: string;
+} | {
+    readonly childrenAlive: readonly string[];
+} | {
+    readonly inProgress: true;
+};
+//# sourceMappingURL=session-deletion.d.ts.map

package/dist/session-deletion.js

@@ -0,0 +1,8 @@
+export const CROSS_PROCESS_TAKEOVER_AFTER_MS = 10 * 60_000;
+export function deletionTokenMintedAt(token) {
+    const hex = token.replace(/-/g, "");
+    if (!/^[0-9a-f]{32}$/i.test(hex) || hex[12] !== "7")
+        return undefined;
+    return parseInt(hex.slice(0, 12), 16);
+}
+//# sourceMappingURL=session-deletion.js.map