@sema-agent/server 7.49.0 → 7.51.0

package/USAGE.md

@@ -554,6 +554,45 @@ SEMA_PARENT_PID=$$      # 壳把自己的 pid 传给它 spawn 出来的引擎
   PID 1 是典型;终端 / launchd / systemd 不在此列),pid 表项仍在,探活同样判"活着"。两条同源:
   `kill(pid, 0)` 是**弱身份**判据。这条腿是**尽力自愈**,不是强一致的父子生命周期绑定。
 
+**可选 — 附着租约自退(`ENGINE_AUTO_EXIT`,默认关)**
+
+上一节那条腿盯的是「**生我的那个 pid** 还在吗」。多个壳会话共享**同一只**引擎时它问错了问题:首壳退了、
+peer 还在用。这条腿问的是那个真正的问题 —— **还有没有人附着**。
+
+```bash
+ENGINE_AUTO_EXIT=true    # 壳 spawn 引擎时注入;服务器部署**不要**设
+ENGINE_LINGER_MS=60000   # 可选,默认 60s,下界 1000
+```
+
+- **默认 `false` = 整件不装配**,存量部署逐字零变化。一台 k8s 上的 replica 半夜没人用是**正常低谷**,
+  不是「该退了」;自退只对**壳自 spawn 的本机引擎**有意义,所以由壳在 spawn 时显式打开。
+- **自退判据 = 三合取,且必须连续满 `ENGINE_LINGER_MS`**:① 没有附着的 SSE 流;② 没有在飞的 run
+  (与 `/health` 的 `inflight` **同一个读数**);③ 没有非探针 HTTP 触点(`/health`、`/metrics*` 不算 ——
+  探针不是「有人在用」),**且**最后一条附着流断开也已满窗。任何一条不满足即把计时**清零**。
+  (最后那半句不是修辞:一条活得比 15s 拍频还短的流整个生命周期都落在两拍之间,自查腿从没看见过它 ——
+  只有在**关闭点**记一笔离场时刻,「已经没人附着满 N 秒」才是精确的。)
+- **「run 在跑就不退」是结构性保护,没有旋钮可以关掉它** —— 最后一个壳关掉、后台 run 还在烧的场景里,
+  引擎必须活到那条 run 落地。
+- **`ENGINE_LINGER_MS` 防的是壳重启窗**:壳崩了/重启的 1-3s 里附着数确实是 0,窗太短就在用户眼皮底下
+  把引擎杀了。窗内任何一次重连即清零重新起算。
+- **实际等待 = `[ENGINE_LINGER_MS, ENGINE_LINGER_MS + 15s)`**:自查拍频固定 15s(不开旋钮),最后一条
+  租约灭在两拍之间时要到下一拍才被看见。方向是**保守**的(只会等更久)。
+- 判死后走的是**和 `SIGTERM` 逐字同一条**优雅排空腿:拒新提交(503 + `Retry-After`)→ 候在途腿跑完 →
+  停机。in-flight 的 run 照常结算 / park,**不是**裸退出;而且因为是受控退,`crash-last.json` 会被清掉
+  ⇒ 下次启动**不会**把这次自退误读成崩溃。
+- 日志:装配时一行 `engine_lease_armed`(带 `lingerMs`),自退时一行 `engine_lease_auto_exit`
+  (带 `attached` / `inflight` / `idleForMs` 三个读数),随后就是那条 `draining_started`。
+- **坏值拒启**:`ENGINE_LINGER_MS` 必须是落在 **`[1000, 86400000]`(1s…24h)** 的整数毫秒,**两端都承重**:
+  下界防 `ENGINE_LINGER_MS=60`(以为单位是秒)—— 60ms 的窗等于把整条防误杀腿静默摘掉;上界防 `1e100`
+  这类值 —— 它能过朴素的「是正整数吗」检查,而计时**永远追不上它**,于是配置看着好好的、自退其实整件
+  失效。两端一律**拒启并指路**而不是夹取。本键**没有**「关掉」的取值 —— 关自退的唯一开关是
+  `ENGINE_AUTO_EXIT=false`。校验**不看** `ENGINE_AUTO_EXIT` 的表态:否则手滑值可以在一台今天关着自退的
+  机器上一直躺着,等哪天有人打开时当场生效。
+- 🔴 **已知收窄(成文,现版不收)**:**parked-待赎回** 的 run 不在判据里,只看 running。数 parked 要发
+  SQL,而这是一只每 15s 无限期跑下去的定时器 —— 不值得为它引入周期性 SQL 轮询。parked 行是 **durable**
+  的,引擎退掉不丢:下次起来(壳的下一次 spawn)仍可赎回,伤害面是**赎回被推迟**而不是丢失。
+- 与 `SEMA_PARENT_PID` 是**两件**,可以同时设,各走各的判据。
+
 **布尔旋钮的取值与极性(运维必读)**
 
 布尔 env **只认 `true` / `false` 两个字面量**。写成 `1` / `yes` / `TRUE` ⇒ 该旋钮退回自己的缺省值,并在启动时

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/engine-lease.d.ts

