@sema-agent/server 7.50.0 → 7.51.0

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

@@ -0,0 +1,79 @@
+/**
+ * design/158 A10 分段 —— **device lane 的装配件**(device-executor-lane-v2 §4.6/§4.7/§5,车A-4)。
+ *
+ * 一处建齐三件活对象:**店**(四表双库的 `DeviceStore`)→ **准入链**(`DeviceEnrollment`,含跨副本
+ * 限速座)→ **WS 汇聚端**(`DeviceWsHub`)。三件的依赖是单向的(hub 吃 store+enrollment),所以它们
+ * 必须在同一处按序建 —— 拆到三处装配点会让「hub 拿到的是不是同一只店」变成一个要读三个文件才答得出
+ * 的问题(而答错的后果是 presence 与租约各写各的)。
+ *
+ * ⚠️ **位置即契约**:必须在 `openStores`(拿 backend)之后、`createExecutionEnv`(第七臂要这三件)之前
+ * 调用;`attach(server)` 则要等 `createHttpServer` 造出裸 `http.Server` 之后(main.ts 的顺序)。
+ *
+ * 🔴 本模块**不**做车道选择:`REMOTE_EXEC=device` 与否由调用方判(main.ts)。它只回答一件事 ——
+ * 「这台机器上,device lane 的三件装配得起来吗」。装不起来就返回 `undefined`,由
+ * {@link assertDeviceLaneWired} 响亮拒启(#157:执行车道上没有静默降级臂)。
+ */
+import { type DeviceEnrollRateLimiter, type DeviceEnrollment } from "../device-enrollment.js";
+import type { DeviceStore } from "../device-store.js";
+import { type DeviceWsHub } from "../device-ws-hub.js";
+import type { ServiceConfig } from "../config.js";
+import type { Logger } from "../observability/logger.js";
+import type { Metrics } from "../observability/metrics.js";
+import type { RateGate } from "../observability/rate-limit.js";
+import type { StoreBackend } from "../plugins/store-backend.js";
+export interface DeviceLaneCtx {
+    config: ServiceConfig;
+    logger: Logger;
+    metrics: Metrics;
+    backend: StoreBackend | undefined;
+    /** 本副本 id(写进连接租约行 —— §4.6 的跨副本排障面)。 */
+    replicaId: string;
+    /**
+     * 既有的**跨副本** RateGate(SQL 后端形 = `TiDBRateLimiter`/`PgRateLimiter`;单副本形 = 进程内
+     * `RateLimiter`)。A-2 的移交义务③:enrollment 的限速不自建第二套计数面,适配这一只。
+     *
+     * 🔴 传的是**取值器**不是值:那一只建在 main.ts 的下游(它要 `counterDegradeHook`),而 device lane
+     * 必须建在 `createExecutionEnv` 之前 —— 顺序对不上。取值器让「谁先建」不再是正确性问题:boot 期
+     * 不可能有 enroll 请求,取不到 ⇒ 座**抛**(fail-closed,enrollment 翻成 429),不是放行。
+     */
+    rateGate?: (() => RateGate | undefined) | undefined;
+}
+export interface DeviceLane {
+    store: DeviceStore;
+    enrollment: DeviceEnrollment;
+    hub: DeviceWsHub;
+}
+/**
+ * 把既有的**同步** {@link RateGate} 适配成 enrollment 要的异步座(A-2 移交义务③)。
+ *
+ * 🔴 为什么是适配而不是新建一只:限速面在本仓已有属主(`observability/rate-limit.ts` + 两支 SQL 孪生),
+ * 而 SQL 孪生是**跨副本**的 —— enrollment 自带的 `createFixedWindowRateLimiter` 诚实地只是每副本窗
+ * (它自己的头注就这么写),对 token 撞库来说「N 个副本 = N 倍配额」。适配既有的那一只,撞库预算才是
+ * 全局的一份。
+ *
+ * 键前缀 `device-enroll:` 是必须的:RateGate 的键空间与 HTTP 面的 principal 键**共用一张表**,不加前缀
+ * 会让一次 enrollment 尝试吃掉调用方的普通请求配额(反过来也一样)。
+ */
+export declare function createDeviceEnrollRateLimiter(gate: () => RateGate | undefined): DeviceEnrollRateLimiter;
+/**
+ * 建齐 device lane 的三件。返回 `undefined` = **建不起来**(没有 SQL 后端 ⇒ 没有四表店)。
+ *
+ * 只在调用方判定本部署是 device 车道时调用;非 device 车道调用它是纯浪费(会白建一只 WS server)。
+ */
+export declare function createDeviceLane(ctx: DeviceLaneCtx): DeviceLane | undefined;
+/**
+ * **装配后**的拒启门(car A-1 的 `device-executor-unwired` 换来的真门;先例逐字 =
+ * `boot/leader.ts` 的 `assertLeaderDurableStore`)。
+ *
+ * config 层的门①判的是「运维配没配 SQL 坐标」——那句话回答的是**意图**。它回答不了「这次启动**真的
+ * 拿到**了店吗」:`openStoreBackendWithFallback` 在 `SESSION_BACKEND=auto`(默认)下,SQL 连不上 /
+ * 建表失败 ⇒ `backend=undefined` + 一条 warn 就继续启动。那次启动里 device lane 的四表整个不在,
+ * 而 `boot/execution-env.ts` 的第七臂拿不到三件 ⇒ `executionEnvFactory` 落 `undefined` ⇒ core 拿
+ * `StubExecutionEnv`:**一台自称在员工设备上执行的 worker 实际在自己进程里跑,而且回执同形**。
+ * 那正是 #157「执行车道禁静默降级」点名的样板病,也正是 A-1 那条临时门当初要拦的东西 —— 换执法点,
+ * 不是取消执法。
+ *
+ * 抛而不是 warn:降级的代价由用户承担(他以为命令跑在自己机器上、看到的却是云上一个空目录的结果)。
+ */
+export declare function assertDeviceLaneWired(isDeviceLane: boolean, lane: DeviceLane | undefined, hasFactory: boolean): void;
+//# sourceMappingURL=device-lane.d.ts.map

