@sema-agent/server 7.145.0 → 7.147.0

package/dist/boot/engine-lease.js

@@ -1,20 +1,86 @@
 export const ENGINE_LEASE_TICK_MS = 15_000;
+export const ENGINE_LANES = ["handover", "orphan", "awaitingFirstAttach", "owned"];
+export const ENGINE_LANE_TABLE = Object.freeze({
+    handover: { countsBackgroundShells: true, sighupYieldsToLease: true },
+    orphan: { countsBackgroundShells: false, sighupYieldsToLease: false },
+    awaitingFirstAttach: { countsBackgroundShells: false, sighupYieldsToLease: false },
+    owned: { countsBackgroundShells: false, sighupYieldsToLease: false },
+});
+export function deriveEngineLane(s) {
+    if (s.handedOver)
+        return "handover";
+    if (s.orphaned)
+        return "orphan";
+    return s.touched ? "owned" : "awaitingFirstAttach";
+}
+export function laneWork(lane, s, reader) {
+    const row = lane === undefined ? undefined : ENGINE_LANE_TABLE[lane];
+    switch (reader) {
+        case "sighup":
+            if (row?.sighupYieldsToLease === true)
+                return true;
+            break;
+        case "lease":
+            break;
+        default: {
+            const unhandled = reader;
+            throw new Error(`laneWork: unknown reader ${String(unhandled)}`);
+        }
+    }
+    return s.attached > 0 || s.inflight > 0 || (row?.countsBackgroundShells === true && s.backgroundShells() > 0);
+}
+export const HANDOVER_REASONS = ["background_exit"];
+export const backgroundShellsUnreachable = () => {
+    throw new Error("engine lease: background-shell count read on a lane table row that counts it, but no handover lane is armed (invariant broken)");
+};
 export function createEngineLeaseTracker(deps) {
     const orphanLane = deps.orphan;
-    const shortestLingerMs = Math.min(deps.lingerMs, orphanLane?.lingerMs ?? Number.POSITIVE_INFINITY);
+    const handoverLane = deps.handover;
+    const shortestLingerMs = Math.min(deps.lingerMs, orphanLane?.lingerMs ?? Number.POSITIVE_INFINITY, handoverLane?.lingerMs ?? Number.POSITIVE_INFINITY);
     const tickMs = deps.tickMs ?? Math.min(ENGINE_LEASE_TICK_MS, shortestLingerMs);
-    const leaseFacts = Number.isFinite(shortestLingerMs) ? Object.freeze({ lingerMs: shortestLingerMs, tickMs }) : undefined;
+    const firstAttachWindowMs = Math.max(deps.lingerMs, deps.firstAttach.windowMs);
     const now = deps.now ?? (() => performance.now());
     let stopped = false;
-    let idleSince = now();
+    const armedAt = now();
+    const armedEpochMs = Date.now();
+    const epochOf = (mono) => Math.round(armedEpochMs + (mono - armedAt));
+    let idleSince = armedAt;
+    let handedOver = null;
+    const backgroundShells = handoverLane?.backgroundShells ?? backgroundShellsUnreachable;
+    function windowOf(lane) {
+        switch (lane) {
+            case "handover":
+                return handoverLane?.lingerMs ?? Number.POSITIVE_INFINITY;
+            case "orphan":
+                return orphanLane?.lingerMs ?? Number.POSITIVE_INFINITY;
+            case "awaitingFirstAttach":
+                return firstAttachWindowMs;
+            case "owned":
+                return deps.lingerMs;
+            default: {
+                const unhandled = lane;
+                throw new Error(`engine lease: unknown lane ${String(unhandled)}`);
+            }
+        }
+    }
+    function laneNow() {
+        const orphaned = orphanLane ? orphanLane.read() : null;
+        const lane = deriveEngineLane({ handedOver: handedOver !== null, orphaned: orphaned !== null, touched: deps.firstAttach.firstTouchAt() !== null });
+        return { lane, orphaned };
+    }
     deps.log("engine_lease_armed", {
         lingerMs: Number.isFinite(deps.lingerMs) ? deps.lingerMs : null,
         orphanLingerMs: orphanLane?.lingerMs ?? null,
+        firstAttachMs: deps.firstAttach.windowMs,
+        firstAttachWindowMs: Number.isFinite(firstAttachWindowMs) ? firstAttachWindowMs : null,
+        handoverLingerMs: handoverLane?.lingerMs ?? null,
         tickMs,
         note: "engine self-exits once NO shell session is attached AND no run is in flight AND no HTTP touch, " +
-            "continuously for the linger window — via the same graceful drain as SIGTERM. The window is " +
-            "ENGINE_LINGER_MS while the parent is alive (or the watch is not armed) and ENGINE_ORPHAN_LINGER_MS " +
-            "once SEMA_PARENT_PID's process is gone. Set ENGINE_AUTO_EXIT=false and unset SEMA_PARENT_PID to disable.",
+            "continuously for the linger window — via the same graceful drain as SIGTERM. The window is chosen by lane: " +
+            "ENGINE_HANDOVER_LINGER_MS after POST /v1/engine/handover (until the next POST /v1/engine/attach; running background " +
+            "shells count as work only there); ENGINE_ORPHAN_LINGER_MS once SEMA_PARENT_PID's process is gone; otherwise " +
+            "max(ENGINE_LINGER_MS, ENGINE_FIRST_ATTACH_MS) until the first non-probe HTTP request ever arrives, and ENGINE_LINGER_MS after it. " +
+            "Set ENGINE_AUTO_EXIT=false and unset SEMA_PARENT_PID to disable.",
     });
     const timer = setInterval(() => {
         if (stopped)
@@ -25,7 +91,8 @@ export function createEngineLeaseTracker(deps) {
         }
         const attached = deps.attachedStreams();
         const inflight = deps.inflight();
-        if (attached > 0 || inflight > 0) {
+        const { lane, orphaned } = laneNow();
+        if (laneWork(lane, { attached, inflight, backgroundShells }, "lease")) {
             idleSince = null;
             return;
         }
@@ -34,8 +101,7 @@ export function createEngineLeaseTracker(deps) {
             idleSince = t;
             return;
         }
-        const orphaned = orphanLane ? orphanLane.read() : null;
-        const linger = orphanLane && orphaned !== null ? orphanLane.lingerMs : deps.lingerMs;
+        const linger = windowOf(lane);
         if (t - deps.lastActivityAt() < linger)
             return;
         if (t - deps.lastAttachEndedAt() < linger)
@@ -43,22 +109,17 @@ export function createEngineLeaseTracker(deps) {
         if (t - idleSince < linger)
             return;
         stop();
+        const orphanedNow = lane === "orphan" ? orphaned : null;
         const report = {
-            orphan: orphaned !== null,
-            reason: orphaned?.reason ?? "idle",
+            lane,
+            reason: orphanedNow?.reason ?? "idle",
             idleForMs: Math.round(t - Math.max(idleSince, deps.lastActivityAt(), deps.lastAttachEndedAt())),
             attached,
             inflight,
             lingerMs: linger,
-            ...(orphaned !== null ? { orphanedForMs: Math.round(t - orphaned.since) } : {}),
+            ...(orphanedNow !== null ? { orphanedForMs: Math.round(t - orphanedNow.since) } : {}),
         };
-        deps.log("engine_lease_auto_exit", {
-            ...report,
-            note: orphaned !== null
-                ? "the parent that spawned this engine is gone AND nobody is attached, no run is in flight and no HTTP touch " +
-                    "for the full orphan linger window — entering the SIGTERM graceful drain path (exit code 0; see exit-last.json)"
-                : "no attached shell session, no in-flight run and no HTTP touch for the full linger window — entering the SIGTERM graceful drain path",
-        });
+        deps.log("engine_lease_auto_exit", { ...report, note: AUTO_EXIT_NOTES[lane] });
         deps.selfExit(report);
     }, tickMs);
     timer.unref?.();
@@ -68,11 +129,76 @@ export function createEngineLeaseTracker(deps) {
         stopped = true;
         clearInterval(timer);
     }
+    function firstAttachFacts() {
+        if (!Number.isFinite(firstAttachWindowMs))
+            return undefined;
+        const touchedAt = deps.firstAttach.firstTouchAt();
+        return Object.freeze({ windowMs: firstAttachWindowMs, since: armedEpochMs, attachedAt: touchedAt === null ? null : epochOf(touchedAt) });
+    }
+    function handoverFacts() {
+        if (handedOver === null || handoverLane === undefined)
+            return undefined;
+        return Object.freeze({
+            since: epochOf(handedOver.since),
+            reason: handedOver.reason,
+            lingerMs: handoverLane.lingerMs,
+            backgroundShells: handoverLane.backgroundShells(),
+        });
+    }
+    const door = handoverLane === undefined
+        ? undefined
+        : {
+            get observing() {
+                return !stopped;
+            },
+            enter(reason) {
+                if (handedOver === null) {
+                    const from = laneNow().lane;
+                    handedOver = { since: now(), reason };
+                    deps.log("engine_lane_changed", { from, to: "handover", reason: "handover_requested", since: epochOf(handedOver.since) });
+                }
+                const facts = handoverFacts();
+                if (facts === undefined)
+                    throw new Error("engine lease: handover facts absent right after entering the handover lane (invariant broken)");
+                return { lane: "handover", since: facts.since, lingerMs: facts.lingerMs, backgroundShells: facts.backgroundShells };
+            },
+            attach() {
+                if (handedOver === null)
+                    return { lane: laneNow().lane };
+                const t = now();
+                const handedOverForMs = Math.round(t - handedOver.since);
+                handedOver = null;
+                const to = laneNow().lane;
+                deps.log("engine_lane_changed", { from: "handover", to, reason: "attached", since: epochOf(t) });
+                return { lane: to, handedOverForMs };
+            },
+        };
     return {
         stop,
         get facts() {
-            return stopped ? undefined : leaseFacts;
+            if (stopped || !Number.isFinite(shortestLingerMs))
+                return undefined;
+            const firstAttach = firstAttachFacts();
+            const handover = handoverFacts();
+            return Object.freeze({
+                lingerMs: shortestLingerMs,
+                tickMs,
+                lane: laneNow().lane,
+                ...(firstAttach !== undefined ? { firstAttach } : {}),
+                ...(handover !== undefined ? { handover } : {}),
+            });
         },
+        lane: () => (stopped ? undefined : laneNow().lane),
+        ...(door !== undefined ? { handover: door } : {}),
     };
 }
+const AUTO_EXIT_NOTES = {
+    handover: "this engine was handed over to the background (POST /v1/engine/handover) and nobody attached, no run and no background shell " +
+        "was running and no HTTP touch for the full ENGINE_HANDOVER_LINGER_MS window — entering the SIGTERM graceful drain path",
+    orphan: "the parent that spawned this engine is gone AND nobody is attached, no run is in flight and no HTTP touch " +
+        "for the full orphan linger window — entering the SIGTERM graceful drain path (exit code 0; see exit-last.json)",
+    awaitingFirstAttach: "no non-probe HTTP request EVER reached this engine within the first-attach window (max(ENGINE_LINGER_MS, ENGINE_FIRST_ATTACH_MS)) " +
+        "and nothing is attached or in flight — entering the SIGTERM graceful drain path",
+    owned: "no attached shell session, no in-flight run and no HTTP touch for the full linger window — entering the SIGTERM graceful drain path",
+};
 //# sourceMappingURL=engine-lease.js.map

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

@@ -20,6 +20,7 @@ import { type TaskAttachmentStore } from "../plugins/task-attachment-store.js";
 import type { TaskInheritEnv } from "../request-value-closure.js";
 import { type HeadRead } from "../session-incarnation.js";
 import type { SpaceReclaimer } from "../workspace-space.js";
+import { type SessionResidentCounts } from "../session-resident-background.js";
 /**
  * per-session 的 **cwd / shellEnv 登记簿**(TOC cwd seam + R-survey shellEnv seam)+ 它们的**租户围栏**。
  *
@@ -55,6 +56,9 @@ export interface SessionScopedRegistries {
      * 请求放宽凭据面)。
      */
     setSessionInheritEnv(sid: string, policy: TaskInheritEnv | undefined): void;
+    /** 本进程见过的会话 → 属主(围栏表本身,只读视图;`null` = 匿名)。**会话驻留后台行的枚举源**:`session-resident-background.ts` 逐会话问注册表
+     *  (core 的访问元组要带 scope,没有进程总数的读口),读的就是这一张 —— 每次提交写一笔、`dropSession` 清一笔、LRU 有界,不另立第二张会话名册。 */
+    readonly sessionOwners: ReadonlyMap<string, string | null>;
     /** 记录/对拍本会话的主人。与上次不同 ⇒ **先清两张表**再记新主(换主即清)。`null` = 匿名会话,
      *  它同样是一个**稳定**的身份值(不是「未知」),所以匿名重入不会被判成换主。 */
     fenceSessionOwner(sid: string, owner: string | null): void;
@@ -171,6 +175,7 @@ export declare function createExecutionEnv(ctx: ExecutionEnvCtx): {
     setSessionInheritEnv: (sid: string, policy: TaskInheritEnv | undefined) => void;
     fenceSessionOwner: (sid: string, owner: string | null) => void;
     dropSessionScoped: (sid: string) => void;
+    sessionResidentBackground: () => SessionResidentCounts;
     executionEnvFactory: import("@sema-agent/core").ExecutionEnvFactory | undefined;
     worktreeReap: (() => Promise<void>) | undefined;
     sendUserFileTaskEnvs: TaskEnvRegistry | undefined;

package/dist/boot/execution-env.js

@@ -26,6 +26,7 @@ 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,9 +38,10 @@ 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, executionLaneOf, laneBindsReads, 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";
 function boundedSessionSetter(map, maxEntries) {
     return (sid, value) => {
         map.delete(sid);
@@ -79,6 +81,7 @@ export function createSessionScopedRegistries(maxEntries = MAX_CWD_SESSIONS) {
     return {
         perSessionCwd,
         perSessionShellEnv,
+        sessionOwners: owners,
         setSessionCwd: (sid, cwd) => {
             perSessionCwd.set(sid, cwd);
             touch(sid, undefined);
@@ -218,14 +221,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), " +
@@ -249,7 +245,7 @@ export function createExecutionEnv(ctx) {
     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,
@@ -265,7 +261,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,
@@ -308,7 +304,7 @@ export function createExecutionEnv(ctx) {
             .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,
@@ -317,9 +313,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,
@@ -334,15 +331,16 @@ 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
@@ -384,7 +382,7 @@ export function createExecutionEnv(ctx) {
             };
         }
     }
-    else if (config.remoteExec?.provider === "local-docker") {
+    else if (config.remoteExec.provider === "local-docker") {
         executionEnvFactory = localDockerExecutionEnvFactory({
             image: config.remoteExec.image,
             ...(config.remoteExec.mountPath ? { mountPath: config.remoteExec.mountPath } : {}),
@@ -400,6 +398,7 @@ export function createExecutionEnv(ctx) {
             ...(config.remoteExec.env ? { env: config.remoteExec.env } : {}),
             sandboxReadFloor: config.sandboxReadFloor,
             ...(workspaceFillOf !== undefined ? { workspaceFillOf } : {}),
+            logger,
         }, ctx.laneDeps?.localDocker);
     }
     if (executionEnvFactory && DEPLOYMENT_SHAPE_PREDICATES.remoteScratchpad.holds(config)) {
@@ -408,15 +407,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 } : {}),
@@ -442,7 +441,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.",
             });
         }
@@ -454,37 +453,30 @@ 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 lspProvider = config.remoteExec.provider;
     const lspLane = executionLaneOf(lspProvider);
     const lspLaneBindsReads = lspLane !== undefined && laneBindsReads(lspLane);
     if ((lspProvider === "e2b" || lspProvider === "k8s") && config.lspEnabled && !lspLaneBindsReads) {
@@ -506,10 +498,42 @@ export function createExecutionEnv(ctx) {
                 : 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))
+                return;
+            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,
+        sessionResidentBackground,
         executionEnvFactory, worktreeReap, sendUserFileTaskEnvs, lspManager, spaceReclaimer, sandboxSecretSeatGate, sandboxPodReaper, sandboxGitPlane,
     };
 }

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 撞上。