@sema-agent/server 7.136.0 → 7.138.0

package/dist/boot/deployment-mods.d.ts

@@ -1,31 +1,61 @@
+import { type EngineDollar, type ModAdmissionRecord, type ModRegistration } from "@sema-agent/core";
+import { type ModsDeclaration } from "../mods-declaration.js";
+import type { Logger } from "../observability/logger.js";
+import type { Metrics } from "../observability/metrics.js";
 /**
- * 部署座(`RunnerDeps.mods`)的注册:**铸**({@link createDeploymentMods})与**起服自证**({@link assertDeploymentModsAdmitted})都在这一处。
- *
- * 起服自证(律三:拒形只有引擎一种读法,本仓只负责「不写」与「启动时自证」):
- * 部署座上的注册是本仓自己铸的。它们坏了
- * —— 坏名、坏档、缺 `uses.calls`、`on` 越出 `uses`、只选无站的名字、`register` 抛 —— 引擎在每条腿的 prepare 里拒
- * (`config.mods_invalid`),那就是每个请求都失败。所以起服时让引擎的 admission 判一次:判官仍是引擎(`admitModChain`),
- * 本函数不判形,只把它的拒折成一句起服错误、拒启。两个起服入口(server 第五段、本地 CLI)同调这一只。
+ * 部署座注册的**出处标签**(谁供的这张注册)—— 宿主自己的词,引擎原样携带、不判;**全仓唯一写点**。
  *
- * 也拒启的两形(同一个理由:部署注册一张都不该缺席,也不该带病挂上):
- *  · admission 期的报告(引擎对坏 `budgetMs` 只报告、回落缺省,不拒)—— 部署注册不设 `budgetMs`,报告出现就是铸法坏了;
- *  · 被 `plugin.register` 判拒的注册(本部署没有这种判官;出现即装配错)。
- * 腿外 admission 只建一只总线并跑一次各注册的 `register`(本仓的 `register` 是纯函数),不碰任何腿。
+ * `wiring_manifest.mods[]` 的一行上有两个词字段,各自一张闭集、互不相交:`seat` 是引擎的座词(`MOD_SEATS`:`deployment` | `task`,这张注册站在哪一座),
+ * `provenance` 是这张表的值(这张注册是谁供的)。两个字段不共用词 —— 同一个词不在一行里指两件事。
+ *  · `minted` → `server`:本服务自己铸的(拒绝计量 / 工具追踪 / 品牌行);
+ *  · `declared` → `operator`:运维在部署声明(`MODS_ROOT` / `MODS_PACKAGES`)里点名装进来的包。词取「谁供的」:与 `server` 同一个维度(供给方),
+ *    并沿用本仓对这件事的既有称呼「运维声明」。不用 `deployment`:它是座词,同一行上同形不同义。
+ * 加一种供给方 = 在这里加一行;取到的词与座词相交 ⇒ 下面的类型门编译红。
  */
-import { type EngineDollar, type ModRegistration } from "@sema-agent/core";
-import type { Logger } from "../observability/logger.js";
-import type { Metrics } from "../observability/metrics.js";
+export declare const MOD_PROVENANCE: {
+    readonly minted: "server";
+    readonly declared: "operator";
+};
 /**
- * 部署座上的注册列表 —— 两个起服入口(server 第五段与本地 CLI)同一只铸法,哪几张、什么顺序只写在这里:
+ * 本仓自铸的部署注册 —— 哪几张、什么顺序只写在这里(装配口 {@link assembleDeploymentMods} 把它们排在声明的包之前):
  *  · 拒绝计量恒挂、在前;工具追踪(`TOOL_TRACE=true`,交 `traceLogger`)在后。两张都是 `prepend` 档的观察者,引擎按「档 → 部署先于任务 → 座内顺序」
  *    串行跑观察者、且都在链之前 ⇒ 同一次拒绝先计数、后写追踪行;
  *  · 品牌行(`brandIdentity`:品牌部署 = local / TOC)—— `prompt.compose` 上的一条部署类 overlay(`capabilities/brand-identity.ts`),与两只观察者
  *    不在同一个事件上,顺序不影响它们。部署开不开品牌只在这一个入参表态。
+ * 出处标签:自铸的每一张都带宿主标签 {@link MOD_PROVENANCE}`.minted`,声明的包由装配口给 `.declared` —— 引擎把宿主给的标签原样记进准入记录与每条腿的
+ * `wiring_manifest.mods[]`,一条腿的部署座由此分得出「本服务自铸」与「运维声明」两种来源。
  */
 export declare function createDeploymentMods(input: {
     readonly metrics: Pick<Metrics, "inc">;
     readonly traceLogger?: Logger | undefined;
     readonly brandIdentity?: boolean | undefined;
 }): readonly ModRegistration<EngineDollar>[];
-export declare function assertDeploymentModsAdmitted(mods: readonly ModRegistration<EngineDollar>[]): Promise<void>;
+/** 起服装上的一只声明包(起服日志行 `mods_package_loaded` 与 `/health` / `/v1/capabilities` 的读数都读这一份)。 */
+export interface LoadedModPackage {
+    readonly name: string;
+    /** 引擎准入记录里这只包站的档(准入判过的那一份,不是声明里写的)。 */
+    readonly tier: ModAdmissionRecord["tier"];
+    /** 读包者按相等判过的引擎契约号(包声明的 `contract` 与引擎的 `KERNEL_CONTRACT_VERSION` 相等才装得上)。 */
+    readonly contract: number;
+    /** 读包者交回的三件字节摘要(`ModPackageRegistration.digest`,按给值记)—— 认得出「装的是哪几份字节」,不是代码完整性凭据。 */
+    readonly digest: string;
+}
+/** 装配的结果:部署座的注册(自铸在前、声明在后,整列已过引擎准入)与装上的声明包(只数声明的包,自铸的不算)。 */
+export interface DeploymentModsAssembly {
+    readonly registrations: readonly ModRegistration<EngineDollar>[];
+    readonly loaded: readonly LoadedModPackage[];
+}
+/** 部署座的唯一装配口(两只起服入口同调;三段与失败见文件头注)。 */
+export declare function assembleDeploymentMods(input: {
+    readonly metrics: Pick<Metrics, "inc">;
+    readonly traceLogger?: Logger | undefined;
+    readonly brandIdentity?: boolean | undefined;
+    readonly declaration: ModsDeclaration;
+    readonly logger: Pick<Logger, "info">;
+}): Promise<DeploymentModsAssembly>;
+/**
+ * 第三段:整列交引擎准入判一次(判官是引擎;本函数不判形,只把它的拒、报告与判拒折成一句 `admission_refused`)。
+ * 过了 ⇒ 交回这一次准入的记录(每张注册一行,全部挂上了 —— 有一行被判拒就不会走到这里)。
+ */
+export declare function assertDeploymentModsAdmitted(mods: readonly ModRegistration<EngineDollar>[]): Promise<readonly ModAdmissionRecord[]>;
 //# sourceMappingURL=deployment-mods.d.ts.map

