@sema-agent/server 7.135.0 → 7.137.0

package/dist/sandbox-git-plane.js

@@ -0,0 +1,105 @@
+import { WEB_ADMIN_ENV } from "@sema-agent/settings-schema";
+import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
+import { SANDBOX_SECRET_SEAT_VERBS } from "./plugins/k8s-exec-protocol.js";
+export const SANDBOX_GIT_PLANE_OFF_REASONS = [
+    "single_user",
+    "lane_without_boundary",
+    "no_caller_credential",
+    "center_not_https",
+    "secret_seat_unverified",
+    "secret_seat_denied",
+    "pod_patch_reaches_broker",
+    "broker_image_unset",
+    "no_origins",
+];
+export const SANDBOX_GIT_PLANE_OFF_TEXT = {
+    single_user: "this is a single-user deployment (REQUIRE_PRINCIPAL is not true): there are no members to keep apart",
+    lane_without_boundary: "the execution lane is not the k8s pod sandbox (REMOTE_EXEC=k8s): only a k8s sandbox pod can carry the credential broker beside the agent",
+    no_caller_credential: "this worker holds no credential the console's vault admits for credential resolution",
+    center_not_https: `the console address (${WEB_ADMIN_ENV.url}) is not https — credentials are never fetched over plain http`,
+    secret_seat_unverified: `the boot could not confirm the sandbox Role's secrets verbs for the lease Secret (${SANDBOX_SECRET_SEAT_VERBS.lease.join(" / ")}) in the sandbox namespace`,
+    secret_seat_denied: `the sandbox Role does not allow secrets ${SANDBOX_SECRET_SEAT_VERBS.lease.join(" / ")} (the lease Secret) in the sandbox namespace`,
+    pod_patch_reaches_broker: "the deployment's pod-spec patch could reach the broker container (a podSecurityContext, or a field outside the broker white-list)",
+    broker_image_unset: "K8S_SANDBOX_BROKER_IMAGE is not set (the broker container's image; this engine's own image is the recommended value)",
+    no_origins: "the effective configuration routes no git origins to the plane (sandboxGit.origins)",
+};
+const isHttps = (url) => url !== undefined && URL.canParse(url) && new URL(url).protocol === "https:";
+export function judgeSandboxGitPlane(p) {
+    const off = (reason) => ({ state: "off", reason });
+    if (!p.multiTenant)
+        return off("single_user");
+    if (!p.k8sLane)
+        return off("lane_without_boundary");
+    if (!p.callerCredential)
+        return off("no_caller_credential");
+    if (!isHttps(p.centerUrl))
+        return off("center_not_https");
+    const seat = p.secretSeat;
+    if (seat === undefined)
+        return off("secret_seat_unverified");
+    switch (seat.state) {
+        case "unverified":
+            return off("secret_seat_unverified");
+        case "denied":
+            return off("secret_seat_denied");
+        case "granted":
+            break;
+        default: {
+            const unreachable = seat;
+            throw new Error(`unhandled sandbox secret seat reading: ${String(unreachable.state)}`);
+        }
+    }
+    if (p.patchRefusal !== undefined)
+        return off("pod_patch_reaches_broker");
+    if (p.brokerImage === undefined || p.brokerImage === "")
+        return off("broker_image_unset");
+    if (p.origins === null || p.origins.length === 0)
+        return off("no_origins");
+    return {
+        state: "on",
+        origins: p.origins.map((origin) => (origin.startsWith("https://") ? { origin, delivers: true } : { origin, delivers: false, reason: "insecure_transport" })),
+    };
+}
+export function sandboxGitPlaneAsksSecretSeat(p) {
+    return p.multiTenant && p.k8sLane && p.callerCredential && isHttps(p.centerUrl);
+}
+export function sandboxGitPlanePremisesOf(config, readings) {
+    const lane = config.remoteExec;
+    return {
+        multiTenant: DEPLOYMENT_SHAPE_PREDICATES.multiTenant.holds(config),
+        k8sLane: lane?.provider === "k8s",
+        callerCredential: readSandboxGitCallerCredential(config),
+        centerUrl: config.webAdmin?.baseUrl,
+        secretSeat: readings.secretSeat,
+        patchRefusal: readings.patchRefusal,
+        brokerImage: lane?.provider === "k8s" ? lane.brokerImage : undefined,
+        origins: readSandboxGitConfig(config)?.origins ?? null,
+    };
+}
+export function readSandboxGitConfig(_config) {
+    return null;
+}
+export function readSandboxGitCallerCredential(_config) {
+    return false;
+}
+export async function runIdentitySourceOf(runId, runs, logger) {
+    if (runId === undefined || runs === undefined)
+        return undefined;
+    try {
+        return (await runs.getRun(runId))?.identity?.source;
+    }
+    catch (e) {
+        logger?.warn("sandbox_broker_identity_unread", {
+            run: runId,
+            error: e instanceof Error ? e.message : String(e),
+            effect: "this run's sandbox pod carries no member-credential broker (its identity could not be read from the run row)",
+        });
+        return undefined;
+    }
+}
+export function sandboxBrokerSeatOf(plane, brokerImage, identitySource) {
+    if (plane.state !== "on" || brokerImage === undefined || brokerImage === "" || identitySource !== "sso")
+        return undefined;
+    return { image: brokerImage, origins: plane.origins.map((o) => o.origin) };
+}
+//# sourceMappingURL=sandbox-git-plane.js.map

package/dist/sandbox-pkg-source.d.ts

