@sema-agent/server 7.49.0 → 7.51.0

package/dist/plugins/remote-env-device.js

@@ -0,0 +1,727 @@
+import { posix } from "node:path";
+import { ExecutionError, FileError, RemoteExecutionError, } from "@sema-agent/core";
+import { DEVICE_ERROR_CODES, DEVICE_RATE_LIMIT_CODE, } from "../device-store.js";
+export const DEVICE_PROVIDER = "device";
+const ok = (value) => ({ ok: true, value });
+const STREAM_PENDING_MAX_BYTES = 2 * 1024 * 1024;
+const STREAM_PENDING_MAX_ENTRIES = 8192;
+const VERIFY_FIRST = "may have already executed on the target; verify its effect before re-running";
+export const DEVICE_OUTCOME_TO_FILE_ERROR = {
+    aborted: "aborted",
+    already_exists: "already_exists",
+    auth_failed: "unknown",
+    callback_error: "unknown",
+    invalid: "invalid",
+    is_directory: "is_directory",
+    not_directory: "not_directory",
+    not_found: "not_found",
+    not_supported: "not_supported",
+    outcome_unknown: "outcome_unknown",
+    permission_denied: "permission_denied",
+    precondition_failed: "precondition_failed",
+    shell_unavailable: "unknown",
+    spawn_error: "unknown",
+    suspended: "unknown",
+    target_unavailable: "transport_lost",
+    timeout: "timeout",
+    transport_lost: "transport_lost",
+    unknown: "unknown",
+};
+export const DEVICE_OUTCOME_TO_EXEC_ERROR = {
+    aborted: "aborted",
+    already_exists: "unknown",
+    auth_failed: "auth_failed",
+    callback_error: "callback_error",
+    invalid: "unknown",
+    is_directory: "unknown",
+    not_directory: "unknown",
+    not_found: "unknown",
+    not_supported: "shell_unavailable",
+    outcome_unknown: "outcome_unknown",
+    permission_denied: "unknown",
+    precondition_failed: "unknown",
+    shell_unavailable: "shell_unavailable",
+    spawn_error: "spawn_error",
+    suspended: "suspended",
+    target_unavailable: "target_unavailable",
+    timeout: "timeout",
+    transport_lost: "transport_lost",
+    unknown: "unknown",
+};
+export const DEVICE_REJECT_TO_EXEC_ERROR = {
+    "device.not_bound": "target_unavailable",
+    "device.offline": "target_unavailable",
+    "device.busy": "target_unavailable",
+    "device.attached_elsewhere": "target_unavailable",
+    "device.claim_conflict": "target_unavailable",
+    "device.provider_mismatch": "auth_failed",
+    "device.identity_mismatch": "auth_failed",
+    "device.revoked": "auth_failed",
+    "device.enrollment_invalid": "auth_failed",
+    "not_found.device": "auth_failed",
+    "limit.rate_exceeded": "target_unavailable",
+};
+export const DEVICE_REJECT_TO_FILE_ERROR = {
+    "device.not_bound": "transport_lost",
+    "device.offline": "transport_lost",
+    "device.busy": "transport_lost",
+    "device.attached_elsewhere": "transport_lost",
+    "device.claim_conflict": "transport_lost",
+    "device.provider_mismatch": "permission_denied",
+    "device.identity_mismatch": "permission_denied",
+    "device.revoked": "permission_denied",
+    "device.enrollment_invalid": "permission_denied",
+    "not_found.device": "permission_denied",
+    "limit.rate_exceeded": "transport_lost",
+};
+const DEVICE_REJECT_TO_REMOTE_ERROR = {
+    "device.not_bound": "connect_failed",
+    "device.offline": "connect_failed",
+    "device.busy": "connect_failed",
+    "device.attached_elsewhere": "connect_failed",
+    "device.claim_conflict": "auth_failed",
+    "device.provider_mismatch": "auth_failed",
+    "device.identity_mismatch": "auth_failed",
+    "device.revoked": "auth_failed",
+    "device.enrollment_invalid": "auth_failed",
+    "not_found.device": "auth_failed",
+    "limit.rate_exceeded": "connect_failed",
+};
+function rejectText(reject) {
+    return `[${reject.code}] ${reject.message}`;
+}
+function assertPosixDevicePlatform(os, deviceId) {
+    switch (os) {
+        case "darwin":
+        case "linux":
+            return;
+    }
+    throw new Error(`device lane: device ${deviceId} declares a platform this adapter has no path flavor for (${String(os)}) — win32 is a follow-on (v2 §4.2 AR-R1-8)`);
+}
+export class RemoteDeviceExecutionEnv {
+    cfg;
+    capabilities = { isolation: false, suspendable: false };
+    externalContentTarget = true;
+    hostLocalPaths = false;
+    cwd;
+    readLink;
+    writeFileExclusive;
+    writeFileGuarded;
+    connected = false;
+    destroyed = false;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.cwd = cfg.cwd;
+        if (cfg.supports?.has("readLink") === true)
+            this.readLink = (p, s) => this.doReadLink(p, s);
+        if (cfg.supports?.has("writeFileExclusive") === true)
+            this.writeFileExclusive = (p, c, s) => this.doWrite("writeFileExclusive", p, c, undefined, s);
+        if (cfg.supports?.has("writeFileGuarded") === true)
+            this.writeFileGuarded = (p, c, e, s) => this.doGuardedWrite(p, c, e, s);
+    }
+    guardFaceSnapshot() {
+        const out = new Set();
+        if (this.writeFileGuarded !== undefined)
+            out.add("writeFileGuarded");
+        if (this.writeFileExclusive !== undefined)
+            out.add("writeFileExclusive");
+        return out;
+    }
+    guardFaceDrift() {
+        const now = this.cfg.hub.declaredSupports(this.cfg.deviceId);
+        if (now === undefined)
+            return [];
+        const minted = this.guardFaceSnapshot();
+        return ["writeFileGuarded", "writeFileExclusive"].filter((k) => now.has(k) && !minted.has(k));
+    }
+    absentGuardFaces() {
+        const minted = this.guardFaceSnapshot();
+        return ["writeFileGuarded", "writeFileExclusive"].filter((k) => !minted.has(k));
+    }
+    driftError(gained, absPath) {
+        return new FileError("not_supported", `[device.capability_drift] the connected device now declares protective write primitives (${gained.join(", ")}) that this environment was minted without — ` +
+            "performing a NON-atomic write here is exactly the silent downgrade guarded writes exist to prevent (#157). Refusing; the per-task factory mints a correctly-shaped env on the next task.", absPath);
+    }
+    resolve(p) {
+        return posix.isAbsolute(p) ? posix.normalize(p) : posix.normalize(posix.join(this.cwd, p));
+    }
+    async absolutePath(p) {
+        return ok(this.resolve(p));
+    }
+    async joinPath(parts) {
+        return ok(posix.join(...parts));
+    }
+    workspaceHandle() {
+        return {
+            sandboxId: `${this.cfg.deviceId}#${this.cwd}`,
+            provider: DEVICE_PROVIDER,
+            mountPath: this.cwd,
+            deviceId: this.cfg.deviceId,
+            restoreMode: "park_only",
+        };
+    }
+    async connect(config) {
+        if (this.destroyed)
+            return { ok: false, error: new RemoteExecutionError("connect_failed", "device env destroyed — create a fresh env instead of reviving") };
+        if (config?.abortSignal?.aborted === true)
+            return { ok: false, error: new RemoteExecutionError("aborted", "connect aborted") };
+        const admitted = await this.cfg.enrollment.admitSession({ rootSessionId: this.cfg.rootSessionId, requester: this.cfg.owner });
+        if (!admitted.ok) {
+            return { ok: false, error: new RemoteExecutionError(DEVICE_REJECT_TO_REMOTE_ERROR[admitted.reject.code], rejectText(admitted.reject)) };
+        }
+        if (admitted.value.deviceId !== this.cfg.deviceId) {
+            return {
+                ok: false,
+                error: new RemoteExecutionError("auth_failed", `[${DEVICE_ERROR_CODES.IDENTITY_MISMATCH}] this session is now bound to a different device than the one this environment was minted for — refusing to silently re-target (device lane identity, v2 §4.5)`),
+            };
+        }
+        {
+            const gained = this.guardFaceDrift();
+            if (gained.length > 0) {
+                return {
+                    ok: false,
+                    error: new RemoteExecutionError("connect_failed", `[device.capability_drift] this environment was minted while the device's protective write primitives (${gained.join(", ")}) were not observable, ` +
+                        "so they are absent from its filesystem face — core would read that absence as \"the backend has no such primitive\" and fall back to a NON-atomic write, " +
+                        "silently re-opening the TOCTOU window guarded writes exist to close (#157). Refusing this connect; the per-task factory will mint a correctly-shaped env on retry."),
+                };
+            }
+        }
+        this.connected = true;
+        return ok(this.workspaceHandle());
+    }
+    async reconnect(_sessionToken) {
+        this.connected = false;
+        return this.connect();
+    }
+    async suspendVM(_options) {
+        return this.unsupported("suspendVM");
+    }
+    async resumeVM(_snapshotId, _options) {
+        return this.unsupported("resumeVM");
+    }
+    async postResumeInit() {
+        return this.unsupported("postResumeInit");
+    }
+    unsupported(op) {
+        return {
+            ok: false,
+            error: new RemoteExecutionError("unsupported", `${op} is not supported on a personal device (real hardware — not snapshotable; capabilities.suspendable=false)`),
+        };
+    }
+    async destroy() {
+        this.connected = false;
+        this.destroyed = true;
+    }
+    async cleanup() {
+        return this.destroy();
+    }
+    shellGate() {
+        if (this.destroyed)
+            return { ok: false, error: new ExecutionError("shell_unavailable", "execution env already destroyed") };
+        if (!this.connected)
+            return { ok: false, error: new ExecutionError("shell_unavailable", "device env not connected — call connect() first") };
+        return undefined;
+    }
+    fsGate(p) {
+        if (this.destroyed)
+            return { ok: false, error: new FileError("unknown", "execution env already destroyed", this.resolve(p)) };
+        if (!this.connected)
+            return { ok: false, error: new FileError("unknown", "device env not connected — call connect() first", this.resolve(p)) };
+        return undefined;
+    }
+    timeoutMsFor(seconds) {
+        return seconds != null && Number.isFinite(seconds) && seconds > 0 ? Math.ceil(seconds * 1000) : this.cfg.execTimeoutMs;
+    }
+    dispatch(kind, args, opts) {
+        const input = {
+            rootSessionId: this.cfg.rootSessionId,
+            requester: this.cfg.owner,
+            kind,
+            args,
+            timeoutMs: opts.timeoutMs,
+            ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+            ...(opts.shellEnv === undefined ? {} : { shellEnv: opts.shellEnv }),
+            ...(opts.payload === undefined ? {} : { payload: opts.payload }),
+            ...(opts.onChunk === undefined ? {} : { onChunk: opts.onChunk }),
+            ...(opts.signal === undefined ? {} : { signal: opts.signal }),
+            ...(opts.refuseIfDeclared === undefined || opts.refuseIfDeclared.length === 0 ? {} : { refuseIfDeclared: opts.refuseIfDeclared }),
+        };
+        return this.cfg.hub.dispatch(input);
+    }
+    fileOutcome(res, absPath, take) {
+        switch (res.kind) {
+            case "rejected":
+                return { ok: false, error: new FileError(DEVICE_REJECT_TO_FILE_ERROR[res.reject.code], rejectText(res.reject), absPath) };
+            case "never_started":
+            case "settled": {
+                const o = res.outcome;
+                if (!o.ok)
+                    return { ok: false, error: new FileError(DEVICE_OUTCOME_TO_FILE_ERROR[o.errorCode], o.message, absPath) };
+                return take(o);
+            }
+        }
+    }
+    wrongOutcome(want, got, absPath) {
+        return { ok: false, error: new FileError("unknown", `device returned a "${got}" outcome for an operation that requires "${want}" — protocol violation`, absPath) };
+    }
+    async exec(command, options) {
+        const gated = this.shellGate();
+        if (gated)
+            return gated;
+        let stdout = "";
+        let stderr = "";
+        const res = await this.dispatch("exec", { command }, {
+            timeoutMs: this.timeoutMsFor(options?.timeout),
+            ...(options?.abortSignal === undefined ? {} : { signal: options.abortSignal }),
+            cwd: options?.cwd === undefined ? this.cwd : this.resolve(options.cwd),
+            ...(mergedEnv(this.cfg.shellEnv, options?.env) === undefined ? {} : { shellEnv: mergedEnv(this.cfg.shellEnv, options?.env) }),
+            onChunk: (c) => {
+                if (c.kind === "stdout") {
+                    const s = c.data?.toString("utf8") ?? "";
+                    stdout += s;
+                    options?.onStdout?.(s);
+                }
+                else if (c.kind === "stderr") {
+                    const s = c.data?.toString("utf8") ?? "";
+                    stderr += s;
+                    options?.onStderr?.(s);
+                }
+            },
+        });
+        switch (res.kind) {
+            case "rejected":
+                return { ok: false, error: new ExecutionError(DEVICE_REJECT_TO_EXEC_ERROR[res.reject.code], rejectText(res.reject)) };
+            case "never_started":
+            case "settled": {
+                const o = res.outcome;
+                if (!o.ok) {
+                    return { ok: false, error: new ExecutionError(DEVICE_OUTCOME_TO_EXEC_ERROR[o.errorCode], o.message, undefined, { stdout, stderr }) };
+                }
+                if (o.kind === "cancelled") {
+                    return { ok: false, error: new ExecutionError("aborted", `the device reported the command as ${o.state} after a cancel`, undefined, { stdout, stderr }) };
+                }
+                if (o.kind !== "exec")
+                    return { ok: false, error: new ExecutionError("unknown", `device returned a "${o.kind}" outcome for an exec — protocol violation`) };
+                return ok({ stdout: markTruncated(stdout, o.truncated?.stdout), stderr: markTruncated(stderr, o.truncated?.stderr), exitCode: o.exitCode });
+            }
+        }
+    }
+    async *execStream(command, options) {
+        if (this.destroyed)
+            throw new RemoteExecutionError("connect_failed", "execution env already destroyed");
+        if (!this.connected)
+            throw new RemoteExecutionError("connect_failed", "device env not connected — call connect() first");
+        const queue = [];
+        let queuedBytes = 0;
+        let done = false;
+        let failure;
+        let localOverflow;
+        let accepting = true;
+        let droppedAfterClose = 0;
+        const closeQueue = () => {
+            if (!accepting)
+                return;
+            accepting = false;
+            queue.length = 0;
+            queuedBytes = 0;
+        };
+        let wake;
+        const signalReady = () => {
+            const w = wake;
+            wake = undefined;
+            w?.();
+        };
+        const inner = new AbortController();
+        let onOuterAbort;
+        if (options?.signal) {
+            if (options.signal.aborted)
+                inner.abort();
+            else {
+                onOuterAbort = () => inner.abort();
+                options.signal.addEventListener("abort", onOuterAbort, { once: true });
+            }
+        }
+        const settled = this.dispatch("execStream", { command }, {
+            timeoutMs: this.timeoutMsFor(options?.timeout),
+            signal: inner.signal,
+            cwd: options?.cwd === undefined ? this.cwd : this.resolve(options.cwd),
+            ...(mergedEnv(this.cfg.shellEnv, options?.env) === undefined ? {} : { shellEnv: mergedEnv(this.cfg.shellEnv, options?.env) }),
+            onChunk: (c) => {
+                if (!accepting) {
+                    if (droppedAfterClose === 0) {
+                        this.cfg.logger?.warn("device_exec_stream_chunks_dropped_after_close", {
+                            deviceId: this.cfg.deviceId,
+                            note: "the stream was refused (buffer overflow) or its consumer left; the remote command has been cancelled but the device keeps sending until its own grace elapses — these chunks are dropped instead of accumulating",
+                        });
+                    }
+                    droppedAfterClose += 1;
+                    return;
+                }
+                if (c.kind === "stdout" || c.kind === "stderr") {
+                    const cost = c.data?.length ?? 0;
+                    queue.push({ chunk: { type: c.kind, data: c.data?.toString("utf8") ?? "" }, cost });
+                    queuedBytes += cost;
+                }
+                else if (c.kind === "exit") {
+                    queue.push({ chunk: { type: "exit", exitCode: c.exitCode ?? 0 }, cost: 0 });
+                }
+                else {
+                    this.cfg.logger?.warn("device_exec_stream_unexpected_chunk_kind", { deviceId: this.cfg.deviceId, kind: c.kind });
+                }
+                if (queuedBytes > STREAM_PENDING_MAX_BYTES || queue.length > STREAM_PENDING_MAX_ENTRIES) {
+                    localOverflow ??= new RemoteExecutionError("unknown", `device execStream pending stream buffer exceeded its bound (${queuedBytes} bytes / ${queue.length} entries; caps ${STREAM_PENDING_MAX_BYTES} bytes / ${STREAM_PENDING_MAX_ENTRIES} entries) ` +
+                        "with an un-drained consumer — the remote command was cancelled and this stream is refused rather than silently truncated");
+                    closeQueue();
+                    inner.abort();
+                }
+                signalReady();
+            },
+        });
+        void settled.then((res) => {
+            failure ??= streamFailure(res);
+            done = true;
+            signalReady();
+        }, (err) => {
+            failure ??= new RemoteExecutionError("unknown", err instanceof Error ? err.message : String(err));
+            done = true;
+            signalReady();
+        });
+        try {
+            for (;;) {
+                if (localOverflow)
+                    throw localOverflow;
+                while (queue.length > 0) {
+                    const item = queue.shift();
+                    queuedBytes -= item.cost;
+                    if (failure && item.chunk.type === "exit")
+                        continue;
+                    yield item.chunk;
+                    if (localOverflow)
+                        throw localOverflow;
+                }
+                if (failure)
+                    throw failure;
+                if (done)
+                    break;
+                await new Promise((r) => {
+                    wake = r;
+                });
+            }
+            while (queue.length > 0) {
+                const item = queue.shift();
+                queuedBytes -= item.cost;
+                yield item.chunk;
+            }
+        }
+        finally {
+            closeQueue();
+            inner.abort();
+            if (onOuterAbort)
+                options?.signal?.removeEventListener("abort", onOuterAbort);
+            void settled.catch(() => undefined);
+        }
+    }
+    async exists(p, abortSignal) {
+        const gated = this.fsGate(p);
+        if (gated)
+            return gated;
+        const abs = this.resolve(p);
+        const res = await this.dispatch("exists", { path: abs }, { timeoutMs: this.cfg.execTimeoutMs, ...(abortSignal === undefined ? {} : { signal: abortSignal }) });
+        return this.fileOutcome(res, abs, (o) => {
+            if (o.kind !== "stat")
+                return this.wrongOutcome("stat", o.kind, abs);
+            if (typeof o.existsValue !== "boolean")
+                return { ok: false, error: new FileError("unknown", "device returned a stat outcome without an existsValue — protocol violation", abs) };
+            return ok(o.existsValue);
+        });
+    }
+    async canonicalPath(p, abortSignal) {
+        const gated = this.fsGate(p);
+        if (gated)
+            return gated;
+        const abs = this.resolve(p);
+        const res = await this.dispatch("canonicalPath", { path: abs }, { timeoutMs: this.cfg.execTimeoutMs, ...(abortSignal === undefined ? {} : { signal: abortSignal }) });
+        return this.fileOutcome(res, abs, (o) => {
+            if (o.kind !== "stat")
+                return this.wrongOutcome("stat", o.kind, abs);
+            if (typeof o.canonicalPath !== "string")
+                return { ok: false, error: new FileError("unknown", "device returned a stat outcome without a canonicalPath — protocol violation", abs) };
+            return ok(o.canonicalPath);
+        });
+    }
+    async fileInfo(p, abortSignal) {
+        const gated = this.fsGate(p);
+        if (gated)
+            return gated;
+        const abs = this.resolve(p);
+        const res = await this.dispatch("fileInfo", { path: abs }, { timeoutMs: this.cfg.execTimeoutMs, ...(abortSignal === undefined ? {} : { signal: abortSignal }) });
+        return this.fileOutcome(res, abs, (o) => {
+            if (o.kind !== "stat")
+                return this.wrongOutcome("stat", o.kind, abs);
+            if (!o.info)
+                return { ok: false, error: new FileError("unknown", "device returned a stat outcome without info — protocol violation", abs) };
+            return ok(toFileInfo(o.info));
+        });
+    }
+    async doReadLink(p, abortSignal) {
+        const gated = this.fsGate(p);
+        if (gated)
+            return gated;
+        const abs = this.resolve(p);
+        const res = await this.dispatch("readLink", { path: abs }, { timeoutMs: this.cfg.execTimeoutMs, ...(abortSignal === undefined ? {} : { signal: abortSignal }) });
+        return this.fileOutcome(res, abs, (o) => {
+            if (o.kind !== "stat")
+                return this.wrongOutcome("stat", o.kind, abs);
+            if (o.linkTarget === null)
+                return { ok: false, error: new FileError("invalid", "not a symlink", abs) };
+            if (typeof o.linkTarget !== "string")
+                return { ok: false, error: new FileError("unknown", "device returned a stat outcome without a linkTarget — protocol violation", abs) };
+            return ok(o.linkTarget);
+        });
+    }
+    async readBinaryFile(p, abortSignal) {
+        const gated = this.fsGate(p);
+        if (gated)
+            return gated;
+        const abs = this.resolve(p);
+        const parts = [];
+        const res = await this.dispatch("readBinaryFile", { path: abs }, {
+            timeoutMs: this.cfg.execTimeoutMs,
+            ...(abortSignal === undefined ? {} : { signal: abortSignal }),
+            onChunk: (c) => {
+                if (c.kind === "data" && c.data)
+                    parts.push(c.data);
+            },
+        });
+        return this.fileOutcome(res, abs, (o) => (o.kind === "read" ? ok(new Uint8Array(Buffer.concat(parts))) : this.wrongOutcome("read", o.kind, abs)));
+    }
+    async readTextFile(p, abortSignal) {
+        const gated = this.fsGate(p);
+        if (gated)
+            return gated;
+        const abs = this.resolve(p);
+        const parts = [];
+        const res = await this.dispatch("readTextFile", { path: abs }, {
+            timeoutMs: this.cfg.execTimeoutMs,
+            ...(abortSignal === undefined ? {} : { signal: abortSignal }),
+            onChunk: (c) => {
+                if (c.kind === "data" && c.data)
+                    parts.push(c.data);
+            },
+        });
+        return this.fileOutcome(res, abs, (o) => (o.kind === "read" ? ok(Buffer.concat(parts).toString("utf8")) : this.wrongOutcome("read", o.kind, abs)));
+    }
+    async readTextLines(p, options) {
+        const gated = this.fsGate(p);
+        if (gated)
+            return gated;
+        const abs = this.resolve(p);
+        const parts = [];
+        const res = await this.dispatch("readTextLines", { path: abs, ...(options?.maxLines === undefined ? {} : { limit: options.maxLines }) }, {
+            timeoutMs: this.cfg.execTimeoutMs,
+            ...(options?.abortSignal === undefined ? {} : { signal: options.abortSignal }),
+            onChunk: (c) => {
+                if (c.kind === "data" && c.data)
+                    parts.push(c.data);
+            },
+        });
+        return this.fileOutcome(res, abs, (o) => {
+            if (o.kind !== "read")
+                return this.wrongOutcome("read", o.kind, abs);
+            const lines = Buffer.concat(parts).toString("utf8").split(/\r?\n/);
+            if (lines.length > 0 && lines[lines.length - 1] === "")
+                lines.pop();
+            return ok(options?.maxLines != null ? lines.slice(0, options.maxLines) : lines);
+        });
+    }
+    async listDir(p, abortSignal) {
+        const gated = this.fsGate(p);
+        if (gated)
+            return gated;
+        const abs = this.resolve(p);
+        const res = await this.dispatch("listDir", { path: abs }, { timeoutMs: this.cfg.execTimeoutMs, ...(abortSignal === undefined ? {} : { signal: abortSignal }) });
+        return this.fileOutcome(res, abs, (o) => {
+            if (o.kind !== "stat")
+                return this.wrongOutcome("stat", o.kind, abs);
+            if (!o.entries)
+                return { ok: false, error: new FileError("unknown", "device returned a stat outcome without entries — protocol violation", abs) };
+            return ok(o.entries.map(toFileInfo));
+        });
+    }
+    async writeFile(p, content, abortSignal) {
+        return this.doWrite("writeFile", p, content, undefined, abortSignal);
+    }
+    async appendFile(p, content, abortSignal) {
+        return this.doWrite("appendFile", p, content, undefined, abortSignal);
+    }
+    async doWrite(kind, p, content, _unused, abortSignal) {
+        const gated = this.fsGate(p);
+        if (gated)
+            return gated;
+        const abs = this.resolve(p);
+        if (kind !== "writeFileExclusive") {
+            const gained = this.guardFaceDrift();
+            if (gained.length > 0)
+                return { ok: false, error: this.driftError(gained, abs) };
+        }
+        const bytes = typeof content === "string" ? Buffer.from(content, "utf8") : Buffer.from(content);
+        const res = await this.dispatch(kind, { path: abs, contentLen: bytes.length, sha256: "" }, {
+            timeoutMs: this.cfg.execTimeoutMs,
+            payload: bytes,
+            ...(abortSignal === undefined ? {} : { signal: abortSignal }),
+            ...(kind === "writeFileExclusive" ? {} : { refuseIfDeclared: this.absentGuardFaces() }),
+        });
+        return this.fileOutcome(res, abs, (o) => {
+            if (kind === "appendFile")
+                return o.kind === "void" ? ok(undefined) : this.wrongOutcome("void", o.kind, abs);
+            return o.kind === "write" ? ok(undefined) : this.wrongOutcome("write", o.kind, abs);
+        });
+    }
+    async doGuardedWrite(p, content, expect, abortSignal) {
+        const gated = this.fsGate(p);
+        if (gated)
+            return gated;
+        const abs = this.resolve(p);
+        const bytes = typeof content === "string" ? Buffer.from(content, "utf8") : Buffer.from(content);
+        const res = await this.dispatch("writeFileGuarded", { path: abs, contentLen: bytes.length, sha256: "", expect: toWireExpectation(expect) }, { timeoutMs: this.cfg.execTimeoutMs, payload: bytes, ...(abortSignal === undefined ? {} : { signal: abortSignal }) });
+        return this.fileOutcome(res, abs, (o) => {
+            if (o.kind !== "write")
+                return this.wrongOutcome("write", o.kind, abs);
+            return ok({
+                canonicalPath: o.canonicalPath,
+                ...(o.inode === undefined ? {} : { fileId: o.inode }),
+                created: o.created ?? this.warnMissingCreated(abs),
+            });
+        });
+    }
+    warnMissingCreated(abs) {
+        this.cfg.logger?.warn("device_write_receipt_missing_created", {
+            deviceId: this.cfg.deviceId,
+            path: abs,
+            note: "the device's write receipt omitted `created`; core's WriteReceipt has no 'unknown' spelling, so the weaker side (false) is reported — the executor should send it",
+        });
+        return false;
+    }
+    async createDir(p, options) {
+        const gated = this.fsGate(p);
+        if (gated)
+            return gated;
+        const abs = this.resolve(p);
+        const res = await this.dispatch("createDir", { path: abs, recursive: options?.recursive ?? true }, { timeoutMs: this.cfg.execTimeoutMs, ...(options?.abortSignal === undefined ? {} : { signal: options.abortSignal }) });
+        return this.fileOutcome(res, abs, (o) => (o.kind === "void" ? ok(undefined) : this.wrongOutcome("void", o.kind, abs)));
+    }
+    async remove(p, options) {
+        const gated = this.fsGate(p);
+        if (gated)
+            return gated;
+        const abs = this.resolve(p);
+        const res = await this.dispatch("remove", { path: abs, recursive: options?.recursive ?? false }, { timeoutMs: this.cfg.execTimeoutMs, ...(options?.abortSignal === undefined ? {} : { signal: options.abortSignal }) });
+        return this.fileOutcome(res, abs, (o) => (o.kind === "void" ? ok(undefined) : this.wrongOutcome("void", o.kind, abs)));
+    }
+    async createTempDir(prefix = "tmp-", abortSignal) {
+        const gated = this.fsGate(this.cwd);
+        if (gated)
+            return gated;
+        const res = await this.dispatch("createTempDir", { prefix }, { timeoutMs: this.cfg.execTimeoutMs, ...(abortSignal === undefined ? {} : { signal: abortSignal }) });
+        return this.fileOutcome(res, this.cwd, (o) => (o.kind === "write" ? ok(o.canonicalPath) : this.wrongOutcome("write", o.kind, this.cwd)));
+    }
+    async createTempFile(options) {
+        const gated = this.fsGate(this.cwd);
+        if (gated)
+            return gated;
+        const res = await this.dispatch("createTempFile", { ...(options?.prefix === undefined ? {} : { prefix: options.prefix }), ...(options?.suffix === undefined ? {} : { suffix: options.suffix }) }, { timeoutMs: this.cfg.execTimeoutMs, ...(options?.abortSignal === undefined ? {} : { signal: options.abortSignal }) });
+        return this.fileOutcome(res, this.cwd, (o) => (o.kind === "write" ? ok(o.canonicalPath) : this.wrongOutcome("write", o.kind, this.cwd)));
+    }
+}
+function mergedEnv(taskEnv, commandEnv) {
+    if (!taskEnv && !commandEnv)
+        return undefined;
+    return { ...(taskEnv ?? {}), ...(commandEnv ?? {}) };
+}
+function markTruncated(text, truncated) {
+    return truncated === true ? `${text}\n[output truncated by the device executor]` : text;
+}
+function toFileInfo(w) {
+    return { name: posix.basename(w.path), path: w.path, kind: w.kind === "dir" ? "directory" : w.kind === "symlink" ? "symlink" : "file", size: w.size, mtimeMs: w.mtimeMs };
+}
+function toWireExpectation(e) {
+    return {
+        canonicalPath: e.canonicalPath,
+        ...(e.fileId === undefined ? {} : { fileId: e.fileId }),
+        ...(e.exclusive === undefined ? {} : { exclusive: e.exclusive }),
+        ...(e.noFollow === undefined ? {} : { noFollow: e.noFollow }),
+    };
+}
+function streamFailure(res) {
+    switch (res.kind) {
+        case "rejected":
+            return new RemoteExecutionError(DEVICE_REJECT_TO_REMOTE_ERROR[res.reject.code], rejectText(res.reject));
+        case "never_started":
+        case "settled": {
+            const o = res.outcome;
+            if (o.ok)
+                return undefined;
+            return new RemoteExecutionError(OUTCOME_TO_REMOTE_ERROR[o.errorCode], o.message);
+        }
+    }
+}
+const OUTCOME_TO_REMOTE_ERROR = {
+    aborted: "aborted",
+    already_exists: "unknown",
+    auth_failed: "auth_failed",
+    callback_error: "unknown",
+    invalid: "unknown",
+    is_directory: "unknown",
+    not_directory: "unknown",
+    not_found: "unknown",
+    not_supported: "unsupported",
+    outcome_unknown: "outcome_unknown",
+    permission_denied: "unknown",
+    precondition_failed: "unknown",
+    shell_unavailable: "connect_failed",
+    spawn_error: "connect_failed",
+    suspended: "suspended",
+    target_unavailable: "connect_failed",
+    timeout: "timeout",
+    transport_lost: "transport_lost",
+    unknown: "unknown",
+};
+export function deviceExecutionEnvFactory(deps) {
+    const execTimeoutMs = deps.execTimeoutMs ?? 1_800_000;
+    return async (ctx) => {
+        const rootSessionId = ctx.placementRootSessionId;
+        if (typeof rootSessionId !== "string" || rootSessionId.length === 0) {
+            throw new Error("device lane: ExecutionEnvFactoryContext.placementRootSessionId is empty [config.placement_root_invalid] — " +
+                "the device placement is keyed on the run tree's placement root; defaulting to the child sessionId would read as a NEW placement (v2 §4.3.2 / core design/380 O1①)");
+        }
+        const binding = await deps.store.getSessionBinding(rootSessionId);
+        if (!binding) {
+            throw new Error(`device lane: no device binding for placement root ${rootSessionId} [${DEVICE_ERROR_CODES.NOT_BOUND}] — ` +
+                "the submit-time admission chain must bind the root session to a device before a run reaches the factory (v2 §4.3.2)");
+        }
+        const view = await deps.store.readDeviceForAdmission(binding.deviceId, binding.owner);
+        if (!view) {
+            throw new Error(`device lane: the bound device is gone or not owned by the binding's principal [${DEVICE_ERROR_CODES.NOT_FOUND}]`);
+        }
+        if (view.row.status === "revoked") {
+            throw new Error(`device lane: the bound device has been revoked [${DEVICE_ERROR_CODES.REVOKED}] — revocation is terminal; re-enrolling mints a NEW deviceId (v2 §8-R4)`);
+        }
+        assertPosixDevicePlatform(view.row.platformOs, view.row.deviceId);
+        return new RemoteDeviceExecutionEnv({
+            hub: deps.hub,
+            enrollment: deps.enrollment,
+            rootSessionId,
+            deviceId: binding.deviceId,
+            owner: binding.owner,
+            cwd: effectiveDeviceCwd(deps.perSessionCwd?.get(ctx.sessionId), ctx.parentCwd, view.row),
+            ...(deps.perSessionShellEnv?.get(ctx.sessionId) === undefined ? {} : { shellEnv: deps.perSessionShellEnv.get(ctx.sessionId) }),
+            execTimeoutMs,
+            supports: deps.hub.declaredSupports(binding.deviceId),
+            ...(deps.logger === undefined ? {} : { logger: deps.logger }),
+        });
+    };
+}
+export function effectiveDeviceCwd(sessionCwd, parentCwd, row) {
+    return sessionCwd ?? parentCwd ?? row.workspaceRoot;
+}
+//# sourceMappingURL=remote-env-device.js.map