package/dist/boot/device-lane.js

@@ -0,0 +1,63 @@
+import { createDeviceEnrollment, createFixedWindowRateLimiter } from "../device-enrollment.js";
+import { createDeviceWsHub } from "../device-ws-hub.js";
+export function createDeviceEnrollRateLimiter(gate) {
+    return {
+        check: async (key) => {
+            const g = gate();
+            if (!g)
+                throw new Error("device enrollment rate gate is not wired yet (boot window) — refusing rather than admitting unmetered enrollment attempts");
+            const verdict = g.check(`device-enroll:${key}`);
+            return { allowed: verdict.allowed, retryAfterSec: verdict.retryAfterSec };
+        },
+    };
+}
+export function createDeviceLane(ctx) {
+    const { config, logger, metrics, backend, replicaId } = ctx;
+    const store = backend?.device?.();
+    if (!store)
+        return undefined;
+    const knobs = config.remoteExec?.provider === "device" ? config.remoteExec : undefined;
+    const enrollment = createDeviceEnrollment({
+        store,
+        ...(ctx.rateGate ? { rateLimiter: createDeviceEnrollRateLimiter(ctx.rateGate) } : { rateLimiter: createFixedWindowRateLimiter({ limit: 10, windowMs: 60_000 }) }),
+    });
+    const hub = createDeviceWsHub({
+        store,
+        enrollment,
+        replicaId,
+        logger: {
+            warn: (msg, fields) => logger.warn(msg, fields),
+            error: (msg, fields) => logger.error(msg, fields),
+            info: (msg, fields) => logger.info(msg, fields),
+        },
+        metrics: { inc: (name, labels) => metrics.inc(name, labels) },
+        ...(knobs?.deliveryTimeoutMs != null ? { dispatchTimeoutMs: knobs.deliveryTimeoutMs } : {}),
+        ...(knobs?.reconnectGraceMs != null ? { reconnectGraceMs: knobs.reconnectGraceMs } : {}),
+        ...(knobs?.maxInflightPerDevice != null ? { maxInflightPerDevice: knobs.maxInflightPerDevice } : {}),
+        ...(knobs?.supersede ? { supersede: knobs.supersede } : {}),
+    });
+    logger.info("device_lane_enabled", {
+        replicaId,
+        maxInflightPerDevice: knobs?.maxInflightPerDevice ?? 4,
+        crossReplicaEnrollRateLimit: ctx.rateGate !== undefined,
+    });
+    return { store, enrollment, hub };
+}
+export function assertDeviceLaneWired(isDeviceLane, lane, hasFactory) {
+    if (!isDeviceLane)
+        return;
+    if (!lane) {
+        throw new Error("REMOTE_EXEC=device but the device lane could not be wired at boot [device-lane-unwired]: the SQL backend is " +
+            "configured yet this replica did not get one (an unreachable DB / failed DDL degrades to the in-memory fallback " +
+            "when SESSION_BACKEND=auto), so the device registry / session↔device binding / audit tables are absent. " +
+            "Refusing to serve a lane that would silently fall back to the in-process stub env — a worker claiming to " +
+            "execute on the employee's device while actually running inside its own process (#157). Fix the database " +
+            "(or unset REMOTE_EXEC) and restart (device-executor-lane-v2 §4.7)");
+    }
+    if (!hasFactory) {
+        throw new Error("REMOTE_EXEC=device but no DeviceExecutionEnv factory was built [device-lane-unwired]: the lane's stores are up " +
+            "yet `boot/execution-env.ts` produced no factory, so core would fall back to the in-process stub env. This is " +
+            "an assembly bug, not a configuration one — refusing to start rather than silently execute in-process (#157)");
+    }
+}
+//# sourceMappingURL=device-lane.js.map

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

@@ -5,19 +5,65 @@ 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 { DeviceEnrollment } from "../device-enrollment.js";
+import type { DeviceStore } from "../device-store.js";
+import type { DeviceWsHub } from "../device-ws-hub.js";
 import { type TaskAttachmentStore } from "../plugins/task-attachment-store.js";
