@sema-agent/server 7.140.0 → 7.142.0

package/dist/plugins/sandbox-read-floor.js

@@ -0,0 +1,608 @@
+import { createHash, randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { ExecutionError } from "@sema-agent/core";
+import { shellQuote } from "./remote-shell.js";
+import { echoCallerText } from "../caller-text-echo.js";
+import { ADAPTER_VOLUME_NAMES } from "./k8s-exec-protocol.js";
+import { SANDBOX_READ_FLOOR_ENV, sandboxReadFloorState } from "../execution-lane-caps.js";
+export const READ_FLOOR_UNAVAILABLE_REASONS = ["arch", "user_notif", "addfd_send", "uid_zero", "writable_system_path", "binary_digest", "relay_silent", "relay_identity", "provenance"];
+const REASON_SET = new Set(READ_FLOOR_UNAVAILABLE_REASONS);
+function reasonSentence(reason) {
+    switch (reason) {
+        case "arch":
+            return "the sandbox's machine architecture has no supervisor build (x86_64 and aarch64 only)";
+        case "user_notif":
+            return "the sandbox kernel does not offer seccomp user notification";
+        case "addfd_send":
+            return "the sandbox kernel cannot hand a judged file to the command (SECCOMP_IOCTL_NOTIF_ADDFD with SEND needs Linux 5.14 or later)";
+        case "uid_zero":
+            return "the command would run as root (a root command can read the raw block device below any path floor) — run the image as a non-root user";
+        case "writable_system_path":
+            return "a system path the supervisor starts from (PATH directories, the dynamic loader, /etc/ld.so.preload) is writable by the command's user";
+        case "binary_digest":
+            return "the supervisor binary in the sandbox is not the one this server pins";
+        case "relay_silent":
+            return "the relay that carries the floor's questions to this server did not answer";
+        case "relay_identity":
+            return "the supervisor could not authenticate its relay";
+        case "provenance":
+            return "the sandbox was not under the floor since it was created (a resumed sandbox without the floor's marker)";
+    }
+}
+export function buildReadFloorUnavailableMessage(reason, detail, floor) {
+    const first = floor?.rows[0];
+    return (`read floor unavailable on this sandbox (${reason}): ${reasonSentence(reason)}${detail ? ` — ${detail}` : ""}. ` +
+        `This command carries a read-deny table${first !== undefined ? ` (first row "${first}")` : ""} this sandbox cannot keep, so it is refused rather than run with fewer rows. ` +
+        `To run this lane without the byte floor, set ${SANDBOX_READ_FLOOR_ENV}=off (the lane then declares keepsReadFloor=false: each run with read-deny rows is announced, or refused when READ_DENY_FLOOR_REQUIRED=true).`);
+}
+export function buildReadFloorMissingMessage(lane) {
+    return (`read floor: this ${lane} sandbox keeps the read-deny byte floor, and this command start carries no floor — it is refused rather than run a process the floor does not judge ` +
+        `(every start on a lane that keeps the floor must carry the run's read-deny table). ` +
+        `To run this lane without the byte floor, set ${SANDBOX_READ_FLOOR_ENV}=off.`);
+}
+export const ADAPTER_START = Object.freeze({ kind: "adapter" });
+export const BOOTSTRAP_START = Object.freeze({ kind: "bootstrap" });
+export function engineStart(readFloor, hold = false) {
+    return hold ? { kind: "engine", readFloor, hold } : { kind: "engine", readFloor };
+}
+const BARE = Object.freeze({ mode: "bare" });
+const ARCH_OF_UNAME = Object.freeze({ x86_64: "x86_64", amd64: "x86_64", aarch64: "aarch64", arm64: "aarch64" });
+export const FLOOR_DIR = "/opt/sema/floor";
+export function floorBinaryPath(arch) {
+    return `${FLOOR_DIR}/${arch}/sema-floor`;
+}
+function laneLaunchPlan(lane) {
+    switch (lane) {
+        case "e2b":
+            return { start: "root", control: "root", dropToWorkspaceOwner: true, stateDir: `${FLOOR_DIR}/state` };
+        case "local-docker":
+            return { start: "exec-user", control: "root", dropToWorkspaceOwner: false, stateDir: `${FLOOR_DIR}/state` };
+        case "k8s":
+            return { start: "exec-user", control: "exec-user", dropToWorkspaceOwner: false, stateDir: "/tmp/.sema-floor-state" };
+    }
+}
+export const FLOOR_ARGV = {
+    run: (bin, startId, as) => [bin, "run", "--start", startId, ...(as !== undefined ? ["--as", as] : [])],
+    plain: (bin, as) => [bin, "plain", ...(as !== undefined ? ["--as", as] : [])],
+    serve: (bin, stateDir, fresh) => [bin, "serve", "--state", stateDir, ...(fresh ? ["--fresh"] : [])],
+    selfcheck: (bin, digest, as) => [bin, "selfcheck", "--digest", digest, ...(as !== undefined ? ["--as", as] : [])],
+};
+function shellLine(argv) {
+    return argv.map(shellQuote).join(" ");
+}
+export function parseSelfcheck(stdout, exitCode) {
+    const line = stdout.split("\n").map((l) => l.trim()).filter((l) => l !== "").at(-1) ?? "";
+    const okm = /^sema-floor selfcheck ok (\S+) (\S+)$/.exec(line);
+    if (okm && exitCode === 0)
+        return { ok: true, version: okm[1], arch: okm[2] };
+    const no = /^sema-floor selfcheck refused ([a-z_]+): ?(.*)$/.exec(line);
+    if (no && exitCode === 125 && REASON_SET.has(no[1]))
+        return { ok: false, reason: no[1], ...(no[2] ? { detail: echoCallerText(no[2], { maxChars: 300 }) } : {}) };
+    return { ok: false, reason: "binary_digest", detail: `the selfcheck answer is not one this server reads (exit ${exitCode}${line !== "" ? `, ${JSON.stringify(echoCallerText(line, { maxChars: 120 }))}` : ", no output"})` };
+}
+const START_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+export const MAX_PATHS_PER_QUESTION = 256;
+export const MAX_RELAY_LINE_BYTES = 1024 * 1024;
+const isInt = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+const exactKeys = (o, keys) => {
+    const ks = Object.keys(o);
+    return ks.length === keys.length && keys.every((k) => Object.hasOwn(o, k));
+};
+export function parseRelayFrame(line) {
+    let v;
+    try {
+        v = JSON.parse(line);
+    }
+    catch (e) {
+        return { t: "broken", why: `not JSON: ${echoCallerText(e instanceof Error ? e.message : String(e), { maxChars: 120 })}` };
+    }
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return { t: "broken", why: "not a JSON object" };
+    const o = v;
+    const id = isInt(o.id) ? o.id : undefined;
+    const count = Array.isArray(o.paths) && o.paths.length >= 1 && o.paths.length <= MAX_PATHS_PER_QUESTION ? o.paths.length : undefined;
+    const broken = (why) => ({ t: "broken", why, ...(id !== undefined ? { id } : {}), ...(id !== undefined && count !== undefined ? { count } : {}) });
+    switch (o.t) {
+        case "ready":
+            return exactKeys(o, ["t", "v", "pid"]) && o.v === 1 && isInt(o.pid) ? { t: "ready", pid: o.pid } : broken("ready: fields");
+        case "refused":
+            return exactKeys(o, ["t", "why", "detail"]) && typeof o.why === "string" && typeof o.detail === "string" ? { t: "refused", why: o.why, detail: o.detail } : broken("refused: fields");
+        case "gone":
+            return exactKeys(o, ["t", "start"]) && typeof o.start === "string" && START_ID.test(o.start) ? { t: "gone", start: o.start } : broken("gone: fields");
+        case "q":
+            if (!exactKeys(o, ["t", "id", "start", "paths"]) || id === undefined || typeof o.start !== "string" || !START_ID.test(o.start) || count === undefined)
+                return broken("q: fields");
+            if (!o.paths.every((p) => typeof p === "string" && p.startsWith("/")))
+                return broken("q: a path that is not an absolute string");
+            return { t: "q", id, start: o.start, paths: o.paths };
+        default:
+            return broken("unknown frame type");
+    }
+}
+export const UNJUDGED_VERDICT = "read floor: no verdict for this start";
+function judgeOne(floor, path) {
+    let v;
+    try {
+        v = floor.denies(path);
+    }
+    catch {
+        v = undefined;
+    }
+    if (v === null)
+        return null;
+    if (typeof v === "string" && v !== "")
+        return v;
+    return floor.rows[0] ?? UNJUDGED_VERDICT;
+}
+export function createFloorJudge() {
+    const starts = new Map();
+    const unjudged = (id, n) => ({ t: "a", id, verdicts: Array.from({ length: n }, () => UNJUDGED_VERDICT) });
+    return {
+        register(floor, held) {
+            const id = randomBytes(12).toString("hex");
+            starts.set(id, { floor, open: held, connected: true });
+            return id;
+        },
+        launch(startId) {
+            const e = starts.get(startId);
+            if (e === undefined || !e.open)
+                return false;
+            e.connected = true;
+            return true;
+        },
+        release(startId) {
+            const e = starts.get(startId);
+            if (e === undefined)
+                return;
+            e.open = false;
+            if (!e.connected)
+                starts.delete(startId);
+        },
+        answer(frame) {
+            switch (frame.t) {
+                case "ready":
+                case "refused":
+                    return undefined;
+                case "gone": {
+                    const e = starts.get(frame.start);
+                    if (e === undefined)
+                        return undefined;
+                    e.connected = false;
+                    if (!e.open)
+                        starts.delete(frame.start);
+                    return undefined;
+                }
+                case "broken":
+                    return frame.id !== undefined && frame.count !== undefined ? unjudged(frame.id, frame.count) : undefined;
+                case "q": {
+                    const e = starts.get(frame.start);
+                    if (e === undefined)
+                        return unjudged(frame.id, frame.paths.length);
+                    return { t: "a", id: frame.id, verdicts: frame.paths.map((p) => judgeOne(e.floor, p)) };
+                }
+            }
+        },
+        get size() {
+            return starts.size;
+        },
+        clear() {
+            starts.clear();
+        },
+    };
+}
+function fsFailure(e) {
+    const code = e instanceof Error ? Reflect.get(e, "code") : undefined;
+    return typeof code === "string" ? code : "unreadable";
+}
+export function createPackagedFloorBinaries(root = new URL("../../native/sandbox-read-floor/", import.meta.url)) {
+    let pinned;
+    const pins = () => {
+        if (pinned !== undefined)
+            return pinned;
+        let text;
+        try {
+            text = readFileSync(new URL("DIGESTS", root), "utf8");
+        }
+        catch (e) {
+            return (pinned = { why: `this package carries no supervisor digests (${fsFailure(e)})` });
+        }
+        const m = new Map();
+        for (const line of text.split("\n")) {
+            const hit = /^([0-9a-f]{64})\s+\*?(x86_64|aarch64)\/sema-floor\s*$/.exec(line.trim());
+            if (hit)
+                m.set(hit[2], hit[1]);
+        }
+        return (pinned = { pins: m });
+    };
+    return {
+        build(arch) {
+            const p = pins();
+            if ("why" in p)
+                return { ok: false, why: p.why };
+            const want = p.pins.get(arch);
+            if (want === undefined)
+                return { ok: false, why: `no supervisor build is pinned for ${arch}` };
+            let b;
+            try {
+                b = readFileSync(new URL(`${arch}/sema-floor`, root));
+            }
+            catch (e) {
+                return { ok: false, why: `the pinned ${arch} build is unreadable (${fsFailure(e)})` };
+            }
+            return createHash("sha256").update(b).digest("hex") === want ? { ok: true, digest: want, bytes: new Uint8Array(b) } : { ok: false, why: `the ${arch} build does not match its pinned digest` };
+        },
+    };
+}
+function createBareFloor(lane, state) {
+    return {
+        lane,
+        state,
+        binaries: undefined,
+        wrap: () => ({ ok: true, value: BARE }),
+        release: () => { },
+        attach: async () => { },
+        refusePlacement: () => { },
+        dispose: () => { },
+    };
+}
+const okLaunch = (value) => ({ ok: true, value });
+const spawnError = (message) => ({ ok: false, error: new ExecutionError("spawn_error", message) });
+export function createKeptSandboxReadFloor(opts) {
+    const lane = opts.lane;
+    const plan = laneLaunchPlan(lane);
+    const judge = createFloorJudge();
+    const readyMs = opts.relayReadyMs ?? 15_000;
+    const maxRestarts = opts.relayRestarts ?? 3;
+    const backoffMs = opts.relayRestartBackoffMs ?? 1_000;
+    let phase = { kind: "idle" };
+    let generation = 0;
+    let attachBegun = false;
+    let verified;
+    let bin;
+    let as;
+    let transport;
+    let link;
+    let relayUp = false;
+    let restarting;
+    let placementRefused;
+    let disposed = false;
+    let broken = 0;
+    const say = (level, event, fields) => {
+        opts.logger?.[level]?.(event, { lane, ...fields });
+    };
+    const linkCall = (what, fn) => {
+        try {
+            fn();
+        }
+        catch (e) {
+            say("warn", "sandbox_read_floor_link_error", { what, error: echoCallerText(String(e), { maxChars: 200 }) });
+        }
+    };
+    const closeLink = () => {
+        const l = link;
+        link = undefined;
+        relayUp = false;
+        if (l !== undefined)
+            linkCall("close", () => l.close());
+    };
+    const openRelay = (gen, fresh) => new Promise((resolve) => {
+        if (transport === undefined || bin === undefined)
+            return resolve({ ok: false, reason: "relay_silent", detail: "the floor is not placed" });
+        let buffered = "";
+        let first = true;
+        let settled = false;
+        let dead = false;
+        let opened;
+        const pendingOut = [];
+        const settle = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(v);
+        };
+        const send = (line) => {
+            const o = opened;
+            if (o === undefined)
+                pendingOut.push(line);
+            else
+                linkCall("send", () => o.send(line));
+        };
+        const lost = (why) => {
+            if (dead)
+                return;
+            dead = true;
+            settle({ ok: false, reason: "relay_silent", detail: why });
+            const o = opened;
+            if (o !== undefined)
+                linkCall("close", () => o.close());
+            if (gen !== generation || o === undefined || link !== o)
+                return;
+            link = undefined;
+            const wasUp = relayUp;
+            relayUp = false;
+            if (!wasUp || disposed)
+                return;
+            say("warn", "sandbox_read_floor_relay_lost", { why });
+            void restartRelay(gen);
+        };
+        const timer = setTimeout(() => lost(`the relay sent no first frame within ${readyMs}ms`), readyMs);
+        timer.unref?.();
+        const events = {
+            data(chunk) {
+                if (dead || gen !== generation)
+                    return;
+                buffered += chunk;
+                let nl;
+                while ((nl = buffered.indexOf("\n")) >= 0) {
+                    const raw = buffered.slice(0, nl);
+                    buffered = buffered.slice(nl + 1);
+                    if (Buffer.byteLength(raw, "utf8") > MAX_RELAY_LINE_BYTES)
+                        return lost(`the relay sent a frame over ${MAX_RELAY_LINE_BYTES} bytes`);
+                    const line = raw.trim();
+                    if (line === "")
+                        continue;
+                    const frame = parseRelayFrame(line);
+                    if (first) {
+                        first = false;
+                        if (frame.t === "ready") {
+                            relayUp = true;
+                            settle({ ok: true });
+                        }
+                        else if (frame.t === "refused") {
+                            settle({ ok: false, reason: REASON_SET.has(frame.why) ? frame.why : "binary_digest", detail: `the relay refused to serve: ${echoCallerText(frame.detail, { maxChars: 200 })}` });
+                        }
+                        else {
+                            settle({ ok: false, reason: "binary_digest", detail: "the relay's first frame is neither ready nor refused" });
+                        }
+                        continue;
+                    }
+                    if (frame.t === "broken") {
+                        broken++;
+                        say("warn", "sandbox_read_floor_frame_broken", { broken, refused: frame.count !== undefined, why: frame.why });
+                    }
+                    const out = judge.answer(frame);
+                    if (out !== undefined)
+                        send(`${JSON.stringify(out)}\n`);
+                }
+                if (Buffer.byteLength(buffered, "utf8") > MAX_RELAY_LINE_BYTES)
+                    lost(`the relay sent more than ${MAX_RELAY_LINE_BYTES} bytes without a line end`);
+            },
+            closed(why) {
+                lost(`the relay closed (${echoCallerText(why, { maxChars: 200 })})`);
+            },
+        };
+        const o = transport.openRelay(plan.control, `exec ${shellLine(FLOOR_ARGV.serve(bin, plan.stateDir, fresh))}`, events);
+        opened = o;
+        if (dead)
+            return linkCall("close", () => o.close());
+        link = o;
+        for (const line of pendingOut.splice(0))
+            send(line);
+    });
+    const restartRelay = (gen) => (restarting ??= (async () => {
+        let last = { ok: false, reason: "relay_silent", detail: "no restart was attempted" };
+        try {
+            for (let i = 0; i < maxRestarts; i++) {
+                if (i > 0)
+                    await new Promise((r) => setTimeout(r, backoffMs * 2 ** (i - 1)));
+                if (disposed || gen !== generation)
+                    return;
+                last = await openRelay(gen, false);
+                if (last.ok) {
+                    say("info", "sandbox_read_floor_relay_restarted", { attempt: i + 1 });
+                    return;
+                }
+            }
+            if (!last.ok)
+                fail(gen, last.reason, `${last.detail} (after ${maxRestarts} restart(s))`);
+        }
+        finally {
+            restarting = undefined;
+        }
+    })());
+    const fail = (gen, reason, detail) => {
+        if (gen !== generation || disposed)
+            return;
+        phase = { kind: "unavailable", reason, ...(detail !== undefined ? { detail } : {}) };
+        say("warn", "sandbox_read_floor_unavailable", { reason, ...(detail !== undefined ? { detail: detail.slice(0, 300) } : {}) });
+    };
+    const runLaunch = (startId) => ({ mode: "run", head: FLOOR_ARGV.run(bin, startId, as), identity: plan.start, startId });
+    return {
+        lane,
+        state: "kept",
+        binaries: opts.binaries,
+        wrap(start) {
+            switch (start.kind) {
+                case "bootstrap":
+                    return phase.kind === "attaching" ? okLaunch({ mode: "control", identity: plan.control }) : spawnError(`read floor: a bootstrap start outside the floor's attach on this ${lane} sandbox is refused (an adapter defect)`);
+                case "adapter":
+                    if (verified !== undefined)
+                        return okLaunch({ mode: "plain", head: FLOOR_ARGV.plain(verified.bin, verified.as), identity: plan.start });
+                    if (!attachBegun)
+                        return okLaunch(BARE);
+                    return spawnError(phase.kind === "unavailable"
+                        ? buildReadFloorUnavailableMessage(phase.reason, phase.detail, undefined)
+                        : `read floor: an adapter command on this ${lane} sandbox while the floor's attach has not verified a supervisor — refused rather than run it outside the floor`);
+                case "under": {
+                    if (phase.kind === "unavailable")
+                        return spawnError(buildReadFloorUnavailableMessage(phase.reason, phase.detail, undefined));
+                    if (bin === undefined || start.startId === undefined || !judge.launch(start.startId))
+                        return spawnError(`read floor: the start this command reads on behalf of is no longer registered on this ${lane} sandbox — refused rather than read its output outside its floor`);
+                    return okLaunch(runLaunch(start.startId));
+                }
+                case "engine": {
+                    const floor = start.readFloor;
+                    if (floor === undefined)
+                        return spawnError(buildReadFloorMissingMessage(lane));
+                    if (phase.kind === "unavailable")
+                        return spawnError(buildReadFloorUnavailableMessage(phase.reason, phase.detail, floor));
+                    if (phase.kind !== "ready" || bin === undefined)
+                        return spawnError(buildReadFloorUnavailableMessage("relay_silent", "the floor is not attached to this sandbox yet", floor));
+                    if (!relayUp && transport !== undefined)
+                        void restartRelay(generation);
+                    const id = judge.register(floor, start.hold === true);
+                    return okLaunch(runLaunch(id));
+                }
+            }
+        },
+        release(startId) {
+            if (startId !== undefined)
+                judge.release(startId);
+        },
+        async attach(t, how) {
+            if (disposed)
+                return;
+            attachBegun = true;
+            const gen = ++generation;
+            closeLink();
+            judge.clear();
+            transport = t;
+            bin = undefined;
+            as = undefined;
+            phase = { kind: "attaching" };
+            if (placementRefused !== undefined)
+                return fail(gen, "binary_digest", placementRefused);
+            const u = await t.bootstrap("uname -m");
+            if (gen !== generation)
+                return;
+            if (!u.ok || u.exitCode !== 0)
+                return fail(gen, "relay_silent", `the sandbox did not answer the architecture probe (${u.ok ? `exit ${u.exitCode}` : echoCallerText(u.error, { maxChars: 200 })})`);
+            const arch = ARCH_OF_UNAME[u.stdout.trim()];
+            if (arch === undefined)
+                return fail(gen, "arch", `uname -m answered ${JSON.stringify(echoCallerText(u.stdout.trim(), { maxChars: 40 }))}`);
+            if (plan.dropToWorkspaceOwner) {
+                const o = await t.bootstrap(`stat -c %u -- ${shellQuote(how.workspaceRoot)}`);
+                if (gen !== generation)
+                    return;
+                const uid = o.ok && o.exitCode === 0 ? o.stdout.trim() : "";
+                if (!/^\d{1,10}$/.test(uid))
+                    return fail(gen, "relay_silent", `the sandbox did not answer the workspace owner probe for ${how.workspaceRoot}`);
+                if (uid === "0")
+                    return fail(gen, "uid_zero", `${how.workspaceRoot} is owned by root`);
+                as = uid;
+            }
+            const build = opts.binaries.build(arch);
+            if (!build.ok)
+                return fail(gen, "binary_digest", `this server carries no usable supervisor build for ${arch} (${build.why})`);
+            const path = floorBinaryPath(arch);
+            const placed = await t.place(path, build.bytes);
+            if (gen !== generation)
+                return;
+            if (!placed.ok)
+                return fail(gen, "binary_digest", `placing the supervisor failed: ${echoCallerText(placed.error, { maxChars: 200 })}`);
+            bin = path;
+            const relay = await openRelay(gen, how.origin === "created");
+            if (gen !== generation)
+                return;
+            if (!relay.ok) {
+                bin = undefined;
+                return fail(gen, relay.reason, relay.detail);
+            }
+            const sc = await t.bootstrap(shellLine(FLOOR_ARGV.selfcheck(path, build.digest, as)));
+            if (gen !== generation)
+                return;
+            if (!sc.ok) {
+                bin = undefined;
+                return fail(gen, "relay_silent", `the selfcheck did not run (${echoCallerText(sc.error, { maxChars: 200 })})`);
+            }
+            const verdict = parseSelfcheck(sc.stdout, sc.exitCode);
+            if (!verdict.ok || verdict.arch !== arch) {
+                bin = undefined;
+                closeLink();
+                return verdict.ok ? fail(gen, "arch", `the supervisor reports ${verdict.arch}, the sandbox answered ${arch}`) : fail(gen, verdict.reason, verdict.detail);
+            }
+            phase = { kind: "ready" };
+            verified = { bin: path, as };
+            say("info", "sandbox_read_floor_attached", { arch, origin: how.origin, version: verdict.version });
+        },
+        refusePlacement(detail) {
+            placementRefused = detail;
+        },
+        dispose() {
+            disposed = true;
+            generation++;
+            closeLink();
+            judge.clear();
+            phase = { kind: "idle" };
+        },
+    };
+}
+export function createSandboxReadFloor(opts) {
+    const state = sandboxReadFloorState(opts.lane, opts.knob);
+    switch (state) {
+        case "kept":
+            return createKeptSandboxReadFloor({ lane: opts.lane, binaries: createPackagedFloorBinaries(), ...(opts.logger !== undefined ? { logger: opts.logger } : {}) });
+        case "off":
+        case "unserved":
+            return createBareFloor(opts.lane, state);
+    }
+}
+export function floorArgv(launch, shellArgv) {
+    switch (launch.mode) {
+        case "bare":
+        case "control":
+            return shellArgv;
+        case "run":
+        case "plain":
+            return [...launch.head, "--", ...shellArgv];
+    }
+}
+export function e2bFloorCommand(launch, command, envs) {
+    switch (launch.mode) {
+        case "bare":
+            return { cmd: command, ...(envs !== undefined ? { envs: { ...envs } } : {}) };
+        case "control":
+            return { cmd: command, ...e2bUser(launch.identity) };
+        case "run":
+            return { cmd: `exec ${shellLine([...launch.head, ...e2bEnvFlags(envs), "--", "/bin/bash", "-l", "-c", command])}`, ...e2bUser(launch.identity) };
+        case "plain":
+            return { cmd: `exec ${shellLine([...launch.head, ...e2bEnvFlags(envs), "--", "/bin/bash", "-c", command])}`, ...e2bUser(launch.identity) };
+    }
+}
+const e2bUser = (identity) => {
+    switch (identity) {
+        case "root":
+            return { user: "root" };
+        case "exec-user":
+            return {};
+    }
+};
+const e2bEnvFlags = (envs) => Object.entries(envs ?? {}).flatMap(([k, v]) => ["--env", `${k}=${v}`]);
+export function dockerIdentityFlags(launch) {
+    switch (launch.mode) {
+        case "bare":
+            return [];
+        case "control":
+        case "run":
+        case "plain":
+            switch (launch.identity) {
+                case "root":
+                    return ["-u", "0"];
+                case "exec-user":
+                    return [];
+            }
+    }
+}
+const ARCHES = ["x86_64", "aarch64"];
+export const FLOOR_K8S_VOLUME_NAMES = Object.freeze({ x86_64: ADAPTER_VOLUME_NAMES.floorX86_64, aarch64: ADAPTER_VOLUME_NAMES.floorAarch64 });
+export const FLOOR_K8S_CONFIGMAP_KEY = "sema-floor";
+export function buildFloorPodSeat(floor) {
+    const binaries = floor.binaries;
+    if (floor.state !== "kept" || floor.lane !== "k8s" || binaries === undefined)
+        return undefined;
+    const configMaps = [];
+    const volumes = [];
+    const mounts = [];
+    for (const arch of ARCHES) {
+        const build = binaries.build(arch);
+        if (!build.ok)
+            continue;
+        const name = `sema-floor-${arch === "x86_64" ? "x86-64" : arch}-${build.digest.slice(0, 16)}`;
+        configMaps.push({ name, arch, binaryDataB64: Buffer.from(build.bytes).toString("base64") });
+        volumes.push({ name: FLOOR_K8S_VOLUME_NAMES[arch], configMap: { name, items: [{ key: FLOOR_K8S_CONFIGMAP_KEY, path: "sema-floor" }], defaultMode: 0o555 } });
+        mounts.push({ name: FLOOR_K8S_VOLUME_NAMES[arch], mountPath: `${FLOOR_DIR}/${arch}`, readOnly: true });
+    }
+    return { configMaps, volumes, mounts };
+}
+//# sourceMappingURL=sandbox-read-floor.js.map