package/dist/boot/deployment-mods.js

@@ -1,26 +1,102 @@
-import { admitModChain } from "@sema-agent/core";
+import { realpathSync, statSync } from "node:fs";
+import { isAbsolute, relative, sep } from "node:path";
+import { admitModChain, KERNEL_CONTRACT_VERSION, loadModPackage } from "@sema-agent/core";
 import { createBrandIdentityRegistration } from "../capabilities/brand-identity.js";
 import { createPermissionDeniedMeter, createToolTracer } from "../observability/tool-trace.js";
+import { errorCodeOf, errorText } from "../observability/err-text.js";
+import { sanitizeWireText } from "../trace/engine-notice-wire.js";
+import { DeploymentModsRefusedError } from "../mods-declaration.js";
+export const MOD_PROVENANCE = { minted: "server", declared: "operator" };
 export function createDeploymentMods(input) {
     return [
         createPermissionDeniedMeter(input.metrics),
         ...(input.traceLogger !== undefined ? [createToolTracer(input.traceLogger)] : []),
         ...(input.brandIdentity === true ? [createBrandIdentityRegistration()] : []),
-    ];
+    ].map((registration) => ({ ...registration, provenance: MOD_PROVENANCE.minted }));
+}
+export async function assembleDeploymentMods(input) {
+    const minted = createDeploymentMods(input);
+    const resolved = resolveDeclaredPackages(input.declaration);
+    const declared = [];
+    for (const { pkg, realDir } of resolved)
+        declared.push(await loadDeclaredPackage(pkg, realDir));
+    const registrations = [...minted, ...declared];
+    const records = await assertDeploymentModsAdmitted(registrations);
+    const loaded = resolved.map(({ pkg }, i) => ({ name: pkg.name, tier: admittedRecordOf(records, pkg.name).tier, contract: KERNEL_CONTRACT_VERSION, digest: declared[i].digest }));
+    for (const row of loaded)
+        input.logger.info("mods_package_loaded", { name: sanitizeWireText(row.name), tier: row.tier, contract: row.contract, digest: row.digest });
+    return { registrations, loaded };
+}
+function fsCauseOf(e) {
+    const code = errorCodeOf(e);
+    return typeof code === "string" && /^E[A-Z0-9]{1,31}$/.test(code) ? code : "unknown";
+}
+function strictlyUnderRoot(root, child) {
+    const rel = relative(root, child);
+    return rel !== "" && rel.split(sep)[0] !== ".." && !isAbsolute(rel);
+}
+function resolveDeclaredPackages(declaration) {
+    if (declaration.packages === undefined)
+        return [];
+    let realRoot;
+    try {
+        realRoot = realpathSync(declaration.root);
+    }
+    catch (e) {
+        throw new DeploymentModsRefusedError({ word: "root_unreadable", cause: fsCauseOf(e) });
+    }
+    return declaration.packages.map((pkg, entry) => {
+        let realDir;
+        let isDirectory;
+        try {
+            realDir = realpathSync(pkg.dir);
+            isDirectory = statSync(realDir).isDirectory();
+        }
+        catch (e) {
+            throw new DeploymentModsRefusedError({ word: "dir_unreadable", entry, cause: fsCauseOf(e) });
+        }
+        if (!strictlyUnderRoot(realRoot, realDir))
+            throw new DeploymentModsRefusedError({ word: "outside_root", entry });
+        if (!isDirectory)
+            throw new DeploymentModsRefusedError({ word: "not_a_directory", entry });
+        return { pkg, realDir };
+    });
+}
+function machineCodeOf(e) {
+    const code = errorCodeOf(e);
+    return typeof code === "string" && /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(code) ? code : undefined;
+}
+async function loadDeclaredPackage(pkg, realDir) {
+    let registration;
+    try {
+        registration = await loadModPackage(realDir, { tier: pkg.tier, provenance: MOD_PROVENANCE.declared, ...("options" in pkg ? { options: pkg.options } : {}) });
+    }
+    catch (e) {
+        throw new DeploymentModsRefusedError({ word: "package_refused", name: pkg.name, code: machineCodeOf(e), reason: errorText(e) });
+    }
+    if (registration.name !== pkg.name)
+        throw new DeploymentModsRefusedError({ word: "name_mismatch", name: pkg.name, packageName: registration.name });
+    return registration;
 }
-const REFUSED = "deployment extension registration refused";
 export async function assertDeploymentModsAdmitted(mods) {
     const reports = [];
     let records;
     try {
-        ({ records } = await admitModChain({ deployment: mods }, (err) => void reports.push(err.message)));
+        ({ records } = await admitModChain({ deployment: mods }, (err) => void reports.push(errorText(err))));
     }
     catch (e) {
-        throw new Error(`${REFUSED}: ${e instanceof Error ? e.message : String(e)}`);
+        throw new DeploymentModsRefusedError({ word: "admission_refused", code: machineCodeOf(e), reason: errorText(e) });
     }
     const refused = records.flatMap((r) => ("refusedBy" in r ? [`"${r.name}" refused by ${r.refusedBy}: ${r.reason}`] : []));
     const problems = [...reports, ...refused];
     if (problems.length > 0)
-        throw new Error(`${REFUSED}: ${problems.join("; ")}`);
+        throw new DeploymentModsRefusedError({ word: "admission_refused", code: undefined, reason: problems.join("; ") });
+    return records;
+}
+function admittedRecordOf(records, name) {
+    const record = records.find((r) => r.seat === "deployment" && r.name === name);
+    if (record === undefined)
+        throw new DeploymentModsRefusedError({ word: "admission_refused", code: undefined, reason: `the engine's admission returned no record for ${JSON.stringify(name)}` });
+    return record;
 }
 //# sourceMappingURL=deployment-mods.js.map

