@sema-agent/server 2.0.0 → 3.0.0

package/dist/boot/coordinators.d.ts

@@ -0,0 +1,33 @@
+/**
+ * design/158 A10:composition root 分段 —— 进程内活体 HITL 协调器 + SendUserFile 工具面。
+ *
+ * 纯搬运:函数体逐字来自 `main.ts`(原 1443-1518 行),缩进不变;新增的只有 import 与包壳。
+ *
+ * ⚠️ **位置即契约**:`durableEnabled` 必须在 `RunnerDeps` 字面量**之前**求值([1.294 G1]:onAsk 的
+ * 在场性本身是 core suspendAsk 的分路条件,不能靠闭包惰性读),故本段整体排在 runner-deps 段之前;
+ * `sendUserFileTaskEnvs` 由 exec-env 段产出,故本段又必须排在它之后。
+ */
+import type { ServiceConfig } from "../config.js";
+import { ElicitationCoordinator } from "../elicitation.js";
+import type { Logger } from "../observability/logger.js";
+import { QuestionCoordinator } from "../question.js";
+import { ToolApprovalCoordinator } from "../tool-approval.js";
+import { SendUserFileEmitter } from "../capabilities/send-user-file-tool.js";
+import { TaskEnvRegistry } from "../capabilities/sandbox-file-send.js";
+import type { StoreBackend } from "../plugins/store-backend.js";
+export interface LiveCoordinatorsCtx {
+    config: ServiceConfig;
+    logger: Logger;
+    backend: StoreBackend | undefined;
+    sendUserFileTaskEnvs: TaskEnvRegistry | undefined;
+}
+export declare function createLiveCoordinators(ctx: LiveCoordinatorsCtx): {
+    elicitation: ElicitationCoordinator | undefined;
+    question: QuestionCoordinator | undefined;
+    toolApproval: ToolApprovalCoordinator | undefined;
+    durableEnabled: boolean;
+    sendUserFileEmitter: SendUserFileEmitter | undefined;
+    sendFileLedger: import("../plugins/send-file-ledger.js").SendFileLedger | undefined;
+    sendUserFileToolSpec: import("@sema-agent/core").ToolSpec<import("typebox").TSchema> | undefined;
+};
+//# sourceMappingURL=coordinators.d.ts.map

package/dist/boot/coordinators.js

