@sema-agent/server 7.136.0 → 7.138.0

package/dist/sandbox-git-plane.d.ts

@@ -0,0 +1,84 @@
+import type { ServiceConfig } from "./config.js";
+import type { SandboxSecretSeat } from "./plugins/remote-env-k8s.js";
+import type { IdentitySource, RunIdentity } from "./identity-source.js";
+import type { Logger } from "./observability/logger.js";
+/** The off reasons, in judge order (closed set; an added premise is a word here, a row in {@link SANDBOX_GIT_PLANE_OFF_TEXT}, a step in the judge). */
+export declare const SANDBOX_GIT_PLANE_OFF_REASONS: readonly ["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 type SandboxGitPlaneOffReason = (typeof SANDBOX_GIT_PLANE_OFF_REASONS)[number];
+/** One origin of an on plane. */
+export type SandboxGitPlaneOrigin = {
+    readonly origin: string;
+    readonly delivers: true;
+} | {
+    readonly origin: string;
+    readonly delivers: false;
+    readonly reason: "insecure_transport";
+};
+/** The plane's reading (the wire value of `credentialPlane.sandboxGit`). */
+export type SandboxGitPlane = {
+    readonly state: "on";
+    readonly origins: readonly SandboxGitPlaneOrigin[];
+} | {
+    readonly state: "off";
+    readonly reason: SandboxGitPlaneOffReason;
+};
+/** Operator sentence per off reason (the boot line and the docs read it; the record type makes a missing word a compile error). */
+export declare const SANDBOX_GIT_PLANE_OFF_TEXT: {
+    readonly [R in SandboxGitPlaneOffReason]: string;
+};
+/** The premises, each as the judge reads it. */
+export interface SandboxGitPlanePremises {
+    readonly multiTenant: boolean;
+    readonly k8sLane: boolean;
+    readonly callerCredential: boolean;
+    /** The console base address (`SEMA_WEB_ADMIN_URL`); absent ⇒ not https. */
+    readonly centerUrl: string | undefined;
+    /** The boot's SelfSubjectAccessReview answer for the sandbox Secret seat; `undefined` = not asked (counts as unverified). */
+    readonly secretSeat: SandboxSecretSeat | undefined;
+    /** The patch judge's refusal for a pod that carries the broker (`podSpecPatchBrokerRefusal`); `undefined` = the patch may land. */
+    readonly patchRefusal: string | undefined;
+    readonly brokerImage: string | undefined;
+    /** The routed origins (`readSandboxGitConfig`); `null` = no `sandboxGit` block. */
+    readonly origins: readonly string[] | null;
+}
+/** THE judge: the first premise that fails, in the written order; all hold ⇒ on with per-origin rows. Pure. */
+export declare function judgeSandboxGitPlane(p: SandboxGitPlanePremises): SandboxGitPlane;
+/** The secret seat is asked for the plane only when every premise before it holds (a deployment the plane is off for asks nothing for it). */
+export declare function sandboxGitPlaneAsksSecretSeat(p: Pick<SandboxGitPlanePremises, "multiTenant" | "k8sLane" | "callerCredential" | "centerUrl">): boolean;
+/** The premises read from config, plus the two boot readings (seat answer, patch refusal) when the boot has them. */
+export declare function sandboxGitPlanePremisesOf(config: ServiceConfig, readings: {
+    readonly secretSeat?: SandboxSecretSeat;
+    readonly patchRefusal?: string;
+}): SandboxGitPlanePremises;
+/**
+ * Wiring point — the effective `sandboxGit` block (the origins this deployment routes through the broker, canonical form, ≤ 16). Its shape
+ * and its canonical-form judge belong to the settings-schema contract package (`SandboxGitConfig`, 14.7.0 — picked up: the block rides the effective
+ * wire verbatim); this reader is not wired to it yet ⇒ `null` (the plane stays off, `no_origins`). To be replaced by the package reader — no local copy of the shape.
+ */
+export declare function readSandboxGitConfig(_config: ServiceConfig): {
+    readonly origins: readonly string[];
+} | null;
+/**
+ * Wiring point — does this worker hold the credential the console's vault admits on its resolve endpoint (the worker-assertion token)?
+ * The server has no reader for it yet ⇒ `false` (the plane stays off, `no_caller_credential`). Replaced by the plane's vault client.
+ */
+export declare function readSandboxGitCallerCredential(_config: ServiceConfig): boolean;
+/** The run store's by-id read, as far as the plane needs it: the row's identity tuple (`RunRecord.identity`). Every run store's `getRun` is one. */
+export interface SandboxGitRunRows {
+    getRun(taskId: string): Promise<{
+        readonly identity: RunIdentity | null;
+    } | null | undefined>;
+}
+/**
+ * The identity source recorded on the pod's run row (`RunRecord.identity.source`, minted once at admission, never recomputed). `runId` is the
+ * ONE reading of "the run that owns this pod" (the per-run binding's: the top-level run's id; a delegated child / a service run / no task id ⇒
+ * none). No run id / no run store / no row / `identity: null` ⇒ `undefined`; a read that throws ⇒ `undefined` and one warn line
+ * `sandbox_broker_identity_unread` —— every miss reads as "not sso" ⇒ no broker (fail-closed), none of them throws into the pod's connect.
+ */
+export declare function runIdentitySourceOf(runId: string | undefined, runs: SandboxGitRunRows | undefined, logger?: Pick<Logger, "warn">): Promise<IdentitySource | undefined>;
+/** The broker seat for one run's pod: the plane on ∧ the image set ∧ the run's recorded identity source `sso` ⇒ the image + every origin of the reading (http too); otherwise none. */
+export declare function sandboxBrokerSeatOf(plane: SandboxGitPlane, brokerImage: string | undefined, identitySource: IdentitySource | undefined): {
+    readonly image: string;
+    readonly origins: readonly string[];
+} | undefined;
+//# sourceMappingURL=sandbox-git-plane.d.ts.map

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/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

@@ -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]` 臂);部署方装在宿主上的 CLI(`docker` / `adb`,命令本身
+ * 语言服务器 / 配方脚本 ⇒ 形状剥 `"scrub"`;请求带来的 settings hooks 命令 ⇒ 严格名单(十二名基础名单,`[names]` 臂;请求的继承词只给工具 shell、对 hook 不作用)、请求的有效环境层作授予叠在继承结果之上(引擎的 `hostChildEnv`);部署方装在宿主上的 CLI(`docker` / `adb`,命令本身
  * 在容器 / 设备里跑、那边的 env 由 `-e` 显式给)⇒ `"all"` —— 只扣本服务自有凭据,CLI 与它的凭据助手 / 插件要读的生态变量照交(形状剥会剥
  * `ADB_VENDOR_KEYS` / `AWS_SECRET_ACCESS_KEY` 一类,实测)。三个继承词只在引擎一处判:
  *  · `"all"` = 整份环境 **减** 本进程声明的自有凭据名;`"scrub"`(缺省)= 形状剥 ∪ 该名单;`[names]` = 严格白名单,点到名单中的名 ⇒ 引擎响亮拒
@@ -94,18 +94,21 @@ export declare function ownCredentialsWithheld(): boolean;
 export declare function ownCredentialValuesWithheld(): boolean;
 /** 测试缝:撤回声明(引擎侧重声明为空表)、忘掉两份声明镜像、点名记账与活配置;生产代码从不调它。 */
 export declare function __resetServerWithheldEnvForTest(): void;
-/** 一条宿主腿要什么:现场(留痕)、继承策略(缺省 `"scrub"`;按头注「腿的继承词」一条由调用点定)、部署方点名放回的键。 */
+/** 一条宿主腿要什么:现场(留痕)、继承策略(缺省 `"scrub"`;按头注「腿的继承词」一条由调用点定)、部署方点名放回的键、调用方显式交的授予(按序叠在继承之上,后者赢)。 */
 export interface HostSubprocessEnvRequest {
     readonly site: SecretEnvScrubSite;
     readonly policy?: InheritEnvPolicy | undefined;
     readonly allow: readonly string[];
+    /** 调用方显式交给子进程的变量(今天只有 settings hooks:有效环境层 = 请求 `settings.env` + hook 自己的变量)。引擎判形:名字空 / 带 `=` / NUL / 孤代理项、
+     *  值不是串或带 NUL / 孤代理项 ⇒ 组合**抛**,拒句点名授予与变量(不带值、不回显坏名);调用点按「起不来」处置。 */
+    readonly grants?: readonly Readonly<Record<string, string>>[] | undefined;
 }
 /**
  * 🔴 **宿主子进程 env 的唯一组合**:{@link composeHostSubprocessEnv} + 留痕。**没有按原样交给子进程**的名字(剥掉的)经 `site` 留痕;点名放回的键取回源值,
  * 不是剥除,不计数、不披露。源 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`,