@@ -0,0 +1,95 @@
+/**
+ * #118(黑板 [5371]②,cli [5394] 认领消费)—— 引擎**附着租约自退**。
+ *
+ * ## 防的是什么
+ *
+ * 壳自 spawn 引擎的本机形里,壳正常退出之后引擎**继续活着**:占端口、占库连接池、占模型配额,而且
+ * 用户已经离开了、再没有人会关心它。#219 的 parent 监视只覆盖「生我的那个 pid 没了」这一形,而
+ * **多壳共享一只引擎**时它结构性地问错了问题 —— 首壳退了 peer 还在用,监视父 pid 要么误杀要么永不触发。
+ * 本件问的是那个真正的问题:**还有没有人附着**。
+ *
+ * ## 机制(逐条都是契约)
+ *
+ *  1. **opt-in**:`ENGINE_AUTO_EXIT` 默认 **false** ⇒ 整件不装配(`boot/shutdown.ts` 连本函数都不调)。
+ *     服务器部署形逐字零变化 —— 一台 k8s 上的 replica 半夜没人用不是「该退了」,是**正常的低谷**。
+ *     壳 spawn 形由壳在 spawn 时显式注入 `true`。**部署级旋钮无条件生效**:它不派生自任何客户端表态
+ *     (本仓 operator-knob 铁律,#153 同病两犯史),`ENGINE_LINGER_MS` 的坏值校验也不挂在本键的表态上。
+ *  2. **自退判据 = 三合取,且必须持续满 `lingerMs`**:
+ *       · 附着租约集空(`attachedStreams() === 0`);
+ *       · 无在飞 run(`inflight() === 0` —— **与 /health 的 `inflight` 同一只 getter**,不另立第二判据);
+ *       · HTTP 触点静默(`now() - lastActivityAt() >= lingerMs`),**且**最后一条附着流的**离场**
+ *         也已满窗(`now() - lastAttachEndedAt() >= lingerMs` —— codex R1-F1,见该 dep 的注)。
+ *     任何一条不满足即把计时清零(连续性判据,不是累计)。
+ *  3. **为什么 HTTP 触点是独立的第三条**(不是冗余):纯轮询壳(零 SSE,每 2s 一次 `GET /v1/sessions`)
+ *     的请求是毫秒级的,而本腿 15s 采样一拍 —— 采样点几乎必然落在两次轮询之间,`attached` 与
+ *     `inflight` **同时读到 0**。只看那两条的实现会在一只**正被使用**的引擎底下把它关掉。租约的
+ *     建立面按设计就是「首个 HTTP/SSE 接触」,不只是 SSE。
+ *  4. **退出 = 走 `drain`**,即 `boot/shutdown.ts` 里 SIGTERM 用的那一条 `drainThenShutdown`:拒新提交
+ *     (503+Retry-After)→ 候在途腿跑完 → `hardShutdown`。in-flight run 的结算 / park 语义与人工停机
+ *     **逐字一致**。本模块自己**从不** `process.exit`。
+ *  5. **crash-last 判别位**([5371] ④「flush 判别位标 auto-exit 非崩溃」):走上面那条受控退,
+ *     `hardShutdown` 一进来就 `clearCrashLast` ⇒ 遗言文件被删 ⇒「文件在场 ⇔ 上次退出=崩溃」这条契约
+ *     对自退**自动成立**。刻意**不**另写一条 `reason:"auto-exit"` 的遗言行:那会把该文件的语义从
+ *     「崩溃判别位」稀释成「上次退出记录」,而运维读它就是为了判前者(见 `crash-last.ts` 顶注)。
+ *     自退的可观察面是 `engine_lease_auto_exit` + 随后的 `draining_started` 两行日志。
+ *  6. **interval 必须 unref**:自退检查腿不得成为「进程本该退出却退不掉」的理由(与 drain tick 刻意
+ *     不 unref 的取向相反 —— 那一只 tick 就是停机驱动,这一只只是观察者)。
+ *  7. **装配即起算**:armed 那一刻若已空闲,计时**当场**开始。覆盖的是「壳 spawn 了引擎,自己却在
+ *     第一次接触之前就崩了」这一形 —— 那只引擎一辈子没有过租约,正是本件要收的孤儿。
+ *  8. **实际窗 = `[lingerMs, lingerMs + tickMs)`**(采样腿的固有滞后,成文而非隐藏):最后一条租约是在
+ *     **两拍之间**灭的,本腿要到下一拍才看见,空闲计时从**那一拍**起表。⇒ 真实等待比 `lingerMs` 多出
+ *     0~1 拍。方向是**保守**的(等得更久,不会更早),所以不修 —— 要修就得让 SSE 关闭点反向通知本腿,
+ *     那是把一只自洽的观察者改成有状态的被通知者,不值当。运维读数以 `engine_lease_auto_exit.idleForMs`
+ *     为准(它报的是真实空闲时长,不是 `lingerMs`)。
+ *
+ * ## 已知收窄(成文,现版不收)
+ *
+ *  · **parked-待赎回 run 不入判据**:设计稿 ② 原文含「无 running/parked-待赎回 run」,本版**只看
+ *    running**。理由 = 廉价读口不存在:parked 是 store 里的**durable 行**,数它必须发 SQL,而本腿是一只
+ *    每 15s 无限期跑下去的定时器 —— 为它引入周期性 SQL 轮询,代价压过收益。**bg run 在跑不退**那一臂
+ *    已由 `inflight()` 结构性守住;parked 行是 durable 的,引擎退掉不丢:下次起来仍可赎回(spawn 形里
+ *    「下次」就是壳的下一次 spawn)。伤害面 = 一条 parked run 的赎回被推迟到下次启动,不是丢失。
+ *    这是**允许的收窄,不是静默**:有了廉价 parked 计数口(或本腿改成事件驱动)之后应当补上。
+ *  · **`/health` 探针不算触点**:`lastActivityAt` 的属主(`http/server.ts` 的 `noteActivity`)按既有契约
+ *    把 `/health` 与 `/metrics*` 排除在活性时钟之外(常态采样噪音不得把空闲窗永远撑开)。⇒ 一只**只**
+ *    轮询 `/health` 的壳不构成租约。这与 SIGHUP 空闲窗的判据同源,刻意保持一致而非在本腿另开一份。
+ */
+/** 自退检查拍频。**固定值,不开 env 旋钮**(与 `PARENT_WATCH_INTERVAL_MS` 同纪律:有真需求再议,防旋钮增殖)。 */
+export declare const ENGINE_LEASE_TICK_MS = 15000;
+export interface EngineLeaseDeps {
+    /** 活附着数 = 本副本当前**打开着的 SSE 流**条数(`drainState.attachedStreams`,由 `createHttpServer` 自赋)。 */
+    attachedStreams: () => number;
+    /** 在飞腿数 —— **`/health` 的 `inflight` 同一只 getter**(`drainState.inflight`)。不自建第二套计数:
+     *  两套计数迟早分叉,而分叉的那一侧恰好是「以为没 run 了」就把引擎关掉。 */
+    inflight: () => number;
+    /** 最后一次**非探针** HTTP 触点的单调时刻(`drainState.lastActivityAt`)。
+     *  ⚠️ 时基契约:必须与本模块的 `now` 同为 `performance.now()` 单调域(`server.ts` 的打点即该域)——
+     *  混入 `Date.now()` 会让 `now() - lastActivityAt` 差出 epoch 量级,静默判据恒真。 */
+    lastActivityAt: () => number;
+    /** 最后一条**附着流断开**的单调时刻(`drainState.lastAttachEndedAt`)。
+     *
+     *  🔴 codex 对抗复审 R1-F1(验真后修):`attachedStreams` 是**采样**面,`lastActivityAt` 记的是
+     *  **入场**(admission)时刻 —— 两者合起来仍漏一个形:一条**整个生命周期都落在两拍之间**的流
+     *  (活得比拍频短)从没被任何一拍看见,于是 `idleSince` 保持着这条流出现**之前**的旧值,而
+     *  「已经没人附着满 lingerMs」这句承诺可以提前至多一整拍兑现。补这条**离场**触点之后,判据变成
+     *  精确的「距最后一次附着结束已满 lingerMs」。缺席(0)= 本进程还没有过附着流结束。 */
+    lastAttachEndedAt: () => number;
+    /** 已有停机属主(`closing || draining`)时本腿站下:一次正在进行的优雅 drain 不该被「也没人附着了」
+     *  升级成第二信号硬停(那会斩掉 in-flight leg)。 */
+    isStopped: () => boolean;
+    /** 自退出口 = SIGTERM 那条 graceful drain(见顶注 4/5)。 */
+    drain: () => void;
+    /** 三合取**持续**满这么久才触发(`config.engineLingerMs`,默认 60s)。 */
+    lingerMs: number;
+    log: (event: string, fields: Record<string, unknown>) => void;
+    /** 检查拍频 seam(测试)。缺省 {@link ENGINE_LEASE_TICK_MS}。 */
+    tickMs?: number;
+    /** 时钟 seam,缺省 `() => performance.now()`(**单调**域)。用 `Date.now()` 会让 NTP/手动跳变吞掉或
+     *  拉长 linger 窗 —— 前跳把窗直接跳过去 = 在一只还有人用的引擎底下提前关停。 */
+    now?: () => number;
+}
+/** 装配并**立刻**起自退检查(装配即 `engine_lease_armed`)。返回停机链用的 `stop()`。 */
+export declare function createEngineLeaseTracker(deps: EngineLeaseDeps): {
+    stop(): void;
+};
+//# sourceMappingURL=engine-lease.d.ts.map