@@ -0,0 +1,97 @@
+import { ElicitationCoordinator } from "../elicitation.js";
+import { QuestionCoordinator } from "../question.js";
+import { ToolApprovalCoordinator } from "../tool-approval.js";
+import { SendUserFileEmitter, SEND_USER_FILE_MAX_BYTES, sendUserFileTool } from "../capabilities/send-user-file-tool.js";
+import { createSandboxFileSend, TaskEnvRegistry } from "../capabilities/sandbox-file-send.js";
+import { createSendUserFileIssuer } from "../plugins/send-user-file.js";
+import { withLedgerRecording } from "../plugins/send-file-ledger.js";
+import { basename, resolve } from "node:path";
+import { stat as fsStat, readFile as fsReadFile } from "node:fs/promises";
+export function createLiveCoordinators(ctx) {
+    const { config, logger, backend, sendUserFileTaskEnvs } = ctx;
+    // E23 (shell-host contract): inbound MCP elicitation coordinator (live-only HITL). Present ONLY when MCP_ELICITATION_ENABLED
+    // — absent ⇒ onElicit is not wired ⇒ core advertises no elicitation capability to any server (fail-closed). Shared
+    // by the runner (the onElicit seam) and the HTTP layer (the respond route + the per-run ALS context wraps).
+    const elicitation = config.mcpElicitation.enabled ? new ElicitationCoordinator(config.mcpElicitation.throttle) : undefined;
+    // §4④: AskUserQuestion LIVE-stream HITL coordinator — the sibling of `elicitation`. Present ⇒ wired onto
+    // `RunnerDeps.onQuestion` (core mounts the AskUserQuestion tool + routes live asks here) AND consumed by the HTTP layer
+    // (the `POST /v1/questions/:id/respond` route + the per-run ALS context wraps on the streaming legs). Absent ⇒ core
+    // mounts the tool with the headless default (a run never hangs; the model just can't get a live answer).
+    const question = config.askQuestionEnabled ? new QuestionCoordinator() : undefined;
+    // [816]/[820]②: the live tool-approval HITL coordinator — the sibling of `question` on core's `RunnerDeps.onAsk`
+    // seam (1.290 sync-ask leg). Present ⇒ a policy `ask` on a LIVE streaming leg becomes a `tool_approval` frame the
+    // shell renders as the CC three-choice card, answered via POST /v1/tool-approvals/:id/respond.
+    // [1535] 正名(旧文「background/workflow ⇒ headless auto-deny stands」已过时):宿主 sync 腿现同时装
+    // `spec.onAsk = boundAsk(ctx)`(server.ts 装配点)——core 继承链把闭包冻给委派子代,**bg/嵌套子代的
+    // ask 浮到宿主 live 流**(带 sourceTaskId);真正无宿主流的腿(durable-submit/headless resume)才留
+    // 「unavailable → durable park;无 park 设施 core fail-closed deny」。durable 部署 G1 语义不变。
+    const toolApproval = config.toolApprovalEnabled ? new ToolApprovalCoordinator() : undefined;
+    // [1.294 G1] durable 姿势必须在 runnerDeps 字面量之前可判(onAsk 的「在场性」本身就是 core suspendAsk 的
+    // 分路条件,不能再靠闭包惰性读)——判据与 checkpointStore 的构造条件同源(backend?.checkpoint 存在 ∧
+    // DURABLE_APPROVAL;store 本体已上移至 subRunner 构造前,[1535] 断点② 双 Runner 挂载)。
+    const durableEnabled = backend?.checkpoint !== undefined && config.durableApproval === true;
+    // SendUserFile(真 CC 契约,clay 2026-07-14)两种 lane 形态,其余缺席=诚实(工具不进 roster):
+    //  - host lane:本地盘读+服务端上传,【单用户 only】——host 多租户=任意路径读→公网 URL 的 exfil 面,
+    //    clay 拍永久关死,不留口子。路径=绝对或相对 process.cwd(用户目录语义,与 CC 一致)。
+    //  - e2b/k8s lane(v2,Plan B 直传):沙箱内 stat+`curl -T` 打 server 预签的单对象 PUT(字节不中转、
+    //    凭据不进沙箱);沙箱自身文件系统=租户边界,故任意租户可用。
+    //  - ssh lane(后补 2026-07-14):同一直传链,但 peer=跨任务共享的真实主机(非租户边界)→
+    //    【单用户 only】,租户门在 sandboxSendLaneEnabled(多租户下注册表不建,工具诚实缺席)。
+    //    adb/local-docker 仍后补。
+    // 签发面缺 S3_PUBLIC_ENDPOINT 时 issue-time fail-loud(工具在但用即报修法);100MiB/文件帽在各 send 面。
+    const sendUserFileEmitter = (() => {
+        if (!config.sendUserFile)
+            return undefined;
+        if (sendUserFileTaskEnvs)
+            return new SendUserFileEmitter(); // e2b/k8s/ssh(单用户):注册表已就位(lane+租户+签发面判定)
+        // unset REMOTE_EXEC(in-process/TOC 本地形态)有意归入 host 语义:exec 与文件都在本机,单用户门
+        // 同样把关(codex 复审提出收紧到显式 "host";判定=不收——unset 单机+配了 S3 是合法 dev/TOC 场景,
+        // 且与 1.187.0 已发行为一致;真正的红线是 requirePrincipal 多租户,这里恒关)。
+        const provider = config.remoteExec?.provider ?? "host";
+        if (provider === "host" && config.requirePrincipal !== true)
+            return new SendUserFileEmitter();
+        return undefined;
+    })();
+    // SendUserFile 账本(多租户治理面,[768]②a 后半):key 里的 scope 段是哈希(URL 不泄 principal),
+    // 按租户列/撤销的 scope↔对象映射记在 server 侧账本(四后端孪生,sendfile_link / JSONL)。有 backend 即建
+    // (签发面也配了才有写点);无 backend(env-only worker)= 无账本 = 不记账不 501 治理面(诚实缺席,
+    // capabilities.sendUserFileLedger=false)。
+    const sendFileLedger = config.sendUserFile && backend ? backend.sendFileLedger() : undefined;
+    const sendUserFileToolSpec = (() => {
+        if (!sendUserFileEmitter || !config.sendUserFile)
+            return undefined;
+        const issuer = createSendUserFileIssuer(config.sendUserFile);
+        // 两条 lane 的 send 都把 ctx.principal(core VERIFIED)传给签发面 → key 带哈希 scope 段 + link 携原文 scope。
+        const rawSend = sendUserFileTaskEnvs
+            ? createSandboxFileSend({
+                registry: sendUserFileTaskEnvs,
+                prepare: (filename, scope) => issuer.prepareDirectUpload(filename, undefined, scope),
+                maxBytes: SEND_USER_FILE_MAX_BYTES,
+            })
+            : async (p, sendCtx) => {
+                const resolved = resolve(p);
+                const st = await fsStat(resolved).catch(() => undefined);
+                if (!st || !st.isFile())
+                    throw new Error(`file not found (or not a regular file): ${p} — ls first; absolute paths are safest`);
+                if (st.size > SEND_USER_FILE_MAX_BYTES)
+                    throw new Error(`file exceeds the ${Math.floor(SEND_USER_FILE_MAX_BYTES / (1024 * 1024))} MiB per-file cap (${st.size} bytes)`);
+                const bytes = await fsReadFile(resolved);
+                // 读后复验(codex 复审 MED):stat→read 间文件可增长——上传的是读到的字节,帽必须按真实字节数把关。
+                if (bytes.byteLength > SEND_USER_FILE_MAX_BYTES)
+                    throw new Error(`file exceeds the ${Math.floor(SEND_USER_FILE_MAX_BYTES / (1024 * 1024))} MiB per-file cap (${bytes.byteLength} bytes)`);
+                return issuer.issue(bytes, basename(resolved), undefined, sendCtx.principal);
+            };
+        // 账本写点(两 lane 同语义):上传+verify 成功后、file_link 帧前记账;记账失败=该文件 fail-loud +
+        // best-effort 删已传对象(治理面必须有行;删失败 warn)。无账本(env-only)= 直通,行为与 1.189 一致。
+        const send = sendFileLedger
+            ? withLedgerRecording(rawSend, {
+                ledger: sendFileLedger,
+                deleteObject: (bucket, key) => issuer.deleteObject(bucket, key),
+                warn: (msg, meta) => logger.warn(msg, meta),
+            })
+            : rawSend;
+        return sendUserFileTool({ send, emitter: sendUserFileEmitter });
+    })();
+    return { elicitation, question, toolApproval, durableEnabled, sendUserFileEmitter, sendFileLedger, sendUserFileToolSpec };
+}
+//# sourceMappingURL=coordinators.js.map

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

