@sema-agent/server 7.147.0 → 7.149.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

@@ -13,7 +13,7 @@
  * 剥掉的键经一个登记过的 `SecretEnvScrubSite` 留痕(现场按**腿**命名);git 腿再叠 git 自己的两件({@link gitSubprocessEnv})。射程 = **每一条**宿主腿:
  * src 里每一只值引 `node:child_process` 的文件都是登记腿、其中每一次起子进程都显式交组合出的 env(普查门在 `test/secret-env-scrub-host-legs.test.ts`)。
  * 腿的继承词是调用点的事实,按「子进程里跑的是谁选的代码」定:模型命令(host shell,交任务自己的词)/ 仓里的钩子与凭据助手(三条 git 腿)/ 执行仓代码的
- * 语言服务器 / 配方脚本 ⇒ 形状剥 `"scrub"`;请求带来的 settings hooks 命令 ⇒ 严格名单(十二名基础名单,`[names]` 臂;请求的继承词只给工具 shell、对 hook 不作用)、请求的有效环境层作授予叠在继承结果之上(引擎的 `hostChildEnv`);部署方装在宿主上的 CLI(`docker` / `adb`,命令本身
+ * 语言服务器 / 配方脚本 ⇒ 形状剥 `"scrub"`;请求带来的 settings hooks 命令 ⇒ 严格名单(十二名基础名单,`[names]` 臂;请求的继承词只给工具 shell、对 hook 不作用)∪ 部署方 `HOOK_ENV_ALLOW` 点名放回、请求的有效环境层作授予叠在继承结果之上(引擎的 `hostChildEnv`);部署方装在宿主上的 CLI(`docker` / `adb`,命令本身
  * 在容器 / 设备里跑、那边的 env 由 `-e` 显式给)⇒ `"all"` —— 只扣本服务自有凭据,CLI 与它的凭据助手 / 插件要读的生态变量照交(形状剥会剥
  * `ADB_VENDOR_KEYS` / `AWS_SECRET_ACCESS_KEY` 一类,实测)。三个继承词只在引擎一处判:
  *  · `"all"` = 整份环境 **减** 本进程声明的自有凭据名;`"scrub"`(缺省)= 形状剥 ∪ 该名单;`[names]` = 严格白名单,点到名单中的名 ⇒ 引擎响亮拒
@@ -25,27 +25,31 @@
  *    与每次生效配置换代(`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)。
- *  · **值臂**(core 7.52.0 [ref]):声明是一张表 `{ names, values }`。`values` = 本进程持有凭据的变量此刻的值(目录 secret 名 ∪ 模型条目 `apiKeyEnv`,{@link serverCredentialValueSources}),
- *    逐个交给引擎的同一只判;引擎判「不是凭据值」的那一个不扣、名照扣、不拒启、点名一次。能力词 `inherit_env.own_credential_values_withheld` 的事实 = {@link ownCredentialValuesWithheld}(位真 ⇔ 值臂真扣)。
+ *    抛同路)。「引擎扣没扣这些名」只有一只读法 {@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})
+ *    此刻装着的**每一枚**本服务凭据 —— 颗粒按本服务读这只变量的那一只解析器定(目录行的 `credentialForm`:整值总在内,`SERVICE_AUTH_TOKENS` 另加每一枚令牌、
+ *    `APPROVAL_HMAC_KEYS` 另加每一把钥;{@link credentialsHeldBy})—— 引擎按整串比,所以一枚令牌换了个变量名放着与原变量同扣,部分重叠 / 前后缀不同的值不扣。
+ *    逐枚交给引擎的同一只判;引擎判「不是凭据值」的那一枚不扣、名照扣、不拒启、点名那个变量一次。能力词 `inherit_env.own_credential_values_withheld` 的事实 = {@link ownCredentialValuesWithheld}(位真 ⇔ 值臂每一枚都真扣)。
+ *    「这个变量是不是本服务的凭据」(名是,或值是)只有一只读法 {@link ownCredentialVariable}(判官 = 引擎此刻的声明):名单型旋钮的解析器与声明增长时的重判都问它。
  *  · 调用方显式传入的 env(`cfg.env` / 单次命令的 `env` / 沙箱的点名放回)不是继承,照旧原样叠在组合结果之上 —— 那是适配器自己的凭据通道。
  * 各腿只调 {@link hostSubprocessEnv} / {@link gitSubprocessEnv} —— 不许再有内联拼装、不许再有 `{ ...process.env }`、不许本仓再判任何一个继承词、不许起子进程不交 env
  * (类级门与普查门在 `test/secret-env-scrub-host-legs.test.ts`)。
  *
  * ## 点名放行([ref] / [ref],一只谓词各处用)
  * {@link allowlistedEnv} 是本仓「一张名单点到哪些 env 键,就把它们从源 env **原样**交给沙箱」的唯一实现。调用:沙箱带外 env 的 `E2B_SANDBOX_ENV` / `DOCKER_SANDBOX_ENV` /
- * `K8S_SANDBOX_ENV`(`config.ts`)与名单解析器的「在不在」判。宿主子进程的剥后放回(`LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`)不经它 —— 那是引擎的严格名单臂(上一段)。
+ * `K8S_SANDBOX_ENV`(`config.ts`)与名单解析器的「在不在」判。宿主子进程的剥后放回(`LSP_ENV_ALLOW` / `HOOK_ENV_ALLOW` / `BAKE_ENV_ALLOW`)不经它 —— 那是引擎的严格名单臂(上一段)。
  * host shell 的 `inheritEnv:[names]`(hermetic 形)7.129.0 起由引擎读(与 core `NodeExecutionEnv` 同名选项同义,点到自有凭据名即拒),不经本谓词。
  * 名单型旋钮的**名单**另由 `config.ts` 的同一只解析器 `parseEnvNameAllowlist` 判形(形错 / 点名名单型旋钮 / 点名本服务自有凭据名 ⇒ 拒启;源里没有的名按序号 warn),本函数只管取值。
  * 「点名」在各处同义:点到的键原样带值(空串值照带),密钥形也照过(点名 = 部署方显式承担);源里没有的名不产生条目。
- * 剥后放回形(`LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`)的放回本身也经引擎:{@link composeHostSubprocessEnv} 把名单交引擎的严格名单臂(`inheritedHostEnv([names])`)叠在
+ * 剥后放回形(`LSP_ENV_ALLOW` / `HOOK_ENV_ALLOW` / `BAKE_ENV_ALLOW`)的放回本身也经引擎:{@link composeHostSubprocessEnv} 把名单交引擎的严格名单臂(`inheritedHostEnv([names])`)叠在
  * 继承结果之上 ⇒ 点到本服务自有凭据名 = 引擎在**组合这一刻**抛(语言服务器在构造时组合一次、之后 spawn 用那份静态记录;bake-runner 每次 spawn 组合;
  * 起服时解析器 `parseEnvNameAllowlist` 已用同一只判 `inheritEnvPolicyProblem` 拒过 —— 解析器对五只名单一律拒,点到**解析时已声明**的自有凭据名的沙箱名单因此
  * 到不了 {@link allowlistedEnv} 取值这一步;声明之后增长(中心 / config.d 模型条目的 `apiKeyEnv` 换代并进)时,换代声明对活配置里每只名单此刻交出去的名用同一只判
- * 重判一次 —— 命中 ⇒ 撤回这次增长、候选整拒,已装好的沙箱 env / 语言服务器 env 不变成本服务的凭据,`config.ts` `ownCredentialHitsInForce`),
- * 点到的变量值是本服务凭据的副本 = 引擎扣下。本仓不另判。
+ * 重判一次 —— 命中 ⇒ 撤回这次增长、候选整拒,已装好的沙箱 env / 语言服务器 env 不变成本服务的凭据,`config.ts` `ownCredentialHitsInForce`)。
+ * 解析器与重判问的是「点到的变量是不是本服务的凭据」—— 名是,**或值是**(另一个名下的副本,{@link ownCredentialVariable})—— 都拒;组合这一刻引擎照样扣下值副本(不变量)。本仓不另判、不比值。
  */
 import { type InheritEnvPolicy, type SecretEnvFinding } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
@@ -60,8 +64,9 @@ export type ModelApiKeyEnvTable = Readonly<Record<string, string>>;
  */
 export declare function serverWithheldEnvNames(modelApiKeyEnv?: ModelApiKeyEnvTable): readonly string[];
 /**
- * 本进程**持有凭据值**的变量名(值臂的来源;core 7.52.0 [ref]):目录 secret 名 ∪ 模型条目 `apiKeyEnv` 的值 —— 名单与值臂两臂同一张表派生,只少名单型旋钮名(它们的值是
- * 一张变量名单,不是凭据)。纯函数,排序只为读数稳定。
+ * 本进程**持有凭据值**的变量名(值臂的来源;core 7.52.0 [ref]):目录 secret 名 ∪ 模型条目 `apiKeyEnv` 的值 —— 名单与值臂两臂同一张表派生,只少不在目录里的名单型旋钮名
+ * (今天 = bake-runner 进程的 `BAKE_ENV_ALLOW`);目录里的名单型旋钮行是 secret 行,原文按凭据类整值对待(行上 `credentialForm: "whole"`)。每个来源装着几枚凭据
+ * 由目录行的颗粒定({@link credentialsHeldBy})。纯函数,排序只为读数稳定。
  */
 export declare function serverCredentialValueSources(modelApiKeyEnv?: ModelApiKeyEnvTable): readonly string[];
 /**
@@ -71,15 +76,14 @@ export declare function serverCredentialValueSources(modelApiKeyEnv?: ModelApiKe
  *  · **名臂**:此前声明过的 ∪ 这张表的 {@link serverWithheldEnvNames}。引擎对坏形名 / 运行时回填名(`PATH` / `HOME` …)响亮抛且声明保持原状 —— 本函数不接住:
  *    起服那次抛 = 拒启;换代那次抛 = 候选整拒(`applyEffective` 抛,与 stage 抛同路)。第一次交表带着名臂与**此前已收下的值**(引擎收过、env 不变 ⇒ 同值照收),
  *    所以这一次抛只可能是名的问题。
- *  · **值臂**:{@link serverCredentialValueSources} 的每一个变量此刻在 env 里的值,逐个交给引擎**同一只**判(不另写「什么算凭据值」的第二份判据):引擎收下 ⇒ 记进值臂;
- *    引擎拒(不是凭据值:空白 / 占位词 / 一个字符重复 / 不足 8 字符;或它是每个子进程都会拿到的变量的值)⇒ 这一个值不扣、名照扣、**不拒启**(与引擎自己的收值口
- *    `holdOwnCredentialValues` 同一姿势:不收 + 说一次),经留痕座结构化点名那个变量一次 —— `warn` 行 `own_credential_value_not_withheld { name, reason }`
+ *  · **值臂**:{@link serverCredentialValueSources} 的每一个变量此刻装着的每一枚凭据({@link credentialsHeldBy}:整值,列表形另加每一枚),逐枚交给引擎**同一只**判
+ *    (不另写「什么算凭据值」的第二份判据):引擎收下 ⇒ 记进值臂;
+ *    引擎拒(不是凭据值:空白 / 占位词 / 一个字符重复 / 不足 8 字符;或它是每个子进程都会拿到的变量的值)⇒ 这一枚不扣(同一变量的其余几枚照收)、名照扣、**不拒启**(与引擎自己的收值口
+ *    `holdOwnCredentialValues` 同一姿势:不收 + 说一次),经留痕座结构化点名那个变量一次(它装着几枚被拒都是一行)—— `warn` 行 `own_credential_value_not_withheld { name, reason }`
  *    ({@link recordOwnCredentialValueNotWithheld};`reason` 是引擎拒句原文,从不回显值;起服第一步还没有 logger 时当拍经进程默认的 JSON 行日志器写 stderr,不缓冲),能力位 `inherit_env.own_credential_values_withheld`
  *    因此答 false(位真 ⇔ 值臂真扣)。引擎拒一个值时声明保持上一份,所以逐个交表的中间态都是上一份的超集。
- *    🔴 **这一行是本服务唯一的写者**:值是网关密钥(`MODEL_API_KEY` / `ANTHROPIC_API_KEY`)时,进程输出里另有一行**引擎**的裸 `console.warn`(`a credential the engine was handed is …`)——
- *    它写在 `createOpenAIBrain` / `createAnthropicBrain` 的收值口,那个口没有通告席(适配器配置没有 `onNotice`;`holdOwnCredentialValues` 不在 core 根导出),core 把这一形记为已知限制。
- *    本仓不在引擎外面吞 console、也不拿声明口去抢引擎的「每进程每值说一次」账(下游不改上游座的语义);等 core 给席或让声明口的拒收记作已说。读数与翻面条件:
- *    `test/own-credential-value-boot-lines.test.ts`(真主进程;零裸行的期望以 `it.fails` 立着,core 改形那天转红再翻成常规钉)。
+ *    🔴 **这一行是唯一的一行**:值是网关密钥(`MODEL_API_KEY` / `ANTHROPIC_API_KEY`)时,引擎在适配器构造口收下同一个值,声明口拒过的值它记作已说、不再说第二遍
+ *    (core 7.62.0 起;此前那里另有一行引擎的裸 `console.warn`)。读数:`test/own-credential-value-boot-lines.test.ts`(真主进程,零裸文本行)。
  * 返回声明的名单(只名、不值)。
  */
 export declare function declareServerWithheldEnv(modelApiKeyEnv?: ModelApiKeyEnvTable): readonly string[];
@@ -92,15 +96,40 @@ 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;
 /**
- * 能力词 `inherit_env.own_credential_values_withheld`(core 7.52.0)在本进程的事实:当前生效配置的每一个凭据值来源({@link serverCredentialValueSources}),只要它此刻在 env 里
- * 有值,那个值都已交进值臂、被引擎收下。位真 ⇔ 值臂真扣:一个值被引擎判「扣不了」⇒ false;env 里没有值的来源没有东西可扣,不影响事实。没绑活配置 / 没声明过 ⇒ false。
+ * 能力词 `inherit_env.own_credential_values_withheld`(core 7.52.0)在本进程的事实:当前生效配置的每一个凭据值来源({@link serverCredentialValueSources})此刻装着的
+ * **每一枚**凭据({@link credentialsHeldBy})都已交进值臂、被引擎收下。位真 ⇔ 值臂真扣:有一枚被引擎判「扣不了」⇒ false;env 里没有值的来源没有东西可扣,不影响事实。
+ * 没绑活配置 / 没声明过 ⇒ false。
  */
 export declare function ownCredentialValuesWithheld(): boolean;
+/** {@link ownCredentialVariable} 的答案:这个变量是本服务的凭据,因为它的**名**是声明过的自有凭据名,还是它此刻的**值**是本服务的某一枚凭据(另一个名下的副本)。 */
+export type OwnCredentialHold = "name" | "value";
+/**
+ * 「本进程环境里这个变量是不是本服务的自有凭据」的**唯一读法**(判官 = 引擎此刻的声明;本仓不比值、不持值):名是声明过的自有凭据名 ⇒ `"name"`;
+ * 名不是,而它此刻的值等于引擎扣着的某一枚凭据(值臂按颗粒逐枚声明的,或引擎自己收下的)⇒ `"value"`;都不是 / 变量不在本进程环境里 ⇒ `undefined`。
+ * 值的那一半读引擎严格名单臂对这一名的扣留(`inheritedHostEnv([name])` 的 `own-credential` 发现 —— 严格名单不做形状剥,那里扣下的只有自有凭据一类)。
+ * 调用方先判过名形(引擎对坏形名同样答「有问题」,会被读成 `"name"`)。读者:名单型旋钮的解析器 ② 与声明增长时的重判(`config.ts` `ownCredentialHitsInForce`)。
+ */
+export declare function ownCredentialVariable(name: string): OwnCredentialHold | undefined;
 /** 测试缝:撤回声明(引擎侧重声明为空表)、忘掉两份声明镜像、点名记账与活配置;生产代码从不调它。 */
 export declare function __resetServerWithheldEnvForTest(): void;
 /** 一条宿主腿要什么:现场(留痕)、继承策略(缺省 `"scrub"`;按头注「腿的继承词」一条由调用点定)、部署方点名放回的键、调用方显式交的授予(按序叠在继承之上,后者赢)。 */
@@ -117,8 +146,9 @@ export interface HostSubprocessEnvRequest {
  * 不是剥除,不计数、不披露。源 env 恒为本进程 env(引擎只读 `process.env`,本仓没有第二个源)。
  *
  * 九条宿主腿都只经它(直接或经 {@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 + 放行名单 + 出路句);其余现场传 `[]`。
+ * 本地语言服务器、bake-runner 的每一只子进程组、local-docker 与 adb 两条 CLI 腿(`"all"`)、settings hooks 的命令腿(十二名严格名单 ∪ `HOOK_ENV_ALLOW` 放回 + 有效环境层作授予)。`allow` 只在**有部署级出路**的现场非空(今天 = `LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`,
+ * 它们的现场在 `SECRET_ENV_SCRUB_SITES` 里登记了 `remedy`,披露行因此是 warn + 放行名单 + 出路句;settings hooks 的 `HOOK_ENV_ALLOW` 也走这只槽,但那条腿是严格名单,
+ * finding 只有自有凭据的扣留、任何名单都放不回,现场登记 `remedy: null`,理由在登记处);其余现场传 `[]`。
  * 「扣了哪些名字」一腿一个读者:host shell 腿由引擎读 `withheldEnv` 说(`inherit_env.names_withheld`,现场登记 `told:"engine-notice"` ⇒ 本函数对它只计数、不写披露行);
  * 其余各条腿(含 host 适配器类里不交给引擎的 git worktree 基环境,`HostEnvConfig.gitBase`)引擎没有读者,披露行是唯一的读法(`told:"log"`)。
  * 返回 `NodeJS.ProcessEnv` 形(值可能是 `undefined` 的键本来就不会进子进程);调用方显式要交的键(`LC_ALL`、`cfg.env` …)叠在它之上。