package/dist/plugins/session-ownership.d.ts

@@ -25,7 +25,8 @@ export declare function assertFirstOwnerWritable(sessionId: string, owner: unkno
 /**
  * 导入者的属主 —— 换装的写腿(公开 `importEntries` / `replaceEntries` 与暂存提交)把调用方给的属主重戳进会话行之前的唯一读法:
  * 主体名或 `null`(匿名)⇒ 原样交回;别的一切(空串、空白串、带控制 / 分隔 / 非连接符格式字符的串、非串)⇒ `TypeError` 响亮拒 ——
- * 与引擎导入口拒同一类值时同一类错、同一句开头(引擎那一判只作用于交给它的属主,而换装交给引擎的是存档自己的戳,所以这一判在本仓)。
+ * 与引擎导入口拒同一类值时同一类错、同一句开头(引擎那一判只作用于交给它的属主,而 local 店交给引擎仓的属主恒缺席 —— 引擎仓是匿名内容仓,属主只在本店的行上 ——
+ * 所以这一判在本仓)。
  * 调用方在读写任何东西之前判,拒了就一个字节没写。判官 = {@link isSessionOwnerValue}(core `principalNameOf`),不在本仓另写规则。
  */
 export declare function importerOwnerOf(owner: unknown): string | null;

package/dist/plugins/session-placement.d.ts

@@ -1,6 +1,6 @@
 /**
  * [ref] C18(core 5.48.0 [ref]「不造新店」提货批,黑板 [ref] 点名义务)——**subagent 转录持久化**
- * 的 placement 语义,SQL 孪生共用的一份判据。
+ * 的 placement 语义,三只会话店(SQL 两孪生 + local)共用的一份声明与判据。
  *
  * ## 这是什么
  *
@@ -35,16 +35,29 @@
  */
 import { type PlacedSessionRow, type SessionPlacement, type SessionPlacementRecord, type SessionStore } from "@sema-agent/core";
 /**
- * 两支 SQL 孪生的 placement **声明**(core `SessionStore.placements`)。
+ * 三只持久会话店(SQL 两孪生 + local 后端)的**会话耐久声明**(core `SessionStore.durability`:未 placed 的会话活不活过进程重启)——
+ * **单源**:三处声明(两孪生类上的顶层 `durability`、`LocalBackend` 交给店的顶层 `durability`)与委派分区的 {@link SESSION_PLACEMENTS}
+ * 引用的都是这一只常量,源码里不再有第二份 `"durable"` 字面(`test/session-store-durability-declaration.test.ts` 的 AST 钉)。
+ *
+ * 为什么必须声明:core 的静态装配对**缺席**折 `"process-local"`(它不能替没表态的店猜),接线清单 `session.store` 与起服自检读的就是它 ——
+ * 不声明 ⇒ 一个真持久的 SQL 部署读成「重启即丢」,没有任何一处报错。依据同下面分区声明那一段:两孪生的会话史落在 `session_meta` + `session_event` 两张真表,
+ * local 的会话史落在数据根下的会话存档,进程重启后都能把已有会话取回来。包装层(缓存层)逐字转发;fork 路由层不声明(它自己的未 placed 会话住进程内短 TTL 店,
+ * 顶层耐久只说未 placed 的会话——见 `fork-routing-session-store.ts` 头注)。
+ */
+export declare const SESSION_DURABILITY: "durable";
+/**
+ * 三只持久会话店的 placement **声明**(core `SessionStore.placements`):两支 SQL 孪生(类上的字段)与 local 后端
+ * (`LocalBackend` 装配 `LocalSessionStore` 时交进去 —— 值与 core `FileStorageBackend` 对同一种文件 repo 的声明同)。
  *
  * 🔴 声明制,不是鸭子类型:core 的铸造门判「row store ∧ session 店声明」,不声明的店**不收** placed
  * 语义(合法降级:placement 参数被忽略,会话就是普通会话)。所以这一格只有在上面六条义务**全部**在
  * 本店实装之后才允许存在——它是一句关于本店行为的承诺,不是一个功能开关。
  * `durable` 的依据:两支孪生的会话史落在 `session_meta`+`session_event` 两张真表上,进程重启后
  * `acquire(id,{requireExisting:true})` 从事件日志重放(义务 1 的机器证在
- * `test/session-placement-db-integration.test.ts` 的跨进程复活格)。
+ * `test/session-placement-db-integration.test.ts` 的跨进程复活格);local 的会话史落在数据根下的会话存档
+ * (元组在存档行头),属主与化身在同一数据根的会话元数据边档(机器证在 `test/local-session-placement.test.ts` 的重启格)。
  */
-export declare const SQL_SESSION_PLACEMENTS: {
+export declare const SESSION_PLACEMENTS: {
     readonly subagent: {
         readonly durability: "durable";
     };

package/dist/plugins/session-placement.js

@@ -1,5 +1,6 @@
 import { SessionError } from "@sema-agent/core";
-export const SQL_SESSION_PLACEMENTS = { subagent: { durability: "durable" } };
+export const SESSION_DURABILITY = "durable";
+export const SESSION_PLACEMENTS = { subagent: { durability: SESSION_DURABILITY } };
 export const PLACEMENT_SELECT_COLUMNS = "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at";
 function toEpochMs(v) {
     if (v == null)