@sema-agent/server 7.146.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 { mkdirSync } from "node:fs";
 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)
@@ -20,7 +23,7 @@ export function provisionSemaConfigDir(config, logger) {
     if (dir === undefined)
         return;
     try {
-        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        ensureDir(dir);
     }
     catch (e) {
         logger.warn("sema_config_dir_unprovisioned", {
@@ -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;
 /**
@@ -119,6 +135,8 @@ export interface HostSubprocessEnvRequest {
  * 九条宿主腿都只经它(直接或经 {@link gitSubprocessEnv}):host shell(三个继承词原样交给 `policy`)、project-memory / center-plugins / leader 三条 git 腿、
  * 本地语言服务器、bake-runner 的每一只子进程组、local-docker 与 adb 两条 CLI 腿(`"all"`)、settings hooks 的命令腿(十二名严格名单 + 有效环境层作授予)。`allow` 只在**有部署级出路**的现场非空(今天 = `LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`,
  * 它们的现场在 `SECRET_ENV_SCRUB_SITES` 里登记了 `remedy`,披露行因此是 warn + 放行名单 + 出路句);其余现场传 `[]`。
+ * 「扣了哪些名字」一腿一个读者:host shell 腿由引擎读 `withheldEnv` 说(`inherit_env.names_withheld`,现场登记 `told:"engine-notice"` ⇒ 本函数对它只计数、不写披露行);
+ * 其余各条腿(含 host 适配器类里不交给引擎的 git worktree 基环境,`HostEnvConfig.gitBase`)引擎没有读者,披露行是唯一的读法(`told:"log"`)。
  * 返回 `NodeJS.ProcessEnv` 形(值可能是 `undefined` 的键本来就不会进子进程);调用方显式要交的键(`LC_ALL`、`cfg.env` …)叠在它之上。
  * 调用时机 = 每次要交 env 时现算一次(`process.env` 在本仓是 boot 期输入,各次同值;计数因此是「每组合一次」)。
  * 引擎对坏策略 / 点到自有凭据名的白名单在这里**抛**(spawn 时的拒是不变量;构造时的拒由各构造点自己先问 `inheritEnvPolicyProblem`)。

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/service-version.d.ts

@@ -1,5 +1,6 @@
 /** Service version for GET /v1/capabilities — read from the package.json shipped next to src/ in the
- *  image (Dockerfile COPYs it), once per process. Best-effort: an unreadable file reports "unknown", never crashes boot. */
+ *  image (Dockerfile COPYs it), once per process. Best-effort: an unreadable file — or a `version` that is not a string — reports "unknown", never crashes boot.
+ *  (Whether "unknown" may serve is each reader's own judgment: the local data root's engine high-water refuses a build whose version is not a release version.) */
 declare function serviceVersion(): string;
 export { serviceVersion };
 //# sourceMappingURL=service-version.d.ts.map

package/dist/service-version.js

@@ -6,8 +6,8 @@ function serviceVersion() {
 }
 function readServiceVersion() {
     try {
-        const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-        return pkg.version ?? "unknown";
+        const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"))?.version;
+        return typeof version === "string" ? version : "unknown";
     }
     catch {
         return "unknown";

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();