@@ -1,4 +1,31 @@
-import { type UrlCredential } from "./url-credential.js";
+/**
+ * RFC B5/B4 抽象点② (sema-internal server/docs/design/ENV-SELECT-AND-REGION-SOURCE.md): the deployment-region package-source →
+ * sandbox env derivation. ENV-FIRST: pod/sandbox env OVERRIDES the image's baked `ENV` (k8s container env wins
+ * over image config and is visible to every exec'd process; e2b sandboxEnv likewise) — so the env-overridable
+ * ecosystem pieces (pip/uv/npm/corepack/go/rustup/flutter/playwright/nuget) switch region on EXISTING images,
+ * no rebake needed. Only the file-bound pieces (apt sources, /etc/gemrc, composer global config, cargo
+ * config.toml) still need the in-image `pkg-source.sh` hook (rebaked images; bake prep chowns those files).
+ *
+ * Profiles:
+ *   cn      → inject only the SEMA_PKG_SOURCE marker (the pool's images bake the CN set as their defaults).
+ *   global  → official endpoints for every env-overridable ecosystem (overrides the baked CN ENV values).
+ *   custom  → SEMA_* explicit URLs (from the service process env) forwarded verbatim + mapped onto the same
+ *             ecosystem variables where a mapping is unambiguous (apt has no env form — hook-only).
+ *
+ * The marker `SEMA_PKG_SOURCE` always rides along: the image's pkg-source.sh hook (pod-start / profile.d)
+ * materializes the file-bound pieces from it; images without the hook simply ignore it.
+ *
+ * ## One law: no URL that rides into the model-visible sandbox env carries a credential
+ * Everything this module derives lands in the env of every sandbox process — including the ones the model drives
+ * (`env`, `printenv`) — so `https://user:pass@mirror/…` or `https://mirror/simple?token=…` among the `custom` addresses would
+ * hand the deployment's package-source credential to the model. {@link customPkgSourceFromEnv} is the ONE reader of the six
+ * addresses and the one place that judges them, in two questions: the shape (the shared URL-shape judge `httpUrlFlaws`, the same
+ * one MEMORY_EMBEDDER_ENDPOINT / A2A_SERVE_URL answer to, plus this seat's backslash rule) and the credential (the shared
+ * credential judge `findUrlCredential` — userinfo, or a query / fragment parameter named in the log redactor's credential-name
+ * table; the request-face MCP `transport.url` answers to the same judge). Either says no ⇒ it throws, startup refuses. Never
+ * stripped, never rewritten, never forwarded quietly. The request face has no package-source address key at all (deployment face only).
+ */
+import { type UrlCredential } from "@sema-agent/settings-schema";
 /** Explicit URLs for `custom` (RFC B: 极端情况出口). Read from the service process env (operator-trusted). */
 export interface CustomPkgSource {
     aptMirror?: string;

package/dist/sandbox-pkg-source.js

@@ -1,6 +1,5 @@
-import { httpUrlFlaws } from "@sema-agent/settings-schema";
+import { findUrlCredential, httpUrlFlaws } from "@sema-agent/settings-schema";
 import { buildHttpUrlRefusal, buildUrlCredentialRefusal } from "./url-refusal.js";
-import { findUrlCredential } from "./url-credential.js";
 const GLOBAL_ENV = {
     PIP_INDEX_URL: "https://pypi.org/simple",
     UV_DEFAULT_INDEX: "https://pypi.org/simple",

package/dist/sealed-key.d.ts

@@ -54,6 +54,25 @@ export declare function projectSealedKeyCapability(face: SealedKeyPublicFace | u
 /** Default id = fingerprint of the RAW public-key bytes: `exec-<sha256(pk)[0..12) hex>`.
  *  Deterministic → regenerating the id from the same key file is stable across boots. */
 export declare function deriveKeyId(publicKeyRaw: Uint8Array): string;
+/** {@link judgeSealedKeyPublicKey} 的拒因(闭集)。 */
+export type SealedKeyPublicKeyFlaw = "non_canonical_base64" | "bad_length" | "small_order";
+/** 公钥判官的拒(类型化;`flaw` 闭集)。公钥是公开材料,句子里点名它无妨;从不带私钥 / 密文。 */
+export declare class SealedKeyPublicKeyRefusedError extends Error {
+    readonly flaw: SealedKeyPublicKeyFlaw;
+    constructor(flaw: SealedKeyPublicKeyFlaw);
+}
+/**
+ * **X25519 公钥的唯一判官** —— 保管店装载({@link ensureSealedKeyStore},每份钥匙文件)、向中心登记({@link reportExecutionPublicKey})、
+ * 封之前({@link createCheckpointCtxSealing},对着最新那把)三处同读这一只;过了交回原始 32 字节,不过抛 {@link SealedKeyPublicKeyRefusedError}。
+ *  1. **规范 base64**:解出来的字节再编码回去必须逐字等于原串 —— 一句话盖住字母表、补齐、填充位三件(一把钥匙只有一种写法);
+ *  2. **32 字节**;
+ *  3. **不是小阶点**:对 {@link SMALL_ORDER_PROBE_SCALAR} 做 `crypto_scalarmult`,结果全零 ⇔ 小阶(libsodium 此时不交结果、抛 `weak public key`)。
+ * 判法取「标量乘结果全零」而不是手抄小阶点表:与 noble 同一判(`x25519.getSharedSecret` 零结果即抛,包侧 `bad_public_key` 读的就是它)、
+ * 就是 RFC 7748 §6.1 要求的那一检;非规范编码(p、p+1)与第 255 位置位的写法由 X25519 自己的约化 / 掩位盖住,不必逐个列;
+ * 高位别名(第 255 位置位、掩掉后是同一个非小阶点)照收 —— 两边同口径。依赖已在树里(libsodium),不新增一张要人维护的表。
+ * 前置:libsodium 已就绪(三处调用方都先等过它);没就绪 ⇒ 当场抛普通错误(不是判决)。
+ */
+export declare function judgeSealedKeyPublicKey(publicKeyB64: string): Uint8Array;
 /**
  * Load every keypair under `dir` (creating dir + ONE fresh keypair when none exist) and return the
  * custody store. Invalid/corrupt files are skipped with a warn (they may be an OLD format or a

package/dist/sealed-key.js

@@ -27,6 +27,37 @@ function b64ToBytes(b64, what) {
         throw new Error(`${what}: not valid base64`);
     return new Uint8Array(Buffer.from(b64, "base64"));
 }
+export class SealedKeyPublicKeyRefusedError extends Error {
+    flaw;
+    constructor(flaw) {
+        super(`sealed-key public key refused (${flaw}): ${SEALED_KEY_PUBLIC_KEY_FLAW_TEXT[flaw]}`);
+        this.name = "SealedKeyPublicKeyRefusedError";
+        this.flaw = flaw;
+    }
+}
+const SEALED_KEY_PUBLIC_KEY_FLAW_TEXT = {
+    non_canonical_base64: "not the canonical standard-base64 spelling of 32 bytes (alphabet A-Z a-z 0-9 + /, `=` padding, zero padding bits)",
+    bad_length: "does not decode to 32 bytes",
+    small_order: "an X25519 small-order point — anything sealed against it can be opened without the private key",
+};
+const SMALL_ORDER_PROBE_SCALAR = new Uint8Array(32).fill(7);
+export function judgeSealedKeyPublicKey(publicKeyB64) {
+    const sodium = _sodium;
+    if (typeof sodium.crypto_scalarmult !== "function")
+        throw new Error("judgeSealedKeyPublicKey: libsodium is not initialized — await its ready promise first");
+    const bytes = new Uint8Array(Buffer.from(publicKeyB64, "base64"));
+    if (Buffer.from(bytes).toString("base64") !== publicKeyB64)
+        throw new SealedKeyPublicKeyRefusedError("non_canonical_base64");
+    if (bytes.length !== sodium.crypto_box_PUBLICKEYBYTES)
+        throw new SealedKeyPublicKeyRefusedError("bad_length");
+    try {
+        sodium.crypto_scalarmult(SMALL_ORDER_PROBE_SCALAR, bytes);
+    }
+    catch {
+        throw new SealedKeyPublicKeyRefusedError("small_order");
+    }
+    return bytes;
+}
 export async function ensureSealedKeyStore(dir, logger) {
     await _sodium.ready;
     const sodium = _sodium;
@@ -40,9 +71,9 @@ export async function ensureSealedKeyStore(dir, logger) {
             if (raw.alg !== SEALED_KEY_ALG || typeof raw.publicKey !== "string" || typeof raw.privateKey !== "string" || typeof raw.publicKeyId !== "string") {
                 throw new Error("missing/unsupported fields");
             }
-            const publicKey = b64ToBytes(raw.publicKey, "publicKey");
+            const publicKey = judgeSealedKeyPublicKey(raw.publicKey);
             const privateKey = b64ToBytes(raw.privateKey, "privateKey");
-            if (publicKey.length !== sodium.crypto_box_PUBLICKEYBYTES || privateKey.length !== sodium.crypto_box_SECRETKEYBYTES)
+            if (privateKey.length !== sodium.crypto_box_SECRETKEYBYTES)
                 throw new Error("bad key length");
             if (name !== `${raw.publicKeyId}.json`)
                 logger?.warn("sealed_key_filename_drift", { file: name, publicKeyId: raw.publicKeyId, note: "content publicKeyId wins; rename the file to silence this" });
@@ -53,7 +84,7 @@ export async function ensureSealedKeyStore(dir, logger) {
             keys.set(raw.publicKeyId, { publicKey, privateKey, publicKeyB64: raw.publicKey, createdAt: typeof raw.createdAt === "string" ? raw.createdAt : "" });
         }
         catch (err) {
-            logger?.warn("sealed_key_file_unreadable", { file: path, errKind: err instanceof Error ? err.name : "unknown", note: "skipped (NOT deleted) — ciphertexts sealed for this key will fail loud per-model" });
+            logger?.warn("sealed_key_file_unreadable", { file: path, errKind: err instanceof Error ? err.name : "unknown", ...(err instanceof SealedKeyPublicKeyRefusedError ? { flaw: err.flaw } : {}), note: "skipped (NOT deleted) — ciphertexts sealed for this key will fail loud per-model" });
         }
     }
     if (keys.size === 0) {
@@ -101,7 +132,7 @@ export function createCheckpointCtxSealing(store) {
     if (typeof sodium.crypto_box_seal !== "function")
         throw new Error("createCheckpointCtxSealing: libsodium is not initialized — build the store with ensureSealedKeyStore() first");
     const { publicKeyId } = store.latest;
-    const publicKey = b64ToBytes(store.latest.publicKey, "publicKey");
+    const publicKey = judgeSealedKeyPublicKey(store.latest.publicKey);
     const sealing = createUncheckedCheckpointCtxSealing(store, publicKeyId, publicKey);
     const probeSession = "sealed-key-self-test";
     let roundTrip;
@@ -144,6 +175,18 @@ function createUncheckedCheckpointCtxSealing(store, publicKeyId, publicKey) {
 }
 export async function reportExecutionPublicKey(opts) {
     const { baseUrl, adminToken, key, notes, logger } = opts;
+    await _sodium.ready;
+    try {
+        judgeSealedKeyPublicKey(key.publicKey);
+    }
+    catch (err) {
+        logger?.warn("sealed_key_public_key_refused", {
+            publicKeyId: key.publicKeyId,
+            ...(err instanceof SealedKeyPublicKeyRefusedError ? { flaw: err.flaw } : { errKind: err instanceof Error ? err.name : "unknown" }),
+            note: "this public key is not registered with the center and not printed for manual registration — fix or remove the key file in the sealed-key directory and restart",
+        });
+        return;
+    }
     const manual = (why) => {
         logger?.warn("sealed_key_public_key", {
             publicKeyId: key.publicKeyId,

package/dist/security.d.ts

@@ -316,6 +316,13 @@ export declare function createAuthorizer(config: ServiceConfig, sessionStore: Ow
 /** F1/F3 (codex scope-ledger audit 2026-07-14) — the auth-boundary principal SHAPE gate, applied to every
  *  verified identity source (trusted header, SSO-bridge sub, direct-door JWT sub) so no downstream consumer
  *  ever sees an ambiguous or over-wide principal:
+ *   - a string that is NOT A PRINCIPAL NAME is REJECTED (7.137.0): the engine's one judge `principalNameOf` (core 7.56.0 [ref] —
+ *     visible content, no control / line-or-paragraph separator / format character other than the two joiners; kept verbatim, never
+ *     normalized). The session stores' first ownership write and fork and the durable rule buckets read the same judge
+ *     (`plugins/session-ownership.ts`, `permission-rule-store-sql.ts`); before this arm the boundary admitted what the store then refused,
+ *     and the request fell into the generic 500 with its code lost. Typical source: a proxy writing raw UTF-8 bytes into the principal
+ *     header — Node reads header bytes one per character (latin1), and a CJK character's continuation bytes often land on 0x80–0x9F,
+ *     the C1 controls;
  *   - RESERVED internal identifiers are REJECTED (修1, 三路复审 A 组 HIGH — see {@link RESERVED_PRINCIPALS} /
  *     {@link RESERVED_PRINCIPAL_PREFIXES} below): a REAL tenant whose principal string-equals an internal scope
  *     sentinel would pass the plain string-compare owner/scope gates downstream and merge with internal rows —
@@ -328,8 +335,8 @@ export declare function createAuthorizer(config: ServiceConfig, sessionStore: Ow
  *   - length > 190 is REJECTED: every scope/owner column the principal lands in VERBATIM is VARCHAR(190)
  *     (sendfile_link.scope, approval.owner/scope, memory-engine scope, rate-limit keys, …) — an over-long
  *     principal would truncate/500 at the INSERT and split one identity into two.
- *  Throws a typed 400 `HttpError` (the HTTP layer maps it); the message names the rule (a reserved identifier /
- *  the length cap), never a secret and never the internal scope's semantics. */
+ *  Throws a typed 400 `HttpError` (the HTTP layer maps it): `principal_not_a_name` / `principal_reserved` / `principal_too_long`; the message
+ *  names the rule (not a name / a reserved identifier / the length cap), never a secret and never the internal scope's semantics. */
 export declare const PRINCIPAL_MAX_LENGTH = 190;
 /**
  * 一个被受理的主体串最多占多少个 UTF-8 字节 —— 按**字节**计宽的身份列(TiDB `VARBINARY(n)`)的列宽**唯一来源**(派生,不手抄第二个数)。
@@ -354,8 +361,13 @@ export declare const RESERVED_PRINCIPAL_PREFIXES: readonly string[];
 /** The principal-shape rule as a VERDICT (the one judge; {@link assertPrincipalShape} is its throwing reader). `undefined` = a
  *  principal may carry this string; otherwise which rule it breaks. A reader that only needs "can this string be anyone?" (the
  *  organization delivery gate's recipient: a string that breaks the rule is nobody, refused with the same bytes as an unknown
- *  principal) reads the verdict instead of catching the throw. */
-export type PrincipalShapeProblem = "reserved" | "too_long";
+ *  principal) reads the verdict instead of catching the throw.
+ *
+ *  Order: "is it a name at all" first — the other two rules presuppose a name (a reserved identifier / a name too wide for the
+ *  column), and the `reserved` sentence echoes the value while the `not_a_name` sentence never does (a string that names nobody may be a
+ *  pasted credential). An empty string is `not_a_name` here (the engine's judge says so); a header reader that treats a blank header as
+ *  "no principal" decides that before asking. */
+export type PrincipalShapeProblem = "not_a_name" | "reserved" | "too_long";
 export declare function principalShapeProblem(principal: string): PrincipalShapeProblem | undefined;
 export declare function assertPrincipalShape(principal: string): void;
 /** The checkpoint `scope` column's single-user/anonymous sentinel — the same "_" documented above

package/dist/security.js

@@ -1,10 +1,11 @@
-import { uuidv7, PROJECT_ID_REGEX } from "@sema-agent/core";
+import { uuidv7, PROJECT_ID_REGEX, principalNameOf } from "@sema-agent/core";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "./deployment-shape.js";
 import { headReadOf } 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 { NOT_A_PRINCIPAL_NAME } from "./plugins/session-ownership.js";
 export function isDestructiveSessionWrite(method, url) {
     if (method === "DELETE")
         return /^\/v1\/sessions\/[^/]+$/.test(url);
@@ -134,6 +135,8 @@ 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)
@@ -145,10 +148,12 @@ export function assertPrincipalShape(principal) {
     switch (problem) {
         case undefined:
             return;
+        case "not_a_name":
+            throw createCodedHttpError(400, "principal_not_a_name", `principal is not a principal name: got ${NOT_A_PRINCIPAL_NAME} — send the identity as visible characters only (a proxy that writes raw UTF-8 bytes into the principal header is read one byte per character, which can produce control characters: encode it upstream as ASCII or another form without them)`);
         case "reserved":
-            throw new HttpError(400, `principal ${JSON.stringify(principal)} is reserved (an internal scope sentinel) — authenticate with a real tenant identifier`, { code: "principal_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 new HttpError(400, `principal exceeds ${PRINCIPAL_MAX_LENGTH} characters (the scope-column width every store pins, e.g. sendfile_link.scope VARCHAR(190)); got ${principal.length}`, { code: "principal_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}`);
         default: {
             const unknownProblem = problem;
             throw new Error(`assertPrincipalShape: unknown problem ${String(unknownProblem)}`);

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

@@ -124,6 +124,12 @@ export declare function hostSubprocessEnv(o: HostSubprocessEnvRequest): NodeJS.P
  * 既不另写一份组合(第二份会漂),也不把一次没发生的 spawn 记进剥除计数。`findings` 是组合点自己的收集器(引擎把形状臂与自有凭据臂的每一条扣下都推进去)。
  */
 export declare function composeHostSubprocessEnv(o: Omit<HostSubprocessEnvRequest, "site">, findings?: SecretEnvFinding[]): NodeJS.ProcessEnv;
+/**
+ * core 7.56.0 [ref] `ExecutionEnv.withheldEnv` 的**宿主子进程**读法:{@link composeHostSubprocessEnv} 那只组合扣下的发现(名 + 规则,从不带值),
+ * 减去适配器显式授予重供的键(`regranted` 的自有键:子进程收得到那个名,不是损失)—— 引擎契约的原句「the findings of that composition less what its
+ * explicit grants re-supply」。同一个名字被两条规则各扣一次 ⇒ 按「名 + 规则」各记一笔(与披露同一去重)。只读组合:不披露、不计数(没有 spawn 发生)。
+ */
+export declare function withheldFromHostSubprocess(o: Omit<HostSubprocessEnvRequest, "site">, regranted: Readonly<Record<string, string>> | undefined): SecretEnvFinding[];
 /** git 子进程腿的现场(闭集里名字带 `.git-` 的那几只 —— 编译期筛;它们都没有点名放行面)。 */
 export type GitSubprocessSite = Extract<SecretEnvScrubSite, `${string}.git-${string}`>;
 /**

package/dist/server-secret-env.js

@@ -86,6 +86,20 @@ export function composeHostSubprocessEnv(o, findings = []) {
     const putBack = o.allow.length > 0 ? inheritedHostEnv([...o.allow], findings) : {};
     return { ...inheritedHostEnv(o.policy ?? "scrub", findings), ...putBack };
 }
+export function withheldFromHostSubprocess(o, regranted) {
+    const findings = [];
+    composeHostSubprocessEnv(o, findings);
+    const withheld = [];
+    const seen = new Set();
+    for (const f of findings) {
+        const k = `${f.key}=${f.kind}`;
+        if (seen.has(k) || (regranted !== undefined && Object.hasOwn(regranted, f.key)))
+            continue;
+        seen.add(k);
+        withheld.push(f);
+    }
+    return withheld;
+}
 export function gitSubprocessEnv(o) {
     return {
         ...hostSubprocessEnv({ site: o.site, allow: [] }),

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

@@ -10,11 +10,10 @@
  *
  * ## 为什么多一个 `face` 参数(而不是单参)
  * core 的 `invalid_session` 是**同词两义**(亲读 dist:`engine/session/import-validate.js` 的导入门拒调用方交来的
- * 日志,`engine/session/storage-base.js` 的建树 / 走根拒**已存**日志里指向缺席条目的叶子或祖先 —— 后者即 core [ref])。
- * 本仓对它的成文义是前者(调用方的日志没过校验 ⇒ 422),而后者今天在打开会话的各口上答的是通用 500 / 同步口
- * 200 + failed([ref] 的 3b 负控格钉住这一形,[ref] 落地后按 core 的新码再对一次)。单参签名装不下这件事:要么
- * 打开面的每个消费点都写一句 `code === "corrupt_session"` 特判,要么把 [ref] 形从今天的应答改成「你交的日志坏了」。
- * ⇒ 面是映射的一维,写进属主,不散在消费点。
+ * 日志,`engine/session/storage-base.js` / `parent-chain-guard.js` 的建树 / 走根拒**已存**日志的结构 —— 叶子或父不在日志里、
+ * 条目是自己的祖先〔自指 / 成环〕)。前者是调用方的日志没过校验(import 面 422),后者是这只会话**存着的**日志坏了(open 面 500,
+ * 调用方没做错任何事)。单参签名装不下这件事:要么打开面的每个消费点都写一句 `code === "invalid_session"` 特判,要么把已存日志坏了
+ * 说成「你交的日志坏了」。⇒ 面是映射的一维,写进属主,不散在消费点。
  *  · `"open"`   —— 为某只会话**打开它已存的日志**(提交各腿的引擎 prepare、鉴权门的归属探针、直接读会话的口);
  *  · `"import"` —— 校验 / 写入**调用方交来的**日志(2c session-sync 的暂存导入)。
  *
@@ -24,7 +23,16 @@
  *    原样上 wire,契约既有立场:不为上游码铸孪生码)。三种会话后端同词:文件店由 core 铸,两只 SQL 店由
  *    `plugins/session-event-payload.ts` 铸(坏的 `session_event.payload` 行)。
  *  · `invalid_session` —— `import` 面 **422 `invalid_entries`**(修前 session-sync 的那一行,码位 / 状态逐字不变);
- *    `open` 面留白([ref] 形,见上)。
+ *    `open` 面 **500 `invalid_session`**:这只会话已存的日志结构坏了(悬空父 / 自指 / 成环 / 叶子缺席),打得开存档、走不通分支。
+ *    句子发 core 的原句(点名条目 id,不含盘上路径),过既有脱敏。
+ *    · **为什么是 500、不是 4xx / 503**:坏的是存着的数据,调用方没做错任何事;重试改不了判(修复在运维手里)—— 与 `corrupt_session` 同一档同一理由。
+ *    · **为什么码是 `invalid_session`、不是 `corrupt_session`**:码不另铸、也不把一个 core 词改名成另一个 core 词。两个词说的是两件事
+ *      (`corrupt_session` = 存档读不出;`invalid_session` = 读得出、结构走不通),而 run 终局上它本来就是引擎词(`terminal.code`,同步口 4xx / 5xx 体的
+ *      `errorCode` 取终局码原样):读口答 `corrupt_session`、提交口答 `invalid_session` 就是同一件事两个名字。所以映射只有一格,
+ *      读口与提交口的 run 终局分诊({@link sessionErrorHttp} 的 open 面,`resumeAtHttpStatus` 读它)同一只、同码同状态。
+ *    · **没有 `reason` 机读位**:core 的 `SessionError` 只带 `code` 与句子;悬空父与叶子缺席是同一句 `Entry <id> not found`,自指与成环是同一句
+ *      `is its own ancestor` —— 本仓分出 {parent_missing, parent_self, parent_cycle} 只有解析句子或再写一只判官两条路(会话视图自己的走链器已在 core 7.54.0 提货时退役:
+ *      视图读的就是引擎读的那条分支,见 `plugins/local-session-window.ts` 头注)。要分,请求 core 把种类放进错误(同 `placement_kind` 的先例),不在这里猜。
  *  · `not_found` —— 留白:每一面各有自己的「不存在」答法(404 `not_found.session` / 同步口的 `resume.session_not_found` /
  *    列表里的缺席),码位各不相同,不由本表统一。
  *  · `placement_refused` —— `import` 面 **409 `conflict.session_placed`**(机读位 `detail.placement_kind`,固定句);`open` 面留白。

package/dist/session-error-wire.js

@@ -3,6 +3,7 @@ export const PLACED_SESSION_SENTENCE = "this session holds a delegated agent's t
 const PLACEMENT_KIND = "subagent";
 export const STAGED_IMPORT_OWNER_CHANGED_SENTENCE = "session owner changed while the import streamed; nothing was imported — start the sync again";
 const CORRUPT_SESSION = { status: 500, errorCode: "corrupt_session" };
+const STORED_LOG_INVALID = { status: 500, errorCode: "invalid_session" };
 const INVALID_ENTRIES = { status: 422, errorCode: "invalid_entries", sentence: STAGED_IMPORT_INVALID_SENTENCE };
 const SESSION_PLACED = { status: 409, errorCode: "conflict.session_placed", sentence: PLACED_SESSION_SENTENCE, detail: { placement_kind: PLACEMENT_KIND } };
 const STAGED_IMPORT_OWNER_CHANGED = { status: 409, errorCode: "conflict", sentence: STAGED_IMPORT_OWNER_CHANGED_SENTENCE };
@@ -11,7 +12,7 @@ export function sessionErrorHttp(code, face) {
         case "corrupt_session":
             return CORRUPT_SESSION;
         case "invalid_session":
-            return face === "import" ? INVALID_ENTRIES : undefined;
+            return face === "import" ? INVALID_ENTRIES : STORED_LOG_INVALID;
         case "placement_refused":
             return face === "import" ? SESSION_PLACED : undefined;
         case "conflict":

package/dist/session-incarnation.d.ts

@@ -27,8 +27,8 @@
  *  · **一位活住客必须有令牌 —— 读到空化身 ⇒ 响亮拒**({@link SessionIncarnationMissingError}):本仓比 core 多的那一条律,只住在一处 ——
  *    把头投成 {@link SessionFace}(属主 + 一只令牌)的 {@link sessionFaceOfHead}(批量来源读与换装回读用同一只 {@link sessionFaceFromRow})。
  *    要拿令牌去**写**(带化身条件的 UPDATE、认领、空间分区键)或要响亮区分「行坏了」的读者经它;只**比较**两头的读者用 `compareOccupants`。
- *    一次性迁移(`plugins/one-time-migrations.ts` 登记表 M5)之后,空值只可能来自没铸化身的写腿或人为改库 —— 把它当「通配」就是让任何人
- *    都能和这一行比成同一位住客。
+ *    空值只可能来自没铸化身的写腿、人为改库,或跳过了 7.104.0–7.135.x(那几版的起服迁移给存量行铸令牌,窗关后已删码)直接升上来的库 ——
+ *    把它当「通配」就是让任何人都能和这一行比成同一位住客。
  *  · **不上 wire、不进模型上下文、不进日志正文**:日志里要点名时只打 {@link incarnationLogPrefix}(前 8 位)。
  *
  * ## 谁读它(全部派生自那一只头读)
@@ -97,8 +97,19 @@ export declare class UnreadableLeaf {
  *  与 core 的读法同义 —— 拒不拒是投影的事,见 {@link sessionFaceOfHead})。叶子那一格读不出({@link UnreadableLeaf})⇒ 头照答属主与住客,
  *  读 `leafId` 的那一位收到那只故障 —— 永不把读不出的叶子答成 `null`(`null` = 空会话)。 */
 export declare function headFromRow(sessionId: string, owner: string | null, incarnation: unknown, leaf: string | null | UnreadableLeaf): SessionHead;
+/**
+ * 🔴 **会话内容读不读得出 —— 会话路由在门放行之后判它的唯一读法**:读头的叶子。内容读不出的头({@link UnreadableLeaf})在这一读上抛那只故障本身
+ * (码 `corrupt_session`,经 `sessionErrorHttp` 的 open 面落 500);读得出 ⇒ 叶子 id(`null` = 空会话)。
+ * 谁在**门放行之后**要动这只会话的内容(读叶子本身、开事件流、改名 —— 改名答的是列表行,列表读存档),谁就经它读一次;
+ * 门之前不许读(非属主对坏档与对好档同答,见头注「头答自会话行」)。三个口各写一句 `head.leafId` 与各写一句"存档坏了怎么办"是同一件事的三种答法
+ * (修前:头探针 500、事件流 200 零帧 —— 观察探针把每拍读叶子抛出的故障当瞬时错吞掉 —— 改名 404 —— 列表跳过读不出的存档,会话被说成不存在)。
+ * SQL 两店的叶子是行上的一列,永不抛 ⇒ 这一读在 SQL 上恒等于 `head.leafId`,这条判据只对内容与行分居两处的店(local)有牙。
+ * 事件流只在开流之前判一次;流开了之后存档才坏,观察探针仍把读叶子的故障当瞬时错续探(流不断、不再产出新帧)。
+ */
+export declare function leafOfAdmittedHead(head: SessionHead): string | null;
 /** 一只头 → 一位活住客({@link SessionFace}):`undefined` 头 = 没有这只会话 ⇒ `undefined`;行在而没有令牌 ⇒ {@link SessionIncarnationMissingError}
  *  (本仓的那条律只住在这里 + {@link sessionFaceFromRow})。 */
+export declare function sessionFaceOfHead(sessionId: string, head: SessionHead): SessionFace;
 export declare function sessionFaceOfHead(sessionId: string, head: SessionHead | undefined): SessionFace | undefined;
 /**
  * 「这只会话店有没有按 id 读(`headOf`)」—— 全仓**只判这一处**:授权口、各路由的属主门、能力位、起服门、k8s 工作区空间的每 run 读与
@@ -116,12 +127,12 @@ export declare function carriedIncarnation(sessionId: string, prior: {
 } | undefined, owner: string | null): string;
 /**
  * `session_meta.incarnation` 的列定义 —— 两方言各一句,**唯一属主**:中央 DDL(`tidb-pool.ts` / `pg-session-storage.ts` 的
- * `CREATE TABLE session_meta`)与一次性迁移 M5 的 `ADD COLUMN`(`plugins/one-time-migrations.ts`)都内插这同一串,
- * 于是「新库建出来的列」与「存量库补上的列」逐字同形([ref] 起服列册探针比的是列名,形由这里保证)。
+ * `CREATE TABLE session_meta`)内插这同一串;存量库缺这一列时,起服列册探针(`schema-consistency.ts`)拒启,拒句里的 `ALTER TABLE … ADD COLUMN …`
+ * 由同一份建表语句解析生成 ⇒ 「新库建出来的列」与「运维按拒句补上的列」逐字同形(探针比的是列名,形由这里保证)。
  *
  * `NOT NULL DEFAULT ''`:空串就是「没铸过」的唯一表示 —— 读口对它响亮拒({@link SessionIncarnationMissingError})。
  * 缺省值只为两件事存在:①存量表 `ADD COLUMN` 在两方言上一句成立(PG 对非空表加无缺省的 NOT NULL 列直接拒);
- * ②一条漏铸的写腿落下的是**读得出来的错**(读口拒),而不是一条插入期的 500 —— 两形都 fail-closed,前者还能被迁移补上。
+ * ②一条漏铸的写腿落下的是**读得出来的错**(读口拒),而不是一条插入期的 500 —— 两形都 fail-closed。
  * 宽度 64:`randomUUID()` 是 36 字符,留出余量但不给任意长串留位。
  */
 export declare const SESSION_META_INCARNATION_COLUMN: {

package/dist/session-incarnation.js

@@ -13,10 +13,10 @@ export class SessionIncarnationMissingError extends Error {
     sessionId;
     code = "session.incarnation_missing";
     constructor(sessionId) {
-        super(`session ${sessionId} has no incarnation token: every session row is minted one when it is created, and rows written before ` +
-            `7.104.0 get one from the one-time migration that runs at boot (plugins/one-time-migrations.ts, entry M5). An empty value ` +
-            `after that means a write path that did not mint one, or a hand-edited row — it is refused rather than read as "matches anyone". ` +
-            `Restart a 7.104.0+ replica so the migration backfills it, or delete the session.`);
+        super(`session ${sessionId} has no incarnation token: every session row is minted one when it is created. An empty value means a write path ` +
+            `that did not mint one, a hand-edited row, or a database upgraded from before 7.104.0 straight to a version after 7.135.x (a boot of any ` +
+            `version in between minted tokens for the older rows; the code that did so has since been removed) — it is refused rather than read as ` +
+            `"matches anyone". Give the row a distinct random token (any opaque string of at most 64 characters), or delete the session.`);
         this.sessionId = sessionId;
         this.name = "SessionIncarnationMissingError";
     }
@@ -57,6 +57,9 @@ export function headFromRow(sessionId, owner, incarnation, leaf) {
         },
     };
 }
+export function leafOfAdmittedHead(head) {
+    return head.leafId;
+}
 export function sessionFaceOfHead(sessionId, head) {
     return head === undefined ? undefined : sessionFaceFromRow(sessionId, head.owner, head.incarnation);
 }

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

@@ -52,7 +52,7 @@ export declare function namespaceCoveringForms(): readonly {
 }[];
 /**
  * 能力位 `sessionRulesNamespaceForms` 的**唯一**判据:会话规则记录里协议命名空间的覆盖形,引擎认成「一组工具」**且**写口收。
- * 对 `PROTOCOL_TABLE` 的每一员:① 它的三只覆盖形,引擎的匹配器(`namespacedRuleNameCovers`,会话层与其余规则面同一只)都判得出覆盖那一员的真工具名
+ * 对 `PROTOCOL_TABLE` 的每一员:① 它的三只覆盖形,引擎的匹配器(`ruleNameCovers`,会话层与其余规则面同一只)都判得出覆盖那一员的真工具名
  * (只当精确名收的写口不算 ——「收」与「认成一组」是两问);② 三形放进 `toolAllow` 与 `toolDeny` 两桶,两条写入腿共用的写口读者
  * {@link readWritableSessionPermissionRules}(= 引擎写口判官)不拒。表非空 ∧ 每员都过 ⇒ `true`。
  *

package/dist/session-policy-wire.js

@@ -1,4 +1,4 @@
-import { PROTOCOL_TABLE, SessionPolicyError, judgeSessionRulesWrite, namespacedRuleNameCovers } from "@sema-agent/core";
+import { PROTOCOL_TABLE, SessionPolicyError, judgeSessionRulesWrite, ruleNameCovers } from "@sema-agent/core";
 import { displayListEntry } from "./list-entry-display.js";
 function isSessionRulesRefusal(e) {
     return e instanceof SessionPolicyError && (e.code === "invalid_shape" || e.code === "inert_entry");
@@ -25,7 +25,7 @@ export function namespaceCoveringForms() {
 export function sessionRulesNamespaceFormsHonored() {
     const probes = namespaceCoveringForms();
     return (probes.length > 0 &&
-        probes.every(({ forms, tool }) => forms.every((form) => namespacedRuleNameCovers(form, tool)) && readWritableSessionPermissionRules({ toolAllow: [...forms], toolDeny: [...forms] }).refusal === undefined));
+        probes.every(({ forms, tool }) => forms.every((form) => ruleNameCovers(form, tool)) && readWritableSessionPermissionRules({ toolAllow: [...forms], toolDeny: [...forms] }).refusal === undefined));
 }
 export function readSessionRulesRecords(raw) {
     if (!Array.isArray(raw))

package/dist/session-row.d.ts

@@ -1,19 +1,3 @@
-/**
- * 会话行的**可写位**(`title` / `pinned`)—— `PATCH /v1/sessions/:id` 的体闭集、两键的判据,与 2c 导入同读的那一套(唯一属主)。
- *
- * ## 一列一事实,写者次序成文
- *  · `title` 是一列(SQL `session_meta.title` / local 标题边档),两个写者,一条律:**用户**经会话店唯一写口 `patchSessionMeta`
- *    **无条件**写 —— 写一个串 = 改名,写 `null` = **清回自动标题**(列回到 NULL);**自动标题器**经 `setTitleIfNull` **只填 NULL**
- *    (每次提交按列读一次:列是 NULL 才起名,见 `session-titler.ts`)。所以清与填是同一列同一律:用户清掉之后,下一次提交由自动标题器
- *    照常填;用户写过串的会话,自动标题器永不覆盖(无条件写盖得掉自动标题,NULL 守卫盖不掉用户标题)。没有第二列(不另设 `userTitle` /
- *    `label`)。清的拼法只有 `null` 一种 —— 空串 `""` 是坏体(`request.body_shape`),不是「清」。
- *  · `pinned` 是一列布尔,缺省 `false`;列表行**恒在场**(置顶是会话的状态,不是能力)。
- *
- * ## 上界 = 列宽
- * {@link SESSION_TITLE_MAX_CHARS} 是 `title` 列的宽度,两方言 DDL 内插的就是这一个数(`tidb-pool.ts` / `pg-session-storage.ts`),
- * wire 上界与存储上界是同一个事实。按**字符**计(Unicode 码点 —— 与 MySQL 协议 utf8mb4 / PostgreSQL 的 `VARCHAR(n)` 同一单位),
- * 不按 UTF-16 位计。自动标题器自己的显示预算(`session-titler.ts` 的 `TITLE_MAX_CHARS`)更短,落在这个上界之内。
- */
 /** `title` 列的宽度(字符)= 用户标题的上界。两方言 DDL 内插它。 */
 export declare const SESSION_TITLE_MAX_CHARS = 120;
 /** 会话行的可写位(体闭集;两键至少一键)。会话店唯一写口 `patchSessionMeta` 的形参。`title: null` = 清回自动标题(列写 NULL)。 */
@@ -28,7 +12,9 @@ export interface SessionRowProblem {
 }
 /**
  * `title` 一格的**唯一**读者(PATCH 体与 2c 导入同读)。`null` ⇒ 清回自动标题;串 ⇒ 1..{@link SESSION_TITLE_MAX_CHARS} 个字符、首尾无空白、
- * 不含 C0 控制字符({@link C0_CONTROL}),存原文(不脱敏、不改写);空串 ⇒ `request.body_shape`(清的拼法只有 `null`);其余 ⇒ `request.field_invalid`。
+ * 不含 C0 控制字符({@link C0_CONTROL})、至少有一个可见字符(经 core 的 `normalizePeerName` 不为空 —— NFKC → 去控制 / 格式码点 → trim;
+ * 与跨会话对端目录判「这一行有没有可用名」是**同一只**判据,`peer-directory.ts`),存原文(不脱敏、不改写);空串 ⇒ `request.body_shape`(清的拼法只有 `null`);其余 ⇒ `request.field_invalid`。
+ * 三道串判的先后固定:边空白 → C0 → 无可见字符(带 C0 的串先报 C0)。
  */
 export declare function readSessionTitle(v: unknown): {
     readonly title: string | null;

package/dist/session-row.js

@@ -1,7 +1,9 @@
+import { normalizePeerName } from "@sema-agent/core";
 export const SESSION_TITLE_MAX_CHARS = 120;
 const SESSION_ROW_PATCH_KEYS = { title: true, pinned: true };
 const BODY_SHAPE_MESSAGE = "the body must be a JSON object carrying at least one of `title` and `pinned`, and nothing else";
 const EMPTY_TITLE_MESSAGE = "title must not be the empty string — send `null` to clear it back to the automatic title";
+const INVISIBLE_TITLE_MESSAGE = "title must contain at least one visible character";
 const C0_CONTROL = /[\u0000-\u001f]/u;
 export function readSessionTitle(v) {
     if (v === null)
@@ -16,6 +18,8 @@ export function readSessionTitle(v) {
         return { problem: { code: "request.field_invalid", message: "title must not start or end with whitespace" } };
     if (C0_CONTROL.test(v))
         return { problem: { code: "request.field_invalid", message: "title must not contain control characters (U+0000 to U+001F)" } };
+    if (normalizePeerName(v) === "")
+        return { problem: { code: "request.field_invalid", message: INVISIBLE_TITLE_MESSAGE } };
     return { title: v };
 }
 export function readSessionPinned(v) {