@@ -0,0 +1,26 @@
+import { NodeLspManager } from "@sema-agent/core";
+import { TaskEnvRegistry } from "../capabilities/sandbox-file-send.js";
+import { SessionEnvironmentSelection } from "../capabilities/select-environment-tool.js";
+import type { ServiceConfig } from "../config.js";
+import type { Logger } from "../observability/logger.js";
+import type { Metrics } from "../observability/metrics.js";
+import { PerTaskImageRegistry } from "../per-task-image.js";
+import { type TaskAttachmentStore } from "../plugins/task-attachment-store.js";
+export interface ExecutionEnvCtx {
+    config: ServiceConfig;
+    logger: Logger;
+    metrics: Metrics;
+    taskAttachmentStore: TaskAttachmentStore | undefined;
+}
+export declare function createExecutionEnv(ctx: ExecutionEnvCtx): {
+    perTaskImage: PerTaskImageRegistry;
+    sessionEnvSelection: SessionEnvironmentSelection;
+    perSessionCwd: Map<string, string>;
+    setSessionCwd: (sid: string, cwd: string) => void;
+    setSessionShellEnv: (sid: string, env: Record<string, string>) => void;
+    executionEnvFactory: import("@sema-agent/core").ExecutionEnvFactory | undefined;
+    worktreeReap: (() => Promise<void>) | undefined;
+    sendUserFileTaskEnvs: TaskEnvRegistry | undefined;
+    lspManager: import("../lsp/manager.js").E2bLspManager | NodeLspManager | undefined;
+};
+//# sourceMappingURL=execution-env.d.ts.map

package/dist/boot/execution-env.js

