@sema-agent/server 7.146.0 → 7.148.0

package/dist/boot/execution-env.js

@@ -1,11 +1,10 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { createHostLspManager } from "../host-lsp-manager.js";
+import { createLspManager } from "../host-lsp-manager.js";
 import { TaskEnvRegistry } from "../capabilities/sandbox-file-send.js";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
 import { SessionEnvironmentSelection } from "../capabilities/select-environment-tool.js";
 import { sandboxEnvNamesInForce } from "../config.js";
-import { createE2bLspManager } from "../lsp/e2b-manager.js";
 import { evictLspOnDestroy } from "../lsp-evict.js";
 import { PerTaskImageRegistry } from "../per-task-image.js";
 import { adbExecutionEnvFactory } from "../plugins/remote-env-adb.js";
@@ -17,15 +16,18 @@ import { boundedStoreCall, checkSandboxEgressPolicy, createSandboxPodApi, create
 import { podSpecPatchBrokerRefusal, SANDBOX_SECRET_SEAT_VERBS } from "../plugins/k8s-exec-protocol.js";
 import { createSandboxBrokerSeatOf, createSandboxGitPlaneSeat, sandboxGitPlanePremisesOf } from "../sandbox-git-plane.js";
 import { createSandboxPodReaper } from "../plugins/k8s-pod-reaper.js";
+import { createLocalDockerReaper } from "../plugins/local-docker-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";
+import { createLocalDockerCapacity, localDockerWorkerLabelOf } from "../plugins/local-docker-capacity.js";
 import { sshExecutionEnvFactory } from "../plugins/remote-env-ssh.js";
 import { withRemoteScratchpad } from "../plugins/remote-scratchpad.js";
 import { FileSchedulerBackend, defaultSchedulerStorePath } from "../plugins/scheduler-support.js";
 import * as facts from "../capability-facts.js";
 import { materializeAttachmentsInto } from "../plugins/task-attachment-store.js";
+import { createAttachmentMaterializingFactory } from "../execution-env-purpose.js";
 import { reapOrphanWorktrees, withWorktreeIsolation } from "../plugins/worktree-isolation.js";
 import { derivePkgSourceEnv } from "../sandbox-pkg-source.js";
 import { effectiveHostWorkspace } from "../task-cwd.js";
@@ -37,7 +39,7 @@ import { workspaceSnapshotTimeoutOf } from "../workspace-space.js";
 import { sayEgressPolicyReading } from "../sandbox-egress-policy.js";
 import { sandboxPathEnvSlots, withSandboxPathEnvSlot } from "./deferred-sandbox-path-env.js";
 import { createLaneHomeAbsenceReporter } from "../lane-home-probe.js";
-import { REMOTE_EXEC_PROVIDER_WORDS, buildLaneHomeBootNote, buildLaneHomeClaim, capabilitiesFor, executionLaneOf, laneBindsReads, laneIsolated, laneSandboxReadFloorState } from "../execution-lane-caps.js";
+import { buildLaneHomeBootNote, buildLaneHomeClaim, capabilitiesFor, laneIsolated, laneSandboxReadFloorState } from "../execution-lane-caps.js";
 import { warnReadDenyFloorUnkept } from "./execution-lane.js";
 import { seatText } from "../trace/exit-seat.js";
 import { countSessionResidentBackground } from "../session-resident-background.js";
@@ -64,11 +66,13 @@ export function createSessionScopedRegistries(maxEntries = MAX_CWD_SESSIONS) {
     const perSessionShellEnv = new Map();
     const perSessionInheritEnv = new Map();
     const owners = new Map();
+    const occupants = new Map();
     const dropSession = (sid) => {
         perSessionCwd.delete(sid);
         perSessionShellEnv.delete(sid);
         perSessionInheritEnv.delete(sid);
         owners.delete(sid);
+        occupants.delete(sid);
     };
     const touch = (sid, owner) => {
         const next = owner === undefined ? (owners.has(sid) ? owners.get(sid) : null) : owner;
@@ -98,8 +102,14 @@ export function createSessionScopedRegistries(maxEntries = MAX_CWD_SESSIONS) {
             perSessionInheritEnv.set(sid, policy);
             touch(sid, undefined);
         },
-        fenceSessionOwner: (sid, owner) => {
-            if (owners.has(sid) && owners.get(sid) !== owner) {
+        fenceSessionOwner: (sid, owner, incarnation) => {
+            const ownerChanged = owners.has(sid) && owners.get(sid) !== owner;
+            const occupantChanged = incarnation !== undefined && occupants.has(sid) && occupants.get(sid) !== incarnation;
+            if (incarnation === undefined)
+                occupants.delete(sid);
+            else
+                occupants.set(sid, incarnation);
+            if (ownerChanged || occupantChanged) {
                 perSessionCwd.delete(sid);
                 perSessionShellEnv.delete(sid);
                 perSessionInheritEnv.delete(sid);
@@ -107,6 +117,12 @@ export function createSessionScopedRegistries(maxEntries = MAX_CWD_SESSIONS) {
             touch(sid, owner);
         },
         dropSession,
+        dropSessionOf: (sid, incarnation) => {
+            if (occupants.get(sid) !== incarnation)
+                return false;
+            dropSession(sid);
+            return true;
+        },
     };
 }
 export function ownsItsWorkspace(ctx) {
@@ -220,14 +236,7 @@ function persistNeedsOccupant(persist) {
             return false;
     }
 }
-function buildRealSystemNote(remoteExec) {
-    if (!DEPLOYMENT_SHAPE_PREDICATES.singleMachineDefaultLane.holds({ remoteExec }))
-        return "non-isolated target — actions are permanent; rely on the policy gate + HITL (design/61 §5)";
-    const sandboxLanes = REMOTE_EXEC_PROVIDER_WORDS.filter((lane) => laneIsolated(lane)).join("|");
-    return ("hands run on this machine with no OS sandbox (single-machine default: REMOTE_EXEC unset, CONFIG_PROVIDER=local) — actions are permanent, " +
-        "and the Bash read boundary is a text-level friction floor, not a safety boundary; the safety boundary is a sandbox lane: " +
-        `set REMOTE_EXEC=${sandboxLanes} (see docs/DEPLOY-PREREQS.md, section "S-281")`);
-}
+const REAL_SYSTEM_NOTE = "non-isolated target — actions are permanent; rely on the policy gate + HITL (design/61 §5)";
 function hostWorktreeUnwrappedRefusal() {
     return Object.assign(new Error('isolation "worktree" was requested but cannot be honored: this host lane has no worktree wrapper active ' +
         "(WORKTREE_ISOLATION_ENABLED=true together with WORKTREE_REPO_ROOT=<a git repository> turns it on; a repo root that does not exist or has no `.git` leaves it off — see the boot log), " +
@@ -244,14 +253,18 @@ export function createExecutionEnv(ctx) {
     const { perSessionCwd, setSessionCwd } = sessionScoped;
     const { perSessionShellEnv, setSessionShellEnv } = sessionScoped;
     const { perSessionInheritEnv, setSessionInheritEnv } = sessionScoped;
+    const lspManager = createLspManager(config, (event, fields) => logger.info(event, fields));
+    if (lspManager)
+        logger.info("lsp_enabled", { provider: config.remoteExec.provider });
     let executionEnvFactory;
     let spaceReclaimer;
     let sandboxSecretSeatGate;
-    let sandboxPodReaper;
+    let sandboxReaper;
+    let sandboxCapacity;
     let sandboxGitPlane = createSandboxGitPlaneSeat((r) => sandboxGitPlanePremisesOf(config, r), {});
     let worktreeReap;
     const workspaceFillOf = taskAttachmentStore === undefined ? undefined : (fctx) => createWorkspaceFill({ store: taskAttachmentStore, sessionId: fctx.sessionId, seeds: ownsItsWorkspace(fctx), logger });
-    if (config.remoteExec?.provider === "e2b") {
+    if (config.remoteExec.provider === "e2b") {
         executionEnvFactory = e2bExecutionEnvFactory({
             apiKey: config.remoteExec.apiKey,
             ...homeDirSeat, ...homeAbsentNotice,
@@ -267,7 +280,7 @@ export function createExecutionEnv(ctx) {
             metrics,
         }, ctx.laneDeps?.e2b);
     }
-    else if (config.remoteExec?.provider === "k8s") {
+    else if (config.remoteExec.provider === "k8s") {
         const k8sCfg = {
             image: config.remoteExec.image,
             ...homeDirSeat, ...homeAbsentNotice,
@@ -305,12 +318,12 @@ export function createExecutionEnv(ctx) {
         if (k8sCfg.cache !== undefined || k8sCfg.s3Snapshot !== undefined)
             spaceReclaimer = createSpaceReclaimer(k8sCfg);
         sandboxSecretSeatGate = () => ensureSandboxSecretSeat(k8sCfg, logger, undefined, () => readSandboxSecretSeat(k8sCfg, "env"));
-        sandboxPodReaper = createSandboxPodReaper({ api: createSandboxPodApi(k8sCfg), logger, metrics });
+        sandboxReaper = createSandboxPodReaper({ api: createSandboxPodApi(k8sCfg), logger, metrics });
         void checkSandboxEgressPolicy(k8sCfg)
             .then((gaps) => sayEgressPolicyReading(gaps, logger, k8sCfg.namespace))
             .catch((e) => logger.error("sandbox_egress_policy_check_crashed", { error: seatText("operator-log-text", 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" }));
     }
-    else if (config.remoteExec?.provider === "ssh") {
+    else if (config.remoteExec.provider === "ssh") {
         executionEnvFactory = sshExecutionEnvFactory({
             host: config.remoteExec.host,
             username: config.remoteExec.username,
@@ -319,9 +332,10 @@ export function createExecutionEnv(ctx) {
             ...(config.remoteExec.port != null ? { port: config.remoteExec.port } : {}),
             ...(config.remoteExec.mountPath ? { mountPath: config.remoteExec.mountPath } : {}),
             ...(config.remoteExec.hostKey !== undefined ? { hostKey: config.remoteExec.hostKey } : {}),
+            logger,
         });
     }
-    else if (config.remoteExec?.provider === "device") {
+    else if (config.remoteExec.provider === "device") {
         if (ctx.deviceLane) {
             executionEnvFactory = deviceExecutionEnvFactory({
                 hub: ctx.deviceLane.hub,
@@ -336,21 +350,23 @@ export function createExecutionEnv(ctx) {
             });
         }
     }
-    else if (config.remoteExec?.provider === "adb") {
+    else if (config.remoteExec.provider === "adb") {
         executionEnvFactory = adbExecutionEnvFactory({
             serial: config.remoteExec.serial,
             ...homeDirSeat, ...homeAbsentNotice,
             ...(config.remoteExec.adbPath ? { adbPath: config.remoteExec.adbPath } : {}),
             ...(config.remoteExec.mountPath ? { mountPath: config.remoteExec.mountPath } : {}),
+            logger,
         });
     }
-    else if (config.remoteExec?.provider === "host") {
+    else if (config.remoteExec.provider === "host") {
         {
             const schedulerStorePath = config.schedulerStorePath ?? defaultSchedulerStorePath(config);
             const hostScheduler = facts.hostScheduler(config).available
                 ? new FileSchedulerBackend({
                     storePath: schedulerStorePath,
                     log: logger,
+                    trust: { declaredOwnerUid: config.configLocalOwnerUid },
                     ...(config.schedulerSessionWakeup === false || config.schedulerSessionLifetime === false
                         ? {
                             caps: {
@@ -386,9 +402,12 @@ export function createExecutionEnv(ctx) {
             };
         }
     }
-    else if (config.remoteExec?.provider === "local-docker") {
-        executionEnvFactory = localDockerExecutionEnvFactory({
+    else if (config.remoteExec.provider === "local-docker") {
+        const workerLabel = localDockerWorkerLabelOf(config.localDataRoot);
+        sandboxCapacity = config.remoteExec.capacity !== undefined ? createLocalDockerCapacity(config.remoteExec.capacity, { label: workerLabel, logger }) : undefined;
+        const localDockerFactory = localDockerExecutionEnvFactory({
             image: config.remoteExec.image,
+            workerLabel,
             ...(config.remoteExec.mountPath ? { mountPath: config.remoteExec.mountPath } : {}),
             ...homeDirSeat, ...homeAbsentNotice,
             ...(config.remoteExec.dockerPath ? { dockerPath: config.remoteExec.dockerPath } : {}),
@@ -402,7 +421,11 @@ export function createExecutionEnv(ctx) {
             ...(config.remoteExec.env ? { env: config.remoteExec.env } : {}),
             sandboxReadFloor: config.sandboxReadFloor,
             ...(workspaceFillOf !== undefined ? { workspaceFillOf } : {}),
+            ...(sandboxCapacity !== undefined ? { capacity: sandboxCapacity } : {}),
+            logger,
         }, ctx.laneDeps?.localDocker);
+        executionEnvFactory = localDockerFactory;
+        sandboxReaper = createLocalDockerReaper({ port: localDockerFactory.reapPort, logger, metrics, ...(ctx.laneDeps?.localDockerReapNow !== undefined ? { now: ctx.laneDeps.localDockerReapNow } : {}) });
     }
     if (executionEnvFactory && DEPLOYMENT_SHAPE_PREDICATES.remoteScratchpad.holds(config)) {
         executionEnvFactory = withRemoteScratchpad(executionEnvFactory, logger);
@@ -410,15 +433,15 @@ export function createExecutionEnv(ctx) {
     if (config.worktreeIsolation && executionEnvFactory) {
         const wtRoot = config.worktreeIsolation.repoRoot;
         const wtValid = existsSync(wtRoot) && existsSync(join(wtRoot, ".git"));
-        if (config.remoteExec?.provider === "host" && !wtValid) {
+        if (config.remoteExec.provider === "host" && !wtValid) {
             logger.error("worktree_isolation_disabled_bad_repo_root", {
                 repoRoot: wtRoot,
                 reason: existsSync(wtRoot) ? "not a git repository (no .git)" : "path does not exist",
                 note: "WORKTREE_ISOLATION_ENABLED is set but WORKTREE_REPO_ROOT is not a usable git repo — isolation left OFF; isolation:'worktree' workflow agents are refused (isolation.unavailable) until it is fixed. Fix the path or unset the flag.",
             });
         }
-        else if (config.remoteExec?.provider === "host") {
-            const gitBaseEnv = new RemoteHostExecutionEnv({ workspaceDir: config.worktreeIsolation.repoRoot, inheritEnv: "all", backgroundShell: config.requirePrincipal !== true });
+        else if (config.remoteExec.provider === "host") {
+            const gitBaseEnv = new RemoteHostExecutionEnv({ workspaceDir: config.worktreeIsolation.repoRoot, inheritEnv: "all", backgroundShell: config.requirePrincipal !== true, gitBase: true });
             executionEnvFactory = withWorktreeIsolation(executionEnvFactory, {
                 repoRoot: config.worktreeIsolation.repoRoot,
                 ...(config.worktreeIsolation.allowedRoots ? { allowedRoots: config.worktreeIsolation.allowedRoots } : {}),
@@ -444,7 +467,7 @@ export function createExecutionEnv(ctx) {
         }
         else {
             logger.warn("worktree_isolation_unsupported_lane", {
-                provider: config.remoteExec?.provider,
+                provider: config.remoteExec.provider,
                 note: "git-worktree isolation v1 covers only the 'host' lane — isolation:'worktree' is a no-op here (the base env is used). Worktree-rooted remote envs are a follow-on.",
             });
         }
@@ -456,59 +479,32 @@ export function createExecutionEnv(ctx) {
         executionEnvFactory = registry.wrapFactory(executionEnvFactory);
         return registry;
     })();
-    if (taskAttachmentStore && executionEnvFactory && !laneIsolated(executionLaneOf(config.remoteExec.provider))) {
-        const inner = executionEnvFactory;
+    if (taskAttachmentStore && executionEnvFactory && !laneIsolated(config.remoteExec.provider)) {
         const attStore = taskAttachmentStore;
-        executionEnvFactory = async (ctx) => {
-            const env = await inner(ctx);
-            const n = await materializeAttachmentsInto(env, attStore, ctx.sessionId);
-            if (n > 0)
-                logger.info("attachments_materialized", { sessionId: ctx.sessionId, count: n });
-            return env;
-        };
+        executionEnvFactory = createAttachmentMaterializingFactory(executionEnvFactory, (env, ctx) => materializeAttachmentsInto(env, attStore, ctx.sessionId), (sessionId, count) => logger.info("attachments_materialized", { sessionId, count }));
     }
     if (executionEnvFactory && DEPLOYMENT_SHAPE_PREDICATES.sandboxPathAdjudication.holds(config)) {
         executionEnvFactory = withSandboxPathEnvSlot(executionEnvFactory, sandboxPathEnvSlots, logger);
     }
     if (executionEnvFactory) {
-        const isolated = laneIsolated(executionLaneOf(config.remoteExec.provider));
+        const isolated = laneIsolated(config.remoteExec.provider);
         const suspendable = DEPLOYMENT_SHAPE_PREDICATES.suspendableHands.holds(config);
         const keepsReadFloor = capabilitiesFor(config).keepsReadFloor;
         const sandboxReadFloor = laneSandboxReadFloorState(config);
         const sandboxEnvKeys = [...sandboxEnvNamesInForce(config)].sort();
         logger.info("remote_exec_enabled", { provider: config.remoteExec.provider, isolated, suspendable, keepsReadFloor, ...(sandboxReadFloor !== undefined ? { sandboxReadFloor } : {}), ...(sandboxEnvKeys.length > 0 ? { sandboxEnvKeys } : {}) });
         if (!isolated)
-            logger.warn("remote_exec_real_system", { provider: config.remoteExec.provider, note: buildRealSystemNote(config.remoteExec) });
+            logger.warn("remote_exec_real_system", { provider: config.remoteExec.provider, note: REAL_SYSTEM_NOTE });
         const homeLine = buildLaneHomeBootNote(config);
         if (homeLine !== undefined)
             logger.warn(homeLine.event, { provider: config.remoteExec.provider, note: homeLine.note });
-        if (executionLaneOf(config.remoteExec.provider) === "host")
+        if (config.remoteExec.provider === "host")
             logger.info("task_inherit_env_honored", { honored: taskInheritEnvRefusal(config) === undefined });
     }
     warnReadDenyFloorUnkept(config, logger);
-    const lspProvider = config.remoteExec?.provider;
-    const lspLane = executionLaneOf(lspProvider);
-    const lspLaneBindsReads = lspLane !== undefined && laneBindsReads(lspLane);
-    if ((lspProvider === "e2b" || lspProvider === "k8s") && config.lspEnabled && !lspLaneBindsReads) {
-        logger.warn("lsp_not_mounted", {
-            provider: lspProvider,
-            reason: "LSP_ENABLED is set, but this lane's execution environment cannot bind a read to the file that was checked (openBound), so every language-server file sync would be refused; the LSP tool is not mounted on this lane in this version",
-        });
-    }
-    const lspManager = (lspProvider === "e2b" || lspProvider === "k8s") && config.lspEnabled && lspLaneBindsReads
-        ? createE2bLspManager({
-            log: (event, fields) => logger.info(event, fields),
-            scheme: lspProvider === "k8s" ? "ws" : "wss",
-            provider: lspProvider,
-            metrics,
-        })
-        :
-            lspProvider === "host" && config.lspHostEnabled && config.requirePrincipal !== true && lspLaneBindsReads
-                ? createHostLspManager(config, (event, fields) => logger.info(event, fields))
-                : undefined;
-    if (lspManager)
-        logger.info("lsp_enabled", { provider: lspProvider });
     const unreadableReported = new Set();
+    let stallReapFailureReported = false;
+    const stallMs = config.backgroundAgentStallMs;
     const sessionResidentBackground = () => countSessionResidentBackground(sessionScoped.sessionOwners, {
         onUnreadable: (sessionId, err) => {
             if (unreadableReported.has(sessionId))
@@ -516,13 +512,35 @@ export function createExecutionEnv(ctx) {
             unreadableReported.add(sessionId);
             logger.warn("session_resident_background_unreadable", { sessionId, counted: 1, err: seatText("operator-log-text", String(err)) });
         },
+        stall: {
+            stallMs,
+            report: (outcome) => {
+                switch (outcome.kind) {
+                    case "reaped":
+                        logger.warn("background_agent_stall_reaped", { reaped: outcome.count, stallMs });
+                        return;
+                    case "failed":
+                        if (stallReapFailureReported)
+                            return;
+                        stallReapFailureReported = true;
+                        logger.warn("background_agent_stall_reap_failed", { stallMs, err: seatText("operator-log-text", String(outcome.err)) });
+                        return;
+                    default: {
+                        const unhandled = outcome;
+                        throw new Error(`background agent stall reap: unknown outcome ${String(unhandled)}`);
+                    }
+                }
+            },
+        },
     });
     return {
         perTaskImage, sessionEnvSelection, perSessionCwd, setSessionCwd, setSessionShellEnv, setSessionInheritEnv,
         fenceSessionOwner: sessionScoped.fenceSessionOwner,
         dropSessionScoped: sessionScoped.dropSession,
+        dropSessionScopedOf: sessionScoped.dropSessionOf,
         sessionResidentBackground,
-        executionEnvFactory, worktreeReap, sendUserFileTaskEnvs, lspManager, spaceReclaimer, sandboxSecretSeatGate, sandboxPodReaper, sandboxGitPlane,
+        executionEnvFactory, worktreeReap, sendUserFileTaskEnvs, lspManager, spaceReclaimer, sandboxSecretSeatGate, sandboxReaper, sandboxGitPlane,
+        sandboxCapacity,
     };
 }
 //# sourceMappingURL=execution-env.js.map

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

@@ -1,10 +1,31 @@
 import { type CrossInvariantView } from "../config-invariants.js";
-import type { ServiceConfig } from "../config-types.js";
-import { buildReadDenyFloorUnkeptNote } from "../execution-lane-caps.js";
+import type { LoadedConfig, ServiceConfig } from "../config-types.js";
+import { type EntryDeclarableLane } from "../config.js";
+import { buildReadDenyFloorUnkeptNote, type ExecutionLane } from "../execution-lane-caps.js";
 import type { Logger } from "../observability/logger.js";
-/** `config.d/remote-exec.json` 能写进来的车道(文件契约里不带密钥名、可 1:1 映射的两条;e2b/k8s/ssh/adb 要 NAME→值解析,尚未接线)。 */
-export declare const FILE_SOURCED_LANES: readonly ["host", "local-docker"];
+/** `config.d/remote-exec.json` 能写进来的车道(文件契约里不带密钥名、可 1:1 映射的三条 —— `none` 零字段;e2b/k8s/ssh/adb 要 NAME→值解析,尚未接线)。 */
+export declare const FILE_SOURCED_LANES: readonly ["host", "local-docker", "none"];
 export type FileSourcedLane = (typeof FILE_SOURCED_LANES)[number];
+/** 判点的拒句(一行;两条照旧行为的修法逐字在句中:7.146.0 非 local 未设 ⇒ `REMOTE_EXEC=none`,local 未设 ⇒ `REMOTE_EXEC=host`)。
+ *  车道词取自车道表(隔离与否读能力表的唯一布尔口 `laneIsolated`),不手抄清单。 */
+export declare const EXECUTION_LANE_UNDECLARED_REFUSAL: string;
+/**
+ * 一个**入口程序**(装配者)对车道说的两句话 —— 合成步对它们只有一条律:声明的先后 = 文件 > env > 入口自身,**在场的最高者终结选择**(文件在场 ⇒ 车道就是文件那一条,
+ * 解析不了即拒,不许 env / 入口顶上;文件缺席 ⇒ env;二者都缺席 ⇒ 入口自身);最终车道必须是入口跑得了的,否则拒(起任何任务之前)。
+ */
+export interface ExecutionLaneEntry {
+    /** 拒句点名的入口(`run-local` / `the HTTP service` …)。 */
+    readonly name: string;
+    /**
+     * 本入口跑得了的车道(闭集;HTTP 服务 = 全部八条,`run-local` = host 与 none —— 它没有容器 / 远程执行器,`none` 不要执行器)。
+     * 能从 `config.d/remote-exec.json` 取的 = 它 ∩ {@link FILE_SOURCED_LANES}(隔离车道 e2b / k8s / ssh / adb 要 NAME→值解析,文件腿尚未接线)。
+     */
+    readonly runs: readonly ExecutionLane[];
+    /** 入口自身的声明(入口 = 部署者,如 run-local ⇒ `host`):文件与 env 都没点名时才填,排在二者之后;缺席 = 本入口不替部署声明。不写进程 env。 */
+    readonly declares?: EntryDeclarableLane;
+}
+/** HTTP 服务这只入口:跑得了全部车道、不替部署声明(它的部署者是运维:声明只来自 env / 文件)。 */
+export declare const HTTP_SERVICE_LANE_ENTRY: ExecutionLaneEntry;
 export interface ExecutionLaneComposeCtx {
     /** 本入口的配置源形态(`configSourceKind` 的答案 —— 与它真建的 provider 同一只判据)。
      *  只有 `local` 才读文件;`undefined` = 纯 env 部署。 */
@@ -12,12 +33,19 @@ export interface ExecutionLaneComposeCtx {
     /** 配置根(与配置源同一个根,不分裂)。 */
     readonly localRoot: string;
     readonly logger: Logger;
-    /** 本入口**驱动得了**的文件车道。HTTP 服务两条都驱动;`run-local` 只驱动 host(它没有容器执行器)—— 文件写了本入口
-     *  驱动不了的车道 ⇒ 不写进 config,落「未接线」告警,env 腿的车道照旧(与 e2b/k8s/ssh/adb 的文件表态同一臂)。 */
-    readonly drivesFromFile: readonly FileSourcedLane[];
+    /** 装配这台部署的入口程序(跑得了哪些车道、自己声明哪一条)。 */
+    readonly entry: ExecutionLaneEntry;
 }
-/** 合成 + 判。覆写就地改写 `config.remoteExec`;坏文件 / 不变量不过 ⇒ 抛(拒启)。 */
-export declare function composeExecutionLane(config: ServiceConfig, ctx: ExecutionLaneComposeCtx): Promise<void>;
+/**
+ * 合成 + 判:raw 配置 → composed 配置(**同一个对象**就地覆写并收窄型,交回给装配链往下传)。没有声明 / 坏文件 / 不变量不过 ⇒ 抛(拒启)。
+ */
+export declare function composeExecutionLane(loaded: LoadedConfig, ctx: ExecutionLaneComposeCtx): Promise<ServiceConfig>;
+/**
+ * 合成步的**同步尾**(文件覆写之后的一切,恰此一份):入口声明补缺席位 → 入口跑不跑得了 → 判点 → 读面按最终车道派生 + 恰一行通告 → 车道交叉不变量 →
+ * `exec_lane_selected {lane}`。{@link composeExecutionLane} 在文件腿之后调它;没有文件腿的纯 env 形(`bench`、测试夹具)直接调它 —— 同一份合成,不是第二个判官。
+ * `entry` 缺席 = 这次装配没有入口程序替部署说话(嵌入方 / 脚本:车道只来自 env,跑得了的不设限)。
+ */
+export declare function composeDeclaredExecutionLane(loaded: LoadedConfig, logger: Pick<Logger, "info">, entry?: ExecutionLaneEntry): ServiceConfig;
 /**
  * **宿主车道的 shell 起服解析**(一次)—— 宿主车道(`provider === "host"`)的命令用本机 shell 起(win32 = Git Bash),起服时把它解析落定,
  * 找不到就在这里响亮地说一次(`warn host_shell_unavailable { err, remedy }`),而不是等第一个用户的第一条 Bash 撞上。

package/dist/boot/execution-lane.js

@@ -1,16 +1,62 @@
 import { loadRemoteExec } from "@sema-agent/settings-schema/node";
 import { assertLocalConfigDirTrusted } from "../config-dir-trust.js";
 import { crossInvariant } from "../config-invariants.js";
-import { buildReadDenyFloorUnkeptNote, executionLaneOf, laneIsolated } from "../execution-lane-caps.js";
+import { entryDeclarableRemoteExec } from "../config.js";
+import { ALL_EXECUTION_LANES, buildReadDenyFloorUnkeptNote, laneIsolated, laneWiresExecutionEnv } from "../execution-lane-caps.js";
 import { buildReadFacePostureNotice, settleDerivedReadFace } from "../read-face-posture.js";
 import { settleHostShellAtBoot } from "../plugins/host-platform.js";
 import { seatText } from "../trace/exit-seat.js";
-export const FILE_SOURCED_LANES = ["host", "local-docker"];
-export async function composeExecutionLane(config, ctx) {
+export const FILE_SOURCED_LANES = ["host", "local-docker", "none"];
+export const EXECUTION_LANE_UNDECLARED_REFUSAL = (() => {
+    const sandboxLanes = ALL_EXECUTION_LANES.filter((lane) => laneIsolated(lane));
+    const otherHandLanes = ALL_EXECUTION_LANES.filter((lane) => lane !== "host" && laneWiresExecutionEnv(lane) && !laneIsolated(lane));
+    return ("No execution lane is declared — every deployment names its execution lane: set REMOTE_EXEC (with CONFIG_PROVIDER=local, config.d/remote-exec.json also declares it). " +
+        "To keep what this deployment did before 7.147.0: REMOTE_EXEC=none when CONFIG_PROVIDER is not \"local\" (no execution environment — the agent's tool hands never mount), " +
+        "REMOTE_EXEC=host when CONFIG_PROVIDER=local (tools run directly on this machine with no OS sandbox). " +
+        `Or name a sandbox lane (${sandboxLanes.join(" | ")}) or ${otherHandLanes.join(" | ")} with that lane's required env. ` +
+        "CONFIG_PROVIDER only selects where configuration is read from; it does not select an execution lane.");
+})();
+export const HTTP_SERVICE_LANE_ENTRY = { name: "the HTTP service", runs: ALL_EXECUTION_LANES };
+function entryCannotRunLaneRefusal(entry, lane, source) {
+    return (`${source} declares the execution lane "${lane}", but ${entry.name} runs only ${entry.runs.join(" / ")} — it has no executor for "${lane}". ` +
+        `Refusing before any task starts rather than run on another lane: declare a lane ${entry.name} runs, or serve "${lane}" from an entry that runs it (the HTTP service runs every lane).`);
+}
+function fileLaneUnresolvableRefusal(entry, lane, envReading, root) {
+    return (`config.d/remote-exec.json under ${root} declares the execution lane "${lane}", but ${entry.name} reads "${lane}"'s coordinates only from REMOTE_EXEC env ` +
+        `(file-source name→value resolution is not wired yet), and ${envReading}. The file's declaration ends the lane selection: no other declaration may stand in for it. ` +
+        `Refusing before any task starts: set REMOTE_EXEC=${lane} with that lane's required env, or change the file to the lane you mean.`);
+}
+export async function composeExecutionLane(loaded, ctx) {
     if (ctx.configSource === "local")
-        await applyRemoteExecFile(config, ctx);
-    settleReadFaceForFinalLane(config, ctx.logger);
+        await applyRemoteExecFile(loaded, ctx);
+    return composeDeclaredExecutionLane(loaded, ctx.logger, ctx.entry);
+}
+export function composeDeclaredExecutionLane(loaded, logger, entry) {
+    if (entry !== undefined)
+        settleEntryLane(loaded, entry);
+    const config = requireDeclaredExecutionLane(loaded);
+    settleReadFaceForFinalLane(config, logger);
     assertExecutionLaneInvariants(config);
+    logger.info("exec_lane_selected", { lane: config.remoteExec.provider });
+    return config;
+}
+function requireDeclaredExecutionLane(loaded) {
+    if (!isComposed(loaded))
+        throw new Error(EXECUTION_LANE_UNDECLARED_REFUSAL);
+    return loaded;
+}
+function settleEntryLane(loaded, entry) {
+    const declaredByEntry = !isComposed(loaded) ? entry.declares : undefined;
+    if (declaredByEntry !== undefined)
+        loaded.remoteExec = entryDeclarableRemoteExec(declaredByEntry);
+    if (!isComposed(loaded))
+        return;
+    const lane = loaded.remoteExec.provider;
+    if (!entry.runs.includes(lane))
+        throw new Error(entryCannotRunLaneRefusal(entry, lane, declaredByEntry !== undefined ? `${entry.name} itself` : `REMOTE_EXEC=${lane}`));
+}
+function isComposed(config) {
+    return config.remoteExec !== undefined;
 }
 function settleReadFaceForFinalLane(config, logger) {
     if (!settleDerivedReadFace(config, config.requirePrincipal !== true))
@@ -20,14 +66,14 @@ function settleReadFaceForFinalLane(config, logger) {
         logger.info(notice.event, notice.fields);
 }
 export async function settleHostLaneShell(config, logger) {
-    if (config.remoteExec?.provider !== "host")
+    if (config.remoteExec.provider !== "host")
         return;
     await settleHostShellAtBoot(logger);
 }
 export function warnReadDenyFloorUnkept(config, logger) {
     const note = buildReadDenyFloorUnkeptNote(config);
     if (note !== undefined)
-        logger.warn("read_deny_floor_required_unkept", { provider: config.remoteExec?.provider, note });
+        logger.warn("read_deny_floor_required_unkept", { provider: config.remoteExec.provider, note });
 }
 export function assertExecutionLaneInvariants(config) {
     const judge = (id) => crossInvariant(id).check({ live: config, next: config });
@@ -61,11 +107,12 @@ async function applyRemoteExecFile(config, ctx) {
     }
     if (!fileRx)
         return;
-    const preemptedLane = executionLaneOf(config.remoteExec?.provider);
-    const disclosePreemption = (winner) => {
+    const envDeclared = config.remoteExec?.provider;
+    const disclosePreemption = envDeclared === undefined ? (_winner) => { } : (winner) => {
+        const preemptedLane = envDeclared;
         if (winner === preemptedLane)
             return;
-        const downgrade = laneIsolated(preemptedLane) && !laneIsolated(winner);
+        const downgrade = laneIsolated(preemptedLane) && laneWiresExecutionEnv(winner) && !laneIsolated(winner);
         logger.warn("remote_exec_lane_preempted_by_file", {
             preemptedLane,
             effectiveLane: winner,
@@ -76,7 +123,7 @@ async function applyRemoteExecFile(config, ctx) {
                 (downgrade ? `. This is an ISOLATION DOWNGRADE: tasks run on a non-isolated target. Delete/fix the file, or unset the lane env if the file is the intended source.` : `. Delete/fix the file, or unset the lane env if the file is the intended source.`),
         });
     };
-    const drives = (lane) => ctx.drivesFromFile.includes(lane);
+    const drives = (lane) => ctx.entry.runs.includes(lane);
     if (fileRx.provider === "host" && drives("host")) {
         config.remoteExec = {
             provider: "host",
@@ -100,18 +147,25 @@ async function applyRemoteExecFile(config, ctx) {
         logger.info("remote_exec_from_file", { provider: "local-docker", root: localRoot, image: fileRx.image });
         return;
     }
+    if (fileRx.provider === "none" && drives("none")) {
+        config.remoteExec = { provider: "none" };
+        disclosePreemption("none");
+        logger.info("remote_exec_from_file", { provider: "none", root: localRoot });
+        return;
+    }
     const fileLane = fileRx.provider;
-    const sourceable = FILE_SOURCED_LANES.some((lane) => lane === fileLane);
+    if (!ctx.entry.runs.includes(fileLane))
+        throw new Error(entryCannotRunLaneRefusal(ctx.entry, fileLane, `config.d/remote-exec.json under ${localRoot}`));
+    if (envDeclared !== fileLane) {
+        const envReading = envDeclared === undefined ? "REMOTE_EXEC is not set" : `REMOTE_EXEC declares "${envDeclared}"`;
+        throw new Error(fileLaneUnresolvableRefusal(ctx.entry, fileLane, envReading, localRoot));
+    }
     logger.warn("remote_exec_file_isolated_lane_unwired", {
         provider: fileLane,
-        effectiveLane: preemptedLane,
-        reason: sourceable ? "entry-has-no-executor" : "needs-name-resolution",
-        note: sourceable
-            ? `config.d/remote-exec.json names "${fileLane}", but this entry has no executor for it (it drives ${ctx.drivesFromFile.join(" / ")} ` +
-                `from the file; the HTTP service drives ${FILE_SOURCED_LANES.join(" / ")}) — the env-derived lane above stays in force`
-            : `this entry drives ${ctx.drivesFromFile.join(" / ")} from config.d/remote-exec.json; "${fileLane}" (like the other isolated lanes ` +
-                `e2b / k8s / ssh / adb) is sourced from REMOTE_EXEC env until file-source NAME→value resolution lands (center field map) — the ` +
-                `env-derived lane above stays in force`,
+        reason: "needs-name-resolution",
+        note: `config.d/remote-exec.json and REMOTE_EXEC both declare "${fileLane}": this entry takes ${FILE_SOURCED_LANES.filter((lane) => ctx.entry.runs.includes(lane)).join(" / ")} ` +
+            `from the file; "${fileLane}" (like the other isolated lanes e2b / k8s / ssh / adb) takes its coordinates from REMOTE_EXEC env until file-source NAME→value ` +
+            `resolution lands (center field map) — the coordinates written in the file for it are not read`,
     });
 }
 //# sourceMappingURL=execution-lane.js.map

package/dist/boot/exit-boundary.d.ts

@@ -24,20 +24,20 @@
  * 不是退出边界)。
  */
 import { type TaskRegistry } from "@sema-agent/core";
-import type { Logger } from "../observability/logger.js";
+import { type Logger } from "../observability/logger.js";
 /**
  * 退出边界的硬收面**此刻**会收掉的后台 shell 行数(`background_bash` + `monitor`,在跑,整张进程级注册表,retain 行按
  * {@link PROCESS_EXIT_INCLUDES_RETAINED} 跳过)—— 「引擎现在退,会不会把一条在跑的后台 shell 一起收掉」这一问的**唯一**读法。
  *
  * 一问一源:数与收读同一只 `includeRetained` 常量,core 的 `countRunningBackgroundShells` 与 `killAllBackgroundShellsNow` 又按同一只访问函数选行
  * (core 注:the count and the walk cannot drift)⇒ 这只数就是硬收面会交出的 `killed` 收据数。
- * **不是** `/health.inflightBreakdown.sessionResident`(`session-resident-background.ts`):那一项回答「引擎托管着多少会话驻留的活」,是总数里的一个分项 ——
+ * **不是** `/health.inflightBreakdown.sessionResident`(`session-resident-background.ts`):那一项回答「引擎托管着多少会话驻留的 shell / monitor」,是总数里的一个分项 ——
  * 只数围栏表里会话的、会话驻留的行(挂在 run 腿上的行算在 http 项里,数它是第二次;围栏外的会话它看不见);本函数整表数、不分会话,
  * 腿上的行、围栏外会话的行都在内。两问的关系 = 读得出时本数 ≥ 驻留项(驻留项的每一行都是本数的一行)。
  *
  * 读不出(core:某行 env 的 retain 声明读抛 ⇒ 计数抛)⇒ 按 **1** 计并经 `onUnreadable` 报出 —— 读不出 ⇒ 非空闲,与驻留项同一条律;
  * 本函数在租约拍(定时器回调)、`/health` 与交接口里被调,**不许抛**(定时器里一抛就是 uncaught,一台交接出去的引擎会因此崩掉并收掉它本该留着的 shell)——
- * 报口自己再抛(抛出物转不成文本之类)也一样:落 `console.error`(不回同一只报口),读数照返 1。
+ * 报口自己再抛(抛出物转不成文本之类)也一样:落日志出口接缝的文本出口 `writeLogText`(不回同一只报口),读数照返 1。
  * `registry` 只供测试换桩(只用到 `countRunningBackgroundShells`)。
  */
 export declare function countShellsExitWouldKill(opts: {

package/dist/boot/exit-boundary.js

@@ -1,5 +1,6 @@
 import { defaultTaskRegistry } from "@sema-agent/core";
 import { reportHardKillReceipts } from "../background-session-reap.js";
+import { writeLogText } from "../observability/logger.js";
 import { liveHostForegroundChildCount, reapHostForegroundChildren } from "../plugins/host-platform.js";
 import { liveEphemeralHostWorkspaceCount, reapEphemeralHostWorkspaces } from "../plugins/host-workspace-registry.js";
 import { seatText } from "../trace/exit-seat.js";
@@ -14,7 +15,7 @@ export function countShellsExitWouldKill(opts) {
             opts.onUnreadable(err);
         }
         catch (reportErr) {
-            console.error("engine_handover_shell_count_report_threw", reportErr);
+            writeLogText("stderr", "engine_handover_shell_count_report_threw", reportErr);
         }
         return 1;
     }
@@ -70,19 +71,19 @@ export function installProcessExitBoundary({ logger }) {
             reapOwnChildProcesses();
         }
         catch (err) {
-            console.error("shutdown_exit_boundary_child_reap_threw", err);
+            writeLogText("stderr", "shutdown_exit_boundary_child_reap_threw", err);
         }
         try {
             reapBackgroundHard();
         }
         catch (err) {
-            console.error("shutdown_exit_boundary_background_hard_kill_threw", err);
+            writeLogText("stderr", "shutdown_exit_boundary_background_hard_kill_threw", err);
         }
         try {
             reapOwnHostWorkspaces();
         }
         catch (err) {
-            console.error("shutdown_exit_boundary_workspace_reap_threw", err);
+            writeLogText("stderr", "shutdown_exit_boundary_workspace_reap_threw", err);
         }
         const left = { foregroundChildren: liveHostForegroundChildCount(), hostWorkspaces: liveEphemeralHostWorkspaceCount() };
         try {
@@ -91,7 +92,7 @@ export function installProcessExitBoundary({ logger }) {
                 logger.warn("shutdown_exit_boundary_incomplete", left);
         }
         catch (err) {
-            console.error("shutdown_exit_boundary_log_threw", err);
+            writeLogText("stderr", "shutdown_exit_boundary_log_threw", err);
         }
     };
     process.once("exit", onProcessExit);

package/dist/boot/exit-last.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { ENGINE_LANES } from "./engine-lease.js";
+import { OWNER_ONLY_FILE_MODE } from "../plugins/owner-only-file-mode.js";
 export const EXIT_LAST_FORMAT = 3;
 const ExitLastSchema = z.object({
     format: z.literal(EXIT_LAST_FORMAT),
@@ -22,7 +23,7 @@ export function exitLastPath(dataRoot) {
 export function writeExitLast(dataRoot, info) {
     try {
         const body = { format: EXIT_LAST_FORMAT, at: new Date().toISOString(), pid: process.pid, ...info };
-        writeFileSync(exitLastPath(dataRoot), JSON.stringify(body) + "\n");
+        writeFileSync(exitLastPath(dataRoot), JSON.stringify(body) + "\n", { mode: OWNER_ONLY_FILE_MODE });
     }
     catch {
     }