+/**
+ * per-session 的 **cwd / shellEnv 登记簿**(TOC cwd seam + R-survey shellEnv seam)+ 它们的**租户围栏**。
+ *
+ * ── 为什么围栏不是可选的(codex R1-F1,判真)────────────────────────────────────────────────────
+ * 这两张表只按 `sessionId` 键控。在 host lane 上那是安全的:那条车道的闸带 `requirePrincipal !== true`,
+ * 整台机器就一个用户。**device lane 把这个前提撤掉了** —— 它的闸(`deviceCwdHonored`)刻意不要求单用户
+ * (员工各连各的设备)。于是一条真实的越权路径出现了:
+ *   ① sessionId 由**调用方自选**,而且 `DELETE /v1/sessions/:id` 之后可以被**别人** `register` 重新登记
+ *      (`boot/session-faces.ts` 的化身围栏注逐字写着这件事);
+ *   ② 会话删除的级联删的是库里的行,**够不着这两张进程内的表**;
+ *   ③ 新主如果没有重发 `settings.env`,工厂读到的就是**上一位主人的** shell env —— 那是秘密面(NPM_TOKEN
+ *      一类),而且会被注进新主自己设备上的指令;cwd 也会跨化身残留。
+ *
+ * 所以围栏做在**身份已知**的那一处:每次提交经 resolve-spec 调 {@link SessionScopedRegistries.fenceSessionOwner}
+ * 对拍,换主即清。删除侧再加一条 {@link SessionScopedRegistries.dropSession}(E21 级联)——那条不是为了
+ * 关这个洞(读面必经提交、提交必过围栏),而是**右侧删除权**:一次删除之后,秘密不该还留在进程内存里。
+ *
+ * ⚠️ 诚实残余(如实登记,不假装关掉):两张表是**每副本进程内**的。围栏与清除都只在处理该请求/该删除的
+ * 那一个副本上发生。跨副本的陈值靠「读面必经本副本的一次提交 ⇒ 必过本副本的围栏」兜住 —— 这条推理成立
+ * 是因为 run 在受理它的那个副本上执行(ARCHITECTURE 副本模型)。device lane 的部署形本身也是单副本(§4.6)。
+ */
+export interface SessionScopedRegistries {
+    readonly perSessionCwd: Map<string, string>;
+    readonly perSessionShellEnv: Map<string, Record<string, string>>;
+    setSessionCwd(sid: string, cwd: string): void;
+    setSessionShellEnv(sid: string, env: Record<string, string>): void;
+    /** 记录/对拍本会话的主人。与上次不同 ⇒ **先清两张表**再记新主(换主即清)。`null` = 匿名会话,
+     *  它同样是一个**稳定**的身份值(不是「未知」),所以匿名重入不会被判成换主。 */
+    fenceSessionOwner(sid: string, owner: string | null): void;
+    /** 会话删除:两张表 + 身份记录一起清(留着身份记录会让同 id 的下一位与一个幽灵身份比对成「同主」)。 */
+    dropSession(sid: string): void;
+}
+export declare function createSessionScopedRegistries(maxEntries?: number): SessionScopedRegistries;
+/** device lane 的三件活对象(店 / 汇聚端 / 准入链)。缺席 = 本部署没有 device 车道。 */
+export interface DeviceLaneWiring {
+    store: DeviceStore;
+    hub: DeviceWsHub;
+    enrollment: DeviceEnrollment;
+}
 export interface ExecutionEnvCtx {
     config: ServiceConfig;
     logger: Logger;
     metrics: Metrics;
     taskAttachmentStore: TaskAttachmentStore | undefined;
+    /** 车A-4:device lane 的装配件(`REMOTE_EXEC=device` 且 SQL 店在场时由 main.ts 建好传进来)。 */
+    deviceLane?: DeviceLaneWiring;
 }
 export declare function createExecutionEnv(ctx: ExecutionEnvCtx): {
     perTaskImage: PerTaskImageRegistry;
     sessionEnvSelection: SessionEnvironmentSelection;
     perSessionCwd: Map<string, string>;
-    setSessionCwd: (sid: string, value: string) => void;
-    setSessionShellEnv: (sid: string, value: Record<string, string>) => void;
+    setSessionCwd: (sid: string, cwd: string) => void;
+    setSessionShellEnv: (sid: string, env: Record<string, string>) => void;
+    fenceSessionOwner: (sid: string, owner: string | null) => void;
+    dropSessionScoped: (sid: string) => void;
     executionEnvFactory: import("@sema-agent/core").ExecutionEnvFactory | undefined;
     worktreeReap: (() => Promise<void>) | undefined;
     sendUserFileTaskEnvs: TaskEnvRegistry | undefined;

package/dist/boot/execution-env.js

@@ -7,6 +7,7 @@ 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 { deviceExecutionEnvFactory } from "../plugins/remote-env-device.js";
 import { e2bExecutionEnvFactory } from "../plugins/remote-env-e2b.js";
 import { hostExecutionEnvFactory, RemoteHostExecutionEnv } from "../plugins/remote-env-host.js";
 import { k8sExecutionEnvFactory } from "../plugins/remote-env-k8s.js";
@@ -27,15 +28,51 @@ function boundedSessionSetter(map, maxEntries) {
             map.delete(map.keys().next().value);
     };
 }
