@sema-agent/server 7.49.0 → 7.51.0

package/dist/device-ws-protocol.js

@@ -0,0 +1,464 @@
+import { createPublicKey, randomBytes, randomInt, verify as edVerify } from "node:crypto";
+export const DEVICE_WS_PATH = "/v1/device/ws";
+export const DEVICE_PROTOCOL_VERSION = 1;
+export const DEVICE_MIN_PROTOCOL_VERSION = 1;
+export const DEVICE_HELLO_DOMAIN_TAG = "sema.device.hello.v1";
+export const DEVICE_WS_LIMITS = {
+    maxFrameBytes: 1024 * 1024,
+    maxPreAuthFrameBytes: 4096,
+    handshakeDeadlineMs: 5000,
+    defaultPayloadPartBytes: 256 * 1024,
+};
+export const DEVICE_FRAME_TYPES = ["hello", "generationAck", "heartbeat", "result", "chunk", "goodbye"];
+export const DEVICE_SERVER_FRAME_TYPES = ["challenge", "helloAck", "helloReject", "instruction", "payload", "cancel", "resultAck", "chunkAck", "bye", "ping"];
+export const DEVICE_HELLO_REJECT_CODES = ["auth_failed", "revoked", "protocol_version_unsupported", "draining", "already_connected"];
+export const DEVICE_BYE_REASONS = ["revoked", "draining", "superseded"];
+export const DEVICE_GOODBYE_REASONS = ["shutdown", "sleep", "user_stop"];
+export const DEVICE_CHUNK_KINDS = ["stdout", "stderr", "data", "exit"];
+export const DEVICE_CANCEL_STATES = ["not_started", "killed"];
+export const DEVICE_INSTRUCTION_STATES = ["queued", "dispatch_committed", "terminal", "terminal_never_started"];
+export const DEVICE_INSTRUCTION_KINDS = [
+    "exec",
+    "execStream",
+    "readTextFile",
+    "readTextLines",
+    "readBinaryFile",
+    "writeFile",
+    "writeFileExclusive",
+    "writeFileGuarded",
+    "appendFile",
+    "fileInfo",
+    "listDir",
+    "canonicalPath",
+    "exists",
+    "readLink",
+    "createDir",
+    "remove",
+    "createTempDir",
+    "createTempFile",
+    "statBatch",
+];
+const INSTRUCTION_KIND_SET = new Set(DEVICE_INSTRUCTION_KINDS);
+export function asInstructionKind(v) {
+    return INSTRUCTION_KIND_SET.has(v) ? v : null;
+}
+export const DEVICE_OUTCOME_ERROR_CODES = [
+    "aborted",
+    "already_exists",
+    "auth_failed",
+    "callback_error",
+    "invalid",
+    "is_directory",
+    "not_directory",
+    "not_found",
+    "not_supported",
+    "outcome_unknown",
+    "permission_denied",
+    "precondition_failed",
+    "shell_unavailable",
+    "spawn_error",
+    "suspended",
+    "target_unavailable",
+    "timeout",
+    "transport_lost",
+    "unknown",
+];
+const OUTCOME_ERROR_CODE_SET = new Set(DEVICE_OUTCOME_ERROR_CODES);
+export function assertCoreOutcomeErrorCodesAreCovered(v) {
+    return v;
+}
+export const DEVICE_FRAME_REJECT_REASONS = ["frame_too_large", "not_json", "not_object", "unknown_type", "bad_shape"];
+export const DEVICE_FRAME_GATE_REJECT_REASONS = ["pre_hello", "generation_mismatch", "unknown_instruction", "instruction_not_committed", "device_mismatch"];
+export const DEVICE_FRAME_AUDIT_REASONS = [...DEVICE_FRAME_REJECT_REASONS, ...DEVICE_FRAME_GATE_REJECT_REASONS];
+function reject(reason, detail) {
+    return { ok: false, reason, detail };
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function str(v) {
+    return typeof v === "string" ? v : null;
+}
+function int(v) {
+    return typeof v === "number" && Number.isSafeInteger(v) ? v : null;
+}
+function nonNegInt(v) {
+    const n = int(v);
+    return n !== null && n >= 0 ? n : null;
+}
+const BASE64_CANONICAL_RE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+export function isCanonicalBase64(v) {
+    if (!BASE64_CANONICAL_RE.test(v))
+        return false;
+    return Buffer.from(v, "base64").toString("base64") === v;
+}
+export function parseGeneration(v) {
+    if (!/^(0|[1-9][0-9]*)$/.test(v))
+        return null;
+    const n = Number(v);
+    return Number.isSafeInteger(n) ? n : null;
+}
+export function formatGeneration(n) {
+    if (!Number.isSafeInteger(n) || n < 0)
+        throw new Error(`device-ws: generation must be a non-negative safe integer (got ${n})`);
+    return String(n);
+}
+function parseOutcomeErrorCode(v) {
+    const s = str(v);
+    return s !== null && OUTCOME_ERROR_CODE_SET.has(s) ? s : null;
+}
+function parseWireFileInfo(v) {
+    if (!isRecord(v))
+        return null;
+    const path = str(v.path);
+    const kind = str(v.kind);
+    const size = int(v.size);
+    const mtimeMs = int(v.mtimeMs);
+    if (path === null || size === null || mtimeMs === null)
+        return null;
+    if (kind !== "file" && kind !== "dir" && kind !== "symlink" && kind !== "other")
+        return null;
+    let mode;
+    if (v.mode !== undefined) {
+        const m = int(v.mode);
+        if (m === null)
+            return null;
+        mode = m;
+    }
+    return { path, kind, size, mtimeMs, ...(mode === undefined ? {} : { mode }) };
+}
+function parseOutcome(v) {
+    if (!isRecord(v))
+        return null;
+    if (v.ok === false) {
+        const errorCode = parseOutcomeErrorCode(v.errorCode);
+        const message = str(v.message);
+        if (errorCode === null || message === null)
+            return null;
+        return { ok: false, errorCode, message };
+    }
+    if (v.ok !== true)
+        return null;
+    const kind = str(v.kind);
+    switch (kind) {
+        case "exec": {
+            const exitCode = int(v.exitCode);
+            if (exitCode === null)
+                return null;
+            if (v.truncated === undefined)
+                return { ok: true, kind: "exec", exitCode };
+            if (!isRecord(v.truncated))
+                return null;
+            const stdout = v.truncated.stdout;
+            const stderr = v.truncated.stderr;
+            if (stdout !== undefined && typeof stdout !== "boolean")
+                return null;
+            if (stderr !== undefined && typeof stderr !== "boolean")
+                return null;
+            return { ok: true, kind: "exec", exitCode, truncated: { ...(stdout === undefined ? {} : { stdout }), ...(stderr === undefined ? {} : { stderr }) } };
+        }
+        case "read":
+            return { ok: true, kind: "read" };
+        case "stat": {
+            const out = { ok: true, kind: "stat" };
+            if (v.info !== undefined) {
+                const info = parseWireFileInfo(v.info);
+                if (info === null)
+                    return null;
+                out.info = info;
+            }
+            if (v.entries !== undefined) {
+                if (!Array.isArray(v.entries))
+                    return null;
+                const entries = [];
+                for (const e of v.entries) {
+                    const parsed = parseWireFileInfo(e);
+                    if (parsed === null)
+                        return null;
+                    entries.push(parsed);
+                }
+                out.entries = entries;
+            }
+            if (v.existsValue !== undefined) {
+                if (typeof v.existsValue !== "boolean")
+                    return null;
+                out.existsValue = v.existsValue;
+            }
+            if (v.canonicalPath !== undefined) {
+                const cp = str(v.canonicalPath);
+                if (cp === null)
+                    return null;
+                out.canonicalPath = cp;
+            }
+            if (v.linkTarget !== undefined) {
+                if (v.linkTarget !== null && typeof v.linkTarget !== "string")
+                    return null;
+                out.linkTarget = v.linkTarget;
+            }
+            return out;
+        }
+        case "write": {
+            const canonicalPath = str(v.canonicalPath);
+            if (canonicalPath === null)
+                return null;
+            let inode;
+            if (v.inode !== undefined) {
+                const s = str(v.inode);
+                if (s === null)
+                    return null;
+                inode = s;
+            }
+            if (v.created !== undefined && typeof v.created !== "boolean")
+                return null;
+            const created = v.created;
+            return { ok: true, kind: "write", canonicalPath, ...(inode === undefined ? {} : { inode }), ...(created === undefined ? {} : { created }) };
+        }
+        case "void":
+            return { ok: true, kind: "void" };
+        case "cancelled": {
+            const state = str(v.state);
+            if (state !== "not_started" && state !== "killed")
+                return null;
+            return { ok: true, kind: "cancelled", state };
+        }
+        default:
+            return null;
+    }
+}
+export function parseDeviceFrameText(text, opts) {
+    const cap = opts?.maxBytes ?? DEVICE_WS_LIMITS.maxFrameBytes;
+    const size = Buffer.byteLength(text, "utf8");
+    if (size > cap)
+        return reject("frame_too_large", `frame is ${size} bytes (cap ${cap})`);
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        return reject("not_json", err instanceof Error ? err.message : String(err));
+    }
+    if (!isRecord(raw))
+        return reject("not_object", "top-level frame must be a JSON object");
+    const t = str(raw.t);
+    if (t === null)
+        return reject("unknown_type", "frame has no string `t`");
+    const type = DEVICE_FRAME_TYPES.find((x) => x === t);
+    if (type === undefined)
+        return reject("unknown_type", `no device→server frame type ${JSON.stringify(t)}`);
+    switch (type) {
+        case "hello": {
+            const protocolVersion = int(raw.protocolVersion);
+            const deviceId = str(raw.deviceId);
+            const epoch = str(raw.epoch);
+            const signatureB64 = str(raw.signatureB64);
+            const workspaceRoot = str(raw.workspaceRoot);
+            const pathFlavor = str(raw.pathFlavor);
+            if (protocolVersion === null || deviceId === null || deviceId === "" || epoch === null || signatureB64 === null || workspaceRoot === null || pathFlavor === null) {
+                return reject("bad_shape", "hello is missing a required scalar field");
+            }
+            if (!isRecord(raw.platform))
+                return reject("bad_shape", "hello.platform must be an object");
+            const os = str(raw.platform.os);
+            const arch = str(raw.platform.arch);
+            const executorVersion = str(raw.platform.executorVersion);
+            if (os === null || arch === null || executorVersion === null)
+                return reject("bad_shape", "hello.platform is missing a field");
+            if (!Array.isArray(raw.supports) || raw.supports.some((s) => typeof s !== "string"))
+                return reject("bad_shape", "hello.supports must be a string array");
+            let resuming;
+            if (raw.resuming !== undefined) {
+                if (!isRecord(raw.resuming))
+                    return reject("bad_shape", "hello.resuming must be an object");
+                const unacked = nonNegInt(raw.resuming.unackedResults);
+                if (unacked === null)
+                    return reject("bad_shape", "hello.resuming.unackedResults must be a non-negative integer");
+                resuming = { unackedResults: unacked };
+            }
+            return {
+                ok: true,
+                frame: {
+                    t: "hello",
+                    protocolVersion,
+                    deviceId,
+                    epoch,
+                    signatureB64,
+                    platform: { os, arch, executorVersion },
+                    workspaceRoot,
+                    pathFlavor,
+                    supports: raw.supports.filter((s) => typeof s === "string"),
+                    ...(resuming === undefined ? {} : { resuming }),
+                },
+            };
+        }
+        case "generationAck": {
+            const gen = str(raw.gen);
+            if (gen === null || parseGeneration(gen) === null)
+                return reject("bad_shape", "generationAck.gen must be a canonical decimal string");
+            return { ok: true, frame: { t: "generationAck", gen } };
+        }
+        case "heartbeat": {
+            const gen = str(raw.gen);
+            const seq = nonNegInt(raw.seq);
+            if (gen === null || parseGeneration(gen) === null || seq === null)
+                return reject("bad_shape", "heartbeat requires gen + non-negative integer seq");
+            if (!Array.isArray(raw.inflight) || raw.inflight.some((s) => typeof s !== "string"))
+                return reject("bad_shape", "heartbeat.inflight must be a string array");
+            return { ok: true, frame: { t: "heartbeat", gen, seq, inflight: raw.inflight.filter((s) => typeof s === "string") } };
+        }
+        case "result": {
+            const gen = str(raw.gen);
+            const instructionId = str(raw.instructionId);
+            const deviceSeq = nonNegInt(raw.deviceSeq);
+            if (gen === null || parseGeneration(gen) === null || instructionId === null || instructionId === "" || deviceSeq === null) {
+                return reject("bad_shape", "result requires gen + instructionId + non-negative integer deviceSeq");
+            }
+            const outcome = parseOutcome(raw.outcome);
+            if (outcome === null)
+                return reject("bad_shape", "result.outcome is not a recognised outcome shape");
+            return { ok: true, frame: { t: "result", gen, instructionId, deviceSeq, outcome } };
+        }
+        case "chunk": {
+            const gen = str(raw.gen);
+            const instructionId = str(raw.instructionId);
+            const streamSeq = nonNegInt(raw.streamSeq);
+            const kindRaw = str(raw.kind);
+            const kind = DEVICE_CHUNK_KINDS.find((k) => k === kindRaw);
+            if (gen === null || parseGeneration(gen) === null || instructionId === null || instructionId === "" || streamSeq === null || kind === undefined) {
+                return reject("bad_shape", "chunk requires gen + instructionId + streamSeq + a known kind");
+            }
+            let dataB64;
+            if (raw.dataB64 !== undefined) {
+                const d = str(raw.dataB64);
+                if (d === null)
+                    return reject("bad_shape", "chunk.dataB64 must be a string");
+                if (!isCanonicalBase64(d))
+                    return reject("bad_shape", "chunk.dataB64 is not canonical base64 (a lax decode would silently corrupt the stream)");
+                dataB64 = d;
+            }
+            let exitCode;
+            if (raw.exitCode !== undefined) {
+                const e = int(raw.exitCode);
+                if (e === null)
+                    return reject("bad_shape", "chunk.exitCode must be an integer");
+                exitCode = e;
+            }
+            switch (kind) {
+                case "exit":
+                    if (exitCode === undefined)
+                        return reject("bad_shape", "an exit chunk must carry exitCode (core OutputChunk contract)");
+                    if (dataB64 !== undefined)
+                        return reject("bad_shape", "an exit chunk must not carry dataB64");
+                    break;
+                case "stdout":
+                case "stderr":
+                case "data":
+                    if (dataB64 === undefined)
+                        return reject("bad_shape", `a ${kind} chunk must carry dataB64`);
+                    if (exitCode !== undefined)
+                        return reject("bad_shape", `a ${kind} chunk must not carry exitCode (only the single exit chunk terminates a stream)`);
+                    break;
+            }
+            return { ok: true, frame: { t: "chunk", gen, instructionId, streamSeq, kind, ...(dataB64 === undefined ? {} : { dataB64 }), ...(exitCode === undefined ? {} : { exitCode }) } };
+        }
+        case "goodbye": {
+            const gen = str(raw.gen);
+            const reasonRaw = str(raw.reason);
+            const reason = DEVICE_GOODBYE_REASONS.find((r) => r === reasonRaw);
+            if (gen === null || parseGeneration(gen) === null || reason === undefined)
+                return reject("bad_shape", "goodbye requires gen + a known reason");
+            let graceMs;
+            if (raw.graceMs !== undefined) {
+                const g = nonNegInt(raw.graceMs);
+                if (g === null)
+                    return reject("bad_shape", "goodbye.graceMs must be a non-negative integer");
+                graceMs = g;
+            }
+            return { ok: true, frame: { t: "goodbye", gen, reason, ...(graceMs === undefined ? {} : { graceMs }) } };
+        }
+    }
+}
+const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const CROCKFORD_INDEX = new Map([...CROCKFORD].map((c, i) => [c, i]));
+export function decodeUlid16(s) {
+    if (s.length !== 26)
+        return null;
+    const first = CROCKFORD_INDEX.get(s[0]);
+    if (first === undefined || first > 7)
+        return null;
+    const out = Buffer.alloc(16);
+    let acc = 0n;
+    for (const ch of s) {
+        const v = CROCKFORD_INDEX.get(ch);
+        if (v === undefined)
+            return null;
+        acc = (acc << 5n) | BigInt(v);
+    }
+    for (let i = 15; i >= 0; i--) {
+        out[i] = Number(acc & 0xffn);
+        acc >>= 8n;
+    }
+    return out;
+}
+function lengthPrefixed(v) {
+    const body = Buffer.from(v, "utf8");
+    const head = Buffer.alloc(4);
+    head.writeUInt32BE(body.length, 0);
+    return Buffer.concat([head, body]);
+}
+export function buildHelloSignaturePayload(input) {
+    const epoch16 = decodeUlid16(input.epoch);
+    if (epoch16 === null)
+        throw new Error(`device-ws: epoch must be a 26-char Crockford ULID (got ${JSON.stringify(input.epoch)})`);
+    if (!Number.isSafeInteger(input.protocolVersion) || input.protocolVersion < 0 || input.protocolVersion > 0xffffffff) {
+        throw new Error(`device-ws: protocolVersion out of u32 range (got ${input.protocolVersion})`);
+    }
+    const version = Buffer.alloc(4);
+    version.writeUInt32BE(input.protocolVersion, 0);
+    return Buffer.concat([Buffer.from(DEVICE_HELLO_DOMAIN_TAG, "utf8"), lengthPrefixed(input.nonce), lengthPrefixed(input.deviceId), epoch16, version]);
+}
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+export function verifyHelloSignature(input) {
+    const raw = Buffer.from(input.pubkeyB64, "base64");
+    if (raw.length !== 32)
+        return { ok: false, reason: `stored pubkey decoded to ${raw.length} bytes (an Ed25519 raw key is 32)` };
+    const sig = Buffer.from(input.signatureB64, "base64");
+    if (sig.length !== 64)
+        return { ok: false, reason: `signature decoded to ${sig.length} bytes (Ed25519 signatures are 64)` };
+    let key;
+    try {
+        key = createPublicKey({ key: Buffer.concat([ED25519_SPKI_PREFIX, raw]), format: "der", type: "spki" });
+    }
+    catch (err) {
+        return { ok: false, reason: `stored pubkey could not be imported: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    let verified;
+    try {
+        verified = edVerify(null, input.payload, key, sig);
+    }
+    catch (err) {
+        return { ok: false, reason: `signature verification threw: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    return verified ? { ok: true } : { ok: false, reason: "signature did not verify against the stored public key" };
+}
+function mintUlid(nowMs) {
+    let ts = Math.max(0, Math.floor(nowMs));
+    const time = [];
+    for (let i = 0; i < 10; i++) {
+        time.unshift(CROCKFORD[ts % 32]);
+        ts = Math.floor(ts / 32);
+    }
+    let rand = "";
+    for (let i = 0; i < 16; i++)
+        rand += CROCKFORD[randomInt(32)];
+    return `${time.join("")}${rand}`;
+}
+export function mintInstructionId(nowMs = Date.now()) {
+    return `ins_${mintUlid(nowMs)}`;
+}
+export function mintChallengeNonce() {
+    return randomBytes(16).toString("base64url");
+}
+export function mintDeviceEpoch(nowMs = Date.now()) {
+    return mintUlid(nowMs);
+}
+//# sourceMappingURL=device-ws-protocol.js.map

package/dist/env-facts.d.ts

@@ -19,6 +19,9 @@ export interface SandboxEnvFacts {
      *     workspace 文件已从快照恢复——「scratch lost」≠「工作丢了」)。
      *   - ssh/adb:park-only,远端 host/device 持续存在 ⇒ scratch preserved;processes 不声明(前台随
      *     连接断,daemon 存活——不知道的不说)。
+     *   - device(v2 §4.2):同 ssh/adb 那一档 —— 工作区是员工机磁盘,park-only 赎回后文件还在
+     *     (core 的 `suspendable:false` 恰恰断言「工作区在目标上外部持久」);processes 不声明:
+     *     executor 是员工机上的独立进程,断连/合盖后前台进程存亡我们不知道,不知道的不说。
      *   - host:同机 ⇒ scratch preserved;processes 不声明(worker 进程可能换代)。
      *   - local-docker:容器跨 leg 存续不保证(reconnect 或有或无)⇒ 整域不声明。 */
     resumeFacts?: {
@@ -42,7 +45,7 @@ export declare function buildEnvFacts(opts: {
  *  codex 复审 medium:k8s 必须按**有效快照能力**分叉,不能只看车道名——s3Snapshot 未配=park-only,
  *  resume 是全新 pod 且**工作区不恢复**,「文件已从快照恢复」那句会让模型信赖不存在的文件(比缺席
  *  更糟的谎)。 */
-export declare function resumeFactsForLane(provider: "e2b" | "k8s" | "ssh" | "adb" | "local-docker" | "host" | undefined, caps?: {
+export declare function resumeFactsForLane(provider: "e2b" | "k8s" | "ssh" | "adb" | "local-docker" | "host" | "device" | undefined, caps?: {
     k8sSnapshot?: boolean;
 }): SandboxEnvFacts["resumeFacts"] | undefined;
 /** Path-safe session segment: the session id can be CALLER-SUPPLIED (body.sessionId), so it must not be able to

package/dist/env-facts.js

@@ -33,6 +33,7 @@ export function resumeFactsForLane(provider, caps) {
                 : { processes: "lost", scratch: "lost", note: "resume provisions a fresh pod — the previous workspace is NOT restored" };
         case "ssh":
         case "adb":
+        case "device":
             return { scratch: "preserved" };
         case "host":
         case undefined:

package/dist/execution-lane-caps.d.ts

@@ -0,0 +1,152 @@
+/**
+ * 执行车道**闭集**与 per-lane 能力表(design device-executor-lane-v2 §4.1 收敛件,车A-1)。
+ *
+ * ## 病根:lane 词表是开放字符串上的十几处独立判别式
+ *
+ * `config.remoteExec?.provider` 的静态型是 `string | undefined` 的判别联合,但消费面从来不是一处
+ * switch —— 而是散在十几个文件里的**独立等式/集合/否定**:`cwdHonored` 比 `=== "host"`、
+ * `isRemoteScratchpadLane` 查一个 `Set`、`isSandboxPathAdjudicationLane` 取 `!== "host"` 的否定、
+ * `sandboxSendLaneEnabled` 是一串 if。于是「lane 词表加一个词」的病形不是编译错,是**每一处的默认
+ * 答案静默错**:新词不在 Set 里 ⇒ 静默 false;不等于 `"host"` ⇒ 静默 true。没有一处会报,每一处都
+ * 给出一个**没有人表过态**的答案(DISEASE-SHAPES V1/V2;#157 执行车道轴的同族病)。
+ *
+ * ## 本模块 = 那张表的单源(三件)
+ *
+ *  ① {@link ExecutionLane}:闭集联合。含 `in-process` —— `REMOTE_EXEC` 未设的进程内 stub 形**是**一条
+ *     真车道(`boot/resolve-spec.ts` 的 `?? "in-process"`、`config.ts` 的落点记账都已在用这个词),
+ *     把它排除在闭集外,普查就少一列。
+ *  ② {@link executionLaneCaps}:**穷举 switch**(先例 = `capabilities/hands-lane.ts` 的
+ *     `pickHandsRunner`:无 `default` 臂 ⇒ 联合加词而此处不加臂 = 编译错,而不是运行期落一个默认行)。
+ *  ③ {@link ExecutionLaneCaps} 的每一位都点名它**今天的判别式坐标**,由对账测试
+ *     `test/execution-lane-caps.test.ts` 逐位跑真判别式与本表对拍。
+ *
+ * ## 🔴 本模块是表,不是执法者
+ *
+ * 消费点今天仍各自判别(把判别式改成读本表 = 分批的后续车)。所以本表的全部价值押在对账测试上:
+ * 表与判别式一旦分叉,门红。**唯一**允许的分叉是 {@link PLANNED_LANE_DIVERGENCES} 里逐条登记的
+ * 「表是目标态、判别式待某车补」;登记项之外的分叉是漂移,登记项被补齐而不销行同样是红(双向)。
+ *
+ * ## 能力位的口径
+ *
+ * 每一位回答的是**车道结构上能不能**,不是「这个部署开没开」:旋钮(`LSP_ENABLED` /
+ * `SCHEDULER_ENABLED` / k8s 的 `s3Snapshot`)由消费点在表之上再合取。租户面是唯一的例外 —— 它与
+ * 车道语义绑死(host 的单用户前提),所以进了 {@link LaneCapability} 的第三个词而不是靠调用方记住。
+ *
+ * 依赖纪律:本文件是**叶**(只 type-import config-types),不引 config.ts —— config.ts 反过来引它取
+ * {@link RemoteExecProvider}(#157 必需 env 表按同一联合键控)。
+ */
+import type { ServiceConfigFlat } from "./config-types.js";
+/** 一位能力的三态。`single-user-only` = 车道支持,但只在单用户部署(`requirePrincipal !== true`)开 ——
+ *  多租户下这一位必须关(host 家族的 cwd/scheduler/backgroundShell/LSP 都是这一档,理由同源:
+ *  一个租户的输入不许把 agent 指向 worker 宿主上另一个租户/运维的文件与进程)。 */
+export type LaneCapability = "supported" | "unsupported" | "single-user-only";
+/** `REMOTE_EXEC` 判别联合里的 provider 词全集 —— **派生自真配置型**,不是手抄一份。
+ *  手抄的那份挡不住本模块要挡的病:给 `ServiceConfigFlat["remoteExec"]` 加一条臂(`remote-docker` 就是
+ *  config-types.ts 里写着的下一条)可以完全不碰本文件而编译通过,穷举 switch 于是只对**自己的**副本穷举,
+ *  能力表与普查数组一起静默漏行(codex R1-F2)。派生之后:配置加臂 ⇒ 本文件的 switch/词表/夹具同时编译红。 */
+export type RemoteExecProvider = NonNullable<ServiceConfigFlat["remoteExec"]>["provider"];
+/** 闭集:执行车道全集 = provider 词 + `in-process`(`REMOTE_EXEC` 未设的进程内 stub 形,配置面无 provider
+ *  可派生 —— 它是「没有 remoteExec」这个状态的名字)。加词 ⇒ {@link executionLaneCaps} 的穷举 switch 与
+ *  {@link EXECUTION_LANE_WORDS} 两处都编译红,这正是要的(「加词必须逐位表态」)。 */
+export type ExecutionLane = "in-process" | RemoteExecProvider;
+/**
+ * per-lane 能力位。每一位的注里点名**今天真正做判决的那处代码**——对账测试按这些坐标跑真函数,
+ * 所以坐标漂了(重命名/搬家/改语义)门会红,注释不会烂在这里。
+ */
+export interface ExecutionLaneCaps {
+    /** 调用方送来的 `cwd` 是否被尊重。判别式:`task-cwd.ts` 的 `cwdHonored`。 */
+    readonly callerCwd: LaneCapability;
+    /** core 的后台 shell 面(`run_in_background`/`BashOutput`/`KillShell`)。判别式:各 adapter 的
+     *  `backgroundCapabilities.supported`(`plugins/remote-env-{host,e2b,k8s}.ts`);host 腿的闸在
+     *  `boot/execution-env.ts` 的 `hostCfg.backgroundShell`。 */
+    readonly backgroundShell: LaneCapability;
+    /** 自唤醒 scheduler(`CronCreate`/…)。判别式:`boot/execution-env.ts` host 臂的 `hostScheduler`
+     *  与 `http/routes/capabilities.ts` 的 `scheduler` 位(两处同判据)。 */
+    readonly scheduler: LaneCapability;
+    /** LSP。判别式:`boot/execution-env.ts` 的 `lspManager` 两臂(沙箱桥 e2b/k8s;host 本地 NodeLspManager)。 */
+    readonly lsp: LaneCapability;
+    /** SendUserFile 的**沙箱直传腿**(host/in-process 的本机 fs 源是另一条腿,不是本位)。
+     *  判别式:`capabilities/sandbox-file-send.ts` 的 `sandboxSendLaneEnabled`。 */
+    readonly sandboxSendUserFile: LaneCapability;
+    /** OS 级隔离边界。判别式:`boot/execution-env.ts` 的 `isolated`(经 `remote_exec_enabled` 日志可观测)。 */
+    readonly isolation: LaneCapability;
+    /** 可挂起(k8s 以配了 `s3Snapshot` 为前提 —— 「结构上能不能」的口径)。判别式:同上的 `suspendable`。 */
+    readonly suspendable: LaneCapability;
+    /** `/tmp/scratchpad/<sessionId>` 远端约定。判别式:`plugins/remote-scratchpad.ts` 的 `isRemoteScratchpadLane`。 */
+    readonly remoteScratchpad: LaneCapability;
+    /** 写门走 #165 的 `DeferredSandboxPathEnv` 代理裁决(而不是直接拿 worker 本机 fs 裁)。
+     *  判别式:`boot/deferred-sandbox-path-env.ts` 的 `isSandboxPathAdjudicationLane`。 */
+    readonly sandboxPathAdjudication: LaneCapability;
+    /** git-worktree 隔离。判别式:`boot/execution-env.ts` 的 host 臂 vs `worktree_isolation_unsupported_lane` warn。 */
+    readonly worktreeIsolation: LaneCapability;
+    /** 记忆持久面的**自动**表态(部署可用 `MEMORY_PERSISTENCE_CAPABLE` 显式覆盖,那是旋钮不是车道位)。
+     *  判别式:`boot/memory-boundary.ts` 的 `effectiveMemoryPersistenceCapable`。 */
+    readonly memoryPersistenceCapable: LaneCapability;
+    /** 文件平面是否就在 worker 本机(= `hostSemanticsLane`)。判别式:`boot/resolve-spec.ts` 的
+     *  `!isSandboxPathAdjudicationLane(...)` 与 `boot/stores.ts` 的 `lane === undefined || lane === "host"`
+     *  ——**两处各写了一份**,对账测试同时咬住两份(它们分叉过就是记忆边界判错盘)。 */
+    readonly hostFilePlane: LaneCapability;
+    /** core 的 `isRemoteExecutionEnv` 对本车道的判决(鸭子类型;判别位 = `config.remoteExec` 在不在场,
+     *  **含 host**)。5.26.0 起它决定 `# Memory` 写指令撤不撤。 */
+    readonly coreRemoteExecutionEnv: LaneCapability;
+}
+/**
+ * per-lane 能力表。**穷举 switch,禁 default 臂**(hands-lane.ts:39-46 先例)。
+ *
+ * device 行的表态来自 v2 §4.1/§4.3:
+ *  · `callerCwd: supported` —— 员工在自己设备的项目目录里干活是这条车道的**存在理由**;host 闸防的
+ *    「跨租户宿主路径穿越」在此结构性不存在(路径落在发起者自己的设备上,归属已由 deviceId↔principal
+ *    绑定验证),故不要求单用户。今天 `cwdHonored` 还答 false ⇒ 登记在 {@link PLANNED_LANE_DIVERGENCES}。
+ *  · `sandboxPathAdjudication: supported` —— 自动判真且**这是深思后的正确默认**:写门经 #165 代理把四读
+ *    原语转发到设备取真文件系统事实,云盘永不参与设备写目标的裁决。
+ *  · `remoteScratchpad: supported` —— executor 平台闭集 = darwin|linux,`/tmp/scratchpad/<sessionId>`
+ *    的惰性 mkdir 约定原样适用;不加词则 scratchpad envFact 对模型整块缺席。
+ *  · scheduler / backgroundShell / lsp / sandboxSendUserFile / worktreeIsolation = v1 **诚实关闭**
+ *    (不是遗漏:设备侧长驻进程、LSP sidecar、直传腿都是 follow-on,声明了就是谎)。
+ *  · `isolation`/`suspendable` = false/false —— 真设备,不隔离不可快照(与 ssh/adb 同宣告);
+ *    `suspendable:false` 在 core 契约里同时断言「工作区在目标上外部持久」,员工机磁盘满足,park-only
+ *    赎回腿因此合法。
+ *  · `memoryPersistenceCapable: unsupported` —— 设备的手够不着云 SQL 记忆店,默认撤 `# Memory` 写指令
+ *    恰是诚实形(§4.3.4)。
+ */
+export declare function executionLaneCaps(lane: ExecutionLane): ExecutionLaneCaps;
+/** 一个开放字符串是不是闭集里的词。判据 = 词表键在不在,故与联合天然同源。 */
+export declare function isExecutionLane(word: string): word is ExecutionLane;
+/** 车道普查全集(顺序 = 词表声明序;对账测试按它逐 lane 跑真判别式)。 */
+export declare const ALL_EXECUTION_LANES: readonly ExecutionLane[];
+/**
+ * `config.remoteExec?.provider` → 车道词。
+ *
+ * · `undefined`(REMOTE_EXEC 未设)⇒ `"in-process"`,那是真车道不是缺席;
+ * · 认不出的词 ⇒ `undefined`,**调用方必须 fail-closed**(禁静默按某个默认车道处理)。生产链上这一臂
+ *   不可达:`loadConfig` 的 #157 拒启门先咬未知词;它存在是为了消费点自卫时有个响亮出口。
+ */
+export declare function executionLaneOf(provider: string | undefined): ExecutionLane | undefined;
+/** 把一位能力在**具体部署**上落成布尔:租户面是唯一入参(旋钮由消费点自己再合取)。
+ *  穷举 switch,无 default 臂 —— {@link LaneCapability} 加词而此处不加臂 = 编译红。 */
+export declare function laneCapabilityHolds(cap: LaneCapability, deployment: {
+    requirePrincipal?: boolean;
+}): boolean;
+/** 一条**已登记**的分叉:表写的是目标态,今天的判别式还答别的。 */
+export interface PlannedLaneDivergence {
+    readonly lane: ExecutionLane;
+    readonly capability: keyof ExecutionLaneCaps;
+    /** 今天那处判别式给出的答案(对账测试拿它对拍 —— 分叉被补齐了这一行就红,逼着销行)。 */
+    readonly today: LaneCapability;
+    /** 谁来补(设计稿里的车号)。 */
+    readonly owner: string;
+    readonly why: string;
+}
+/**
+ * 分叉登记簿 —— **闭集**。对账测试双向咬:表外分叉 = 漂移(红),表内分叉被补齐而不销行 = 陈账(红)。
+ *
+ * 🟢 **空表 = 今天的真实状态**(车A-4,2026-08-28 销行)。唯一那条(device 的 `callerCwd`)已按登记的
+ * 条件补齐:`deviceCwdHonored`(`task-cwd.ts`)+ 写侧闸(`boot/resolve-spec.ts` 的同一处单写者)+ 读侧
+ * 消费(`plugins/remote-env-device.ts` 的 `effectiveDeviceCwd`)**同批**落地,于是能力表写的 `supported`
+ * 与判别式给的答案一致,分叉自然消失 —— 对账测试的双向咬(表外分叉 = 红 / 表内陈账 = 红)因此对本表
+ * 只剩「保持空」这一条要求。
+ *
+ * 加行的门槛不变:一条分叉必须写清 today / owner / why 三件,并在补齐的**同一批**里销掉。
+ */
+export declare const PLANNED_LANE_DIVERGENCES: readonly PlannedLaneDivergence[];
+//# sourceMappingURL=execution-lane-caps.d.ts.map