@amaster.ai/mirrorx-device-client 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,1459 @@
+/** Persistent Pi/Codex device bridge; desktop callers restrict restoration to their signed-in user and service. */
+import clientManifest from "../package.json" with { type: "json" };
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, mkdir, open, readFile, readdir, rename, rm, rmdir, stat, unlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { setTimeout as delay } from "node:timers/promises";
+import { canonicalServerOrigin, mirrorxIdentityHome, readOrCreateDeviceProfile } from "./device-id.js";
+import { inspectDeviceReadiness } from "./readiness.js";
+import { acquireDeviceResourceLock, deviceResourceKey } from "./resource-lock.js";
+import { isPiDeviceCommand, preparePiDeviceCommand } from "./pi-runtime.js";
+import { discardCodebuddySession } from "./codebuddy-session.js";
+import { reclaimCodebuddyLocks } from "./codebuddy-locks.js";
+import { isCodebuddyCommand, prepareCodebuddyCommand } from "./codebuddy-runtime.js";
+import { resolveCodexExecutable } from "./codex-runtime.js";
+import { recordDeviceSession, findDeviceSession } from "./session-index.js";
+import { createManagedWorkspace, validateManagedCwd, confineManagedCommand } from "./managed-workspace.js";
+import { observeConfiguration, reclaimConfiguration } from "./configuration-lifetime.js";
+const pluginPath = "/api/plugins/mx-device-execution/api/device";
+// The complete stream is stored in MirrorX object storage. The command result
+// carries only enough beginning/ending context for existing adapter parsers.
+const RESULT_HEAD_CHARS = 32_000;
+const RESULT_TAIL_CHARS = 480_000;
+// Two streams plus JSON metadata must fit the host's 1,000,000-byte body limit.
+const RESULT_STREAM_BYTES = 400_000;
+const OUTPUT_SEGMENT_CHARS = 256_000;
+const OUTPUT_PENDING_CHARS = 8 * 1024 * 1024;
+const STOP_GRACE_MS = 3_000;
+const GROUP_REAP_GRACE_MS = 5_000;
+const POST_ROOT_GROUP_GRACE_MS = 30_000;
+function processGroupAlive(pid) {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ESRCH")
+            return false;
+        // Permission denial proves existence, not exit. Keep bounded observation.
+        if (error.code === "EPERM")
+            return true;
+        throw error;
+    }
+}
+function signalProcessGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch (error) {
+        if (error.code !== "ESRCH")
+            throw error;
+    }
+}
+class DeviceProcessGroupPendingError extends Error {
+}
+async function stopProcessTree(child, interruptFirst = false) {
+    if (!child.pid)
+        return;
+    if (child.exitCode !== null || child.signalCode !== null) {
+        // A reaped root PID no longer identifies an owned process/tree. Observing
+        // group visibility is safe, but never start another signal sequence here.
+        if (process.platform !== "win32" && !processGroupAlive(child.pid))
+            return;
+        throw new DeviceProcessGroupPendingError("Device root exited; descendant ownership requires reconciliation");
+    }
+    if (process.platform === "win32") {
+        // Windows has no POSIX process groups. /T includes descendants and /F
+        // ensures the command cannot be acknowledged while tools still run.
+        const killer = spawn("taskkill", ["/PID", String(child.pid), "/T", "/F"], { windowsHide: true });
+        const code = await new Promise((resolve, reject) => {
+            killer.once("error", reject);
+            killer.once("close", resolve);
+        });
+        if (code !== 0) {
+            throw new Error(`Could not stop device process tree: taskkill exited ${code}`);
+        }
+        return;
+    }
+    const pid = child.pid;
+    if (!processGroupAlive(pid))
+        return;
+    if (interruptFirst) {
+        // Codex owns tools in separate process groups. Its Ctrl-C handler interrupts
+        // the turn and reaps those tools; SIGTERM would bypass that cleanup.
+        signalProcessGroup(pid, "SIGINT");
+        const interruptEnds = Date.now() + STOP_GRACE_MS;
+        while (processGroupAlive(pid) && Date.now() < interruptEnds)
+            await delay(50);
+        if (!processGroupAlive(pid))
+            return;
+        if (child.exitCode !== null || child.signalCode !== null) {
+            throw new DeviceProcessGroupPendingError("Codex root exited before interrupt cleanup completed");
+        }
+    }
+    signalProcessGroup(pid, "SIGTERM");
+    const graceEnds = Date.now() + STOP_GRACE_MS;
+    while (processGroupAlive(pid) && Date.now() < graceEnds)
+        await delay(50);
+    if (processGroupAlive(pid)) {
+        if (child.exitCode !== null || child.signalCode !== null) {
+            throw new DeviceProcessGroupPendingError("Device root exited before escalation; descendants require reconciliation");
+        }
+        signalProcessGroup(pid, "SIGKILL");
+    }
+    const killEnds = Date.now() + STOP_GRACE_MS;
+    while (processGroupAlive(pid) && Date.now() < killEnds)
+        await delay(50);
+    if (processGroupAlive(pid))
+        throw new DeviceProcessGroupPendingError("Device process tree has not stopped");
+    // Forced root termination cannot attest that Codex reaped its separate tool
+    // groups. Do not let a disappearing root group turn that uncertainty into ACK.
+    if (interruptFirst)
+        throw new Error("Codex interrupt timed out; tool shutdown requires reconciliation");
+}
+// Root exit starts observation; inherited pipes must not delay its deadline.
+// Windows stop confirmation never uses POSIX group probes, including Pending errors.
+async function confirmCommandCompletion(input) {
+    const { child, signal } = input;
+    const toolsUntil = input.rootExitedAt + POST_ROOT_GROUP_GRACE_MS;
+    try {
+        if (process.platform === "win32") {
+            await input.stopTask(); // No stop: normal foreground completion. Any failure: reconcile.
+        }
+        else if (input.observeDescendants && child.pid) {
+            while (processGroupAlive(child.pid) && !input.stopTask()) {
+                if (signal?.aborted || Date.now() >= toolsUntil) {
+                    throw new DeviceProcessGroupPendingError("Device root exited; descendant wait ended without confirmed exit");
+                }
+                await delay(250);
+            }
+        }
+        if (process.platform !== "win32") {
+            try {
+                await input.stopTask();
+            }
+            catch (error) {
+                if (!(error instanceof DeviceProcessGroupPendingError) || !child.pid)
+                    throw error;
+                const reapUntil = Date.now() + GROUP_REAP_GRACE_MS;
+                while (processGroupAlive(child.pid) && !signal?.aborted && Date.now() < reapUntil)
+                    await delay(250);
+                if (processGroupAlive(child.pid))
+                    throw error;
+            }
+        }
+        // close also waits for inherited stdout/stderr, even if an escaped tool is
+        // no longer visible in the root group. Drain only within the same deadline.
+        while (!input.stdioClosed()) {
+            if (signal?.aborted || Date.now() >= toolsUntil) {
+                throw new DeviceProcessGroupPendingError("Device root exited; output pipes did not close before observation ended");
+            }
+            await delay(50);
+        }
+        // A stop can arrive while inherited pipes are draining after root exit.
+        if (process.platform === "win32")
+            await input.stopTask();
+        return { state: "completed" };
+    }
+    catch (error) {
+        return { state: "reconcile", error };
+    }
+}
+function takeOutputChunk(value, limit) {
+    let end = Math.min(value.length, limit);
+    if (end < value.length && end > 0) {
+        const last = value.charCodeAt(end - 1);
+        const next = value.charCodeAt(end);
+        if (last >= 0xd800 && last <= 0xdbff && next >= 0xdc00 && next <= 0xdfff)
+            end -= 1;
+    }
+    return value.slice(0, end);
+}
+export class DeviceRequestError extends Error {
+    status;
+    code;
+    constructor(status, method, route, code) {
+        super(`MirrorX request failed: HTTP ${status} on ${method} ${route.split("?")[0]}`);
+        this.status = status;
+        this.code = code;
+    }
+}
+function outputSegmentFile(directory, seq) {
+    return path.join(directory, `${String(seq).padStart(10, "0")}.json`);
+}
+function retainOutput(head, tail, total, chunk) {
+    return {
+        head: (head + chunk).slice(0, RESULT_HEAD_CHARS),
+        tail: (tail + chunk).slice(-RESULT_TAIL_CHARS),
+        total: total + chunk.length,
+    };
+}
+function retainedResult(value) {
+    if (value.total <= RESULT_TAIL_CHARS)
+        return value.tail;
+    if (value.total <= RESULT_HEAD_CHARS + RESULT_TAIL_CHARS) {
+        return value.head + value.tail.slice(-(value.total - value.head.length));
+    }
+    return `${value.head}\n[MirrorX: middle output omitted from command result]\n${value.tail}`;
+}
+function boundedOutput(value) {
+    const serializedBytes = (text) => Buffer.byteLength(JSON.stringify(text), "utf8");
+    if (serializedBytes(value) <= RESULT_STREAM_BYTES)
+        return value;
+    const bytes = Buffer.from(value, "utf8");
+    const marker = "\n[MirrorX: middle output omitted from command result]\n";
+    let budget = Math.min(bytes.length, RESULT_STREAM_BYTES);
+    for (;;) {
+        const headBytes = Math.min(24_000, Math.floor(budget / 4));
+        const tailBytes = Math.max(0, budget - headBytes - Buffer.byteLength(marker) - 8);
+        const tail = tailBytes === 0 ? "" : bytes.subarray(-tailBytes).toString("utf8");
+        const candidate = `${bytes.subarray(0, headBytes).toString("utf8")}${marker}${tail}`;
+        if (serializedBytes(candidate) <= RESULT_STREAM_BYTES)
+            return candidate;
+        budget = Math.floor(budget * 0.7);
+    }
+}
+function boundedResult(result, companyId, claimId) {
+    const bounded = { ...result, stdout: boundedOutput(result.stdout), stderr: boundedOutput(result.stderr) };
+    const requestBytes = Buffer.byteLength(JSON.stringify({ companyId, claimId, result: bounded, outputLost: true }), "utf8");
+    if (requestBytes > 900_000)
+        throw new Error("MirrorX command result exceeds its request budget");
+    return bounded;
+}
+export function mirrorxDeviceHome() {
+    return process.env.MIRRORX_DEVICE_HOME?.trim()
+        ? path.resolve(process.env.MIRRORX_DEVICE_HOME.trim()) : path.join(os.homedir(), ".mirrorx-device");
+}
+function defaultWorkspace(kind, companyId) {
+    // WorkBuddy's workspace cannot overlap its protected device-state tree.
+    const root = mirrorxDeviceHome() + "-workspaces";
+    return path.join(root, companyId, kind);
+}
+function configFile(kind, companyId, config) {
+    return path.join(mirrorxDeviceHome(), `${kind}-${companyId}${config?.principalId && config.deviceProfileId
+        ? `-${deviceResourceKey({ ...config, bindingId: config.workspaceMode === "managed" ? config.bindingId : undefined, principalId: config.principalId, deviceProfileId: config.deviceProfileId })}` : ""}.json`);
+}
+async function configsFor(kind) {
+    const home = mirrorxDeviceHome();
+    const files = await readdir(home).catch((error) => {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    });
+    const names = files.filter((name) => name.startsWith(`${kind}-`) && name.endsWith(".json") && !name.endsWith("-journal.json"));
+    const configs = (await Promise.all(names.map((name) => loadJson(path.join(home, name)))))
+        .filter((value) => value !== null);
+    const legacy = await loadJson(path.join(home, `${kind}.json`));
+    if (legacy && !configs.some((config) => config.companyId === legacy.companyId))
+        configs.push(legacy);
+    const byBinding = new Map();
+    for (const config of configs) {
+        const key = JSON.stringify([base(config.baseUrl), config.userSubject ?? config.principalId ?? "legacy", config.companyId, config.bindingId]);
+        const previous = byBinding.get(key), generation = config.generation ?? 1, previousGeneration = previous?.generation ?? 1;
+        if (!previous || generation > previousGeneration || generation === previousGeneration && !previous.deviceProfileId && config.deviceProfileId)
+            byBinding.set(key, config);
+        else if (generation === previousGeneration && previous.deviceProfileId && config.deviceProfileId && previous.deviceProfileId !== config.deviceProfileId)
+            throw new Error("Conflicting same-generation device profiles; select an authenticated restore instead of guessing");
+    }
+    return [...byBinding.values()];
+}
+export async function hasMirrorxDevicePairing(kind) {
+    return (await configsFor(kind)).length > 0;
+}
+async function saveJson(file, value) {
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    await writeFile(temporary, JSON.stringify(value), { mode: 0o600 });
+    await chmod(temporary, 0o600);
+    await rename(temporary, file);
+}
+async function loadJson(file) {
+    try {
+        return JSON.parse(await readFile(file, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+async function acquireBridgeLock(kind, companyId, instanceId) {
+    const file = path.join(mirrorxDeviceHome(), `${kind}-${companyId}.lock`);
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+            const handle = await open(file, "wx", 0o600);
+            try {
+                await handle.writeFile(JSON.stringify({ pid: process.pid, instanceId }));
+            }
+            catch (error) {
+                await handle.close();
+                await unlink(file).catch(() => undefined);
+                throw error;
+            }
+            await handle.close();
+            return async () => {
+                const owner = await loadJson(file).catch(() => null);
+                if (owner?.instanceId === instanceId)
+                    await unlink(file).catch(() => undefined);
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const owner = await loadJson(file).catch(() => null);
+            if (owner?.pid) {
+                try {
+                    process.kill(owner.pid, 0);
+                    throw new Error("Another MirrorX bridge is running for this executor and company");
+                }
+                catch (probe) {
+                    if (probe.code !== "ESRCH")
+                        throw probe;
+                }
+            }
+            else {
+                const age = await stat(file).then((entry) => Date.now() - entry.mtimeMs).catch(() => 0);
+                if (age < 5_000)
+                    throw new Error("MirrorX bridge lock is being initialized");
+            }
+            await unlink(file).catch((removeError) => {
+                if (removeError.code !== "ENOENT")
+                    throw removeError;
+            });
+        }
+    }
+    throw new Error("Could not acquire MirrorX bridge lock");
+}
+function base(url) { return canonicalServerOrigin(url); }
+async function request(baseUrl, route, options = {}) {
+    const response = await fetch(new URL(route, baseUrl), {
+        method: options.method ?? "GET",
+        headers: {
+            "x-mirrorx-device-protocol-min": String(clientManifest.mirrorxDeviceProtocol.min), "x-mirrorx-device-protocol-max": String(clientManifest.mirrorxDeviceProtocol.max),
+            "x-mirrorx-device-client-version": clientManifest.version,
+            ...(options.body === undefined ? {} : { "content-type": "application/json" }),
+            ...(options.token ? { authorization: `Bearer ${options.token}` } : {}),
+            ...(options.deviceToken ? { "x-mirrorx-device-token": options.deviceToken } : {}),
+        },
+        ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+        signal: options.signal
+            ? AbortSignal.any([options.signal, AbortSignal.timeout(options.timeoutMs ?? 25_000)])
+            : AbortSignal.timeout(options.timeoutMs ?? 25_000),
+        redirect: "error",
+    });
+    if (!response.ok) {
+        // Project only a closed set of machine codes. Never expose upstream text,
+        // commands, credentials, arbitrary error bodies or query strings.
+        const body = await response.json().catch(() => null);
+        const candidate = body?.details?.code ?? body?.code;
+        const known = new Set(["DEVICE_SESSION_EXPIRED", "DEVICE_SESSION_ROTATED", "DEVICE_SESSION_SIGNED_OUT", "DEVICE_SESSION_INVALID", "DEVICE_REVOKED",
+            "DEVICE_MEMBERSHIP_LOST", "DEVICE_PROTOCOL_UNSUPPORTED", "PI_IDENTITY_CHOICE_REQUIRED", "DEVICE_BUSY", "DEVICE_RECOVERY_REQUIRED", "DEVICE_RECONCILIATION_REQUIRED", "DEVICE_INTENT_COMMITTED"]);
+        throw new DeviceRequestError(response.status, options.method ?? "GET", route, typeof candidate === "string" && known.has(candidate) ? candidate : undefined);
+    }
+    return await response.json();
+}
+/** Redeem a one-use code created by the signed-in MirrorX user. */
+export async function pairMirrorxDevice(input) {
+    const baseUrl = base(input.baseUrl);
+    const context = await request(baseUrl, "/api/devices/pairing-codes/context", {
+        method: "POST", body: { code: input.code, executorKind: input.executorKind },
+    });
+    if (context.enrollment && (!input.workspaceRoot || path.resolve(input.workspaceRoot) !== context.enrollment.workspaceRoot)) {
+        throw new Error("Use the exact workspace authorized in MirrorX");
+    }
+    const deviceProfileId = await readOrCreateDeviceProfile(baseUrl, context.principalId);
+    const deviceId = `${input.executorKind}:profile:${deviceProfileId}`;
+    const workspaceRoot = path.resolve(input.workspaceRoot ?? defaultWorkspace(input.executorKind, context.companyId));
+    await mkdir(workspaceRoot, { recursive: true, mode: 0o700 });
+    await validateDeviceWorkspace(workspaceRoot);
+    const release = await acquireDeviceResourceLock({ baseUrl, principalId: context.principalId, deviceProfileId, companyId: context.companyId, executorKind: input.executorKind }, randomUUID());
+    try {
+        const registration = await request(baseUrl, "/api/devices/pairing-codes/claim", {
+            method: "POST",
+            body: {
+                code: input.code,
+                deviceId, deviceProfileId,
+                executorKind: input.executorKind,
+                displayName: input.executorKind === "pi" ? "My Pi" : input.executorKind === "codebuddy" ? "My WorkBuddy" : "My Codex",
+            },
+        });
+        const companyId = registration.companyId;
+        const config = {
+            baseUrl, companyId, managedBy: "standalone", principalId: context.principalId, deviceProfileId, deviceId: registration.deviceId ?? deviceId, ...(registration.generation ? { generation: registration.generation } : {}), executorKind: input.executorKind, workspaceRoot,
+            bindingId: registration.bindingId, agentId: registration.agentId,
+            sessionId: registration.deviceSession.sessionId,
+            deviceToken: registration.deviceSession.token,
+        };
+        await saveJson(configFile(input.executorKind, companyId, config), config);
+        return {
+            baseUrl, companyId, principalId: context.principalId, deviceProfileId, deviceId, executorKind: input.executorKind, workspaceRoot,
+            bindingId: registration.bindingId, agentId: registration.agentId, sessionId: registration.deviceSession.sessionId,
+        };
+    }
+    finally {
+        await release();
+    }
+}
+/** Reuse the Pi login's IAM bearer; no second browser approval or board key. */
+export async function enrollMirrorxDevice(input) {
+    const baseUrl = base(input.baseUrl);
+    if (input.executorKind !== "pi")
+        throw new Error("External tools require explicit MirrorX enrollment authorization");
+    const identity = await request(baseUrl, "/api/devices/iam-context", {
+        token: input.iamAccessToken, ...(input.signal ? { signal: input.signal } : {}),
+    });
+    if (identity.subject !== input.userSubject)
+        throw new Error("MirrorX IAM identity does not match the signed-in Pi user");
+    const deviceProfileId = await authenticatedDeviceProfile(baseUrl, identity.principalId);
+    const deviceId = `${input.executorKind}:profile:${deviceProfileId}`;
+    const registrationBody = { deviceId, deviceProfileId, executorKind: input.executorKind,
+        displayName: input.executorKind === "pi" ? "My Pi" : input.executorKind === "codebuddy" ? "My WorkBuddy" : "My Codex" };
+    const savedConfigs = (await configsFor(input.executorKind)).filter((config) => config.baseUrl === baseUrl && config.userSubject === input.userSubject && config.workspaceMode !== "managed"
+        && typeof config.deviceToken === "string");
+    const register = async (companyId) => {
+        const result = await request(baseUrl, "/api/devices/iam-registration", {
+            method: "POST", token: input.iamAccessToken,
+            body: { ...registrationBody, bindingReferences: Object.fromEntries(savedConfigs.map(config => [config.companyId, config.bindingId])), ...(companyId ? { companyId,
+                    ...(savedConfigs.find(config => config.companyId === companyId)?.bindingId
+                        ? { bindingId: savedConfigs.find(config => config.companyId === companyId).bindingId } : {}) } : {}) },
+            ...(input.signal ? { signal: input.signal } : {}),
+        });
+        if (result.subject !== input.userSubject) {
+            throw new Error("MirrorX IAM identity does not match the signed-in Pi user");
+        }
+        if (companyId && result.registrations.some(entry => entry.companyId !== companyId)) {
+            throw new Error("MirrorX returned an unexpected device company");
+        }
+        return result;
+    };
+    const configs = [];
+    const saveRegistrations = async (registrations) => {
+        for (const registration of registrations) {
+            input.signal?.throwIfAborted();
+            const workspaceRoot = savedConfigs.find(config => config.companyId === registration.companyId && config.bindingId === registration.bindingId)?.workspaceRoot ?? defaultWorkspace(input.executorKind, registration.companyId);
+            await mkdir(workspaceRoot, { recursive: true, mode: 0o700 });
+            const config = {
+                baseUrl, userSubject: input.userSubject, managedBy: "desktop", companyId: registration.companyId,
+                ...(registration.generation ? { generation: registration.generation } : {}), deviceId: registration.deviceId ?? deviceId, principalId: identity.principalId, deviceProfileId, executorKind: input.executorKind, workspaceRoot,
+                bindingId: registration.bindingId, agentId: registration.agentId,
+                sessionId: registration.deviceSession.sessionId, deviceToken: registration.deviceSession.token,
+            };
+            await saveJson(configFile(input.executorKind, registration.companyId, config), config);
+            configs.push(config);
+        }
+    };
+    input.signal?.throwIfAborted();
+    const first = { subject: input.userSubject, registrations: [], failures: [] };
+    if (input.companyIds) {
+        for (const companyId of new Set(input.companyIds)) {
+            try {
+                const result = await register(companyId);
+                first.registrations.push(...result.registrations);
+                first.failures.push(...result.failures ?? []);
+                if (!result.registrations.some(entry => entry.companyId === companyId)
+                    && !result.failures?.some(entry => entry.companyId === companyId)) {
+                    first.failures.push({ companyId, status: 0, retryable: false, error: "Device company registration was not returned" });
+                }
+            }
+            catch (error) {
+                input.signal?.throwIfAborted();
+                const status = error instanceof DeviceRequestError ? error.status : 0;
+                const retryable = status === 408 || status === 429 || status >= 500
+                    || error instanceof TypeError || error instanceof Error && ["AbortError", "TimeoutError"].includes(error.name);
+                first.failures.push({ companyId, status, retryable, error: "Device company registration failed" });
+            }
+        }
+    }
+    else
+        Object.assign(first, await register());
+    await saveRegistrations(first.registrations);
+    for (const failure of first.failures ?? []) {
+        if (failure.code === "active_session") {
+            const saved = savedConfigs.find((config) => config.companyId === failure.companyId);
+            if (saved && saved.sessionId === failure.sessionId) {
+                // A whole-set retry must keep the token already used by this device.
+                configs.push(saved);
+                continue;
+            }
+        }
+        if (!failure.retryable && failure.code !== "active_session") {
+            input.onRegistrationFailure?.(failure);
+            continue;
+        }
+        let remaining = failure;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            await delay((attempt + 1) * 200, undefined, input.signal ? { signal: input.signal } : {});
+            try {
+                // Target only the failed company: a whole-set retry would rotate the
+                // sessions already saved above and leave their client tokens dead.
+                const retried = await register(failure.companyId);
+                await saveRegistrations(retried.registrations);
+                if (retried.registrations.some((entry) => entry.companyId === failure.companyId)) {
+                    remaining = undefined;
+                    break;
+                }
+                remaining = retried.failures?.find((entry) => entry.companyId === failure.companyId) ?? remaining;
+                if (!remaining?.retryable)
+                    break;
+            }
+            catch (error) {
+                input.signal?.throwIfAborted();
+                if (error instanceof DeviceRequestError) {
+                    remaining = { companyId: failure.companyId, status: error.status, error: "Device company registration failed",
+                        retryable: error.status === 408 || error.status === 429 || error.status >= 500 };
+                    if (!remaining.retryable)
+                        break;
+                }
+                // Preserve the last structured failure for the caller's diagnostics.
+            }
+        }
+        if (remaining)
+            input.onRegistrationFailure?.(remaining);
+    }
+    return configs.map(({ deviceToken: _token, ...config }) => config);
+}
+/** Non-sensitive inspection; restoration never scans unselected tools. */
+export async function listMirrorxDevicePairings(input) {
+    const kinds = input.executorKind ? [input.executorKind] : ["pi", "codex", "codebuddy"];
+    const configs = (await Promise.all(kinds.map(configsFor))).flat().filter(config => (!input.expectedSubject || config.userSubject === input.expectedSubject) && (!input.expectedBaseUrl || base(config.baseUrl) === base(input.expectedBaseUrl)));
+    return configs.map(({ deviceToken: _token, ...config }) => config);
+}
+/** Restore credentials only for a retained, explicitly authorized desktop tool.
+ * A live Pi session proves the same account/company/profile to the server. */
+export async function restoreMirrorxToolSession(input) {
+    input.signal?.throwIfAborted();
+    const baseUrl = base(input.expectedBaseUrl);
+    const config = (await configsFor(input.executorKind)).find(c => c.bindingId === input.bindingId && c.managedBy === "desktop"
+        && c.userSubject === input.expectedSubject && base(c.baseUrl) === baseUrl);
+    if (!config || config.executorKind === "pi" && config.workspaceMode !== "managed" || !config.deviceProfileId || !config.generation)
+        throw new Error("Original desktop tool connection is unavailable");
+    if (config.deviceToken && !config.signedOut) {
+        try {
+            const proof = await request(baseUrl, "/api/devices/session/context", { deviceToken: config.deviceToken, ...(input.signal ? { signal: input.signal } : {}) });
+            if (proof.bindingId !== config.bindingId || proof.generation !== config.generation)
+                throw new Error("Tool session identity mismatch");
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof DeviceRequestError) || !["DEVICE_SESSION_EXPIRED", "DEVICE_SESSION_ROTATED", "DEVICE_SESSION_SIGNED_OUT"].includes(error.code ?? ""))
+                throw error;
+        }
+    }
+    const pi = (await configsFor("pi")).find(c => c.companyId === config.companyId && c.principalId === config.principalId && c.workspaceMode !== "managed"
+        && c.deviceProfileId === config.deviceProfileId && c.userSubject === input.expectedSubject && base(c.baseUrl) === baseUrl && c.deviceToken && !c.signedOut && c.managedBy === "desktop");
+    if (!pi)
+        throw new Error("Sign in to the original Pi computer before reconnecting tools");
+    const result = await request(baseUrl, "/api/devices/session/restore", {
+        method: "POST", deviceToken: pi.deviceToken, ...(input.signal ? { signal: input.signal } : {}),
+        body: { bindingId: config.bindingId, sessionId: config.sessionId, generation: config.generation },
+    });
+    input.signal?.throwIfAborted();
+    if (result.bindingId !== config.bindingId || result.agentId !== config.agentId || result.companyId !== config.companyId
+        || result.deviceProfileId !== config.deviceProfileId || result.generation !== config.generation)
+        throw new Error("Restored tool identity mismatch");
+    await saveJson(configFile(config.executorKind, config.companyId, config), { ...config, signedOut: false,
+        sessionId: result.deviceSession.sessionId, deviceToken: result.deviceSession.token });
+}
+async function authenticatedDeviceProfile(baseUrl, principalId) {
+    const retained = new Set();
+    for (const kind of ["pi", "codex", "codebuddy"]) {
+        for (const config of await configsFor(kind)) {
+            if (base(config.baseUrl) !== baseUrl || config.principalId !== principalId || !config.deviceToken || config.signedOut)
+                continue;
+            const proof = await request(baseUrl, "/api/devices/session/context", { deviceToken: config.deviceToken }).catch(() => null);
+            if (proof?.principalId === principalId && proof.bindingId === config.bindingId && proof.companyId === config.companyId && proof.deviceProfileId)
+                retained.add(proof.deviceProfileId);
+        }
+    }
+    if (retained.size > 1)
+        throw new Error("Multiple retained device identities; explicitly select a binding to restore");
+    return readOrCreateDeviceProfile(baseUrl, principalId, [...retained][0]);
+}
+async function validateDeviceWorkspace(workspaceRoot) {
+    const root = await import("node:fs/promises").then(fs => fs.realpath(workspaceRoot));
+    const protectedRoots = [mirrorxDeviceHome(), mirrorxIdentityHome()];
+    const overlaps = (a, b) => { const relative = path.relative(a, b); return !relative || !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative); };
+    for (const protectedRoot of protectedRoots) {
+        const real = await import("node:fs/promises").then(fs => fs.realpath(protectedRoot)).catch(() => path.resolve(protectedRoot));
+        if (overlaps(root, real) || overlaps(real, root))
+            throw new Error("Workspace overlaps private connection identity or state");
+    }
+}
+export async function getMirrorxEnrollmentIntent(input) {
+    if (!/^[0-9a-f-]{36}$/i.test(input.enrollmentIntentId))
+        throw new Error("Invalid enrollment intent");
+    const intent = await request(base(input.baseUrl), `/api/devices/intents/${input.enrollmentIntentId}`, { token: input.iamAccessToken });
+    if (intent.subject !== input.userSubject || !(["codex", "codebuddy"].includes(intent.executorKind) || intent.executorKind === "pi" && (intent.recoveryBindingId || intent.explicitPiChoice || intent.enrollment.workspaceMode === "managed")))
+        throw new Error("Enrollment identity/tool mismatch");
+    return intent;
+}
+export async function connectMirrorxEnrollmentIntent(input) {
+    const baseUrl = base(input.baseUrl);
+    const intent = await getMirrorxEnrollmentIntent(input);
+    const profileId = await authenticatedDeviceProfile(baseUrl, intent.principalId);
+    const managed = intent.enrollment.workspaceMode === "managed";
+    input.signal?.throwIfAborted();
+    const workspaceRoot = managed ? await createManagedWorkspace({ baseUrl, principalId: intent.principalId,
+        deviceProfileId: profileId, companyId: intent.companyId, workspaceId: intent.enrollmentIntentId }) : input.workspaceRoot;
+    if (!workspaceRoot || !managed && (!input.confirmed || path.resolve(workspaceRoot) !== workspaceRoot || intent.enrollment.workspaceRoot !== workspaceRoot)) {
+        throw new Error("Confirm the exact authorized workspace on this computer");
+    }
+    await validateDeviceWorkspace(workspaceRoot);
+    const requestFile = path.join(mirrorxDeviceHome(), "enrollment-requests", `${intent.enrollmentIntentId}.json`);
+    const prior = await loadJson(requestFile);
+    const claimRequestId = prior?.claimRequestId ?? randomUUID();
+    if (!prior)
+        await saveJson(requestFile, { claimRequestId });
+    const unlock = await acquireDeviceResourceLock({ baseUrl, principalId: intent.principalId, deviceProfileId: profileId,
+        companyId: intent.companyId, executorKind: intent.executorKind, ...(managed ? { bindingId: intent.enrollmentIntentId } : {}) }, randomUUID());
+    try {
+        input.signal?.throwIfAborted();
+        const registration = await request(baseUrl, `/api/devices/intents/${intent.enrollmentIntentId}/claim`, { method: "POST", token: input.iamAccessToken,
+            body: { deviceProfileId: profileId, claimRequestId, workspaceRoot, confirmed: true }, ...(input.signal ? { signal: input.signal } : {}) });
+        if (registration.subject !== input.userSubject || registration.principalId !== intent.principalId
+            || registration.companyId !== intent.companyId)
+            throw new Error("Enrollment result identity mismatch");
+        const config = { baseUrl, userSubject: input.userSubject, managedBy: "desktop", principalId: intent.principalId,
+            deviceProfileId: profileId, generation: registration.generation, companyId: intent.companyId, executorKind: intent.executorKind, deviceId: registration.deviceId,
+            workspaceRoot, ...(managed ? { workspaceMode: "managed" } : {}), bindingId: registration.bindingId, agentId: registration.agentId,
+            sessionId: registration.deviceSession.sessionId, deviceToken: registration.deviceSession.token };
+        const discardCancelledSession = async () => {
+            // Preserve only the binding reference for authenticated recovery. Revoke
+            // this response's narrow session, never every session for the account.
+            await saveJson(configFile(intent.executorKind, config.companyId, config), { ...config, deviceToken: "", signedOut: true });
+            await request(baseUrl, "/api/devices/session/revoke", { method: "POST", deviceToken: config.deviceToken,
+                body: { reason: "sign_out" } });
+        };
+        if (input.signal?.aborted) {
+            await discardCancelledSession();
+            input.signal.throwIfAborted();
+        }
+        await saveJson(configFile(intent.executorKind, config.companyId, config), config);
+        // Cancellation can also happen while the atomic file write is in progress.
+        if (input.signal?.aborted) {
+            await discardCancelledSession();
+            input.signal.throwIfAborted();
+        }
+        const { deviceToken: _token, ...summary } = config;
+        return summary;
+    }
+    finally {
+        await unlock();
+    }
+}
+export async function runMirrorxDevices(input) {
+    const configs = (await configsFor(input.executorKind)).filter((config) => (!input.expectedSubject || config.userSubject === input.expectedSubject)
+        && (!input.expectedBaseUrl || base(config.baseUrl) === base(input.expectedBaseUrl))
+        && (!input.companyIds || input.companyIds.includes(config.companyId))
+        && (!input.bindingIds || input.bindingIds.includes(config.bindingId))
+        && (!input.computerCarrierOnly || config.executorKind === "pi" && config.workspaceMode !== "managed"));
+    if (configs.length === 0)
+        throw new Error("No MirrorX companies are connected");
+    await Promise.all(configs.map((config) => runMirrorxDevice({ ...input, companyId: config.companyId, bindingId: config.bindingId,
+        onConnectionState: state => input.onConnectionState?.(config.companyId, state) })));
+}
+/** Revoke the narrow device sessions when the user signs out of Pi. */
+export async function disconnectMirrorxDevices(kind, userSubject) {
+    const configs = (await configsFor(kind)).filter((config) => config.userSubject === userSubject && (config.managedBy === "desktop" || kind === "pi" && !config.managedBy));
+    await Promise.all(configs.map(async (config) => {
+        // Keep a non-secret binding reference for authenticated parent-IAM
+        // restoration. A logout is neither identity deletion nor a new employee.
+        const retained = { ...config, deviceToken: "", signedOut: true };
+        await saveJson(configFile(kind, config.companyId, config), retained);
+        const legacyFile = path.join(mirrorxDeviceHome(), `${kind}.json`);
+        const legacy = await loadJson(legacyFile);
+        if (legacy?.bindingId === config.bindingId)
+            await saveJson(legacyFile, { ...legacy, deviceToken: "", signedOut: true });
+        // Persist logout locally even if the server commits but its reply is lost.
+        const response = await fetch(new URL("/api/devices/session/revoke", config.baseUrl), {
+            method: "POST", headers: { "x-mirrorx-device-token": config.deviceToken, "content-type": "application/json" },
+            body: JSON.stringify({ reason: "sign_out" }),
+            signal: AbortSignal.timeout(5_000), redirect: "error",
+        });
+        if (!response.ok && response.status !== 401)
+            throw new Error(`MirrorX device sign-out failed: HTTP ${response.status}`);
+    }));
+}
+/** Local operator recovery only: this neither acknowledges nor relaunches the command. */
+export async function reclaimMirrorxDeviceConfiguration(input) {
+    if (!input.confirmedStopped)
+        throw new Error("Confirm all command tools have stopped before reclaiming their configuration");
+    if (![input.companyId, input.commandId].every(value => /^[a-zA-Z0-9_-]+$/.test(value)))
+        throw new Error("Invalid company or command ID");
+    const config = input.bindingId ? (await configsFor(input.executorKind)).find(item => item.companyId === input.companyId && item.bindingId === input.bindingId) : undefined;
+    if (input.bindingId && !config)
+        throw new Error("Requested connection profile was not found");
+    const resource = config?.principalId && config.deviceProfileId
+        ? { ...config, bindingId: config.workspaceMode === "managed" ? config.bindingId : undefined, principalId: config.principalId, deviceProfileId: config.deviceProfileId } : undefined;
+    const release = resource ? await acquireDeviceResourceLock(resource, randomUUID()) : await acquireBridgeLock(input.executorKind, input.companyId, randomUUID());
+    try {
+        const file = path.join(mirrorxDeviceHome(), `${input.executorKind}-${input.companyId}${resource ? `-${deviceResourceKey(resource)}` : ""}-journal.json`);
+        const journal = await loadJson(file);
+        const record = journal?.[input.commandId];
+        if (!record?.configurationDirectory)
+            throw new Error("No retained configuration is recorded for this command");
+        await reclaimConfiguration(record, true, () => reclaimCodebuddyLocks(record, mirrorxDeviceHome()));
+        delete record.configurationDirectory;
+        delete record.configurationToken;
+        await saveJson(file, journal);
+    }
+    finally {
+        await release();
+    }
+}
+/** Operator reset discards native context only; the original command still needs reconciliation. */
+export async function resetMirrorxCodebuddySession(input) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(input.companyId))
+        throw new Error("Invalid company ID");
+    if (!input.confirmedStopped)
+        throw new Error("Confirm all original command tools have stopped before resetting a native session");
+    const release = await acquireBridgeLock("codebuddy", input.companyId, randomUUID());
+    try {
+        await discardCodebuddySession({ ...input, stateRoot: mirrorxDeviceHome() });
+    }
+    finally {
+        await release();
+    }
+}
+export async function runMirrorxDevice(input) {
+    const connectionAbort = new AbortController();
+    const signal = input.signal ? AbortSignal.any([input.signal, connectionAbort.signal]) : connectionAbort.signal;
+    const matches = (await configsFor(input.executorKind)).filter(config => (!input.companyId || config.companyId === input.companyId)
+        && (!input.bindingId || config.bindingId === input.bindingId)
+        && (!input.expectedSubject || config.userSubject === input.expectedSubject)
+        && (!input.expectedBaseUrl || base(config.baseUrl) === base(input.expectedBaseUrl)));
+    if (matches.length > 1)
+        throw new Error("Choose an unambiguous MirrorX connection profile");
+    const loadedConfig = matches[0] ?? null;
+    if (!loadedConfig)
+        throw new Error("Pair this device with MirrorX first");
+    if (input.companyId && loadedConfig.companyId !== input.companyId)
+        throw new Error("MirrorX company is not paired");
+    const config = loadedConfig;
+    if (!config.deviceToken || config.signedOut)
+        throw new Error("Sign in or explicitly reconnect this MirrorX tool first");
+    if (input.expectedSubject && config.userSubject !== input.expectedSubject) {
+        throw new Error("MirrorX device pairing belongs to another signed-in user");
+    }
+    if (input.expectedBaseUrl && base(config.baseUrl) !== base(input.expectedBaseUrl)) {
+        throw new Error("MirrorX device pairing belongs to another service");
+    }
+    const resourceSuffix = config.principalId && config.deviceProfileId
+        ? `-${deviceResourceKey({ ...config, bindingId: config.workspaceMode === "managed" ? config.bindingId : undefined, principalId: config.principalId, deviceProfileId: config.deviceProfileId })}` : "";
+    const journalPath = path.join(mirrorxDeviceHome(), `${input.executorKind}-${config.companyId}${resourceSuffix}-journal.json`);
+    const outputRoot = path.join(mirrorxDeviceHome(), "output-outbox", config.companyId);
+    let loadedJournal = await loadJson(journalPath);
+    if (!loadedJournal) {
+        // Legacy journals have no owner metadata. Only the matching saved config
+        // may prove their binding, account, server and generation before adoption.
+        for (const stem of [`${input.executorKind}-${config.companyId}`, input.executorKind]) {
+            const legacy = await loadJson(path.join(mirrorxDeviceHome(), `${stem}.json`));
+            const sameBinding = legacy && legacy.companyId === config.companyId && base(legacy.baseUrl) === base(config.baseUrl)
+                && legacy.bindingId === config.bindingId && legacy.userSubject === config.userSubject
+                && (legacy.generation ?? 1) === (config.generation ?? 1)
+                && (!legacy.principalId || legacy.principalId === config.principalId);
+            if (!sameBinding)
+                continue;
+            loadedJournal = await loadJson(path.join(mirrorxDeviceHome(), `${stem}-journal.json`));
+            if (loadedJournal) {
+                await saveJson(journalPath, loadedJournal);
+                break;
+            }
+        }
+    }
+    const journal = loadedJournal ?? {};
+    const active = new Map();
+    const stopTasks = new WeakMap();
+    function requestStop(child) {
+        if (stopTasks.has(child))
+            return;
+        const stop = stopProcessTree(child, input.executorKind === "codex");
+        stopTasks.set(child, stop);
+        void stop.catch(() => undefined); // execute() observes the same failure before reporting completion.
+    }
+    const inFlight = new Set();
+    const executions = new Set();
+    const reportedReconciliation = new Set();
+    const reportedOutputPending = new Set();
+    const reportedConfigurationPending = new Set();
+    const recentlyCompleted = new Set();
+    const receiptRetryAt = new Map();
+    async function persist() { await saveJson(journalPath, journal); }
+    async function reclaimRetainedConfigurations() {
+        let changed = false;
+        for (const [id, record] of Object.entries(journal)) {
+            if (!record.configurationDirectory || inFlight.has(id))
+                continue;
+            try {
+                if (await reclaimConfiguration(record, false, () => reclaimCodebuddyLocks(record, mirrorxDeviceHome()))) {
+                    delete record.configurationDirectory;
+                    delete record.configurationToken;
+                    changed = true;
+                }
+            }
+            catch {
+                if (!reportedConfigurationPending.has(id)) {
+                    reportedConfigurationPending.add(id);
+                    input.onState?.(`Command ${id} private configuration cleanup requires operator attention`);
+                }
+            }
+        }
+        if (changed)
+            await persist();
+    }
+    const api = (route, options = {}) => request(config.baseUrl, `${pluginPath}${route}`, {
+        ...(options.method ? { method: options.method } : {}),
+        ...(options.body === undefined ? {} : { body: options.body }),
+        ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+        deviceToken: config.deviceToken,
+        ...(signal && !options.afterStop ? { signal: signal } : {}),
+    });
+    async function uploadOutput(command, segment) {
+        const bytes = Buffer.from(segment.chunk, "utf8");
+        const sha256 = createHash("sha256").update(bytes).digest("hex");
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            try {
+                const prepared = await api(`/commands/${command.id}/output/prepare`, {
+                    method: "POST", body: { companyId: config.companyId, claimId: command.claimId,
+                        seq: segment.seq, stream: segment.stream, byteSize: bytes.length, sha256 },
+                    timeoutMs: 15_000, afterStop: true,
+                });
+                if (!prepared.accepted)
+                    throw new Error("MirrorX did not prepare the output object");
+                if (!prepared.committed && !prepared.discard) {
+                    if (!prepared.url)
+                        throw new Error("MirrorX did not provide an output upload address");
+                    const response = await fetch(prepared.url, {
+                        method: "PUT", headers: prepared.headers ?? {}, body: bytes,
+                        signal: AbortSignal.timeout(15_000), redirect: "error",
+                    });
+                    if (!response.ok)
+                        throw new Error(`MirrorX output object upload failed: HTTP ${response.status}`);
+                    await api(`/commands/${command.id}/output/commit`, {
+                        method: "POST", body: { companyId: config.companyId, claimId: command.claimId, seq: segment.seq },
+                        timeoutMs: 15_000, afterStop: true,
+                    });
+                }
+                await unlink(outputSegmentFile(path.join(outputRoot, command.id), segment.seq)).catch((error) => {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                });
+                return;
+            }
+            catch (error) {
+                if (error instanceof DeviceRequestError
+                    && [400, 401, 403, 404, 409, 410, 422].includes(error.status))
+                    throw error;
+                if (attempt === 2)
+                    throw error;
+                if (attempt === 0)
+                    input.onState?.(`MirrorX output transfer is retrying for command ${command.id}`);
+                // This path also drains output after a requested stop. Keep the retry
+                // bounded, then leave the durable outbox for a later connection.
+                await delay(1_000 * 2 ** attempt);
+            }
+        }
+        throw new Error("MirrorX output upload was not acknowledged");
+    }
+    async function replayOutput(command) {
+        const directory = path.join(outputRoot, command.id);
+        const names = await readdir(directory).catch((error) => {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        });
+        for (const name of names.filter((value) => /^\d{10}\.json$/.test(value)).sort()) {
+            const segment = await loadJson(path.join(directory, name));
+            if (!segment)
+                continue;
+            await uploadOutput(command, segment);
+        }
+    }
+    async function complete(command, result, outputLost = false) {
+        receiptRetryAt.set(command.id, Date.now() + 10_000);
+        if (!outputLost)
+            await replayOutput(command);
+        await api(`/commands/${command.id}/complete`, {
+            method: "POST", body: { companyId: config.companyId, claimId: command.claimId, result,
+                ...(outputLost ? { outputLost: true } : {}) },
+            timeoutMs: 10_000, afterStop: true,
+        });
+        recentlyCompleted.add(command.id);
+        receiptRetryAt.delete(command.id);
+        // A successful acknowledgement is durable on the server. Keep finished
+        // results only while an acknowledgement is missing, so normal operation
+        // does not rewrite an ever-growing journal on every state transition.
+        delete journal[command.id];
+        await persist();
+        const outputDirectory = path.join(outputRoot, command.id);
+        if (outputLost) {
+            await rm(outputDirectory, { recursive: true, force: true });
+            return;
+        }
+        await readdir(outputDirectory).then(async (names) => {
+            if (names.length === 0)
+                await rmdir(outputDirectory);
+        }).catch(() => undefined);
+    }
+    function reportReconciliation(command, error) {
+        if (reportedReconciliation.has(command.id))
+            return;
+        reportedReconciliation.add(command.id);
+        const reason = error instanceof Error ? `: ${error.message}` : "";
+        input.onState?.(`Command ${command.id} needs manual reconciliation${reason}`);
+    }
+    async function execute(command) {
+        const prior = journal[command.id];
+        if (prior?.state === "finished" && prior.result) {
+            await complete(command, prior.result, prior.outputLost === true);
+            return;
+        }
+        const retryableClaim = prior?.state === "claimed" && prior.preSpawnSafe === true;
+        if (retryableClaim && prior.configurationDirectory) {
+            // Preparation may have crashed with workspace/session locks held. Keep
+            // its recovery authority until confirmed-stop reclamation, never overwrite it.
+            reportReconciliation(command, new Error("Retained preparation requires reclaim-config after confirmed stop"));
+            return;
+        }
+        if (prior && !retryableClaim && !active.has(command.id)) {
+            // A previous process may have reached external systems. Never relaunch it
+            // just because this bridge lost its in-memory child handle. Older claimed
+            // records lack the write-ahead guarantee and also need reconciliation.
+            reportReconciliation(command);
+            return;
+        }
+        if (active.has(command.id)) {
+            if (command.stopRequested)
+                requestStop(active.get(command.id));
+            return;
+        }
+        if (command.state === "running" && !retryableClaim) {
+            // A previous bridge may still own this process. A new instance may
+            // receive its command after takeover, but must never launch it again.
+            reportReconciliation(command);
+            return;
+        }
+        if (command.state === "reconcile_required" && !retryableClaim) {
+            reportReconciliation(command);
+            return;
+        }
+        // "claimed" is written before contacting the server, and "running" is
+        // durably written before spawn below. Only a claimed record proves that
+        // this client has not launched the process, including after a lost start
+        // response or a claim expiry.
+        journal[command.id] = { claimId: command.claimId, state: "claimed", preSpawnSafe: true };
+        await persist();
+        const start = await api(`/commands/${command.id}/start`, {
+            method: "POST", body: { companyId: config.companyId, claimId: command.claimId,
+                instanceId, preSpawnSafe: true },
+        });
+        if (!start.accepted)
+            throw new Error("MirrorX did not accept command start");
+        signal.throwIfAborted();
+        if (start.stopRequested) {
+            const result = { exitCode: null, signal: "SIGTERM", timedOut: false, stdout: "", stderr: "" };
+            journal[command.id] = { claimId: command.claimId, state: "finished", result };
+            await persist();
+            await complete(command, result);
+            return;
+        }
+        const payload = command.payload;
+        let prepared;
+        try {
+            if (config.workspaceMode === "managed") {
+                const execution = payload.managedExecution;
+                if (!execution || execution.companyId !== config.companyId || execution.bindingId !== config.bindingId || execution.agentId !== config.agentId)
+                    throw new Error("Managed command identity mismatch");
+                await validateManagedCwd(config.workspaceRoot, execution.cwd);
+                if (!payload.cwd || (path.relative(execution.cwd, payload.cwd).split(path.sep)[0] === "..") || path.isAbsolute(path.relative(execution.cwd, payload.cwd)))
+                    throw new Error("Managed command escaped its task");
+            }
+            prepared = input.executorKind === "codebuddy" && isCodebuddyCommand(payload.command)
+                ? await prepareCodebuddyCommand({ args: payload.args, env: payload.env, cwd: payload.cwd ?? config.workspaceRoot,
+                    authority: { baseUrl: config.baseUrl, companyId: config.companyId, agentId: config.agentId, bindingId: config.bindingId, ...(config.deviceProfileId ? { deviceProfileId: config.deviceProfileId } : {}), ...(config.generation ? { generation: config.generation } : {}) }, stateRoot: mirrorxDeviceHome(),
+                    onConfiguration: async (reference) => {
+                        journal[command.id] = { claimId: command.claimId, state: "claimed", preSpawnSafe: true, ...reference };
+                        await persist();
+                    } })
+                : await preparePiDeviceCommand(payload.command, payload.args, payload.env, input.executorKind === "pi" ? input.piRuntime ?? {
+                    configDir: process.env.PI_CODING_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent"),
+                } : undefined);
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            const reference = journal[command.id];
+            if (reference?.configurationDirectory && await stat(reference.configurationDirectory).catch((failure) => {
+                if (failure.code === "ENOENT")
+                    return null;
+                throw failure;
+            })) {
+                reportReconciliation(command, new Error("Retained preparation requires reclaim-config after confirmed stop"));
+                return;
+            }
+            const result = { exitCode: 1, signal: null, timedOut: false, stdout: input.executorKind === "codebuddy" && isCodebuddyCommand(payload.command)
+                    ? JSON.stringify({ type: "mirrorx_codebuddy_bootstrap_error", version: 1, providerWorkStarted: false }) + "\n" : "",
+                stderr: error instanceof Error ? error.message : "Could not prepare Pi device runtime" };
+            journal[command.id] = { claimId: command.claimId, state: "finished", result };
+            await persist();
+            await complete(command, result);
+            return;
+        }
+        let executionOutcome = "not-started";
+        try {
+            signal.throwIfAborted();
+            const outputDirectory = path.join(outputRoot, command.id);
+            await mkdir(outputDirectory, { recursive: true, mode: 0o700 });
+            signal.throwIfAborted();
+            journal[command.id] = { claimId: command.claimId, state: "running",
+                ...(prepared.configDirectory ? { configurationDirectory: prepared.configDirectory,
+                    configurationToken: prepared.configurationToken } : {}) };
+            await persist();
+            const executable = input.executorKind === "pi" && isPiDeviceCommand(payload.command)
+                ? input.piRuntime?.executable : undefined;
+            // Preparation and the write-ahead journal both await I/O. Cancellation
+            // may have drained active while this command did not yet own a child.
+            // No await may separate this check, spawn and active.set below.
+            signal.throwIfAborted();
+            const launchCwd = prepared.cwd ?? payload.cwd ?? config.workspaceRoot;
+            let launch = { command: prepared.command ?? executable?.command ?? (payload.command === "node" ? process.execPath : payload.command),
+                args: [...(executable?.argsPrefix ?? []), ...prepared.args],
+                env: prepared.command ? prepared.env : { ...process.env, ...prepared.env, ...(executable ? { PI_AGENT_NODE: executable.command } : {}) } };
+            if (input.executorKind === "codex")
+                launch.command = await resolveCodexExecutable(launch.command, launchCwd, launch.env);
+            if (config.workspaceMode === "managed")
+                launch = await confineManagedCommand({ ...launch, cwd: launchCwd, workspaceRoot: config.workspaceRoot, ...(executable?.readableFiles ? { runtimeFiles: executable.readableFiles } : {}), ...(payload.managedExecution ? { taskRoot: payload.managedExecution.cwd } : {}), ...(prepared.configDirectory ? { configurationDirectory: prepared.configDirectory,
+                        privateConfigurationCwd: input.executorKind === "codebuddy" && isCodebuddyCommand(payload.command) } : {}) });
+            signal.throwIfAborted();
+            const child = spawn(launch.command, launch.args, {
+                cwd: launchCwd,
+                env: launch.env,
+                shell: false,
+                detached: process.platform !== "win32",
+                windowsHide: true,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            if (child.pid)
+                executionOutcome = "running";
+            const configuration = prepared.configDirectory && prepared.configurationToken
+                ? observeConfiguration({ configurationDirectory: prepared.configDirectory, configurationToken: prepared.configurationToken }, child, () => input.onState?.(`Command ${command.id} private configuration cleanup requires operator attention`)) : undefined;
+            active.set(command.id, child);
+            let stdout = { head: "", tail: "", total: 0 };
+            let stderr = { head: "", tail: "", total: 0 };
+            let timedOut = false;
+            let outputSeq = 0;
+            let pendingChars = 0;
+            let outputError = null;
+            let stagingError = null;
+            let outputUploads = Promise.resolve();
+            const stagingWrites = new Set();
+            const buffers = { stdout: "", stderr: "" };
+            let flushTimer = null;
+            const decoders = { stdout: new StringDecoder("utf8"), stderr: new StringDecoder("utf8") };
+            function flushOutput(stream) {
+                while (buffers[stream]) {
+                    const chunk = takeOutputChunk(buffers[stream], OUTPUT_SEGMENT_CHARS);
+                    buffers[stream] = buffers[stream].slice(chunk.length);
+                    const segment = { seq: ++outputSeq, stream, chunk };
+                    pendingChars += chunk.length;
+                    if (!outputError && pendingChars >= OUTPUT_PENDING_CHARS) {
+                        child.stdout?.pause();
+                        child.stderr?.pause();
+                    }
+                    const staged = saveJson(outputSegmentFile(outputDirectory, segment.seq), segment);
+                    stagingWrites.add(staged);
+                    void staged.then(() => stagingWrites.delete(staged), (error) => {
+                        stagingWrites.delete(staged);
+                        // Once local spooling fails, neither the live upload nor a later
+                        // reconnect can recover the stream. Stop instead of hanging forever.
+                        stagingError = error;
+                        outputError = error;
+                        requestStop(child);
+                    });
+                    outputUploads = outputUploads.then(async () => {
+                        await staged;
+                        if (outputError)
+                            return;
+                        await uploadOutput(command, segment);
+                        pendingChars -= chunk.length;
+                        if (pendingChars < OUTPUT_PENDING_CHARS / 2 && !signal?.aborted) {
+                            child.stdout?.resume();
+                            child.stderr?.resume();
+                        }
+                    }).catch((error) => {
+                        outputError = error;
+                        // A transfer failure must not leave a noisy process blocked on a
+                        // paused pipe. Keep staging later segments for reconnect replay.
+                        pendingChars = 0;
+                        child.stdout?.resume();
+                        child.stderr?.resume();
+                    });
+                }
+            }
+            function appendOutput(stream, text, final = false) {
+                if (stream === "stdout")
+                    prepared.observeStdout?.(text);
+                if (prepared.redact)
+                    text = prepared.redact(stream, text, final);
+                if (!text)
+                    return;
+                if (stream === "stdout")
+                    stdout = retainOutput(stdout.head, stdout.tail, stdout.total, text);
+                else
+                    stderr = retainOutput(stderr.head, stderr.tail, stderr.total, text);
+                buffers[stream] += text;
+                if (buffers[stream].length >= OUTPUT_SEGMENT_CHARS)
+                    flushOutput(stream);
+                if (!flushTimer) {
+                    flushTimer = setTimeout(() => {
+                        flushTimer = null;
+                        flushOutput("stdout");
+                        flushOutput("stderr");
+                    }, 500);
+                }
+            }
+            child.stdout?.on("data", (part) => appendOutput("stdout", decoders.stdout.write(part)));
+            child.stderr?.on("data", (part) => appendOutput("stderr", decoders.stderr.write(part)));
+            child.stdin?.end(payload.stdin ?? undefined);
+            const timeout = payload.timeoutMs > 0
+                ? setTimeout(() => {
+                    if (child.exitCode !== null || child.signalCode !== null)
+                        return;
+                    timedOut = true;
+                    requestStop(child);
+                }, payload.timeoutMs)
+                : null;
+            let rootExitedAt = 0, stdioClosed = false;
+            child.once("close", () => { stdioClosed = true; });
+            const result = await new Promise((resolve) => {
+                child.once("error", (error) => {
+                    rootExitedAt = Date.now();
+                    resolve({ exitCode: null, signal: null, timedOut: false,
+                        stdout: retainedResult(stdout),
+                        stderr: retainedResult(retainOutput(stderr.head, stderr.tail, stderr.total, error.message)),
+                    });
+                });
+                child.once("exit", (exitCode, signal) => {
+                    rootExitedAt = Date.now();
+                    resolve({ exitCode, signal, timedOut, stdout: retainedResult(stdout), stderr: retainedResult(stderr) });
+                });
+            });
+            try {
+                const completion = await confirmCommandCompletion({ child,
+                    stopTask: () => stopTasks.get(child), observeDescendants: !!prepared.configDirectory,
+                    rootExitedAt, stdioClosed: () => stdioClosed, signal: signal,
+                });
+                executionOutcome = completion.state;
+                if (completion.state === "reconcile") {
+                    child.stdin?.destroy();
+                    if (configuration)
+                        configuration.retain();
+                    else {
+                        child.stdout?.destroy();
+                        child.stderr?.destroy();
+                    }
+                    reportReconciliation(command, completion.error);
+                    return; // Journal remains running; the reconciliation notice owns this outcome.
+                }
+            }
+            finally {
+                if (timeout)
+                    clearTimeout(timeout);
+                if (flushTimer)
+                    clearTimeout(flushTimer);
+                // Execution ownership ends here. inFlight still covers output/ACK
+                // retries; a late stop must not signal a completed/reaped process.
+                active.delete(command.id);
+            }
+            if (config.workspaceMode === "managed" && payload.managedExecution && ["pi", "codex"].includes(config.executorKind)) {
+                await recordDeviceSession({ home: mirrorxDeviceHome(), authority: config, cwd: payload.managedExecution.cwd,
+                    runId: payload.managedExecution.runId, ...(payload.managedExecution.issueId ? { issueId: payload.managedExecution.issueId } : {}),
+                    args: payload.args, env: payload.env, stdout: result.stdout, executorKind: config.executorKind })
+                    .catch(() => input.onState?.("Native session history index could not be saved; original task execution and files are retained"));
+            }
+            // Persist shutdown evidence and reclaim credentials before replacing the
+            // running record or ACKing. A crash during removal is retried on startup.
+            // Some CLIs catch SIGTERM and exit 0 without a terminal protocol event.
+            // Once shutdown is verified, preserve the stop outcome rather than asking
+            // the provider to checkpoint a success that never happened.
+            if (stopTasks.has(child) && !result.signal && !result.timedOut) {
+                result.signal = input.executorKind === "codex" ? "SIGINT" : "SIGTERM";
+            }
+            if (configuration) {
+                try {
+                    if (await prepared.finalize?.(result.exitCode === 0 && !result.timedOut && !result.signal) === "failed") {
+                        result.exitCode = 1;
+                    }
+                }
+                catch (error) {
+                    executionOutcome = "reconcile";
+                    reportReconciliation(command, error);
+                    return; // Keep the running journal and private profile; do not replay or claim the checkpoint survived.
+                }
+                await configuration.completed();
+                await prepared.cleanup();
+            }
+            appendOutput("stdout", decoders.stdout.end(), true);
+            appendOutput("stderr", decoders.stderr.end(), true);
+            if (flushTimer)
+                clearTimeout(flushTimer);
+            flushOutput("stdout");
+            flushOutput("stderr");
+            // The adapter's generic file-read fallback emits base64 bytes on stdout.
+            // The plugin reconstructs that bounded read from object storage on return;
+            // the command result in PostgreSQL must not duplicate credential bytes.
+            const isTransferRead = payload.args.some((arg) => /\bdd if=.*\|\s*base64\b/.test(arg));
+            result.stdout = isTransferRead ? "" : retainedResult(stdout);
+            result.stderr = retainedResult(stderr);
+            await Promise.allSettled([...stagingWrites]);
+            if (stagingError) {
+                // Missing bytes cannot be replayed. Report a failed command instead of
+                // pretending the partial output is a successful execution.
+                if (result.exitCode === 0)
+                    result.exitCode = 1;
+                result.stderr = `${result.stderr}\nMirrorX could not stage command output on this device`.trim();
+            }
+            const finalResult = boundedResult(result, config.companyId, command.claimId);
+            journal[command.id] = { claimId: command.claimId, state: "finished", result: finalResult,
+                ...(stagingError ? { outputLost: true } : {}) };
+            await persist();
+            await outputUploads;
+            if (stagingError) {
+                await complete(command, finalResult, true);
+                return;
+            }
+            if (outputError)
+                throw outputError;
+            await complete(command, finalResult);
+        }
+        finally {
+            // An unconfirmed child may still read its private configuration on either
+            // platform. The journal reaper consumes verified shutdown evidence; an
+            // ambiguous crash or failed Windows tree stop needs operator confirmation.
+            const retainConfiguration = ["running", "reconcile"].includes(executionOutcome);
+            if (!retainConfiguration) {
+                if (executionOutcome === "not-started")
+                    await prepared.rollbackUnstarted?.();
+                await prepared.cleanup();
+                if (executionOutcome === "not-started") {
+                    // This bridge knows spawn was never reached. Restore the safe claim
+                    // only after cleanup; a real/unknown launched process stays running.
+                    journal[command.id] = { claimId: command.claimId, state: "claimed", preSpawnSafe: true };
+                    await persist();
+                }
+            }
+            else if (prepared.configDirectory)
+                input.onState?.(`Command ${command.id} retained private ${input.executorKind === "codebuddy" ? "WorkBuddy" : "Pi"} configuration because descendant shutdown could not be verified`);
+        }
+    }
+    const instanceId = randomUUID();
+    const releaseBridgeLock = config.principalId && config.deviceProfileId
+        ? await acquireDeviceResourceLock({ ...config, bindingId: config.workspaceMode === "managed" ? config.bindingId : undefined, principalId: config.principalId, deviceProfileId: config.deviceProfileId }, instanceId)
+        : await acquireBridgeLock(input.executorKind, config.companyId, instanceId);
+    let readiness = { state: "unknown", checkedAt: new Date().toISOString() };
+    let readinessTask;
+    let nextReadinessAt = 0;
+    let managedEnrollmentTask;
+    function refreshReadiness() {
+        if (readinessTask || Date.now() < nextReadinessAt || signal.aborted)
+            return;
+        nextReadinessAt = Date.now() + 30_000;
+        readinessTask = inspectDeviceReadiness({ executorKind: config.executorKind, workspaceRoot: config.workspaceRoot, piAvailable: input.piRuntime?.available,
+            ...(input.piRuntime?.executable?.command ? { piExecutable: input.piRuntime.executable.command } : {}) })
+            .then(result => { readiness = config.workspaceMode === "managed" && process.platform !== "darwin" ? { state: "workspace_unavailable", checkedAt: result.checkedAt } : result; }).catch(() => { readiness = { state: "unknown", checkedAt: new Date().toISOString() }; })
+            .finally(() => { readinessTask = undefined; });
+    }
+    function retryFinishedReceipt(commandId) {
+        // Drain settles attempts already in flight, but must never replenish them.
+        // This gate covers both background recovery and finished commands from poll.
+        if (input.drainSignal?.aborted)
+            return;
+        // A server may commit completion before its HTTP response is lost. Such a
+        // terminal command is no longer returned by /poll. Replay only the durable
+        // result, never the process, and retain the journal until it is acknowledged.
+        // Oldest eligible attempt first: a permanently rejected record must not
+        // starve later receipts when an idle long poll exceeds the retry interval.
+        const pending = Object.entries(journal).filter(([id, record]) => (!commandId || id === commandId)
+            && record.state === "finished" && record.result && !inFlight.has(id)
+            && Date.now() >= (receiptRetryAt.get(id) ?? 0))
+            .sort(([left], [right]) => (receiptRetryAt.get(left) ?? 0) - (receiptRetryAt.get(right) ?? 0))[0];
+        if (!pending)
+            return;
+        const [id, record] = pending;
+        inFlight.add(id);
+        const receipt = complete({ id, claimId: record.claimId }, record.result, record.outputLost === true)
+            .catch(() => {
+            if (!reportedOutputPending.has(id)) {
+                reportedOutputPending.add(id);
+                input.onState?.(`Command ${id} finished locally; its receipt will retry when reachable`);
+            }
+        })
+            .finally(() => { inFlight.delete(id); executions.delete(receipt); });
+        executions.add(receipt);
+    }
+    try {
+        await reclaimRetainedConfigurations();
+        while (!signal?.aborted) {
+            if (input.drainSignal?.aborted && executions.size === 0) {
+                if (Object.values(journal).some(record => record.state === "running" || record.state === "finished")) {
+                    throw new Error("Device drain requires reconciliation; original journal retained");
+                }
+                break;
+            }
+            retryFinishedReceipt();
+            try {
+                await reclaimRetainedConfigurations();
+                refreshReadiness(); // Never delay the independent lease/long-poll loop.
+                await api("/connect", {
+                    method: "POST", body: {
+                        companyId: config.companyId,
+                        instanceId,
+                        workspaceRoot: config.workspaceRoot,
+                        capabilities: { [input.executorKind]: true, ...(config.managedBy === "desktop" && config.executorKind === "pi" && config.workspaceMode !== "managed" && input.piRuntime && input.piRuntime.available !== false && process.platform === "darwin" ? { managedPiEmployees: true } : {}), ...(config.managedBy === "desktop" && process.platform === "darwin" ? { managedWorkspaces: "seatbelt" } : {}), ...(config.workspaceMode === "managed" ? { workspaceMode: "managed", filesystemBoundary: process.platform === "darwin" ? "seatbelt" : "unavailable" } : {}), readiness, protocol: clientManifest.mirrorxDeviceProtocol, channel: config.managedBy === "desktop" ? "desktop" : "npm", clientVersion: clientManifest.version, platform: `${process.platform}-${process.arch}` },
+                    },
+                });
+                input.onConnectionState?.("connected");
+                if (input.executorKind === "pi" && config.managedBy === "desktop" && input.onManagedIntent && !managedEnrollmentTask) {
+                    managedEnrollmentTask = (async () => {
+                        const pending = await request(config.baseUrl, "/api/devices/managed-intents", { deviceToken: config.deviceToken, signal }).catch(() => []);
+                        const connectedBindings = new Set((await Promise.all([configsFor("pi"), configsFor("codex"), configsFor("codebuddy")])).flat().filter(entry => entry.userSubject === config.userSubject && entry.baseUrl === config.baseUrl && entry.deviceToken).map(entry => entry.bindingId));
+                        for (const intent of pending) {
+                            if (intent.bindingId && connectedBindings.has(intent.bindingId))
+                                continue;
+                            signal.throwIfAborted();
+                            await input.onManagedIntent(intent.enrollmentIntentId).catch(() => input.onState?.("Managed employee connection failed; inspect MirrorX settings before retrying"));
+                        }
+                    })().catch(() => undefined).finally(() => { managedEnrollmentTask = undefined; });
+                }
+                const inFlightCommandIds = [...inFlight].slice(0, 32).join(",");
+                const polled = await api(`/poll?companyId=${encodeURIComponent(config.companyId)}&instanceId=${instanceId}`
+                    + (inFlightCommandIds ? `&inFlightCommandIds=${encodeURIComponent(inFlightCommandIds)}` : "")
+                    + (input.drainSignal?.aborted ? "&acceptingWork=false" : ""), { timeoutMs: 22_000 });
+                if (signal?.aborted)
+                    break;
+                if (!polled.command)
+                    recentlyCompleted.clear();
+                if (polled.command && !recentlyCompleted.has(polled.command.id)) {
+                    const command = polled.command;
+                    if (inFlight.has(command.id)) {
+                        if (command.stopRequested && active.has(command.id))
+                            requestStop(active.get(command.id));
+                    }
+                    else if (journal[command.id]?.state === "finished" && journal[command.id]?.result) {
+                        // Poll and background recovery share cooldown and the original claim.
+                        retryFinishedReceipt(command.id);
+                    }
+                    else {
+                        inFlight.add(command.id);
+                        const execution = execute(command)
+                            .catch((error) => {
+                            if (!signal?.aborted && journal[command.id]?.state === "finished") {
+                                if (!reportedOutputPending.has(command.id)) {
+                                    reportedOutputPending.add(command.id);
+                                    input.onState?.(`Command ${command.id} finished locally; output transfer will resume when reachable`);
+                                }
+                            }
+                            else if (!signal?.aborted) {
+                                input.onState?.(error instanceof Error ? error.message : String(error));
+                            }
+                        })
+                            .finally(() => { inFlight.delete(command.id); executions.delete(execution); });
+                        executions.add(execution);
+                    }
+                }
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    break;
+                if (error instanceof DeviceRequestError && [401, 403, 426].includes(error.status)) {
+                    input.onConnectionState?.("failed");
+                    connectionAbort.abort();
+                    throw error;
+                }
+                input.onConnectionState?.("retrying");
+                input.onState?.(error instanceof Error ? error.message : String(error));
+                await delay(3_000, undefined, { signal: signal }).catch(() => undefined);
+            }
+        }
+    }
+    finally {
+        connectionAbort.abort();
+        for (const child of active.values())
+            requestStop(child);
+        await Promise.allSettled([...executions, ...(managedEnrollmentTask ? [managedEnrollmentTask] : [])]);
+        // The provider accepts stop proof only from this exact live instance and
+        // only after every queue claim has settled. Unknown journals retain fences.
+        if (!Object.values(journal).some(record => record.state === "running" || record.state === "finished")) {
+            await api("/disconnect", { method: "POST", body: { companyId: config.companyId, instanceId }, afterStop: true, timeoutMs: 10_000 })
+                .catch(() => input.onState?.("Graceful disconnect is unverified; restore requires reconciliation"));
+        }
+        await releaseBridgeLock();
+    }
+}
+/** Resolve only exact references owned by this login and canonical service. */
+export async function findMirrorxDeviceSession(input) {
+    for (const kind of ["pi", "codex"]) {
+        for (const authority of await configsFor(kind)) {
+            if (authority.userSubject !== input.expectedSubject || base(authority.baseUrl) !== base(input.expectedBaseUrl) || authority.workspaceMode !== "managed")
+                continue;
+            const reference = await findDeviceSession({ home: mirrorxDeviceHome(), authority, sessionId: input.sessionId });
+            if (reference)
+                return reference;
+        }
+    }
+    return undefined;
+}
+/** Computer-only enrollment can claim only a web-authorized managed employee. */
+export async function connectMirrorxComputerIntent(input) {
+    if (!/^[0-9a-f-]{36}$/i.test(input.enrollmentIntentId))
+        throw new Error("Invalid enrollment intent");
+    const baseUrl = base(input.baseUrl);
+    const intent = await request(baseUrl, `/api/computers/intents/${input.enrollmentIntentId}`, { deviceToken: input.computerToken, signal: input.signal });
+    if (intent.enrollmentIntentId !== input.enrollmentIntentId || intent.companyId !== input.companyId || intent.principalId !== input.principalId
+        || intent.enrollment.workspaceMode !== "managed" || intent.enrollment.targetBindingId !== input.computerId
+        || !["codex", "codebuddy"].includes(intent.executorKind))
+        throw new Error("Enrollment identity/tool mismatch");
+    const existing = (await configsFor(intent.executorKind)).find(config => config.computerId === input.computerId && config.bindingId === intent.bindingId && base(config.baseUrl) === baseUrl && config.principalId === input.principalId);
+    if (existing)
+        return { bindingId: existing.bindingId, executorKind: existing.executorKind };
+    const unlock = await acquireDeviceResourceLock({ baseUrl, principalId: input.principalId, deviceProfileId: input.deviceProfileId,
+        companyId: input.companyId, executorKind: intent.executorKind, bindingId: input.enrollmentIntentId }, randomUUID());
+    try {
+        input.signal?.throwIfAborted();
+        const workspaceRoot = await createManagedWorkspace({ ...input, workspaceId: input.enrollmentIntentId });
+        await validateDeviceWorkspace(workspaceRoot);
+        const requestFile = path.join(mirrorxDeviceHome(), "enrollment-requests", `${input.enrollmentIntentId}.json`);
+        const prior = await loadJson(requestFile);
+        const claimRequestId = prior?.claimRequestId ?? randomUUID();
+        if (!prior)
+            await saveJson(requestFile, { claimRequestId });
+        const registration = await request(baseUrl, `/api/computers/intents/${input.enrollmentIntentId}/claim`, { method: "POST", deviceToken: input.computerToken, body: { claimRequestId, workspaceRoot }, signal: input.signal });
+        if (registration.companyId !== input.companyId || registration.principalId !== input.principalId || registration.deviceProfileId !== input.deviceProfileId)
+            throw new Error("Enrollment response identity mismatch");
+        const config = { baseUrl, managedBy: "standalone", computerId: input.computerId, principalId: input.principalId, deviceProfileId: input.deviceProfileId,
+            companyId: input.companyId, executorKind: intent.executorKind, generation: registration.generation, deviceId: registration.deviceId,
+            workspaceRoot, workspaceMode: "managed", bindingId: registration.bindingId, agentId: registration.agentId, sessionId: registration.deviceSession.sessionId, deviceToken: registration.deviceSession.token };
+        // Persist the committed result even during shutdown; the next supervisor resumes the same employee.
+        await saveJson(configFile(config.executorKind, config.companyId, config), config);
+        return { bindingId: config.bindingId, executorKind: config.executorKind };
+    }
+    finally {
+        await unlock();
+    }
+}
+export async function restoreMirrorxComputerEmployee(input) {
+    const configs = (await configsFor(input.executorKind)).filter(config => base(config.baseUrl) === base(input.baseUrl) && config.computerId === input.computerId && config.bindingId === input.bindingId);
+    if (configs.length !== 1)
+        throw new Error("Original employee configuration unavailable");
+    const config = configs[0];
+    const restored = await request(config.baseUrl, "/api/computers/session/restore", {
+        method: "POST", deviceToken: input.computerToken, signal: input.signal, body: { bindingId: config.bindingId, sessionId: config.sessionId, generation: config.generation ?? 1 }
+    });
+    if (restored.bindingId !== config.bindingId || restored.generation !== (config.generation ?? 1))
+        throw new Error("Restoration response identity mismatch");
+    await saveJson(configFile(config.executorKind, config.companyId, config), { ...config, sessionId: restored.deviceSession.sessionId, deviceToken: restored.deviceSession.token, signedOut: false });
+}
+//# sourceMappingURL=index.js.map