+ * 本地语言服务器、bake-runner 的每一只子进程组、local-docker 与 adb 两条 CLI 腿(`"all"`)、settings hooks 的命令腿(十二名严格名单 + 有效环境层作授予)。`allow` 只在**有部署级出路**的现场非空(今天 = `LSP_ENV_ALLOW` / `BAKE_ENV_ALLOW`,
  * 它们的现场在 `SECRET_ENV_SCRUB_SITES` 里登记了 `remedy`,披露行因此是 warn + 放行名单 + 出路句);其余现场传 `[]`。
  * 返回 `NodeJS.ProcessEnv` 形(值可能是 `undefined` 的键本来就不会进子进程);调用方显式要交的键(`LC_ALL`、`cfg.env` …)叠在它之上。
  * 调用时机 = 每次要交 env 时现算一次(`process.env` 在本仓是 boot 期输入,各次同值;计数因此是「每组合一次」)。
@@ -124,6 +127,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

@@ -1,4 +1,4 @@
-import { declareWithheldEnv, inheritedHostEnv } from "@sema-agent/core";
+import { declareWithheldEnv, hostChildEnv, 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 { recordSecretEnvScrub } from "./observability/secret-env-scrub.js";
@@ -84,7 +84,23 @@ export function hostSubprocessEnv(o) {
 }
 export function composeHostSubprocessEnv(o, findings = []) {
     const putBack = o.allow.length > 0 ? inheritedHostEnv([...o.allow], findings) : {};
-    return { ...inheritedHostEnv(o.policy ?? "scrub", findings), ...putBack };
+    const child = hostChildEnv(o.policy ?? "scrub", putBack, ...(o.grants ?? []));
+    findings.push(...child.withheld);
+    return child.env;
+}
+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 {

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

@@ -117,14 +117,13 @@ export declare function sessionFaceOfHead(sessionId: string, head: SessionHead |
  */
 export declare function headReadOf(store: object | undefined): HeadRead | undefined;
 /**
- * session-sync **整段换装**(replace)时化身的去留 —— 三只店共用的一句判据:换装删掉再插回的是**同一位住客**的那一行
- * (删除带属主门),所以行在、属主相同、那一格里有一只令牌(唯一解码 {@link incarnationFromCell} 的 `absent` 读法)⇒ 沿用;
- * 行不在(这是一次新建)或还是空的存量形 ⇒ 铸一只新的。
+ * session-sync **换装**(整段换装 / 暂存提交 / local 落在既有行上的导入)时化身的去留 —— 三只店共用的一句判据:换装只换内容,换的是**同一行**
+ * ⇒ 行在且那一格里有一只令牌(唯一解码 {@link incarnationFromCell} 的 `absent` 读法)⇒ 沿用(属主重戳与否不改这一判:同一行 = 同一位住客);
+ * 行不在(这是一次新建)或还是空的存量形 ⇒ 铸一只新的。属主不在这里判:每只店在自己的属主门上判过被换的那一行,读不中的换装一个字节不写。
  */
 export declare function carriedIncarnation(sessionId: string, prior: {
-    owner?: unknown;
     incarnation?: unknown;
-} | undefined, owner: string | null): string;
+} | undefined): string;
 /**
  * `session_meta.incarnation` 的列定义 —— 两方言各一句,**唯一属主**:中央 DDL(`tidb-pool.ts` / `pg-session-storage.ts` 的
  * `CREATE TABLE session_meta`)内插这同一串;存量库缺这一列时,起服列册探针(`schema-consistency.ts`)拒启,拒句里的 `ALTER TABLE … ADD COLUMN …`

package/dist/session-incarnation.js

@@ -67,8 +67,8 @@ export function headReadOf(store) {
     const read = store?.headOf;
     return typeof read === "function" ? read.bind(store) : undefined;
 }
-export function carriedIncarnation(sessionId, prior, owner) {
-    const held = prior !== undefined && (prior.owner ?? null) === owner ? incarnationFromCell(sessionId, prior.incarnation, "absent") : undefined;
+export function carriedIncarnation(sessionId, prior) {
+    const held = prior === undefined ? undefined : incarnationFromCell(sessionId, prior.incarnation, "absent");
     return held ?? mintSessionIncarnation();
 }
 export const SESSION_META_INCARNATION_COLUMN = {

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-sync.d.ts

@@ -50,7 +50,7 @@ import type { ServiceFileHistoryStore, ServiceSessionPolicyStore, ResumeAnchorSt
 /**
  * core 7.55.0 [ref] T2([ref]):一只会话的文件历史**读不全**(撕裂 / 读不出的边界、读不出的跟踪集 —— 店的 `exportHistory` 答 `{ ok: false }`,`adopt_failed`
  * 带店判的 `permanence`)。它**不是**「没有历史」:读成 `null` 的同步会把这只会话的全部 rewind 历史丢在路上、还答成功。会话同步的两只拉取口
- * (manifest、history blob)对它答同一句 503 `state.file_history_unreadable`(路由 `sendPullUnreadable`;连接类故障在拉取口同码同体键答 `permanence: "transient"`)。
+ * (manifest、history blob)对它答同一句 503 `state.file_history_unreadable`(路由 `sendPullUnreadable`;连接类故障在拉取口同码同体键答 `permanence: "transient"`,部署错配类故障〔缺表 / 权限拒〕答 `permanence: "terminal"`)。
  */
 export declare class FileHistoryUnreadableError extends Error {
     readonly sessionId: string;

package/dist/session-workspace.d.ts

@@ -0,0 +1,130 @@
+/**
+ * **会话的位置与项目** —— 一个事实、一个写者、一种读法(引擎 7.58.0:`workspace_changed` 是腿的整份快照;
+ * 会话行 = 该会话上最后一帧)。
+ *
+ * ## 律(三句)
+ *  · **判官只有引擎一只**:每条腿起点一帧 `workspace_changed`(`cwd` / `root` / `entered?` / `project?` / `remote`),之后每变一帧;
+ *    这条腿属于哪个项目由引擎对检出的 `.sema/project` 记号判一次(带了 `TaskSpec.projectId` 就必须等于记号,
+ *    否则整腿拒 `config.project_identity_mismatch`;没有记号时声明就是身份)。本仓**不判**项目、不读记号。
+ *  · **会话行只存一格**:`workspace` = 该会话上一条腿**自己的**最后一帧(SQL `session_meta.workspace`;local 店
+ *    `session-workspaces.json` 那一格)。成员由 {@link SESSION_WORKSPACE_DISPOSITIONS} 一张表定(引擎给帧加成员 ⇒ 表 tsc 红,
+ *    门在 `trace/core-keyset-guard.ts` ⑰ 读同一张表)。**唯一写者** = 腿的记录座 {@link createSessionWorkspaceRecorder}
+ *    (持流的四条腿逐帧喂同一只;委派子代转上来的帧 —— 带 `parentToolCallId` / `sourceTaskId` / `bgAgentId` —— 不是这条腿的位置,不认)。
+ *    每一笔写**在腿的流循环里等完**(不排队、没有在飞的写:腿从任何出口离开时都没有它的写还悬着 ⇒ 写恒落在这条腿的 run 认领之内,
+ *    同一会话的下一条腿不会被一笔晚到的写盖掉),并且**只写受理时见证到的那一位住客**({@link stampLegSessionWitness}:resolveSpec
+ *    受理时读会话行的化身那一读,同一只值也是委派树根的见证)—— 会话被删掉又以同一 id 重建之后,上一位住客的腿写不进新住客的行。
+ *  · **每条腿声明一个值**:`TaskSpec.projectId` = 这次提交自己带的 `projectId`(新提交的请求体;续跑腿重放的是持久化的同一个体)
+ *    ?? 会话行上最后一帧的 `project.id` —— **只当它是调用方声明过的**(`source: "declared"`:没有记号的检出里声明就是身份,行存它就是为了接着声明);
+ *    `source: "marker"` 是引擎对**那一次**检出的记号判决,不续声明(引擎每条腿对自己的检出再判 —— 记号改写 / 换检出之后续跑照跑);
+ *    都没有 ⇒ 不带(引擎在有记号的检出里自判)。唯一铸点 {@link legProjectIdOf},唯一调用点 `boot/resolve-spec.ts`(新提交与续跑同经那一只装配)。
+ *
+ * ## 什么因此变少
+ * 修前请求键 `projectId` 被提交口受理、却从不交给引擎(keyset 守卫记该引擎座「未接线」,与受理表相反 —— 编译门 ② 红着);
+ * 会话在没有记号的检出里续跑时,项目随每一次不带 `projectId` 的提交丢掉。现在:一个值进引擎、一格存引擎的答案、下一条腿读那一格。
+ *
+ * ## 不在这里的(如实)
+ *  · **记忆项目层**(单用户 `userrepo:` 键,`project-identity.ts` 的 git 检出身份)不是这个事实:它在装配期(任何帧之前)交给
+ *    `TaskSpec.memory.projectKey`,按 git 仓库(origin 远端 / 本机路径)键控,与 `.sema/project` 记号无关;引擎 7.58.0 自己也写明
+ *    「只声明的身份不改记忆的键」。两者是否该合成一个身份,是另一张设计票。
+ *  · 多租户记忆分区(`proj:<租户>/<projectId>`)与登记簿种子读的是**这次提交**的 `projectId`(按提交挑盘,修前即如此),不读行。
+ *  · 行上的 `root` / `cwd` / `entered` / `remote` 今天只存不读(会话面读它们归 wire 半场那一车);fork 出的新会话从「没有记录」起。
+ *  · **只回结果的腿(verify / cascade,含续跑的 verify 臂)不记行**:引擎在组合入口里自己排空内层腿的流,宿主手里没有流,而引擎给组合入口开的
+ *    帧座(`onStatusEvent` / `onWiringManifest`)没有这一帧 ⇒ 这条腿的位置与项目到不了行,行停在更早一条腿的那一帧(没有记号的检出里,
+ *    下一条不带 `projectId` 的提交续声明的是那一帧声明过的项目)。本仓不替引擎铸「这条腿站在哪里」;要引擎为组合入口开这一帧的座。
+ *  · **行读在 run 认领之前**(resolveSpec 的每一读都是):同一会话两次提交交叠、后一次的装配读行之后前一次才落定并放认领 ⇒ 后一次读到的是更早
+ *    一条腿的项目(有记号的检出里多一次 409,没有记号的检出里续声明旧项目)。修法要把声明的装配挪到认领之后,不在本模块补第二个写者。
+ */
+import type { TaskEvent, TaskSpec } from "@sema-agent/core";
+import type { DelegationRootWitness } from "./delegated-session-owner.js";
+/**
+ * `workspace_changed` 帧在会话行上的样子(**唯一**一张表;表序 = 存储形的键序)。`forward` = 原值存进行;`strip` = 不进行。
+ * 腿身份四键(`eventId` / `parentToolCallId` / `sourceTaskId` / `bgAgentId`)是这一帧在流上的身份,不是位置;`type` 是臂名。
+ */
+export declare const SESSION_WORKSPACE_DISPOSITIONS: {
+    readonly type: "strip";
+    readonly cwd: "forward";
+    readonly root: "forward";
+    readonly entered: {
+        readonly nested: {
+            readonly dir: "forward";
+            readonly byPath: "forward";
+        };
+    };
+    readonly project: {
+        readonly nested: {
+            readonly id: "forward";
+            readonly source: "forward";
+        };
+    };
+    readonly remote: "forward";
+    readonly eventId: "strip";
+    readonly parentToolCallId: "strip";
+    readonly sourceTaskId: "strip";
+    readonly bgAgentId: "strip";
+};
+type WorkspaceFrame = Extract<TaskEvent, {
+    type: "workspace_changed";
+}>;
+/** 表里存进行的键(`strip` 之外的)—— 存储形由表派生,不另写一份成员清单。 */
+type KeptKeys = {
+    [K in keyof typeof SESSION_WORKSPACE_DISPOSITIONS]: (typeof SESSION_WORKSPACE_DISPOSITIONS)[K] extends "strip" ? never : K;
+}[keyof typeof SESSION_WORKSPACE_DISPOSITIONS];
+/** 会话行上那一格的值:最后一帧里本仓存下的成员(型从引擎的帧臂派生)。 */
+export type SessionWorkspace = Pick<WorkspaceFrame, KeptKeys>;
+/** 会话店的这一面(两只方法都在才算 —— 只有一半的店让读写不同源)。 */
+export interface SessionWorkspaceStore {
+    /** 这只会话上最后一帧;没有记录 / 没有这一行 ⇒ `undefined`。格读不出 ⇒ 读作没有记录并计一次(`decodeSessionWorkspaceCell`)。 */
+    readSessionWorkspace(sessionId: string): Promise<SessionWorkspace | undefined>;
+    /**
+     * 整格覆写(最后一帧胜),**只写住客是 `incarnation` 那一位的行**:行不在、或此刻坐的是另一位住客 ⇒ 不写、不抛(那一行不是这条腿的)。
+     * 写**没有提交**必须抛。SQL 两孪生走店的一般查询面(与腿循环里的账本追加同一形,不设每查询的客户端超时 —— 客户端放弃等待而服务端照跑完的写,
+     * 正是能在这条腿离开之后落地的那一形);卡住的上界归服务端(锁等待超时 / 部署的 `DB_QUERY_TIMEOUT_MS`)。
+     */
+    recordSessionWorkspace(sessionId: string, incarnation: string, workspace: SessionWorkspace): Promise<void>;
+}
+/** 店有没有这一面 —— 结构判(包装店 `CachingSessionStore` 逐方法转发,判的是能力不是名字)。没有 ⇒ 不记、不读(core 的内存 dev 店)。 */
+export declare function sessionWorkspaceStoreOf(store: unknown): SessionWorkspaceStore | undefined;
+/**
+ * 这条腿的会话**在受理时**是哪一位住客(会话 id + 化身令牌)的 spec 字段键 —— 与 run 名册 / 执行车道字段同一形:symbol 键随 spread / rest 解构走
+ * (续跑腿的 `taskConfig` 是 rest 解构出来的),对引擎的键面不可见(JSON / 结构化克隆跳过 symbol 键)。铸点唯一 = resolveSpec 出口
+ * ({@link stampLegSessionWitness}),值 = 受理时读会话行的那**一**读(同一只值也交给场景层作委派树根的见证);读点唯一 = {@link legSessionWitnessOf}。
+ */
+export declare const LEG_SESSION_WITNESS_FIELD: unique symbol;
+/** 铸见证(**单一属主**:只许 resolveSpec 的出口调用)。`writable:false` + `configurable:false`:同一只 spec 被第二次铸 ⇒ 当场 TypeError。缺席 ⇒ 不铸。 */
+export declare function stampLegSessionWitness<T extends TaskSpec>(spec: T, witness: DelegationRootWitness | undefined): T;
+/** 读见证。`undefined` = 这只 spec 不是本仓装配出口产的,或这条腿没有会话 ⇒ 记录座不写(没有住客可认)。入参收 `object`:续跑腿手里是 rest 解构出来的 taskConfig。 */
+export declare function legSessionWitnessOf(spec: object): DelegationRootWitness | undefined;
+/**
+ * 一帧 → 会话行上那一格的值。只认这条腿**自己的**帧(腿身份三键任一在场 = 委派子代转上来的,不是这条腿站在哪里);
+ * 按表投影后过存储形的同一只读者(写得进的就是读得出的)。读不出(引擎不会铸出这种帧)⇒ 不记、计一次。
+ */
+export declare function sessionWorkspaceOfFrame(ev: TaskEvent): SessionWorkspace | undefined;
+/** 腿的记录座。 */
+export interface SessionWorkspaceRecorder {
+    /**
+     * 持流的腿**逐帧**调用并等它(在本腿的取消成因闩之后)。这条腿自己的 `workspace_changed` ⇒ 这一笔写写完(或失败计一次)才兑现 ——
+     * 帧按到达序一笔一笔写,最后一帧胜;腿从任何出口(`done`、断连 `break`、抛)离开时没有写还悬着。其余帧当场兑现。**从不抛、从不拒**。
+     */
+    observe(ev: TaskEvent): Promise<void>;
+}
+/**
+ * 记录座的**唯一**铸点(四条持流腿各在开流时铸一只:后台腿 `runs.ts`、活流腿与同步腿 `http/routes/tasks.ts`、续跑腿 `http/resume-legs.ts`),
+ * `witness` = 这条腿 spec 上的受理见证({@link legSessionWitnessOf})。店没有这一面、或见证缺席 / 受理时这只会话还没有住客令牌 ⇒
+ * 一只什么都不做的座(诚实缺席:认不出住客就不写 —— 写错住客比少记一次坏)。
+ *
+ * 失败方向(F 类):写失败(库抖 / 盘满 / 锁等待超时)⇒ 行停在上一帧,计一次;下一帧照写。放行的最坏后果 = 下一条不带 `projectId` 的提交读到旧的
+ * (或没有)项目 —— 有记号的检出里引擎照判记号(声明不等就响亮拒),没有记号的检出里这只会话少一次续声明。不放行的代价是把一条在跑的腿
+ * 为一次记录摔掉。等一笔写的代价 = 这条腿的流晚一次主键 UPDATE 的时延(引擎不等宿主消费,只是帧晚到;一条腿的帧只有起点一帧加每次换位一帧)。
+ * 库卡住(池取不到连接)时这条腿交给调用方的结果跟着等:后台腿与续跑腿的循环本来每一帧就等店写(账本追加);同步腿与不落账的活流腿此前循环里没有店写,
+ * 现在多等这一笔 —— 但同一只池上引擎自己的会话条目写(每一轮 `appendEntry`,`plugins/store-backend.ts` 的 `session()` 与其余店共用一池)本来就在
+ * 这条腿的关键路径上,池饿死时这条腿本来就停;上界归部署(`DB_QUERY_TIMEOUT_MS`、MySQL 池的排队上界)。local 后端的写不经池。
+ */
+export declare function createSessionWorkspaceRecorder(store: SessionWorkspaceStore | undefined, witness: DelegationRootWitness | undefined): SessionWorkspaceRecorder;
+/**
+ * **这条腿交给引擎的 `TaskSpec.projectId`**(唯一铸点;见文件头第三句)。`submitted` = 这次提交自己带的、已过形状门且折成小写的值
+ * (新提交:鉴权口的 `resolvedProjectId`;续跑:持久化体的同一个键)。它在场就不读行。行读失败(库抖)原样上抛 —— 读不到「这只会话的项目」
+ * 不能悄悄折成「没有项目」(那会把一只登记在项目下的会话在没有记号的检出里改成无项目)。
+ */
+export declare function legProjectIdOf(submitted: string | undefined, store: SessionWorkspaceStore | undefined, sessionId: string | undefined): Promise<string | undefined>;
+export {};
+//# sourceMappingURL=session-workspace.d.ts.map