package/dist/boot/execution-env.d.ts

@@ -7,7 +7,9 @@ import { PerTaskImageRegistry } from "../per-task-image.js";
 import type { DeviceEnrollment } from "../device-enrollment.js";
 import type { DeviceStore } from "../device-store.js";
 import type { DeviceWsHub } from "../device-ws-hub.js";
-import { k8sExecutionEnvFactory, type K8sEnvConfig, type K8sEnvDeps } from "../plugins/remote-env-k8s.js";
+import { k8sExecutionEnvFactory, type K8sEnvConfig, type K8sEnvDeps, type SandboxSecretSeat } from "../plugins/remote-env-k8s.js";
+import { type SandboxGitPlane, type SandboxGitRunRows } from "../sandbox-git-plane.js";
+import { type SandboxPodReaper } from "../plugins/k8s-pod-reaper.js";
 import { type SpaceCommitRows } from "../workspace-space-commit.js";
 import * as facts from "../capability-facts.js";
 import { type TaskAttachmentStore } from "../plugins/task-attachment-store.js";
@@ -76,6 +78,10 @@ export declare function createSessionScopedRegistries(maxEntries?: number): Sess
  */
 export declare function createK8sRunEnvFactory(k8sCfg: K8sEnvConfig, seats: {
     imageOf(sessionId: string): string | undefined;
+    /** The member git-credential broker seat for the pod's run (`runId` = the one reading of the run that owns the pod, the same value its
+     *  `sema.io/run` label carries; `sandbox-git-plane.ts` `sandboxBrokerSeatOf` over the boot's plane reading and the run row's identity);
+     *  absent seat / `undefined` answer ⇒ the pod carries no broker. */
+    brokerSeatOf?(runId: string | undefined): Promise<K8sEnvConfig["sandboxBroker"]>;
     /** The session store's by-id head read (`SessionStore.headOf`, picked once by `headReadOf`); the occupant is its live-occupant projection
      *  (`sessionFaceOfHead`). Absent ⇔ the store has none, which `assertWorkspaceSpaceReadable` refuses together with `space` (embeddings that
      *  wire another lane pass none). */
@@ -84,6 +90,17 @@ export declare function createK8sRunEnvFactory(k8sCfg: K8sEnvConfig, seats: {
      *  or without a store backend — the latter `assertWorkspaceSpaceReadable` refuses together with `space`. */
     spaceCommits(): SpaceCommitRows | undefined;
 }, deps?: K8sEnvDeps): ReturnType<typeof k8sExecutionEnvFactory>;
+/**
+ * k8s 车道沙箱秘密座的**起服前提**(装配后的真门,第 5 段 await)。法只有一条:**秘密座非空(`K8S_SANDBOX_ENV` 点到了本进程环境里有的键)⇒
+ * 问一次 SelfSubjectAccessReview(env 座那一行动词 {@link SANDBOX_SECRET_SEAT_VERBS}`.env`,沙箱命名空间)** —— 只问这一座自己发的调用,
+ * 不问租约座的 `patch`(那一座由凭据平面的判官在它的前提都成立时另问,见 `readSandboxGitPlane`):
+ *  · 答了「不许」(任一动词)⇒ 拒启,一行拒句点名缺的动词、命名空间、Role 规则原文与出路(`[sandbox-secret-rbac]`)—— 不等第一个 run 才失败;
+ *  · 问不到(请求失败 / 审查本身被拒 / 答复没有 `status.allowed`)⇒ 照常起服:F 类兜底口 `server.sandbox-secret.seat-unverified` 计数 + 一行
+ *    `sandbox_secret_seat_unverified`。放行的最坏后果:RBAC 真缺时第一个要建 Secret 的 run 连接即拒(`auth_failed`,pod 被删)—— 秘密值仍然
+ *    只经 Secret,不回落明文;
+ *  · 秘密座空 ⇒ 一个请求都不发(没有 Secret 要建)。
+ */
+export declare function ensureSandboxSecretSeat(k8sCfg: K8sEnvConfig, logger: Pick<Logger, "warn">, deps?: K8sEnvDeps, read?: () => Promise<SandboxSecretSeat>): Promise<void>;
 /**
  * k8s 工作区空间的**起服前提**(装配后的真门;同段先例 = `assertDeviceLaneWired`)。法只有一条:
  * **生效策略 `space`(事实 `workspaceSpace`)∧ {@link createK8sRunEnvFactory} 的两只座缺一 ⇒ 拒启。**
@@ -119,6 +136,9 @@ export interface ExecutionEnvCtx {
     spaceCommits?: () => SpaceCommitRows | undefined;
     /** k8s 工作区空间的住客读:会话店的按 id 读(`headReadOf(sessionStore)`,第 5 段判一次、与起服门同一只)。不传 ⇒ 同上,不开、响亮。 */
     headOf?: HeadRead;
+    /** run 店的按 id 读(成员凭据代理座读 run 行上受理时记下的身份元组 `RunRecord.identity`)。取值闭包:run 店第 7 段才绑(`late-binds.ts`),
+     *  平面开着时每个 run 的 pod 建起前求值一次。不传 / 答 `undefined`(没有存储后端)⇒ 读不到身份 ⇒ 不挂代理。 */
+    runRows?: () => SandboxGitRunRows | undefined;
 }
 export declare function createExecutionEnv(ctx: ExecutionEnvCtx): {
     perTaskImage: PerTaskImageRegistry;
@@ -134,5 +154,8 @@ export declare function createExecutionEnv(ctx: ExecutionEnvCtx): {
     sendUserFileTaskEnvs: TaskEnvRegistry | undefined;
     lspManager: import("@sema-agent/core").NodeLspManager | import("../lsp/manager.js").E2bLspManager | undefined;
     spaceReclaimer: SpaceReclaimer | undefined;
+    sandboxSecretSeatGate: (() => Promise<void>) | undefined;
+    sandboxPodReaper: SandboxPodReaper | undefined;
+    readSandboxGitPlane: () => Promise<SandboxGitPlane>;
 };
 //# sourceMappingURL=execution-env.d.ts.map

package/dist/boot/execution-env.js

@@ -11,7 +11,11 @@ import { adbExecutionEnvFactory } from "../plugins/remote-env-adb.js";
 import { deviceExecutionEnvFactory } from "../plugins/remote-env-device.js";
 import { e2bExecutionEnvFactory } from "../plugins/remote-env-e2b.js";
 import { hostExecutionEnvFactory, RemoteHostExecutionEnv } from "../plugins/remote-env-host.js";
-import { boundedStoreCall, checkSandboxEgressPolicy, createSpaceReclaimer, K8S_SANDBOX_NAMESPACE_DEFAULT, k8sExecutionEnvFactory, rpcTimeoutMsOf } from "../plugins/remote-env-k8s.js";
+import { boundedStoreCall, checkSandboxEgressPolicy, createSandboxPodApi, createSpaceReclaimer, K8S_SANDBOX_NAMESPACE_DEFAULT, k8sExecutionEnvFactory, readSandboxSecretSeat, rpcTimeoutMsOf } from "../plugins/remote-env-k8s.js";
+import { podSpecPatchBrokerRefusal, SANDBOX_SECRET_SEAT_VERBS } from "../plugins/k8s-exec-protocol.js";
+import { judgeSandboxGitPlane, runIdentitySourceOf, sandboxBrokerSeatOf, sandboxGitPlaneAsksSecretSeat, sandboxGitPlanePremisesOf } from "../sandbox-git-plane.js";
+import { createSandboxPodReaper } from "../plugins/k8s-pod-reaper.js";
+import { recordFailOpen } from "../observability/fail-open.js";
 import { createRunWorkspaceSnapshotSeat } from "../fleet/workspace-snapshot-residual.js";
 import { createSpaceCommitFence } from "../workspace-space-commit.js";
 import { localDockerExecutionEnvFactory } from "../plugins/remote-env-local-docker.js";
@@ -58,7 +62,12 @@ function forwardedSandboxEnvKeys(remoteExec) {
     }
 }
 function buildSandboxLaneEnv(config, explicit) {
-    const merged = { ...derivePkgSourceEnv(config.sandboxPkgSource, config.sandboxPkgSourceCustom), ...(explicit ?? {}) };
+    const secretEnv = { ...(explicit ?? {}) };
+    const env = Object.fromEntries(Object.entries(derivePkgSourceEnv(config.sandboxPkgSource, config.sandboxPkgSourceCustom)).filter(([name]) => !Object.hasOwn(secretEnv, name)));
+    return { ...(Object.keys(env).length > 0 ? { env } : {}), ...(Object.keys(secretEnv).length > 0 ? { secretEnv } : {}) };
+}
+function sandboxLaneEnvMerged(lane) {
+    const merged = { ...(lane.env ?? {}), ...(lane.secretEnv ?? {}) };
     return Object.keys(merged).length > 0 ? merged : undefined;
 }
 const MAX_CWD_SESSIONS = 4096;
@@ -118,6 +127,8 @@ export function createK8sRunEnvFactory(k8sCfg, seats, deps) {
         const child = ctx.placementRootSessionId !== ctx.sessionId;
         const s3Snapshot = child && k8sCfg.s3Snapshot !== undefined ? spaceOff(k8sCfg.s3Snapshot) : k8sCfg.s3Snapshot;
         const spaceOccupant = child ? undefined : await occupantOf(seats, ctx.sessionId, ctx.taskId, rpcTimeoutMsOf(k8sCfg));
+        const runId = !child && ctx.taskId !== undefined ? ctx.taskId : undefined;
+        const sandboxBroker = await seats.brokerSeatOf?.(runId);
         const { cache, ...deploymentCfg } = k8sCfg;
         return k8sExecutionEnvFactory({
             ...deploymentCfg,
@@ -125,6 +136,8 @@ export function createK8sRunEnvFactory(k8sCfg, seats, deps) {
             ...(s3Snapshot !== undefined ? { s3Snapshot } : {}),
             image: seats.imageOf(ctx.sessionId) ?? k8sCfg.image,
             ...(spaceOccupant !== undefined ? { spaceOccupant } : {}),
+            ...(runId !== undefined ? { runId } : {}),
+            ...(sandboxBroker !== undefined ? { sandboxBroker } : {}),
             onWorkspaceSnapshot,
         }, deps)(ctx);
     };
@@ -156,6 +169,34 @@ function spaceOff(store) {
     const { space: _off, ...parkOnly } = store;
     return parkOnly;
 }
+export async function ensureSandboxSecretSeat(k8sCfg, logger, deps, read = () => readSandboxSecretSeat(k8sCfg, "env", deps)) {
+    const names = Object.keys(k8sCfg.podSecretEnv ?? {});
+    if (names.length === 0)
+        return;
+    const namespace = k8sCfg.namespace ?? K8S_SANDBOX_NAMESPACE_DEFAULT;
+    const seat = await read();
+    switch (seat.state) {
+        case "granted":
+            return;
+        case "denied":
+            throw new Error(`K8S_SANDBOX_ENV forwards ${names.length} variable(s) into the k8s sandbox, but this service account may not ${seat.verbs.join(", ")} secrets ` +
+                `in namespace ${namespace} [sandbox-secret-rbac]: the forwarded values reach a sandbox pod only through that pod's own Secret (the pod spec carries ` +
+                `references, never the values). Add to the sandbox Role in ${namespace}: \`- apiGroups: [""] resources: [secrets] verbs: [${SANDBOX_SECRET_SEAT_VERBS.env.join(", ")}]\` ` +
+                "(or unset K8S_SANDBOX_ENV), and restart");
+        case "unverified":
+            recordFailOpen("server.sandbox-secret.seat-unverified", `namespace=${namespace} ${seat.detail}`);
+            logger.warn("sandbox_secret_seat_unverified", {
+                namespace,
+                detail: seat.detail,
+                effect: `the boot could not confirm the sandbox Secret RBAC (secrets ${SANDBOX_SECRET_SEAT_VERBS.env.join(" / ")}) — the service starts; if the Role lacks them, the first run that forwards K8S_SANDBOX_ENV is refused at connect (auth_failed) and its pod deleted — the values never go into the pod spec`,
+            });
+            return;
+        default: {
+            const unreachable = seat;
+            throw new Error(`unhandled sandbox secret seat reading: ${String(unreachable.state)}`);
+        }
+    }
+}
 export function assertWorkspaceSpaceReadable(space, seats, cache, sessionStoreLabel) {
     if (space.available && persistNeedsOccupant(space.policy.persist)) {
         const missing = seats.headOf === undefined ? `the session store (${sessionStoreLabel}) has no by-id occupant read (headOf)`
@@ -207,6 +248,10 @@ export function createExecutionEnv(ctx) {
     const { perSessionInheritEnv, setSessionInheritEnv } = sessionScoped;
     let executionEnvFactory;
     let spaceReclaimer;
+    let sandboxSecretSeatGate;
+    let sandboxPodReaper;
+    const planeCell = {};
+    let readSandboxGitPlane = async () => (planeCell.current = judgeSandboxGitPlane(sandboxGitPlanePremisesOf(config, {})));
     let worktreeReap;
     if (config.remoteExec?.provider === "e2b") {
         executionEnvFactory = e2bExecutionEnvFactory({
@@ -217,7 +262,7 @@ export function createExecutionEnv(ctx) {
             ...(config.remoteExec.livenessMs != null ? { livenessMs: config.remoteExec.livenessMs } : {}),
             ...(config.remoteExec.allowInternetAccess != null ? { allowInternetAccess: config.remoteExec.allowInternetAccess } : {}),
             ...(config.remoteExec.mountPath ? { mountPath: config.remoteExec.mountPath } : {}),
-            ...((env) => (env !== undefined ? { sandboxEnv: env } : {}))(buildSandboxLaneEnv(config, config.remoteExec.sandboxEnv)),
+            ...((env) => (env !== undefined ? { sandboxEnv: env } : {}))(sandboxLaneEnvMerged(buildSandboxLaneEnv(config, config.remoteExec.sandboxEnv))),
             logger,
             metrics,
         });
@@ -243,11 +288,29 @@ export function createExecutionEnv(ctx) {
             ...((f) => (f.available ? { cache: f.cache } : {}))(facts.workspaceCache(config)),
             ...(config.remoteExec.workspaceSnapshotExclude ? { snapshotExclude: config.remoteExec.workspaceSnapshotExclude } : {}),
             logger,
-            ...((env) => (env !== undefined ? { podEnv: env } : {}))(buildSandboxLaneEnv(config, config.remoteExec.sandboxEnv)),
+            ...((lane) => ({ ...(lane.env !== undefined ? { podEnv: lane.env } : {}), ...(lane.secretEnv !== undefined ? { podSecretEnv: lane.secretEnv } : {}) }))(buildSandboxLaneEnv(config, config.remoteExec.sandboxEnv)),
         };
-        executionEnvFactory = createK8sRunEnvFactory(k8sCfg, { imageOf: (sid) => perTaskImage.get(sid), headOf: ctx.headOf, spaceCommits: ctx.spaceCommits ?? (() => undefined) });
+        const brokerImage = config.remoteExec.brokerImage;
+        executionEnvFactory = createK8sRunEnvFactory(k8sCfg, {
+            imageOf: (sid) => perTaskImage.get(sid),
+            headOf: ctx.headOf,
+            spaceCommits: ctx.spaceCommits ?? (() => undefined),
+            brokerSeatOf: async (runId) => {
+                const plane = planeCell.current;
+                if (plane === undefined || plane.state !== "on")
+                    return undefined;
+                return sandboxBrokerSeatOf(plane, brokerImage, await runIdentitySourceOf(runId, ctx.runRows?.(), logger));
+            },
+        });
         if (k8sCfg.cache !== undefined || k8sCfg.s3Snapshot !== undefined)
             spaceReclaimer = createSpaceReclaimer(k8sCfg);
+        sandboxSecretSeatGate = () => ensureSandboxSecretSeat(k8sCfg, logger, undefined, () => readSandboxSecretSeat(k8sCfg, "env"));
+        readSandboxGitPlane = async () => {
+            const premises = sandboxGitPlanePremisesOf(config, { ...((r) => (r !== undefined ? { patchRefusal: r } : {}))(podSpecPatchBrokerRefusal(k8sCfg.podSpecPatch)) });
+            const secretSeat = sandboxGitPlaneAsksSecretSeat(premises) ? await readSandboxSecretSeat(k8sCfg, "lease") : undefined;
+            return (planeCell.current = judgeSandboxGitPlane({ ...premises, secretSeat }));
+        };
+        sandboxPodReaper = createSandboxPodReaper({ api: createSandboxPodApi(k8sCfg), logger, metrics });
         void checkSandboxEgressPolicy(k8sCfg)
             .then((gaps) => sayEgressPolicyReading(gaps, logger, k8sCfg.namespace ?? K8S_SANDBOX_NAMESPACE_DEFAULT))
             .catch((e) => logger.error("sandbox_egress_policy_check_crashed", { error: e instanceof Error ? e.message : String(e), effect: "the sandbox egress self-check did not complete this boot — the lane runs; the egress policy was not read" }));
@@ -446,7 +509,7 @@ export function createExecutionEnv(ctx) {
         perTaskImage, sessionEnvSelection, perSessionCwd, setSessionCwd, setSessionShellEnv, setSessionInheritEnv,
         fenceSessionOwner: sessionScoped.fenceSessionOwner,
         dropSessionScoped: sessionScoped.dropSession,
-        executionEnvFactory, worktreeReap, sendUserFileTaskEnvs, lspManager, spaceReclaimer,
+        executionEnvFactory, worktreeReap, sendUserFileTaskEnvs, lspManager, spaceReclaimer, sandboxSecretSeatGate, sandboxPodReaper, readSandboxGitPlane,
     };
 }
 //# sourceMappingURL=execution-env.js.map

package/dist/boot/governance-seams.d.ts

@@ -41,13 +41,13 @@
  *
  * ## 件D 的边界(成文,别读成「数据会被删」)
  *
- * 本仓**没有任何** store 声明 `retention:"managed"`(亲验:session/checkpoint/tool-result 三族 SQL 双生
- * 与 local 形都没有这一位),托管留存的执行面(调度/重试/副本协调/逐行审计)按 §5.2 是「server 半场四件
- * 皆新建」,不在本批。所以本装配点对件D 只做两件事:①把策略递给 core 的启动期校验
- * (`assertRetentionCapability` —— 锁着 + 店不能删 ⇒ 拒启,「策略锁着、数据永存」不许发生);②策略在场
- * 而没有任何 managed 店时打一条响亮 warn。**不**假装有执行面。
+ * 三只被托管的 SQL 店(session / checkpoint / tool-result)的 `retention` 声明读一个事实 —— 留存扫车道开不开(`plugins/retention-store-sql.ts` 的
+ * `retentionSweepRuns`):开 ⇒ `managed`,关(缺省)⇒ `none`;local 形的店恒声明 `none`。删除的执行面是扫车道(`boot/retention-lane.ts`)与 SQL 店上的
+ * 执行器,不在本装配点。所以本装配点对件D 只做两件事:①把策略与执行器递给 core 的启动期校验
+ * (`assertRetentionCapability` —— 配对由引擎一个判官判:店声明 `managed` 而部署不跑执行器、执行器不是执行器,锁不锁都拒;锁着 + 店不能删 ⇒ 拒启,
+ * 「策略锁着、数据永存」不许发生);②策略在场而没有任何 managed 店时打一条响亮 warn。**不**假装有执行面。
  */
-import { type LockedKey, type RunnerDeps } from "@sema-agent/core";
+import { type LockedKey, type ManagedRetentionCapability, type RunnerDeps } from "@sema-agent/core";
 import type { ServiceConfig } from "../config.js";
 import type { Logger } from "../observability/logger.js";
 /** 装配产物:三个 core 座席 + 已校验的锁集(同步拒面 `assertRequestMcpUnlocked` 读它)。 */
@@ -72,18 +72,11 @@ export interface GovernanceSeamsCtx {
         store: object | undefined;
     }>;
     /**
-     * [ref] 车1 —— **本 build 是否真的接了留存执行器**(sweep lane;车2 的 `startRetentionLane()`)。
-     * 缺席 = `false`。
-     *
-     * 🔴 为什么这一位必须存在(codex 交叉复审 R2-[critical],验真后修):core 的
-     * `assertRetentionCapability` 只读**店的声明位**。[ref] 车1 让三只 SQL 店如实声明了 `"managed"`
-     * (它们的行确实由托管留存删),于是那道门从此**放行** locked policy —— 可执行器还在车2 手里。
-     * 两者之间的窗口如果什么都不做,后果正是本仓最忌的那种:部署自述「策略已受管」、审计与能力面
-     * 也这么说,而**没有任何东西在删数据**;车1 之前那条 `retention_policy_not_executed` 的响亮 warn
-     * 还会因为"有 managed 店在场"而**静音**。
-     * ⇒ 判据改成问「有没有东西真会删」,而不是「有没有店说自己被管」。车2 接上 lane 时把这一位传 true。
+     * 交给引擎启动检查的留存执行器 —— 本部署跑扫车道 ⇒ 那只执行器(`backend.retention`),不跑 ⇒ `null`(必填:漏递即编译红,
+     * 引擎对 `undefined` 也拒启)。「店说 managed」与「有执行器」的配对由引擎一个判官判(引擎 7.58.0:锁不锁都判);
+     * 店的词与这一格读同一个事实(`retention-store-sql.ts` 的 `retentionSweepRuns`),本仓不再另判一遍。
      */
-    retentionExecutorWired?: boolean;
+    retentionExecutor: ManagedRetentionCapability | null;
 }
 /**
  * 件C 的装配相容性判据(纯,可单测)——见文件头「两条判据」。

package/dist/boot/governance-seams.js

@@ -49,30 +49,18 @@ export function createGovernanceSeams(ctx) {
     }
     const retentionPolicy = config.retentionPolicy;
     const locked = lockedKeys.has("retentionPolicy");
-    assertRetentionCapability({ policy: retentionPolicy, locked, stores: retentionStores });
+    assertRetentionCapability({ policy: retentionPolicy, locked, stores: retentionStores, executor: ctx.retentionExecutor });
     if (retentionPolicy !== undefined) {
         const managed = retentionStores.filter((s) => s.store?.retention === "managed");
-        const executorWired = ctx.retentionExecutorWired === true;
         if (managed.length === 0) {
             logger.warn("retention_policy_not_executed", {
                 maxAgeDays: retentionPolicy.maxAgeDays,
-                note: "RETENTION_MAX_AGE_DAYS is configured but NO wired store declares retention:\"managed\", and this build ships no " +
-                    "retention scheduler — the policy is a DECLARATION only; nothing deletes data on its account. It is relayed to the " +
-                    "engine for the startup capability check and will become effective when a managed-retention store + scheduler land.",
+                note: "RETENTION_MAX_AGE_DAYS is configured but NO wired store declares retention:\"managed\" (the retention sweep lane is off — " +
+                    "RETENTION_SWEEP_INTERVAL_SEC unset or 0 — or the store medium has no sweep) — the policy is a DECLARATION only; nothing " +
+                    "deletes data on its account. It is relayed to the engine for the startup capability check; run the sweep lane on a SQL " +
+                    "backend to make it effective.",
             });
         }
-        else if (!executorWired) {
-            const detail = `retention policy is configured (maxAgeDays=${retentionPolicy.maxAgeDays}) and ${managed.length} wired store(s) declare ` +
-                `retention:"managed", but THIS BUILD WIRES NO RETENTION EXECUTOR (the sweep lane) — nothing enumerates domains or calls ` +
-                `the destructive store methods, so no data is deleted on the policy's account. A "managed" declaration is a statement ` +
-                `about who OWNS deleting those rows, not proof that a scheduler is running.`;
-            if (locked) {
-                throw new Error(`${detail} Refusing to start with the retentionPolicy key LOCKED: a locked policy over a deployment that does not ` +
-                    `actually delete is exactly the "policy locked, data immortal" posture the engine's capability check exists to ` +
-                    `prevent. Unlock the key, remove the policy, or run a build whose retention sweep lane is wired.`);
-            }
-            logger.warn("retention_policy_not_executed", { maxAgeDays: retentionPolicy.maxAgeDays, note: detail });
-        }
     }
     return { compliancePostureResolver, lockedConfig, retentionPolicy, lockedKeys };
 }

package/dist/boot/leader.d.ts

@@ -49,6 +49,9 @@ export interface LeaderCtx {
      *  唯一出口就是它(`runtask.js` 的 `catch (flushErr) => deps.onError`),所以它与 `usageWindowStore`
      *  席同生共死:挂窗不挂汇 = 治理轴上的静默失败面([ref])。必填键,理由同 `tracer`。 */
     onError: RunnerDeps["onError"];
+    /** 部署座 —— 起服第 5 段装配口 `assembleDeploymentMods` 交回的**同一份**(主车道各 Runner 经共享基座吃的就是它)。leader 车道的每一只 Runner 都要带:
+     *  缺席 = 运维声明的 mod 包管不到 leader 派出的腿。必填键,理由同 `tracer`。 */
+    deploymentMods: NonNullable<RunnerDeps["mods"]>;
     /** [ref] 车4 件1:durable store 后端(leader-run 登记表从这里取)。缺席 = 无 DB 的 env-only worker。 */
     backend?: StoreBackend | undefined;
 }

package/dist/boot/leader.js

@@ -59,6 +59,7 @@ export function createLeaderFace(ctx) {
                 : {}),
             ...(ctx.promptSource ? { promptSource: ctx.promptSource } : {}),
             ...(ctx.onError ? { onError: ctx.onError } : {}),
+            mods: ctx.deploymentMods,
             fanoutEnabled: config.leaderFanoutEnabled,
             ...((process.env.MODEL_ROUTER_ID || process.env.MODEL_CHEAP_ID)
                 ? { routerModel: (process.env.MODEL_ROUTER_ID || process.env.MODEL_CHEAP_ID) }

package/dist/boot/org-delivery.js

@@ -1,5 +1,17 @@
 import { principalInboxConsumerOf } from "@sema-agent/core";
 import { createOrgDeliveryGate } from "../org-delivery-gate.js";
+function declarationOf(consumer) {
+    switch (consumer.kind) {
+        case "assistant":
+            return { declared: "PRINCIPAL_INBOX_ASSISTANT declares a principal-inbox consumer", undeclare: "unset PRINCIPAL_INBOX_ASSISTANT" };
+        case "terminals":
+            return { declared: 'RunnerDeps.principalInboxConsumer declares "terminals" (the scope\'s terminal sessions drain the principal inbox)', undeclare: "drop the RunnerDeps.principalInboxConsumer declaration" };
+        default: {
+            const unknown = consumer;
+            throw new Error(`unknown principal-inbox consumer kind: ${JSON.stringify(unknown)}`);
+        }
+    }
+}
 export function mountOrgDeliveryGate(input) {
     const consumer = principalInboxConsumerOf(input.runnerDeps);
     if (consumer.kind === "none")
@@ -11,8 +23,9 @@ export function mountOrgDeliveryGate(input) {
             ...(directory === undefined ? ["an organization membership directory (a web-admin center, or MEMORY_ORG_DIRECTORY_JSON)"] : []),
             ...(backend === undefined ? ["a store backend for the delivery quota (DB_BACKEND=mysql|pg|local)"] : []),
         ];
-        throw new Error(`PRINCIPAL_INBOX_ASSISTANT declares a principal-inbox consumer, so this deployment must mount the organization delivery gate — but it lacks ${missing.join("; ")}. ` +
-            `Refusing to boot rather than run with a declared inbox that nothing may legitimately write to; provide the missing pieces or unset PRINCIPAL_INBOX_ASSISTANT.`);
+        const { declared, undeclare } = declarationOf(consumer);
+        throw new Error(`${declared}, so this deployment must mount the organization delivery gate — but it lacks ${missing.join("; ")}. ` +
+            `Refusing to boot rather than run with a declared inbox that nothing may legitimately write to; provide the missing pieces or ${undeclare}.`);
     }
     input.logger.info("org_delivery_gate_mounted", { consumer: consumer.kind });
     return createOrgDeliveryGate({ directory, mailbox: mailboxStore, quota: backend.orgDeliveryQuota(), consumer });

package/dist/boot/reapers.d.ts

@@ -25,6 +25,7 @@ import type { FileHistoryErasureFace } from "../file-history-capture.js";
 import type { ApprovalNonceStore, CheckpointStoreFull, CostQuotaStore, ImageBake, RateLimiterStore, ServiceWorkflowJournalStore, StoreBackend, ToolResultStoreFull } from "../plugins/store-backend.js";
 import type { ToolApprovalCoordinator } from "../tool-approval.js";
 import type { ParkCommitWatch } from "../plugins/park-commit-watch.js";
+import { type SandboxPodReaper } from "../plugins/k8s-pod-reaper.js";
 import { type AuditRotationPort } from "../approval-ask-retention.js";
 /** [ref] / [ref]§五(sema-comms `audits/failopen-governance-176.md` §7 "Z 类 1 条"):default consecutive-failure
  *  count before a reaper leg's swallowed error gets a `warn` line. The ~15 `.catch(() => undefined)` sites
@@ -113,6 +114,8 @@ export interface ReapersCtx {
     approvalAskAudit: AuditRotationPort | undefined;
     /** 晚绑(server 造出来才有)——见文件头「位置即契约」①。 */
     getRunDenySweep: () => ((now: number) => Promise<void>) | undefined;
+    /** k8s 车道的沙箱 Pod reaper(`plugins/k8s-pod-reaper.ts`;第 5 段与 run 工厂同一份 k8s 配置铸)。缺席 = 非 k8s 车道 ⇒ 本腿零调用。 */
+    sandboxPodReaper?: SandboxPodReaper;
 }
 /** core 5.48 `reapDurableAgents` 的 `deps.sessions` 面(结构形,只列本仓要填的三格)。 */
 export interface ReapSessionsFacade {

package/dist/boot/reapers.js

@@ -4,6 +4,7 @@ import { CostQuota } from "../observability/cost-quota.js";
 import { isAdoptionQuiescing, trackMaintenanceLeg } from "../adoption/quiesce.js";
 import { createApprovalReconciler } from "../approval-reconciler.js";
 import { createE2bOrphanSandboxProvider, reclaimOrphanE2bSandboxes, E2B_ORPHAN_GRACE_MS } from "../plugins/e2b-orphan-reclaim.js";
+import { SANDBOX_POD_REAP_PERIOD_MS } from "../plugins/k8s-pod-reaper.js";
 import { APPROVAL_ASK_RETENTION_PASS_MS, runApprovalAskRetentionPass } from "../approval-ask-retention.js";
 export const REAPER_FAILURE_WARN_THRESHOLD = 5;
 export function createThrottledReaperCatch(name, logger, threshold = REAPER_FAILURE_WARN_THRESHOLD) {
@@ -57,7 +58,7 @@ export function createPlacementAwareReapSessions(deps) {
     };
 }
 export function startReapers(ctx) {
-    const { config, logger, metrics, localRoot, backend, subRunner, runStore, checkpointStore, parkCommits, rateLimiter, costQuota, toolResultStore, fileHistoryErasure, taskAttachmentStore, imageBakes, worktreeReap, workflowNotifyGate, workflowRecoverOpts, workflowJournalStore, sqlWorkflowRunStore, workflowNotifyJournal, rosterStore, backgroundAgentStore, mailboxStore, toolApproval, permissionRuleStores, approvalNonceStore, getRunDenySweep, userInputLedger, approvalAskAudit, } = ctx;
+    const { config, logger, metrics, localRoot, backend, subRunner, runStore, checkpointStore, parkCommits, rateLimiter, costQuota, toolResultStore, fileHistoryErasure, taskAttachmentStore, imageBakes, worktreeReap, workflowNotifyGate, workflowRecoverOpts, workflowJournalStore, sqlWorkflowRunStore, workflowNotifyJournal, rosterStore, backgroundAgentStore, mailboxStore, toolApproval, permissionRuleStores, approvalNonceStore, getRunDenySweep, userInputLedger, approvalAskAudit, sandboxPodReaper, } = ctx;
     const leg = (p) => {
         if (p !== undefined)
             trackMaintenanceLeg(p);
@@ -73,6 +74,8 @@ export function startReapers(ctx) {
         : undefined;
     let e2bOrphanLastRunMs = Date.now() - E2B_ORPHAN_GRACE_MS;
     let e2bOrphanInFlight = false;
+    let sandboxPodReapLastRunMs = Date.now() - SANDBOX_POD_REAP_PERIOD_MS;
+    let sandboxPodReapInFlight = false;
     let wfRunReapInFlight = false;
     let attachmentSweepInFlight = false;
     let bgAgentReapInFlight = false;
@@ -80,6 +83,7 @@ export function startReapers(ctx) {
     const probeClockSkewGuard = createThrottledReaperCatch("probe_clock_skew", logger);
     const runsReapStaleGuard = createThrottledReaperCatch("runs_reap_stale", logger);
     const e2bOrphanGuard = createThrottledReaperCatch("e2b_orphan_reclaim", logger);
+    const sandboxPodReapGuard = createThrottledReaperCatch("sandbox_pod_reap", logger);
     const checkpointsReapExpiredGuard = createThrottledReaperCatch("checkpoints_reap_expired", logger);
     const approvalNonceReapExpiredGuard = createThrottledReaperCatch("approval_nonce_reap_expired", logger);
     const runsFailSuspendedExpiredCheckpointGuard = createThrottledReaperCatch("runs_fail_suspended_expired_checkpoint", logger);
@@ -366,6 +370,16 @@ export function startReapers(ctx) {
                 e2bOrphanInFlight = false;
             }));
         }
+        if (sandboxPodReaper && Date.now() - sandboxPodReapLastRunMs >= SANDBOX_POD_REAP_PERIOD_MS && !sandboxPodReapInFlight) {
+            sandboxPodReapInFlight = true;
+            sandboxPodReapLastRunMs = Date.now();
+            leg(sandboxPodReaper
+                .reapOnce(runStore)
+                .then(() => sandboxPodReapGuard.onSuccess(), sandboxPodReapGuard.onError)
+                .finally(() => {
+                sandboxPodReapInFlight = false;
+            }));
+        }
     }, config.reapIntervalSec * 1000);
     reaper.unref?.();
     return reaper;

package/dist/boot/resolve-spec.d.ts

@@ -2,6 +2,7 @@ import { type MemoryBackend } from "@sema-agent/core";
 import { SessionEnvironmentSelection, selectEnvironmentTool } from "../capabilities/select-environment-tool.js";
 import { sendUserFileTool } from "../capabilities/send-user-file-tool.js";
 import { selectScenario } from "../capabilities/scenarios.js";
+import { type LoadedSkill } from "../capabilities/skills.js";
 import type { ServiceConfig } from "../config.js";
 import { type LiveQuestionFace } from "../deployment-governance.js";
 import { FleetEventBus } from "../fleet/fleet-bus.js";
@@ -17,6 +18,7 @@ import { type TaskAttachmentStore } from "../plugins/task-attachment-store.js";
 import { type createPrincipalEntitlementsClient } from "../runtime-caps-resolver.js";
 import { type OwnerAwareSessionStore } from "../security.js";
 import type { MemorySyncRunner } from "../memory-sync-client.js";
+import type { PeerDesk } from "../peer-seat.js";
 import type { RunnerDepsOnAsk } from "./runner-deps.js";
 type PrincipalCaps = ReturnType<typeof createPrincipalEntitlementsClient>;
 /** `resolveSpec` 原先从 `main()` 闭包里拿到的全部 boot 局部量。 */
@@ -83,6 +85,11 @@ export interface ResolveSpecCtx {
     /** [ref] 件C:本部署已校验的锁集(boot/governance-seams.ts 的产物,与 `RunnerDeps.lockedConfig`
      *  同源一次解析)。空集 = 无锁 = 现行为。本域只用它做**同步拒面**(§4.3),不做第二次裁决。 */
     lockedKeys: ReadonlySet<import("@sema-agent/core").LockedKey>;
+    /** 本进程的对端座 desk(stage-05 建、HTTP 服务的 `peerDesk` 同一只):请求面 MCP / A2A 的胜出草稿在 `opts.lease` 下经它登记,换回声明带的引用 —— 两只漏斗开的租约属于它。 */
+    peerDesk: PeerDesk;
+    /** 本部署**装载簿**(stage-07 的出厂技能 + 配置源覆盖之后的终表,场景工厂读的同一份)。本装配器只拿它答「场景交来的这只技能来自哪里」
+     *  (run 名册 `wiring_manifest.skills[].source`,`buildRunSkills`);名字在装载簿里唯一(装载器同名即抛、配置源按名覆盖)。 */
+    loadedSkills: readonly LoadedSkill[];
 }
 export declare function createResolveSpec(ctx: ResolveSpecCtx): ServiceDeps["resolveSpec"];
 export {};