@@ -0,0 +1,370 @@
+/**
+ * design/158 A10:composition root 分段 —— 执行环境装配(per-task 镜像 / cwd·shellEnv 注册表 /
+ * 五条 remote-exec 腿的工厂 / 三层工厂装饰 / LSP 管理器)。
+ *
+ * 纯搬运:函数体逐字来自 `main.ts`(原 997-1302 行),缩进不变;新增的只有 import 与包壳。
+ *
+ * ⚠️ **位置即契约 —— 装饰顺序就是行为**:`executionEnvFactory` 由内向外被依次包装,
+ * 次序逐字保留不可动:
+ *    base(e2b|k8s|ssh|adb|host|local-docker)
+ *      → `withRemoteScratchpad`(远程车道首 exec 才 mkdir)
+ *      → `withWorktreeIsolation`(host 车道 per-agent worktree,定 cwd)
+ *      → `TaskEnvRegistry.wrapFactory`(SendUserFile 直传登记 taskId→env)
+ *      → 附件物化(**最外层**:内层先定 cwd,附件才落在最终 cwd —— 原文逐字注释即此)。
+ * 另:`lspManager` 声明在 host 工厂**之后**,host 工厂闭包对它是同作用域前向引用(闭包每任务才跑,
+ * 那时已初始化)——本段整体搬运保住了这个前向引用,拆开两个模块就会破。
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { NodeLspManager } from "@sema-agent/core";
+import { sandboxSendLaneEnabled, TaskEnvRegistry } from "../capabilities/sandbox-file-send.js";
+import { SessionEnvironmentSelection } from "../capabilities/select-environment-tool.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";
+import { e2bExecutionEnvFactory } from "../plugins/remote-env-e2b.js";
+import { hostExecutionEnvFactory, RemoteHostExecutionEnv } from "../plugins/remote-env-host.js";
+import { k8sExecutionEnvFactory } from "../plugins/remote-env-k8s.js";
+import { localDockerExecutionEnvFactory } from "../plugins/remote-env-local-docker.js";
+import { sshExecutionEnvFactory } from "../plugins/remote-env-ssh.js";
+import { isRemoteScratchpadLane, withRemoteScratchpad } from "../plugins/remote-scratchpad.js";
+import { FileSchedulerBackend, defaultSchedulerStorePath } from "../plugins/scheduler-support.js";
+import { materializeAttachmentsInto } from "../plugins/task-attachment-store.js";
+import { reapOrphanWorktrees, withWorktreeIsolation } from "../plugins/worktree-isolation.js";
+import { customPkgSourceFromEnv, derivePkgSourceEnv } from "../sandbox-pkg-source.js";
+import { effectiveHostWorkspace } from "../task-cwd.js";
+export function createExecutionEnv(ctx) {
+    const { config, logger, metrics, taskAttachmentStore } = ctx;
+    // design/48 v1b: deployment-level remote execution(部署级路由 + 懒汉连接). When
+    // REMOTE_EXEC=e2b, this deployment is a "code-agent worker" — each task's hand runs in a per-task E2B VM,
+    // provisioned lazily on first hand use (a plan-only task pays zero VM cost). Unset → in-process stub env.
+    // design/48 v1b + design/61: pick the remote-exec backend by provider (peer adapters). SSH/ADB target REAL
+    // systems (not isolated/suspendable) — the leader's autonomy + the design/37 gate + HITL run accordingly.
+    // §7 P0.5 per-task sandbox image: the trusted-control-plane bridge from resolveSpec (resolves the requested
+    // profile → digest with the caller's principal, fail-closed) to the k8s factory (applies it per-pod). See
+    // per-task-image.ts + resolveSpec below. Worker-global default image is the fallback when no profile is requested.
+    const perTaskImage = new PerTaskImageRegistry();
+    // RFC A2: session-keyed environment selection (PROFILE intent, never a digest) written by the model-facing
+    // SelectEnvironment tool; resolveSpec re-resolves it FAIL-CLOSED per task (same re-admit as a body profile).
+    const sessionEnvSelection = new SessionEnvironmentSelection();
+    // [#40 / TOC cwd seam] per-session launch dir → the host lane's agent workspace (resolveSpec registers it gated by
+    // cwdHonored; the host factory reads it by ctx.sessionId). Only ever written for the single-user host lane.
+    // BOUNDED (avoid unbounded growth over the persistent local engine's lifetime): an LRU cap; the shell
+    // re-sends cwd on every request, so evicting a stale session is harmless (it re-registers on next use).
+    const MAX_CWD_SESSIONS = 4096;
+    const perSessionCwd = new Map();
+    const setSessionCwd = (sid, cwd) => {
+        perSessionCwd.delete(sid); // re-insert at the tail = most-recently-used
+        perSessionCwd.set(sid, cwd);
+        if (perSessionCwd.size > MAX_CWD_SESSIONS)
+            perSessionCwd.delete(perSessionCwd.keys().next().value); // evict oldest
+    };
+    // [R-survey / TOC shellEnv seam, core PLAN批注] per-session `settings.env` → the host lane's agent shell env
+    // (resolveSpec registers it gated by cwdHonored — single-user host lane only; the host factory merges it by
+    // ctx.sessionId). design/107 "env = capability axis". Same LRU bound + re-send-on-every-request semantics as cwd.
+    const perSessionShellEnv = new Map();
+    const setSessionShellEnv = (sid, env) => {
+        perSessionShellEnv.delete(sid);
+        perSessionShellEnv.set(sid, env);
+        if (perSessionShellEnv.size > MAX_CWD_SESSIONS)
+            perSessionShellEnv.delete(perSessionShellEnv.keys().next().value);
+    };
+    let executionEnvFactory;
+    // SVC-3 worktree isolation: the reaper (defined far below) reuses ONE long-lived git base env + repoRoot to
+    // `git worktree prune` crash-orphaned worktrees. Holders are populated when the wrapper is wired (host lane).
+    let worktreeReap;
+    if (config.remoteExec?.provider === "e2b") {
+        executionEnvFactory = e2bExecutionEnvFactory({
+            apiKey: config.remoteExec.apiKey,
+            ...(config.remoteExec.template ? { template: config.remoteExec.template } : {}),
+            ...(config.remoteExec.timeoutMs != null ? { timeoutMs: config.remoteExec.timeoutMs } : {}),
+            ...(config.remoteExec.livenessMs != null ? { livenessMs: config.remoteExec.livenessMs } : {}),
+            ...(config.remoteExec.allowInternetAccess != null ? { allowInternetAccess: config.remoteExec.allowInternetAccess } : {}),
+            // [1452]/[1454] CWD-A: workspace 根透传(E2B_MOUNT_PATH)——缺省仍 /home/user(adapter 默认)。
+            ...(config.remoteExec.mountPath ? { mountPath: config.remoteExec.mountPath } : {}),
+            // RFC B5: region package-source env set rides the operator-trusted sandboxEnv — ENV-FIRST, the derived
+            // ecosystem overrides (pip/uv/npm/go/rustup/flutter/…) beat the image's baked CN ENV on existing images,
+            // no rebake needed. Explicit E2B_SANDBOX_ENV keys win over derived on collision (deliberate override).
+            ...(() => {
+                const merged = { ...derivePkgSourceEnv(config.sandboxPkgSource, customPkgSourceFromEnv()), ...(config.remoteExec.sandboxEnv ?? {}) };
+                return Object.keys(merged).length > 0 ? { sandboxEnv: merged } : {};
+            })(),
+            logger,
+            metrics,
+        });
+    }
+    else if (config.remoteExec?.provider === "k8s") {
+        const k8sCfg = {
+            image: config.remoteExec.image,
+            ...(config.remoteExec.apiUrl ? { apiUrl: config.remoteExec.apiUrl } : {}),
+            ...(config.remoteExec.token ? { token: config.remoteExec.token } : {}),
+            ...(config.remoteExec.caCert ? { caCert: config.remoteExec.caCert } : {}),
+            ...(config.remoteExec.insecureTls ? { insecureTls: true } : {}),
+            ...(config.remoteExec.namespace ? { namespace: config.remoteExec.namespace } : {}),
+            ...(config.remoteExec.runtimeClass != null ? { runtimeClass: config.remoteExec.runtimeClass } : {}),
+            ...(config.remoteExec.mountPath ? { mountPath: config.remoteExec.mountPath } : {}),
+            ...(config.remoteExec.timeoutMs != null ? { timeoutMs: config.remoteExec.timeoutMs } : {}),
+            // Resource-profile knobs. config.ts reads K8S_MEMORY/K8S_CPU; this passthrough was
+            // missing, so the adapter silently stayed on its 2Gi default (Kata VM = default_memory 2G + limit 2G = 4G
+            // MemTotal — task02b run9/10 integration gradle OOM'd there even after the env was set).
+            ...(config.remoteExec.memory ? { memory: config.remoteExec.memory } : {}),
+            ...(config.remoteExec.cpu ? { cpu: config.remoteExec.cpu } : {}),
+            ...(config.remoteExec.s3Snapshot ? { s3Snapshot: config.remoteExec.s3Snapshot } : {}),
+            // RFC B5: region package-source env set → pod container env (operator-trusted, never task-controlled).
+            // ENV-FIRST: pod env beats image ENV and reaches every exec — the derived ecosystem overrides switch
+            // region on existing images; the SEMA_PKG_SOURCE marker drives the in-image hook (file-bound pieces).
+            ...(() => {
+                const derived = derivePkgSourceEnv(config.sandboxPkgSource, customPkgSourceFromEnv());
+                return Object.keys(derived).length > 0 ? { podEnv: derived } : {};
+            })(),
+        };
+        // §7 P0.5: per-pod image override. resolveSpec resolved the requested profile→digest (with the caller's
+        // principal, fail-closed) and registered it by sessionId — the ONLY identifier stable across the factory ctx
+        // on every path (adversarial-review round-2: /v1/runs mints its own durable taskId that CLOBBERS spec.taskId,
+        // so taskId-keying misses on the primary path; sessionId survives). get() is non-removing (the factory may be
+        // invoked >once per logical task). Absent ⇒ the worker-global k8sCfg.image. Building the factory per task is a
+        // cheap closure alloc; the ref is immutable (repo@digest). podSpecPatch can NOT carry the image (hard invariant).
+        executionEnvFactory = (ctx) => k8sExecutionEnvFactory({ ...k8sCfg, image: perTaskImage.get(ctx.sessionId) ?? k8sCfg.image })(ctx);
+    }
+    else if (config.remoteExec?.provider === "ssh") {
+        executionEnvFactory = sshExecutionEnvFactory({
+            host: config.remoteExec.host,
+            username: config.remoteExec.username,
+            privateKey: config.remoteExec.privateKey,
+            ...(config.remoteExec.port != null ? { port: config.remoteExec.port } : {}),
+            ...(config.remoteExec.mountPath ? { mountPath: config.remoteExec.mountPath } : {}),
+        });
+    }
+    else if (config.remoteExec?.provider === "adb") {
+        executionEnvFactory = adbExecutionEnvFactory({
+            serial: config.remoteExec.serial,
+            ...(config.remoteExec.adbPath ? { adbPath: config.remoteExec.adbPath } : {}),
+            ...(config.remoteExec.mountPath ? { mountPath: config.remoteExec.mountPath } : {}),
+        });
+    }
+    else if (config.remoteExec?.provider === "host") {
+        // DUAL-MODE §5: the TOC `host` lane — run on THIS machine, no container (isolation=none). Fan-out still
+        // works (bounded by one box). Secrets are env-NAMEs the host resolves from its own process.env.
+        {
+            // R7 self-wake: inject the self-wake SchedulerCapability backend on the single-user TOC host lane
+            // (opt-in SCHEDULER_ENABLED). `hasScheduler(env)` then mounts CronCreate/CronDelete/CronList(旧名 CronCancel、Sleep 已 design/136 撤除——L8 注释订正,且挂载在 core prepare-task 非 createHandsToolkit); the TOC shell
+            // daemon reads the SAME ~/.sema/scheduled_tasks.json store (registry-core /node binding) and fires due intents.
+            // Multi-tenant (requirePrincipal) routes scheduling to center, NOT this host daemon → gate it off there. ONE
+            // backend instance at boot → every host task shares the same store file.
+            const hostScheduler = config.schedulerEnabled && config.requirePrincipal !== true
+                ? new FileSchedulerBackend({
+                    ...(config.schedulerStorePath ? { storePath: config.schedulerStorePath } : {}),
+                    // [1009]② host-signal: the spawning shell knows whether a resident daemon will honor session
+                    // wakeups — SCHEDULER_SESSION_WAKEUP=false flips the capability off at CONSTRUCTION (instance-
+                    // lifetime snapshot, core TOCTOU 契约) so core's ScheduleWakeup refuses up front.
+                    ...(config.schedulerSessionWakeup === false ? { caps: { supportsSessionWakeup: false } } : {}),
+                })
+                : undefined;
+            if (hostScheduler)
+                logger.info(`R7: self-wake scheduler enabled (host lane), store=${config.schedulerStorePath ?? defaultSchedulerStorePath()}`);
+            const hostCfg = {
+                ...(config.remoteExec.workspaceBase ? { workspaceBase: config.remoteExec.workspaceBase } : {}),
+                ...(config.remoteExec.commandTimeoutMs != null ? { commandTimeoutMs: config.remoteExec.commandTimeoutMs } : {}),
+                ...(hostScheduler ? { scheduler: hostScheduler } : {}),
+                // design/103 background shell: single-user host lane only (parity with scheduler/cwd). Multi-tenant host
+                // lane (which shouldn't exist — host runs on the worker's own box) → INERT (run_in_background/etc. don't mount).
+                backgroundShell: config.requirePrincipal !== true,
+            };
+            // [#40 / TOC cwd seam] per-request workspace: if resolveSpec registered a caller `cwd` for this session (gated by
+            // cwdHonored — single-user host lane only), run the agent VERBATIM in that dir (persistent, never deleted — the
+            // user's project). Else the boot-time host config (ephemeral random subdir). Mirrors the k8s perTaskImage wrap.
+            // core 1.219 `ctx.parentCwd` (dogfood finding: sub-agents landed in an EMPTY sandbox): a DELEGATED child
+            // (workflow ctx.agent / Task tool) now roots at its PARENT's working dir — CC parity — via core's TRUSTED
+            // RunInternals channel. Precedence in effectiveHostWorkspace: session cwd → parentCwd (unless the child asked
+            // for isolation:"worktree" — that wrapper wins below) → ephemeral. Container lanes never consult this.
+            executionEnvFactory = (ctx) => {
+                const cwd = effectiveHostWorkspace(perSessionCwd.get(ctx.sessionId), ctx);
+                const shellEnv = perSessionShellEnv.get(ctx.sessionId);
+                const env = hostExecutionEnvFactory({
+                    ...hostCfg,
+                    ...(cwd ? { workspaceDir: cwd } : {}),
+                    ...(shellEnv ? { env: shellEnv } : {}), // R-survey: per-task shell env (merged UNDER per-command options.env by the host adapter)
+                })(ctx);
+                // core 1.191: an EPHEMERAL host workspace (no honored `cwd` → a per-task `sema-host-<id>` dir destroy()
+                // rm's) evicts its LSP servers at task-end so a busy server doesn't accumulate one heavy language server per
+                // task. cwdHonored (persistent project) is NOT evicted — its stable root stays warm across turns (CC-parity);
+                // worktree/fan-out is bounded by maxSessions=16. Only wraps when a NodeLspManager is actually active.
+                return lspManager && !cwd ? evictLspOnDestroy(env, lspManager) : env;
+            };
+        }
+    }
+    else if (config.remoteExec?.provider === "local-docker") {
+        // DUAL-MODE §5: the TOC `local-docker` lane — a per-task container on THIS machine's docker daemon
+        // (isolation:true, suspendable:false). The base image comes ENTIRELY from config (no docker.io default —
+        // domestic-images iron rule). Secrets are resolved env-NAME→value here (config.ts already did the forward).
+        executionEnvFactory = localDockerExecutionEnvFactory({
+            image: config.remoteExec.image,
+            ...(config.remoteExec.mountPath ? { mountPath: config.remoteExec.mountPath } : {}),
+            ...(config.remoteExec.dockerPath ? { dockerPath: config.remoteExec.dockerPath } : {}),
+            ...(config.remoteExec.dockerHost ? { dockerHost: config.remoteExec.dockerHost } : {}),
+            ...(config.remoteExec.memory ? { memory: config.remoteExec.memory } : {}),
+            ...(config.remoteExec.cpus != null ? { cpus: config.remoteExec.cpus } : {}),
+            ...(config.remoteExec.network ? { network: config.remoteExec.network } : {}),
+            ...(config.remoteExec.commandTimeoutMs != null ? { commandTimeoutMs: config.remoteExec.commandTimeoutMs } : {}),
+            ...(config.remoteExec.env ? { env: config.remoteExec.env } : {}),
+        });
+    }
+    // [848] remote scratchpad: decorate the REMOTE sandbox lanes (e2b/k8s/local-docker/ssh) so each env
+    // lazily `mkdir -p`s `/tmp/scratchpad/<sessionId>` on its FIRST exec — never at factory time (e2b is
+    // lazy-VM; a factory-time exec would force-boot the VM). adb is skipped (no standard /tmp on Android);
+    // host keeps its worker-local scratchpad (ensureScratchpadDir at the envFacts consumer). The envFacts
+    // advertisement below uses the SAME remoteScratchpadDirFor rule, so fact and mkdir can never disagree.
+    if (executionEnvFactory && isRemoteScratchpadLane(config.remoteExec?.provider)) {
+        executionEnvFactory = withRemoteScratchpad(executionEnvFactory, logger);
+    }
+    // SVC-3 (design/97 CORE-6): wrap the factory with git-worktree isolation. When core marks an agent
+    // `isolation:"worktree"` (TRUSTED RunInternals — never a TaskSpec), the wrapper mints a per-agent detached
+    // worktree under the operator-trusted repoRoot; otherwise it passes the base env through untouched. v1
+    // covers the `host` lane (the TOC fan-out lane). Other lanes would need a worktree-ROOTED REMOTE env from
+    // `rootEnvAt` (a follow-on; a host/NodeExecutionEnv worktree is not durable-suspendable — see the plugin
+    // header) — they are left unwrapped here, isolation:"worktree" is then a no-op for them (the base env wins).
+    if (config.worktreeIsolation && executionEnvFactory) {
+        // M4 (adversarial-review): a mis-wired WORKTREE_REPO_ROOT must fail LOUD at boot, not per-task at runtime. The
+        // root must exist AND be a git repo (`.git` dir or worktree-link file). On a bad root, log an error + LEAVE
+        // isolation OFF (the factory unwrapped) rather than wiring a factory that throws on every isolated agent.
+        const wtRoot = config.worktreeIsolation.repoRoot;
+        const wtValid = existsSync(wtRoot) && existsSync(join(wtRoot, ".git"));
+        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' agents run on the shared base env. Fix the path or unset the flag.",
+            });
+        }
+        else if (config.remoteExec?.provider === "host") {
+            // The SHARED base env that runs `git worktree add/remove/prune` (cwd:repoRoot is passed explicitly by
+            // core on every git call, so this env's own root is irrelevant — it just needs `exec` + git on PATH).
+            // ONE long-lived env per deployment; the reaper reuses it. `inheritEnv:"all"` so the operator's git
+            // config/credentials are visible (this is the operator's own machine + own repo, the TOC posture).
+            // systematic-audit (gate-fail-direction): every worktree-lane RemoteHostExecutionEnv carries the SAME
+            // background-shell gate as the primary host factory (main.ts ~442) — not the env's `?? true` default. The
+            // git-base env is git-ops only (agents run on rootEnvAt below), but gating it keeps the policy uniform / future-proof.
+            const gitBaseEnv = new RemoteHostExecutionEnv({ workspaceDir: config.worktreeIsolation.repoRoot, inheritEnv: "all", backgroundShell: config.requirePrincipal !== true });
+            executionEnvFactory = withWorktreeIsolation(executionEnvFactory, {
+                repoRoot: config.worktreeIsolation.repoRoot,
+                ...(config.worktreeIsolation.allowedRoots ? { allowedRoots: config.worktreeIsolation.allowedRoots } : {}),
+                ...(config.worktreeIsolation.commit ? { commit: config.worktreeIsolation.commit } : {}),
+                baseEnvForGit: gitBaseEnv,
+                // Host-lane worktree-rooted env: a host adapter in PERSISTENT-DIR mode — its own destroy() does NOT
+                // rm the dir (so core's `git worktree remove` owns teardown), and it keeps the host adapter's secret
+                // scrub + timeout semantics (vs a bare NodeExecutionEnv). inheritEnv defaults to "scrub" (model-driven).
+                rootEnvAt: (dir) => {
+                    const env = new RemoteHostExecutionEnv({ workspaceDir: dir, backgroundShell: config.requirePrincipal !== true });
+                    // A worktree root is per-agent + ephemeral (core's `git worktree remove` reclaims it at
+                    // task-end), so evict its LSP servers DETERMINISTICALLY too — not just via the maxSessions LRU backstop. The
+                    // worktree dir IS the LSP cache root (env.cwd), so evict(env.cwd) on destroy hits it. (`lspManager` is declared
+                    // below but this closure only runs per-task, well after it's initialized — same forward-ref as the host factory.)
+                    return lspManager ? evictLspOnDestroy(env, lspManager) : env;
+                },
+                logger,
+            });
+            // 复审 2026-07-30 F3:in-flight 单飞语义内建在铸造处——本函数有**两个**调用点(下方 boot recovery
+            // sweep 与 reapers.ts 的周期 tick),守卫只装 tick 侧会漏 boot 长跑(>REAP_INTERVAL_SEC 的
+            // `git worktree prune` 与首个 tick 叠跑,正是守卫要防的并发)。装在源头,调用点全免疫。
+            {
+                let inFlight = false;
+                worktreeReap = () => {
+                    if (inFlight)
+                        return Promise.resolve();
+                    inFlight = true;
+                    return reapOrphanWorktrees(gitBaseEnv, config.worktreeIsolation.repoRoot, logger).finally(() => (inFlight = false));
+                };
+            }
+            logger.info("worktree_isolation_enabled", { provider: "host", repoRoot: config.worktreeIsolation.repoRoot });
+            // BOOT recovery sweep: reap any worktrees orphaned by a crash BEFORE this process started (the periodic
+            // reaper would otherwise wait a full interval). Best-effort, fire-and-forget; never blocks boot.
+            void worktreeReap().catch(() => undefined);
+        }
+        else {
+            // Not a no-op-silent: an operator who set WORKTREE_ISOLATION_ENABLED on a non-host lane should know it
+            // doesn't take effect yet (the worktree-rooted REMOTE env is a follow-on). Fail-loud-ish via a warning.
+            logger.warn("worktree_isolation_unsupported_lane", {
+                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.",
+            });
+        }
+    }
+    // SendUserFile v2(clay 拍 2026-07-14,Plan B 直传):沙箱 lane 的文件源需要「工具执行时拿到当前
+    // 任务的 env」——core 把 per-task env 关在 prepare-task 闭包里(ToolExecuteContext 无 env 面),但
+    // 工厂是我们装配的、工厂 ctx 自带 taskId,包一层登记 taskId→env(destroy 时注销)即可,零 core 改动
+    // (withWorktreeIsolation 同款包装先例)。lane 门+租户门=sandboxSendLaneEnabled(判定依据在其 doc):
+    // e2b/k8s=一任务一沙箱(沙箱文件系统=租户边界)任意租户可用;ssh(后补 2026-07-14)=同一 exec 契约
+    // (timeout 秒×1000/Result shape 同形)直传链零适配,但 peer=一台跨任务共享的常驻真实主机
+    // (sshExecutionEnvFactory 忽略 ctx、destroy=断连不删文件、isolation:false)→「沙箱 scoped 读=租户
+    // 隔离」不成立,与 host 同门单用户 only(requirePrincipal!==true 恒关多租户,不留口子)。
+    // 其余 lane 不包(零开销);签发面未配同样不包。
+    const sendUserFileTaskEnvs = (() => {
+        const provider = config.remoteExec?.provider;
+        if (!config.sendUserFile || !executionEnvFactory || !sandboxSendLaneEnabled(provider, config.requirePrincipal))
+            return undefined;
+        const registry = new TaskEnvRegistry();
+        executionEnvFactory = registry.wrapFactory(executionEnvFactory);
+        return registry;
+    })();
+    // D-1 附件物化包装(半场③):env 每次建立(fresh + resume/重建沙箱)都把该 session 绑定的附件写进
+    // 工作目录 `attachments/`。全 lane 统一(host/e2b/k8s/ssh/adb 都走 factory;ExecutionEnv.writeFile
+    // 双向通用);路径与 objective 告知共用 materializedRelPaths(确定性,两处不漂)。**fail-loud**:
+    // objective 已向模型宣告文件在场,静默缺文件=模型按幻影文件行动,比任务失败更糟 ⇒ 写失败即抛
+    // (env 建立失败,任务带明确错误)。链尾最外层:worktree 隔离等内层先定 cwd,附件落在最终 cwd。
+    if (taskAttachmentStore && executionEnvFactory) {
+        const inner = executionEnvFactory;
+        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;
+        };
+    }
+    if (executionEnvFactory) {
+        // k8s (Kata) is isolated; it becomes WORKSPACE-suspendable when an S3 snapshot store is configured
+        // (tar→S3→fresh pod restore — files durable, in-VM memory not); e2b is fully suspendable.
+        const isolated = config.remoteExec.provider === "e2b" ||
+            config.remoteExec.provider === "k8s" ||
+            config.remoteExec.provider === "local-docker"; // a container is a real OS-level isolation boundary
+        const suspendable = config.remoteExec.provider === "e2b" ||
+            (config.remoteExec.provider === "k8s" && !!config.remoteExec.s3Snapshot);
+        // Out-of-band sandbox env (e2b): log the KEY NAMES only (never the secret values) so ops can confirm
+        // injection is active without leaking the credential.
+        const sandboxEnvKeys = config.remoteExec.provider === "e2b" ? Object.keys(config.remoteExec.sandboxEnv ?? {}) : [];
+        logger.info("remote_exec_enabled", { provider: config.remoteExec.provider, isolated, suspendable, ...(sandboxEnvKeys.length > 0 ? { sandboxEnvKeys } : {}) });
+        if (!isolated)
+            logger.warn("remote_exec_real_system", { provider: config.remoteExec.provider, note: "non-isolated target — actions are permanent; rely on the policy gate + HITL (design/61 §5)" });
+    }
+    // LSP sidecar (design/64 §13.1, the 1.86.2 seam): ONE stateless manager on RunnerDeps — core passes each
+    // task's env into sessionFor at the tool mount point, so the manager reaches the SAME sandbox the agent edits
+    // (no sessionId registry / per-task construction). Opt-in (LSP_ENABLED — the SANDBOX lane's knob; the host lane
+    // below has its own, LSP_HOST_ENABLED, because its default is the opposite); with the baked `sema-code-lsp`
+    // template the first call is fast, without it the language server installs on first use (slow once per sandbox).
+    // k8s lane (gate#2 alignment): same manager/bridge over the pod network — `ws://podIP:port` instead of E2B's
+    // public wss proxy, so it needs an IN-CLUSTER worker and a sandbox image with node + the language servers baked
+    // (no on-the-fly npm path on Kata; a miss degrades the lsp tool gracefully, same as E2B).
+    const lspProvider = config.remoteExec?.provider;
+    const lspManager = (lspProvider === "e2b" || lspProvider === "k8s") && config.lspEnabled
+        ? createE2bLspManager({ log: (event, fields) => logger.info(event, fields), scheme: lspProvider === "k8s" ? "ws" : "wss" })
+        : // TOC local LSP (core 1.190): the host lane runs on THIS machine, so core's `NodeLspManager` spawns the
+            // language server as a LOCAL child_process over stdio (CC `services/lsp` parity). Its default resolveRoot uses
+            // `env.cwd` — and core passes each task's executionEnv (the per-agent WORKTREE env, so the server roots in the
+            // worktree not the base repo) into sessionFor. host ONLY: ssh/adb target another host/device and local-docker a
+            // container, none of which a local child_process can reach (those keep the E2B-style bridge / stay degraded).
+            // 🔒 `requirePrincipal !== true` gate = uniform with the sibling host powers (scheduler/backgroundShell/
+            // loadProjectMemory): the host lane is single-user by design; a (discouraged) multi-tenant host fails SAFE to
+            // grep/read rather than fanning a per-tenant×language×root pool of heavy language servers (double-review B).
+            lspProvider === "host" && config.lspHostEnabled && config.requirePrincipal !== true
+                ? new NodeLspManager({ log: (event, fields) => logger.info(event, fields) })
+                : undefined;
+    if (lspManager)
+        logger.info("lsp_enabled", { provider: lspProvider });
+    return {
+        perTaskImage, sessionEnvSelection, perSessionCwd, setSessionCwd, setSessionShellEnv,
+        executionEnvFactory, worktreeReap, sendUserFileTaskEnvs, lspManager,
+    };
+}
+//# sourceMappingURL=execution-env.js.map

package/dist/boot/leader.d.ts

@@ -0,0 +1,27 @@
+/**
+ * design/158 A10:composition root 分段 —— v2 leader endpoint(design/50 + design/68)。
+ *
+ * 纯搬运:函数体逐字来自 `main.ts`(原 3094-3171 行),缩进不变;新增的只有 import 与包壳。
+ *
+ * ⚠️ **位置即契约**:必须在 `executionEnvFactory` / `checkpointStore` / `sessionStore` 都装配完之后调用
+ * (工厂模式的 k8s/host 腿以 `executionEnvFactory` 在场为门;durable 子 worker 挂 `checkpointStore`)。
+ */
+import type { ServiceConfig } from "../config.js";
+import type { createBrain } from "../brain.js";
+import type { buildPricing } from "../budget.js";
+import { createLeaderEndpoint } from "../leader/endpoint.js";
+import type { Logger } from "../observability/logger.js";
+import type { CheckpointStoreFull, StoreBackend, ToolResultStoreFull } from "../plugins/store-backend.js";
+import type { RunnerDeps } from "@sema-agent/core";
+export interface LeaderCtx {
+    config: ServiceConfig;
+    logger: Logger;
+    brain: ReturnType<typeof createBrain>;
+    pricing: ReturnType<typeof buildPricing>;
+    executionEnvFactory: RunnerDeps["executionEnvFactory"];
+    toolResultStore: ToolResultStoreFull | undefined;
+    sessionStore: ReturnType<StoreBackend["session"]>;
+    checkpointStore: CheckpointStoreFull | undefined;
+}
+export declare function createLeaderFace(ctx: LeaderCtx): ReturnType<typeof createLeaderEndpoint> | undefined;
+//# sourceMappingURL=leader.d.ts.map