@sema-agent/server 7.49.0 → 7.51.0

package/dist/boot/shutdown.d.ts

@@ -64,12 +64,22 @@ export interface ShutdownCtx {
         since?: number;
         inflight?: () => number;
         lastActivityAt?: () => number;
+        attachedStreams?: () => number;
+        lastAttachEndedAt?: () => number;
     };
     /** #131-2:store 活体探针(main 建)——不停的话 hardShutdown 后仍对正在关闭的池发探针,刷假
      *  store_probe_dead 告警(文件头契约 3 的同族漏网)。缺席 = 该部署形没建探针。 */
     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

@@ -2,9 +2,10 @@ import { Runner, defaultTaskRegistry } from "@sema-agent/core";
 import { writeCrashLast, clearCrashLast, readCrashLast } from "./crash-last.js";
 import { createSighupIdleHandler } from "../sighup-idle.js";
 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);
@@ -45,6 +46,7 @@ export function installShutdownHandlers(ctx) {
     process.on("unhandledRejection", onUnhandledRejection);
     let closing = false;
     let parentWatch;
+    let engineLease;
     const hardShutdown = () => {
         if (closing)
             return;
@@ -62,7 +64,9 @@ export function installShutdownHandlers(ctx) {
                 .catch(() => undefined);
         fleetReconcile.reconciler.stop();
         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();
@@ -104,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;
@@ -145,6 +150,18 @@ export function installShutdownHandlers(ctx) {
             log: (event, fields) => logger.info(event, fields),
         });
     }
+    if (config.engineAutoExit) {
+        engineLease = createEngineLeaseTracker({
+            attachedStreams: () => drainState.attachedStreams?.() ?? 0,
+            inflight: () => drainState.inflight?.() ?? 0,
+            lastActivityAt: () => drainState.lastActivityAt?.() ?? 0,
+            lastAttachEndedAt: () => drainState.lastAttachEndedAt?.() ?? 0,
+            isStopped: () => closing || draining,
+            drain: drainThenShutdown,
+            lingerMs: config.engineLingerMs,
+            log: (event, fields) => logger.info(event, fields),
+        });
+    }
     let disposed = false;
     return {
         dispose: () => {
@@ -162,6 +179,7 @@ export function installShutdownHandlers(ctx) {
                 drainTick = undefined;
             }
             parentWatch?.stop();
+            engineLease?.stop();
         },
     };
 }

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;
@@ -1223,6 +1235,25 @@ export interface ServiceConfigFlat {
      *  已知残余(成文,不收窄):两拍窗口内 pid 被系统复用 ⇒ 探活看到的是**新**进程,监视判"父还活着"
      *  而不自退。监视是**尽力自愈**、不是强一致的父子生命周期绑定。 Env: `SEMA_PARENT_PID`。 */
     parentPid?: number;
+    /** #118(黑板 [5371]②):引擎**附着租约自退**总开关。壳自 spawn 引擎的本机形里,壳退出之后引擎
+     *  继续活着 = 占端口/占库连接/占模型配额的孤儿。设了本键 = 引擎每 15s 自查一次「还有没有人附着」,
+     *  **三合取**(无附着 SSE 流 ∧ 无在飞 run ∧ 无非探针 HTTP 触点)**持续**满 {@link engineLingerMs}
+     *  才自退,且自退走的是与 SIGTERM **逐字同一条** graceful drain 腿(不是裸 `process.exit`)。
+     *  **默认 false** —— 服务器部署形永不自退(k8s replica 半夜没人用是正常低谷,不是「该退了」);
+     *  壳 spawn 形由壳显式注入 `true`。**部署级旋钮无条件生效**,不派生自任何客户端表态。
+     *  与 {@link parentPid} 是**两件**:那条问「生我的 pid 还在吗」(多壳共享一引擎时结构性问错),
+     *  这条问「还有没有人附着」。两条可同时装,各走各的判据。 Env: `ENGINE_AUTO_EXIT`(默认 off)。 */
+    engineAutoExit: boolean;
+    /** #118:自退前三合取必须**持续**成立的静默窗。默认 60s —— 防的是**壳重启窗**:壳崩了/重启的 1-3s
+     *  里附着数确实是 0,窗太短就在用户眼皮底下把引擎杀了,窗内任何一次重连即把计时清零。
+     *  {@link engineAutoExit} 关着时本值不生效,但**照样解析、坏值照样拒启**(部署级旋钮的解析不挂在
+     *  另一个旋钮的表态上 —— 否则手滑值躺在配置里,等哪天有人打开自退时当场生效且从没人报过警)。
+     *  **坏值拒启**(#210 A 档):非安全整数 / 落在 `[1000, 86400000]`(1s…24h)之外一律 boot 期 throw
+     *  带指路 —— 「把 60(秒)填进一个毫秒键」是这类旋钮最常见的手滑,而 60ms 的 linger 等于把整条防误杀
+     *  腿静默摘掉;上界那一侧同样承重(codex R1-F2):`1e100` 能过朴素的「正整数吗」检查,而 elapsed
+     *  **永远追不上它** ⇒ 看着配好了、自退其实整件失效。要「永不自退」请用 `ENGINE_AUTO_EXIT=false`。
+     *  Env: `ENGINE_LINGER_MS`(默认 60000,闭区间 [1000, 86400000])。 */
+    engineLingerMs: number;
     /** E23 (shell-host contract): inbound MCP elicitation HITL. When enabled, the service mounts `RunnerDeps.onElicit` + the
      *  `POST /v1/elicitations/:id/respond` route so an opted-in MCP server (`McpServerSpec.elicitation`, itself default
      *  OFF) can ask the END USER for input mid-tool-call. LIVE-ONLY (no durable suspend; lost on crash/replica-change).
@@ -1496,7 +1527,7 @@ export type ServiceAuthConfig = Pick<ServiceConfigFlat, "authToken" | "authToken
 /** 组:orchestration(编排 + 执行车道 + 沙箱面 + workflow/后台 agent 存留)。 */
 export type ServiceOrchestrationConfig = Pick<ServiceConfigFlat, "remoteExec" | "worktreeIsolation" | "leaderEnabled" | "leaderFanoutEnabled" | "routerEnabled" | "selfOrchestrationEnabled" | "selfOrchestrationModels" | "selfOrchestrationWorkerIsolation" | "forkEnabled" | "experimentalObserverAgents" | "schedulerEnabled" | "schedulerSessionWakeup" | "schedulerSessionLifetime" | "schedulerStorePath" | "planModeEnabled" | "hooksTimeoutMs" | "workflowRunStoreBackend" | "workflowOrphanGraceMs" | "workflowJournalRetentionMs" | "workflowRunRetentionMs" | "usageWindows" | "workflowAgentsReadOnly" | "workflowSizeGuideline" | "backgroundAgentRetentionMs" | "backgroundAgentStaleRunningMs" | "backgroundAgentParkClaimStaleMs" | "delegationEntryCaps" | "rosterRetentionMs" | "leaderRunStaleMs" | "scratchpadSweepTtlMs" | "sandboxPkgSource" | "sessionAutoTitle" | "selectEnvironmentTool" | "envFactsEnabled" | "toolDeferLongtail" | "lspEnabled" | "lspHostEnabled" | "imageBakes" | "readFace" | "readDenyPatterns" | "readDenyBuiltinTiers" | "readDenyBuiltinExclude">;
 /** 组:limitsHttp(HTTP 面 + 各类上限/配额/回收窗)。 */
-export type ServiceLimitsHttpConfig = Pick<ServiceConfigFlat, "port" | "attachmentOrphanGraceMs" | "workspaceFileMaxBytes" | "attachmentMaxBytes" | "attachmentMimeAllowlist" | "attachmentUnboundTtlMs" | "infraCostRates" | "drainGraceMs" | "sighupIdleGraceMs" | "parentPid" | "rateLimitPerMin" | "maxTaskCostUsd" | "maxTaskTokens" | "maxPrincipalCostUsd" | "costQuotaWindowSec" | "reapIntervalSec" | "runStaleSec" | "toolResultTtlSec">;
+export type ServiceLimitsHttpConfig = Pick<ServiceConfigFlat, "port" | "attachmentOrphanGraceMs" | "workspaceFileMaxBytes" | "attachmentMaxBytes" | "attachmentMimeAllowlist" | "attachmentUnboundTtlMs" | "infraCostRates" | "drainGraceMs" | "sighupIdleGraceMs" | "parentPid" | "engineAutoExit" | "engineLingerMs" | "rateLimitPerMin" | "maxTaskCostUsd" | "maxTaskTokens" | "maxPrincipalCostUsd" | "costQuotaWindowSec" | "reapIntervalSec" | "runStaleSec" | "toolResultTtlSec">;
 /** 组:observability(可观测)。 */
 export type ServiceObservabilityConfig = Pick<ServiceConfigFlat, "metricsToken" | "traceToken" | "toolTrace" | "traceThinking" | "logLevel" | "otel">;
 /** 组:integrations(外部集成)。`mcpServers` / `a2aPeers` 由 sema-registry 适配器填(无 env 腿),归本组。 */

package/dist/config.js

@@ -11,6 +11,7 @@ import { DEFAULT_QUESTION_THROTTLE } from "./question.js";
 import { GIT_API_KINDS, isGitApiKind } from "./git-api-kind.js";
 import { RETENTION_MODES, MEMORY_CONSOLIDATION_MIN_INTERVAL_SEC } from "./config-types.js";
 import { normalizeSshFingerprint } from "./ssh-host-key.js";
+import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
 export { RETENTION_MODES, MEMORY_CONSOLIDATION_MIN_INTERVAL_SEC } from "./config-types.js";
 function csv(name) {
     return (process.env[name] ?? "")
@@ -736,11 +737,17 @@ function parseDegradeOn(words) {
     }
     return words;
 }
+const PRESENTED_NAME_MAX = 160;
+function presentToolName(name) {
+    const clean = name.replace(CONTROL_AND_BIDI_STRIP_RE, "");
+    return clean.length <= PRESENTED_NAME_MAX ? clean : `${clean.slice(0, PRESENTED_NAME_MAX)}…(${name.length} chars)`;
+}
 function ccRuleFormGuidance(name) {
     if (!name.includes("(") && !name.includes(")"))
         return undefined;
-    return (`CC-form rule specifier — this list matches the WHOLE tool name verbatim, so it can only ever match a tool literally named "${name}". ` +
-        `Drop the parentheses to gate the tool itself ("${name.split("(")[0] ?? name}"); ` +
+    const shown = presentToolName(name);
+    return (`CC-form rule specifier — this list matches the WHOLE tool name verbatim, so it can only ever match a tool literally named "${shown}". ` +
+        `Drop the parentheses to gate the tool itself ("${presentToolName(name.split("(")[0] ?? name)}"); ` +
         `to decide per COMMAND use \`runtime.commandPolicy\` ({command, decision} — bare argv[0] names); ` +
         `to put every shell call behind an approval use MANUAL_MODE_SHELL_GATE=always`);
 }
@@ -783,7 +790,7 @@ export function findUnmatchableToolNames(names) {
         const ns = protocolOf(name);
         if (ns === undefined) {
             if (name.includes("__"))
-                out.push({ name, guidance: `pre-prefix short form — the live name carries a protocol prefix: ${PROTOCOL_TABLE.map((e) => `${e.prefix}${name}`).join(" or ")}` });
+                out.push({ name, guidance: `pre-prefix short form — the live name carries a protocol prefix: ${PROTOCOL_TABLE.map((e) => `${e.prefix}${presentToolName(name)}`).join(" or ")}` });
             continue;
         }
         if (ns.parse(name) === undefined) {
@@ -794,7 +801,7 @@ export function findUnmatchableToolNames(names) {
 }
 export function formatUnmatchableToolNames(source, bad) {
     return (`${source} names tool(s) that can never match a live tool (these lists are RAW whole-name comparisons — core 5.0.0 RB-476 removed the alias/auto-prefix folds): ` +
-        bad.map((b) => `${b.name} → ${b.guidance}`).join("; "));
+        bad.map((b) => `${presentToolName(b.name)} → ${b.guidance}`).join("; ")).replace(CONTROL_AND_BIDI_STRIP_RE, "");
 }
 function streamApprovalConfig() {
     const cfg = {
@@ -962,6 +969,24 @@ function parentPidEnv() {
     }
     return { parentPid: n };
 }
+const ENGINE_LINGER_FLOOR_MS = 1_000;
+const ENGINE_LINGER_CEIL_MS = 24 * 60 * 60 * 1_000;
+function engineLingerMsEnv() {
+    const raw = process.env.ENGINE_LINGER_MS;
+    if (raw === undefined || raw.trim() === "")
+        return 60_000;
+    const n = parseNumOrFail("ENGINE_LINGER_MS", raw);
+    if (!Number.isSafeInteger(n) || n < ENGINE_LINGER_FLOOR_MS || n > ENGINE_LINGER_CEIL_MS) {
+        throw new Error(`env ENGINE_LINGER_MS="${raw}" must be an INTEGER number of MILLISECONDS in ` +
+            `[${ENGINE_LINGER_FLOOR_MS}, ${ENGINE_LINGER_CEIL_MS}] (1s … 24h) — it is how long ` +
+            `"nobody attached, no run in flight, no HTTP touch" must hold CONTINUOUSLY before the engine self-exits. ` +
+            `A value like "60" is the seconds-for-milliseconds slip: a 60ms window kills the engine inside a shell's own ` +
+            `restart gap. A value like "1e100" passes a naive "is it a positive integer" check but the elapsed clock can ` +
+            `NEVER reach it, which silently turns self-exit off while looking configured. ` +
+            `There is no "disable" value here — set ENGINE_AUTO_EXIT=false to turn self-exit off entirely.`);
+    }
+    return n;
+}
 function parseMemoryEmbedder(ctx) {
     const endpoint = process.env.MEMORY_EMBEDDER_ENDPOINT || undefined;
     const model = process.env.MEMORY_EMBEDDER_MODEL || undefined;
@@ -1259,10 +1284,11 @@ function parseOrchestrationDomain(ctx) {
                 adb: ["ADB_SERIAL"],
                 host: [],
                 "local-docker": ["DOCKER_IMAGE"],
+                device: [],
             };
-            const required = Object.hasOwn(REQUIRED_ENVS_BY_LANE, lane) ? REQUIRED_ENVS_BY_LANE[lane] : undefined;
+            const required = Object.entries(REQUIRED_ENVS_BY_LANE).find(([word]) => word === lane)?.[1];
             if (required === undefined) {
-                throw new Error(`REMOTE_EXEC="${lane}" is not an execution lane — valid: e2b | k8s | ssh | adb | host | local-docker. ` +
+                throw new Error(`REMOTE_EXEC="${lane}" is not an execution lane — valid: ${Object.keys(REQUIRED_ENVS_BY_LANE).join(" | ")}. ` +
                     `An unrecognized value used to fall through to the host/in-process lane silently; refusing to start instead (#157).`);
             }
             const missing = required.filter((name) => !process.env[name]);
@@ -1367,9 +1393,19 @@ function parseOrchestrationDomain(ctx) {
                                                         ...(process.env.DOCKER_SANDBOX_ENV ? { env: resolveEnvForward(process.env.DOCKER_SANDBOX_ENV) } : {}),
                                                     }
                                                     :
-                                                        process.env.CONFIG_PROVIDER === "local"
-                                                            ? { provider: "host" }
-                                                            : undefined,
+                                                        process.env.REMOTE_EXEC === "device"
+                                                            ? {
+                                                                provider: "device",
+                                                                ...((n) => (n !== undefined ? { deliveryTimeoutMs: n } : {}))(optNumEnvStrict("DEVICE_DELIVERY_TIMEOUT_MS")),
+                                                                ...((n) => (n !== undefined ? { reconnectGraceMs: n } : {}))(optNumEnvStrict("DEVICE_RECONNECT_GRACE_MS")),
+                                                                ...((n) => (n !== undefined ? { execTimeoutMs: n } : {}))(optNumEnvStrict("DEVICE_EXEC_TIMEOUT_MS")),
+                                                                ...((n) => (n !== undefined ? { maxInflightPerDevice: n } : {}))(optNumEnvStrict("DEVICE_MAX_INFLIGHT_PER_DEVICE")),
+                                                                ...(process.env.DEVICE_SUPERSEDE ? { supersede: enumEnv("DEVICE_SUPERSEDE", "stale_only", ["stale_only", "deny"]) } : {}),
+                                                            }
+                                                            :
+                                                                process.env.CONFIG_PROVIDER === "local"
+                                                                    ? { provider: "host" }
+                                                                    : undefined,
         worktreeIsolation: boolEnv("WORKTREE_ISOLATION_ENABLED", false) && process.env.WORKTREE_REPO_ROOT
             ? {
                 repoRoot: process.env.WORKTREE_REPO_ROOT,
@@ -1472,6 +1508,8 @@ function parseLimitsHttpDomain() {
         drainGraceMs: clampEnvWithWarn("DRAIN_GRACE_MS", String(10 * 60 * 1000), LIMITS_HTTP_FLOORS.drainGraceMs),
         sighupIdleGraceMs: clampEnvWithWarn("SIGHUP_IDLE_GRACE_MS", String(120_000), 5_000),
         ...parentPidEnv(),
+        engineAutoExit: boolEnv("ENGINE_AUTO_EXIT", false),
+        engineLingerMs: engineLingerMsEnv(),
         rateLimitPerMin: numEnv("RATE_LIMIT_RPM", "0"),
         maxTaskCostUsd: numEnv("MAX_TASK_COST_USD", "0"),
         maxTaskTokens: numEnv("MAX_TASK_TOKENS", "0"),
@@ -1667,7 +1705,9 @@ const ORCHESTRATION_GROUP_KEYS = [
 ];
 const LIMITS_HTTP_GROUP_KEYS = [
     "port", "attachmentOrphanGraceMs", "workspaceFileMaxBytes", "attachmentMaxBytes", "attachmentMimeAllowlist",
-    "attachmentUnboundTtlMs", "infraCostRates", "drainGraceMs", "sighupIdleGraceMs", "parentPid", "rateLimitPerMin", "maxTaskCostUsd",
+    "attachmentUnboundTtlMs", "infraCostRates", "drainGraceMs", "sighupIdleGraceMs", "parentPid",
+    "engineAutoExit", "engineLingerMs",
+    "rateLimitPerMin", "maxTaskCostUsd",
     "maxTaskTokens", "maxPrincipalCostUsd", "costQuotaWindowSec", "reapIntervalSec", "runStaleSec", "toolResultTtlSec",
 ];
 const OBSERVABILITY_GROUP_KEYS = ["metricsToken", "traceToken", "toolTrace", "traceThinking", "logLevel", "otel"];
@@ -1781,6 +1821,25 @@ export function loadConfig() {
             "push. Point the service at a durable store (DB_BACKEND=mysql|pg), or turn the leader off (unset LEADER_ENABLED) " +
             "(#193 车4 件2 / staleness ledger P1-9+P1-10 boot invariant)");
     }
+    {
+        const deviceLane = orchestration.remoteExec?.provider === "device";
+        const deviceSqlStore = (store.dbBackend === "mysql" && store.tidb !== undefined) || (store.dbBackend === "pg" && store.pg !== undefined);
+        if (deviceLane && !deviceSqlStore) {
+            throw new Error(`REMOTE_EXEC=device with DB_BACKEND=${store.dbBackend} and no SQL connection coordinates built is refused ` +
+                "[device-durable-store]: the device registry, the session↔device binding and the device audit trail are all " +
+                "SQL-backed — without a real SQL store the binding lives in this process only, so a restart forgets WHICH device " +
+                "a parked run must resume onto and a second replica cannot see it at all. Note DB_BACKEND alone is not enough: " +
+                "SESSION_BACKEND=memory (or auto with no MYSQL_HOST/PG_HOST) builds no coordinates at all. Configure a durable " +
+                "store (DB_BACKEND=mysql|pg + its *_HOST/*_USER/*_DATABASE), or unset REMOTE_EXEC " +
+                "(device-executor-lane-v2 §4.7 boot invariant)");
+        }
+        if (deviceLane && !dgDurable) {
+            throw new Error("REMOTE_EXEC=device without DURABLE_APPROVAL=true is refused [device-durable-approval]: a personal device goes " +
+                "offline (lid closed, network drop) at arbitrary points, so an in-flight approval that outlives the window MUST " +
+                "have a park exit — without the durable approval store there is none and the run is stuck with nowhere to persist. " +
+                "Set DURABLE_APPROVAL=true, or unset REMOTE_EXEC (device-executor-lane-v2 §4.7 boot invariant)");
+        }
+    }
     EXEC_LANE_NOTICE = buildExecLaneNotice(orchestration.remoteExec);
     return attachConfigGroups({
         ...store,

package/dist/device-enrollment.d.ts

@@ -0,0 +1,125 @@
+/**
+ * device lane 准入链(design/device-executor-lane-v2 §4.3.2 提交期准入 + §7-T5 enrollment 五件 +
+ * §7-T6 反枚举)—— **纯函数层**:没有 HTTP、没有 WS、没有 core 装配,只有「店 + 判据 → typed 判决」。
+ * 端点(`/v1/devices/*`、`GET /v1/device/ws`)由车A-3/车C 接;它们**必须**经由这里的判决,不得自建判据。
+ *
+ * ── 五件(§7-T5,逐条落在哪儿)────────────────────────────────────────────────────────────────────
+ *  ① TTL —— `DeviceStore.consumeEnrollToken` 的 CAS 谓词 `expires_at > NOW(3)`(**DB 时钟**,§4.6-F18)。
+ *  ② 绑定 principal —— 同一条 CAS 谓词里 `target_tenant/target_subject` 逐字节等值;不匹配 = 拒。
+ *  ③ 消费一次性 CAS —— `consumed_at IS NULL` 谓词 + `rev=rev+1`;**affected=0 时只有同 pubkey 放行**。
+ *  ④ 重用审计 —— 异 pubkey ⇒ `device_enroll_token_reuse` 审计行(告警级);principal 不符 ⇒
+ *     `device_identity_mismatch` 审计行。两条都在**拒绝之前**写,失败即整条请求失败(fail-closed:
+ *     审计写不进去 ≠ 放行)。
+ *  ⑤ 限速 —— {@link DeviceEnrollRateLimiter},注入式。缺席 = **不限速**,所以端点车必须传一个
+ *     (§7-T5 ⑤ 双限速);本层不替它兜底,也不假装限了。
+ *
+ * ── 反枚举(§4.8 + memory `anti-enum-404-ambiguity`)──────────────────────────────────────────────
+ * enrollment 的**全部**拒绝理由(token 不存在 / 过期 / principal 不符 / 被别的 pubkey 用过)在 wire
+ * 上是**同一个** `device.enrollment_invalid`;设备读面的「不存在」与「不是你的」是同一个
+ * `not_found.device`。细分只进审计。
+ *
+ * ── 吊销在途语义(§8-R4)──────────────────────────────────────────────────────────────────────────
+ * `revoked` 是终态:①绑定的 session 后续提交 = `device.revoked`(admitSession 步 2,**先于** presence
+ * 判定);②吊销同事务把连接租约作废并把 `conn_generation` 推进一格 ⇒ 在途连接的每一次带世代谓词的写
+ * 都会影响 0 行,设备侧因此立刻失权(§4.6 步 2);③重新 enrollment = 新 deviceId,不复活旧行。
+ */
+import { DEVICE_RATE_LIMIT_CODE, type DeviceErrorCode, type DeviceOwner, type DeviceRow, type DeviceSessionRow, type DeviceStore, type NewDeviceInput } from "./device-store.js";
+/** typed 拒绝 —— 端点层只负责把它翻成 HTTP(status 已在体内,不许调用方另算)。 */
+export interface DeviceRejection {
+    code: DeviceErrorCode | typeof DEVICE_RATE_LIMIT_CODE;
+    status: number;
+    message: string;
+    /** 限流专用:`Retry-After` 的秒值(附录 A 的 429 族纪律)。 */
+    retryAfterSec?: number;
+}
+export type DeviceOutcome<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reject: DeviceRejection;
+};
+/**
+ * 限速座(§7-T5 ⑤)。**fail-closed**:`check` 抛错 = 拒绝(不是放行)—— 限速器不可用时放行,正是
+ * token 撞库最想要的那一刻。
+ */
+export interface DeviceEnrollRateLimiter {
+    check(key: string): Promise<{
+        allowed: boolean;
+        retryAfterSec?: number;
+    }>;
+}
+export interface EnrollDeviceInput {
+    /** 明文 token(**只**在这里出现,落库前立刻摘要)。 */
+    token: string;
+    /** 请求方**验证过**的复合身份(SSO/凭据链产出,恒不取自可伪造头)。 */
+    requester: DeviceOwner;
+    /** 🔴 `deviceId` 与 `owner` **不在**这里:前者恒由 server 铸(调用方选 id = 让请求方挑自己的设备身份,
+     *  与 §6「server 铸 dev_<ulid>」相悖),后者恒取自**验证过的** requester —— 两个字段都不接受请求体供给。
+     *  测试要确定性 id ⇒ 注入 {@link DeviceEnrollmentDeps.mintId},不是从入参开一个口子。 */
+    device: Omit<NewDeviceInput, "deviceId" | "owner">;
+}
+export interface EnrollDeviceValue {
+    device: DeviceRow;
+    /** `true` = 幂等重放(响应丢失重试),`false` = 本次真注册。wire 上两者同为 200 + 同 deviceId。 */
+    replayed: boolean;
+}
+export interface AdmitSessionInput {
+    rootSessionId: string;
+    requester: DeviceOwner;
+    /** 提交体携带的 deviceId(§4.3.2:仅根任务携;缺席 = 沿用绑定)。 */
+    requestedDeviceId?: string;
+}
+export interface AdmitSessionValue {
+    deviceId: string;
+    device: DeviceRow;
+    /**
+     * 判决**当刻**的连接世代(§4.6 fencing token)。
+     *
+     * 🔴 **准入判决是一个快照,不是一把锁**(codex 对抗轮 F4,判真但归属下一车):`admitSession` 返回后、
+     * 调用方真正下发指令前,一次 `revokeDevice` 可以提交 —— 它会作废租约并把 `conn_generation` 推进一格,
+     * 但它**追不回**已经基于旧判决发出去的指令。这不是本层能关掉的窗(§6 注③ 刻意不落指令表,所以持久层
+     * 没有「派发」这个写点可以带谓词);设计给的答案是**在下发边界重新断言世代**(§4.6 步 2/3:每一次带
+     * `conn_generation = ?` 谓词的写影响 0 行 = 本连接已失权 ⇒ 停发并断连)。
+     * 本字段就是那个断言要用的值 —— 车A-3 的 WS 汇聚端**必须**拿它去 fence,拿不到就不要下发。
+     * 残余诚实:窗口上界 = 心跳周期(吊销后设备侧最迟一个心跳失败即失权),§8-R4 对已发指令的账面处置是
+     * 「在途结果帧丢弃 + 审计,对应调用按 outcome-unknown 收尾」。
+     */
+    connGeneration: number;
+}
+export interface DeviceEnrollment {
+    enroll(input: EnrollDeviceInput): Promise<DeviceOutcome<EnrollDeviceValue>>;
+    bindPlacement(input: {
+        rootSessionId: string;
+        deviceId: string;
+        requester: DeviceOwner;
+    }): Promise<DeviceOutcome<DeviceSessionRow>>;
+    admitSession(input: AdmitSessionInput): Promise<DeviceOutcome<AdmitSessionValue>>;
+    revoke(input: {
+        deviceId: string;
+        requester: DeviceOwner;
+        revokedBy: string;
+        reason?: string | null;
+    }): Promise<DeviceOutcome<DeviceRow>>;
+}
+export interface DeviceEnrollmentDeps {
+    store: DeviceStore;
+    /** 缺席 = 不限速(端点车必须传;见文件头注 ⑤)。 */
+    rateLimiter?: DeviceEnrollRateLimiter;
+    /** 测试可注入确定性铸造;默认 `mintDeviceId()`。 */
+    mintId?: () => string;
+}
+export declare function createDeviceEnrollment(deps: DeviceEnrollmentDeps): DeviceEnrollment;
+/**
+ * 进程内固定窗限速(§7-T5 ⑤ 的**默认**实现)。
+ *
+ * 🔴 诚实边界:这是**每副本**的窗。跨副本的真限速属主是既有的 `observability/rate-limit.ts` RateGate
+ * (SQL 后端),端点车把它适配成 {@link DeviceEnrollRateLimiter} 传进来即可 —— 本函数不假装自己是
+ * 那个东西,也不在多副本部署下声称有全局上界。
+ */
+export declare function createFixedWindowRateLimiter(opts: {
+    limit: number;
+    windowMs: number;
+    now?: () => number;
+}): DeviceEnrollRateLimiter;
+//# sourceMappingURL=device-enrollment.d.ts.map