+const MAX_CWD_SESSIONS = 4096;
+export function createSessionScopedRegistries(maxEntries = MAX_CWD_SESSIONS) {
+    const perSessionCwd = new Map();
+    const perSessionShellEnv = new Map();
+    const owners = new Map();
+    const dropSession = (sid) => {
+        perSessionCwd.delete(sid);
+        perSessionShellEnv.delete(sid);
+        owners.delete(sid);
+    };
+    const touch = (sid, owner) => {
+        const next = owner === undefined ? (owners.has(sid) ? owners.get(sid) : null) : owner;
+        owners.delete(sid);
+        owners.set(sid, next);
+        while (owners.size > maxEntries)
+            dropSession(owners.keys().next().value);
+    };
+    return {
+        perSessionCwd,
+        perSessionShellEnv,
+        setSessionCwd: (sid, cwd) => {
+            perSessionCwd.set(sid, cwd);
+            touch(sid, undefined);
+        },
+        setSessionShellEnv: (sid, env) => {
+            perSessionShellEnv.set(sid, env);
+            touch(sid, undefined);
+        },
+        fenceSessionOwner: (sid, owner) => {
+            if (owners.has(sid) && owners.get(sid) !== owner) {
+                perSessionCwd.delete(sid);
+                perSessionShellEnv.delete(sid);
+            }
+            touch(sid, owner);
+        },
+        dropSession,
+    };
+}
 export function createExecutionEnv(ctx) {
     const { config, logger, metrics, taskAttachmentStore } = ctx;
     const perTaskImage = new PerTaskImageRegistry();
     const sessionEnvSelection = new SessionEnvironmentSelection();
-    const MAX_CWD_SESSIONS = 4096;
-    const perSessionCwd = new Map();
-    const setSessionCwd = boundedSessionSetter(perSessionCwd, MAX_CWD_SESSIONS);
-    const perSessionShellEnv = new Map();
-    const setSessionShellEnv = boundedSessionSetter(perSessionShellEnv, MAX_CWD_SESSIONS);
+    const sessionScoped = createSessionScopedRegistries();
+    const { perSessionCwd, setSessionCwd } = sessionScoped;
+    const { perSessionShellEnv, setSessionShellEnv } = sessionScoped;
     let executionEnvFactory;
     let worktreeReap;
     if (config.remoteExec?.provider === "e2b") {
@@ -85,6 +122,19 @@ export function createExecutionEnv(ctx) {
             ...(config.remoteExec.hostKey !== undefined ? { hostKey: config.remoteExec.hostKey } : {}),
         });
     }