package/dist/boot/engine-lease.js

@@ -0,0 +1,56 @@
+export const ENGINE_LEASE_TICK_MS = 15_000;
+export function createEngineLeaseTracker(deps) {
+    const tickMs = deps.tickMs ?? ENGINE_LEASE_TICK_MS;
+    const now = deps.now ?? (() => performance.now());
+    let stopped = false;
+    let idleSince = now();
+    deps.log("engine_lease_armed", {
+        lingerMs: deps.lingerMs,
+        tickMs,
+        note: "engine self-exits once NO shell session is attached AND no run is in flight AND no HTTP touch, " +
+            "continuously for lingerMs — via the same graceful drain as SIGTERM. Set ENGINE_AUTO_EXIT=false to disable.",
+    });
+    const timer = setInterval(() => {
+        if (stopped)
+            return;
+        if (deps.isStopped()) {
+            stop();
+            return;
+        }
+        const attached = deps.attachedStreams();
+        const inflight = deps.inflight();
+        if (attached > 0 || inflight > 0) {
+            idleSince = null;
+            return;
+        }
+        const t = now();
+        if (idleSince === null) {
+            idleSince = t;
+            return;
+        }
+        if (t - deps.lastActivityAt() < deps.lingerMs)
+            return;
+        if (t - deps.lastAttachEndedAt() < deps.lingerMs)
+            return;
+        if (t - idleSince < deps.lingerMs)
+            return;
+        stop();
+        deps.log("engine_lease_auto_exit", {
+            attached,
+            inflight,
+            lingerMs: deps.lingerMs,
+            idleForMs: Math.round(t - Math.max(idleSince, deps.lastActivityAt(), deps.lastAttachEndedAt())),
+            note: "no attached shell session, no in-flight run and no HTTP touch for the full linger window — entering the SIGTERM graceful drain path",
+        });
+        deps.drain();
+    }, tickMs);
+    timer.unref?.();
+    function stop() {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(timer);
+    }
+    return { stop };
+}
+//# sourceMappingURL=engine-lease.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)