+    else if (config.remoteExec?.provider === "device") {
+        if (ctx.deviceLane) {
+            executionEnvFactory = deviceExecutionEnvFactory({
+                hub: ctx.deviceLane.hub,
+                store: ctx.deviceLane.store,
+                enrollment: ctx.deviceLane.enrollment,
+                ...(config.remoteExec.execTimeoutMs != null ? { execTimeoutMs: config.remoteExec.execTimeoutMs } : {}),
+                perSessionCwd,
+                perSessionShellEnv,
+                logger,
+            });
+        }
+    }
     else if (config.remoteExec?.provider === "adb") {
         executionEnvFactory = adbExecutionEnvFactory({
             serial: config.remoteExec.serial,
@@ -236,6 +286,8 @@ export function createExecutionEnv(ctx) {
         logger.info("lsp_enabled", { provider: lspProvider });
     return {
         perTaskImage, sessionEnvSelection, perSessionCwd, setSessionCwd, setSessionShellEnv,
+        fenceSessionOwner: sessionScoped.fenceSessionOwner,
+        dropSessionScoped: sessionScoped.dropSession,
         executionEnvFactory, worktreeReap, sendUserFileTaskEnvs, lspManager,
     };
 }

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

@@ -40,6 +40,9 @@ export interface ResolveSpecCtx {
     perSessionCwd: Map<string, string>;
     setSessionCwd: (sid: string, cwd: string) => void;
     setSessionShellEnv: (sid: string, env: Record<string, string>) => void;
+    /** 两张 per-session 登记簿的**租户围栏**(codex R1-F1):每次提交对拍本会话的主人,换主即清。
+     *  论证(为什么 device lane 把这条从「不需要」变成「必需」)逐字见 `createSessionScopedRegistries` 头注。 */
+    fenceSessionOwner: (sid: string, owner: string | null) => void;
     hookLlm: ReturnType<typeof createHookLlm>["hookLlm"];
     hookAgent: HookLlmCall;
     fleetBus: FleetEventBus;

package/dist/boot/resolve-spec.js

@@ -26,7 +26,7 @@ import { HttpError, encodeCheckpointScope } from "../security.js";
 import { memorySpecForRequest } from "../memory-scope.js";
 import { a2aForScenario, mcpForScenario } from "../config-center/facade.js";
 import { normalizeAttachments, normalizeResilience, normalizeResumeAtMode, normalizeSuggestNextPrompts, promptProfileFromBody, resolveTaskLimits, retainBackgroundProcessesFromBody, taskAgentsSpecFragment, toolMaterializeStrategyFromBody, toolNameListFromBody } from "../spec-fields.js";
-import { cwdHonored, effectiveHostWorkspace, inProcessSingleUserLane, isValidCwd, parseAdditionalDirectories, satisfiedByProcessCwd, shellEnvMismatchCount } from "../task-cwd.js";
+import { cwdHonored, deviceCwdHonored, effectiveHostWorkspace, inProcessSingleUserLane, isValidCwd, parseAdditionalDirectories, satisfiedByProcessCwd, shellEnvMismatchCount } from "../task-cwd.js";
 import { assertRequestA2aUnlocked, resolveRequestA2a } from "../task-a2a.js";
 import { assertRequestMcpContentOrigin, assertRequestMcpUnlocked, resolveRequestMcp } from "../task-mcp.js";
 import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, acceptAppendSystemPrompt, applyTaskSettings, effectivePermissionMode, effectiveThinking, hasConstitutionAnchors, parseTaskSettings, providerDropsAppend, shellGateForMode, withPermissionMode } from "../task-settings.js";
@@ -35,7 +35,7 @@ import { redactSecrets } from "../trace/redact.js";
 import { DeferredSandboxPathEnv, isSandboxPathAdjudicationLane, sandboxPathEnvSlots } from "./deferred-sandbox-path-env.js";
 import { effectiveMemoryPersistenceCapable } from "./memory-boundary.js";
 export function createResolveSpec(ctx) {
-    const { config, logger, metrics, localRoot, scenarios, principalCaps, centerRuntimeCapsResolver, handsLanes, getCenterPrompts, getKeyResolver, taskAttachmentStore, perSessionCwd, setSessionCwd, setSessionShellEnv, hookLlm, hookAgent, fleetBus, hookWakeBus, resumeAnchorStore, ownerAware, taskLimitCaps, taskTimeoutSec, selectEnvTool, sendUserFileToolSpec, memoryEngine, durableEnabled, approvalExemptionStore, singleUserAutoAcceptBaseline, checkpointStore, deploymentHooks, imageIndex, perTaskImage, sessionEnvSelection, liveQuestionFace, lockedKeys, } = ctx;
+    const { config, logger, metrics, localRoot, scenarios, principalCaps, centerRuntimeCapsResolver, handsLanes, getCenterPrompts, getKeyResolver, taskAttachmentStore, perSessionCwd, setSessionCwd, setSessionShellEnv, fenceSessionOwner, hookLlm, hookAgent, fleetBus, hookWakeBus, resumeAnchorStore, ownerAware, taskLimitCaps, taskTimeoutSec, selectEnvTool, sendUserFileToolSpec, memoryEngine, durableEnabled, approvalExemptionStore, singleUserAutoAcceptBaseline, checkpointStore, deploymentHooks, imageIndex, perTaskImage, sessionEnvSelection, liveQuestionFace, lockedKeys, } = ctx;
     assertGuardPatternsUsable(config);
     const onlySensitiveBaseline = buildOnlySensitiveBaselineWarning(config, { durableEnabled, singleUserAutoAcceptBaseline });
     if (onlySensitiveBaseline)
@@ -116,17 +116,20 @@ export function createResolveSpec(ctx) {
     };
     const bindSettingsCwdEnvAndModel = (body, auth, gated, effMode, opts) => {
         const { objective, parsedSettings } = gated;
+        const cwdWriteGate = cwdHonored(config) || deviceCwdHonored(config);
         const execLane = config.remoteExec?.provider ?? "in-process";
+        if (auth?.sessionId)
+            fenceSessionOwner(auth.sessionId, auth.principal ?? null);
         if (typeof body.cwd === "string" && body.cwd.length > 0 && auth?.sessionId) {
-            if (cwdHonored(config) && isValidCwd(body.cwd))
+            if (cwdWriteGate && isValidCwd(body.cwd))
                 setSessionCwd(auth.sessionId, body.cwd);
             else if (inProcessSingleUserLane(config) && isValidCwd(body.cwd) && satisfiedByProcessCwd(body.cwd, realpathSync))
                 logger.debug("task_cwd_inherited", { lane: execLane, sessionId: auth.sessionId });
             else
-                logger.warn("task_cwd_ignored", { honored: cwdHonored(config), lane: execLane, sessionId: auth.sessionId });
+                logger.warn("task_cwd_ignored", { honored: cwdWriteGate, lane: execLane, sessionId: auth.sessionId });
         }
         if (parsedSettings.settings?.shellEnv && auth?.sessionId) {
-            if (cwdHonored(config))
+            if (cwdWriteGate)
                 setSessionShellEnv(auth.sessionId, parsedSettings.settings.shellEnv);
             else if (inProcessSingleUserLane(config)) {
                 const requested = parsedSettings.settings.shellEnv;
@@ -204,22 +207,22 @@ export function createResolveSpec(ctx) {
         let resumeAtEntryId;
         if (typeof body.resumeAt === "string" && body.resumeAt.length > 0) {
             if (!auth?.sessionId)
-                throw new HttpError(422, "resumeAt requires a session to branch (resume_at.no_session)");
+                throw new HttpError(422, "resumeAt requires a session to branch (resume_at.no_session)", { code: "resume_at.no_session" });
             if (!resumeAnchorStore || !ownerAware.getLeafId)
                 throw new HttpError(501, "resume-at is not available on this worker (no session-store backend for the anchor map)");
             resumeAtEntryId = await resumeAnchorStore.resolve(auth.sessionId, body.resumeAt, auth.principal ?? null);
             if (resumeAtEntryId === undefined)
-                throw new HttpError(404, "resumeAt: no such message in this session (resume_at.unknown_event)");
+                throw new HttpError(404, "resumeAt: no such message in this session (resume_at.unknown_event)", { code: "resume_at.unknown_event" });
         }
         let rewindFilesToEntryId;
         if (resumeAtEntryId === undefined && typeof body.rewindFilesTo === "string" && body.rewindFilesTo.length > 0) {
             if (!auth?.sessionId)
-                throw new HttpError(422, "rewindFilesTo requires a session (rewind_files_to.no_session)");
+                throw new HttpError(422, "rewindFilesTo requires a session (rewind_files_to.no_session)", { code: "rewind_files_to.no_session" });
             if (!resumeAnchorStore || !ownerAware.getLeafId)
                 throw new HttpError(501, "rewind-files-to is not available on this worker (no session-store backend for the anchor map)");
             rewindFilesToEntryId = await resumeAnchorStore.resolve(auth.sessionId, body.rewindFilesTo, auth.principal ?? null);
             if (rewindFilesToEntryId === undefined)
-                throw new HttpError(404, "rewindFilesTo: no such message in this session (rewind_files_to.unknown_event)");
+                throw new HttpError(404, "rewindFilesTo: no such message in this session (rewind_files_to.unknown_event)", { code: "rewind_files_to.unknown_event" });
         }
         const s4ProjectId = auth?.resolvedProjectId ?? (typeof body.projectId === "string" && body.projectId ? body.projectId.toLowerCase() : undefined);
         const s4DefaultScopes = s4ProjectId ? config.projects[s4ProjectId]?.defaultScopes : undefined;

package/dist/boot/session-faces.d.ts

@@ -6,6 +6,7 @@ import { PlanCacheProbe } from "../plan-cache-probe.js";
 import type { CheckpointStoreFull, StoreBackend, ToolResultStoreFull } from "../plugins/store-backend.js";
 import type { TaskAttachmentStore } from "../plugins/task-attachment-store.js";
 import type { OwnerAwareSessionStore } from "../security.js";
+import type { DeviceStore } from "../device-store.js";
 import { SessionWatchRegistry } from "../session-watch.js";
 import type { TaskListLane } from "./task-list-lane.js";
 export interface SessionFacesCtx {
@@ -26,6 +27,10 @@ export interface SessionFacesCtx {
     workflowCompletionInbox: WorkflowCompletionInbox | undefined;
     /** #318:会话级任务清单车道(E21 级联的一条腿)。缺席 = 装配未接本车道 ⇒ 无清单可删。 */
     taskListLane: TaskListLane | undefined;
+    /** device lane 的四表店(E21 级联的一条腿:`device_session` 绑定行随会话删)。缺席 = 非 SQL 后端。 */
+    deviceStore: DeviceStore | undefined;
+    /** per-session cwd/shellEnv 登记簿的清除口(E21 级联的一条腿,codex R1-F1)。缺席 = 装配未接。 */
+    dropSessionScoped: ((sid: string) => void) | undefined;
 }
 export declare function createSessionFaces(ctx: SessionFacesCtx): {
     ownerAware: OwnerAwareSessionStore;

package/dist/boot/session-faces.js

@@ -6,7 +6,7 @@ import { setLeafAdvanceListener } from "../session-leaf-bus.js";
 import { SessionWatchRegistry, posIntEnv } from "../session-watch.js";
 import { defaultTaskRegistry } from "@sema-agent/core";
 export function createSessionFaces(ctx) {
-    const { config, logger, metrics, localRoot, backend, sessionStore, runStore, checkpointStore, toolResultStore, resumeAnchorStore, approvalExemptionStore, sessionPolicyStore, taskAttachmentStore, fileSnapshotStore, workflowCompletionInbox, taskListLane, } = ctx;
+    const { config, logger, metrics, localRoot, backend, sessionStore, runStore, checkpointStore, toolResultStore, resumeAnchorStore, approvalExemptionStore, sessionPolicyStore, taskAttachmentStore, fileSnapshotStore, workflowCompletionInbox, taskListLane, deviceStore, dropSessionScoped, } = ctx;
     const mysqlPool = backend?.mysqlPool();
     const auditPgPool = backend?.pgPool();
     const auditLocalRoot = backend?.kind === "local" ? (config.localDataRoot ?? localRoot) : undefined;
@@ -63,6 +63,9 @@ export function createSessionFaces(ctx) {
                 await taskAttachmentStore.deleteBySession(sessionId);
             if (taskListLane)
                 await taskListLane.deleteBySession(sessionId);
+            if (deviceStore)
+                await deviceStore.deleteByRootSession(sessionId);
+            dropSessionScoped?.(sessionId);
             if (fileSnapshotStore?.deleteBySession)
                 await fileSnapshotStore.deleteBySession(sessionId);
             if (workflowCompletionInbox)

package/dist/boot/shutdown.d.ts

@@ -72,6 +72,14 @@ export interface ShutdownCtx {
     storeLiveProbe: {
         stop(): void;
     } | undefined;
+    /**
+     * device lane 的 WS 汇聚端(§8-R7 发版排空,车A-4)。缺席 = 本部署没有 device 车道。
+     *
+     * 🔴 排空联动**必须**由装配层驱动(`http/server.ts` 的 `deviceHub` 键头注逐字):§8-R7 的顺序
+     * (新提交 503 → 新 upgrade 拒 → 停发新指令 → 在途结果照收 → 才断连)是**部署编排**的语义,
+     * HTTP 层不能自作主张。所以 `drainState.draining` 翻真的那一刻,这里同步调 `beginDrain()`。
+     */
+    deviceHub: import("../device-ws-hub.js").DeviceWsHub | undefined;
     /** #131-2:config 60s 刷新环(config-center startRefreshLoop)——不停的话停机中途还可能热应用
      *  一份新配置。缺席 = 纯 env 部署没起环。 */
     configCenter: {

package/dist/boot/shutdown.js

@@ -5,7 +5,7 @@ import { createParentWatch } from "../parent-watch.js";
 import { createEngineLeaseTracker } from "./engine-lease.js";
 import { isScriptRealmRejection, describeRejectionReason } from "../orchestration/hardened-vm-runner.js";
 export function installShutdownHandlers(ctx) {
-    const { config, logger, server, reaper, fleetReconcile, retentionLane, releaseRetentionLease, otelExporter, breakerState, costQuota, rateLimiter, runner, subRunner, lspManager, workflowNotifyJournal, fleetClient, backend, drainState, storeLiveProbe, configCenter, version, } = ctx;
+    const { config, logger, server, reaper, fleetReconcile, retentionLane, releaseRetentionLease, otelExporter, breakerState, costQuota, rateLimiter, runner, subRunner, lspManager, workflowNotifyJournal, fleetClient, backend, drainState, storeLiveProbe, configCenter, version, deviceHub, } = ctx;
     const dataRoot = config.localDataRoot;
     if (dataRoot) {
         const prior = readCrashLast(dataRoot);
@@ -66,6 +66,7 @@ export function installShutdownHandlers(ctx) {
         parentWatch?.stop();
         engineLease?.stop();
         storeLiveProbe?.stop();
+        void deviceHub?.close().catch((err) => logger.warn("device_hub_close_failed", { err: String(err) }));
         configCenter?.stopRefreshLoop();
         otelExporter?.stop();
         breakerState?.stop();
@@ -107,6 +108,7 @@ export function installShutdownHandlers(ctx) {
         }
         draining = true;
         drainState.draining = true;
+        deviceHub?.beginDrain();
         drainState.since = Date.now();
         void fleetClient?.announceNow();
         const inflight = drainState.inflight?.() ?? 0;

package/dist/boot/stores.js

@@ -17,6 +17,7 @@ import { PgTaskAttachmentStore, TiDBTaskAttachmentStore, ensurePgTaskAttachmentS
 import { createSessionStore } from "../plugins/session-store.js";
 import { createTaskListLane } from "./task-list-lane.js";
 import { ensurePgTaskListSchema, ensureTiDBTaskListSchema } from "../plugins/task-list-store-sql.js";
+import { ensurePgDeviceSchema, ensureTiDBDeviceSchema } from "../plugins/device-store-sql.js";
 import { assertCloudSnapshotBlobPosture, openStoreBackendWithFallback } from "../plugins/store-backend.js";
 import { buildMemoryRemoteLaneWarn, memoryEngineBackendFor, memoryEngineRemoteLanePosture } from "../memory-scope.js";
 import { assertToolResultProvenanceSchema } from "../plugins/tool-result-store-sql.js";
@@ -343,6 +344,14 @@ export async function openStores(ctx) {
             await ensureTiDBTaskListSchema(mysqlPool);
         return createTaskListLane({ mysqlPool, pgPool, logger });
     })();
+    {
+        const mysqlPool = backend?.mysqlPool?.();
+        const pgPool = backend?.pgPool?.();
+        if (pgPool)
+            await ensurePgDeviceSchema(async (text, params) => pgPool.query(text, params));
+        if (mysqlPool)
+            await ensureTiDBDeviceSchema(mysqlPool);
+    }
     const sessionStore = createSessionStore(config, backend, metrics);
     if (config.requirePrincipal && backend?.kind === "local") {
         throw new Error("REQUIRE_PRINCIPAL=true is not supported on the local file backend (DB_BACKEND=local): session/run CONTENT is " +

package/dist/config-center/types.d.ts

@@ -353,10 +353,17 @@ export interface EffectiveConfig {
 /** (stage7 P5,registry-core 0.8 `execution` 域): the center-resolved per-principal execution
  *  ruling riding the caps view. `required=false` / ruling absent = no enforcement (legacy). `allowedLanes` is
  *  an OPEN value domain (adding one is never BREAKING; consumers tolerate unknown names). Known lane names:
- *  `host`/`e2b`/`k8s`/`ssh`/`adb`/`local-docker` (the REMOTE_EXEC providers) **plus `in-process`** — the
- *  REMOTE_EXEC-unset fleet posture (OA/review-style workers; named distinctly from the explicit
+ *  `host`/`e2b`/`k8s`/`ssh`/`adb`/`local-docker`/`device` (the REMOTE_EXEC providers) **plus `in-process`**
+ *  — the REMOTE_EXEC-unset fleet posture (OA/review-style workers; named distinctly from the explicit
  *  `host` lane on purpose). ⚠️ Admins writing `required=true` policies must include `in-process` when such
- *  workers should stay admittable — center UI/doc 词表待补齐。 */
+ *  workers should stay admittable — center UI/doc 词表待补齐。
+ *
+ *  🔴 **`device` 是 per-principal 执行面上最需要写清的一条**(device-executor-lane-v2 §4.1 的 config-center
+ *  行,车A-4 补):它是「在**员工自己的机器**上执行」的那条车道 —— 允许它 ≠ 允许一台云沙箱,而是允许
+ *  这个 principal 把裁决过的指令投到一台**受管设备**上。⚠️ 但**别把它当设备准入门用**:本 ruling 的
+ *  粒度是 lane 名,它表达不了 principal×device 绑定,而且 no-ruling 是 **fail-open** 的
+ *  (`runtime-caps-resolver.ts` 的 P 类债)。device lane 的真准入是自建的 fail-closed 查表
+ *  (绑定行 owner 谓词 + 设备 active + presence,§4.3.2)—— center 白名单是**外加**的一层,不是替代。 */
 export interface ExecutionRuling {
     required: boolean;
     allowedLanes: string[];

package/dist/config-invariants.d.ts

@@ -28,9 +28,9 @@ import type { ServiceConfigFlat } from "./config-types.js";
  */
 export declare const LIVENESS_HEARTBEAT_MS = 30000;
 /** 闭集:新增一条不变量必须在这里加词(拼错 = 编译红,而不是运行期悄悄不判)。 */
-export type CrossInvariantId = "run-stale-heartbeat" | "bind-posture" | "bake-runner-credential" | "direct-door-anchors" | "operator-principals-required" | "bake-operator-principals" | "sensitive-write-patterns" | "leader-host-lane" | "leader-durable-store";
+export type CrossInvariantId = "run-stale-heartbeat" | "bind-posture" | "bake-runner-credential" | "direct-door-anchors" | "operator-principals-required" | "bake-operator-principals" | "sensitive-write-patterns" | "leader-host-lane" | "leader-durable-store" | "device-durable-store" | "device-durable-approval";
 /** 表读的键集(取自平铺配置型 ⇒ 键名/类型永不与真配置漂)。 */
-export type CrossInvariantView = Readonly<Pick<ServiceConfigFlat, "runStaleSec" | "authToken" | "authTokens" | "allowUnauthedWrites" | "imageBakes" | "directApprovalDoor" | "durableApproval" | "approvalHmacKeys" | "principalJwtPubkeys" | "principalJwtIss" | "principalJwtAud" | "requirePrincipal" | "operatorPrincipals" | "sensitiveWritePatterns" | "leaderEnabled" | "remoteExec" | "dbBackend">>;
+export type CrossInvariantView = Readonly<Pick<ServiceConfigFlat, "runStaleSec" | "authToken" | "authTokens" | "allowUnauthedWrites" | "imageBakes" | "directApprovalDoor" | "durableApproval" | "approvalHmacKeys" | "principalJwtPubkeys" | "principalJwtIss" | "principalJwtAud" | "requirePrincipal" | "operatorPrincipals" | "sensitiveWritePatterns" | "leaderEnabled" | "remoteExec" | "dbBackend" | "tidb" | "pg">>;
 export interface CrossInvariantInput {
     /** 现役配置(boot 期 = 候选自身)。 */
     readonly live: CrossInvariantView;

package/dist/config-invariants.js

@@ -111,6 +111,24 @@ export const CONFIG_CROSS_INVARIANTS = [
             ? `LEADER_ENABLED with DB_BACKEND=${next.dbBackend} (no external SQL store) degrades the leader-run registry to a per-process Map`
             : undefined,
     },
+    {
+        id: "device-durable-store",
+        keys: ["remoteExec", "dbBackend", "tidb", "pg"],
+        restartReason: "device-lane",
+        bootAnchor: { file: "src/config.ts", marker: "CROSS-INVARIANT:device-durable-store" },
+        check: ({ next }) => next.remoteExec?.provider === "device" && !((next.dbBackend === "mysql" && next.tidb !== undefined) || (next.dbBackend === "pg" && next.pg !== undefined))
+            ? `REMOTE_EXEC=device with DB_BACKEND=${next.dbBackend} and no SQL connection coordinates leaves the device registry/binding/audit in a per-process map — a restart forgets which device a parked run must resume onto (DB_BACKEND alone is only an engine selector)`
+            : undefined,
+    },
+    {
+        id: "device-durable-approval",
+        keys: ["remoteExec", "durableApproval"],
+        restartReason: "device-lane",
+        bootAnchor: { file: "src/config.ts", marker: "CROSS-INVARIANT:device-durable-approval" },
+        check: ({ next }) => next.remoteExec?.provider === "device" && !next.durableApproval
+            ? "REMOTE_EXEC=device without DURABLE_APPROVAL=true has no park exit for an approval that outlives the device's offline window"
+            : undefined,
+    },
 ];
 export function checkCrossInvariants(input) {
     for (const inv of CONFIG_CROSS_INVARIANTS) {

package/dist/config-types.d.ts

@@ -577,6 +577,18 @@ export interface ServiceConfigFlat {
         provider: "host";
         workspaceBase?: string;
         commandTimeoutMs?: number;
+    } | {
+        provider: "device";
+        /** `DEVICE_DELIVERY_TIMEOUT_MS`(默认 10s)= 等在途槽的上限;到期 = `device.busy`(§5.5)。 */
+        deliveryTimeoutMs?: number;
+        /** `DEVICE_RECONNECT_GRACE_MS`(默认 120s)= 断连后在途不判丢的窗(§5.4 同 epoch 重连)。 */
+        reconnectGraceMs?: number;
+        /** `DEVICE_EXEC_TIMEOUT_MS`(默认 1800s)= 指令级默认超时;core 的 per-command `timeout` 可收紧。 */
+        execTimeoutMs?: number;
+        /** `DEVICE_MAX_INFLIGHT_PER_DEVICE`(§11-O3 clay 已裁 = 4)。 */
+        maxInflightPerDevice?: number;
+        /** `DEVICE_SUPERSEDE`(默认 `stale_only`)= 同 deviceId 二连的顶替策略(§5.2)。 */
+        supersede?: "stale_only" | "deny";
     } | {
         provider: "local-docker";
         image: string;