letagents 0.12.11 → 0.12.13

package/dist/mcp/server/runtime/supervisor-bridge.js

@@ -1,33 +1,340 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, readFile, realpath } from "node:fs/promises";
 import { createConnection } from "node:net";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parsePositivePgIntegerScopedId } from "../../../../shared/message-contracts.mjs";
+import { getCurrentSupervisedRoomAuthority } from "./supervised-room-authority.js";
 const NEGOTIATION_PROTOCOL_VERSION = 1;
 const SUPPORTED_SUPERVISOR_PROTOCOL_VERSIONS = new Set([1, 2]);
 const DEFAULT_REQUEST_TIMEOUT_MS = 5_000;
+const CONFIRMED_BINDING_VERIFY_TIMEOUT_MS = 250;
+const SUPERVISOR_CONTEXT_FILE = ".letagents-supervisor-context.json";
+const WORK_ATTEMPT_MARKER_FILE = ".letagents-work-attempt.json";
+const MAX_SUPERVISOR_CONTEXT_BYTES = 4 * 1024;
+const confirmedBindingsBySession = new Map();
+const confirmedRequestsBySession = new Map();
+const confirmedProtocolsBySession = new Map();
+const pendingCursorCheckpoints = new Map();
+const activeCursorCheckpointDrains = new Set();
+const cursorCheckpointRetryTimers = new Map();
+const CURSOR_CHECKPOINT_RETRY_DELAYS_MS = [250, 1_000, 3_000];
+export async function executeCurrentSupervisedTool(input, env = process.env, options = {}) {
+    const coordinates = await requireCurrentSupervisedCoordinates(env, options);
+    const timeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const negotiated = await negotiateSupervisor(coordinates.socketPath, timeoutMs);
+    if (negotiated.generation === null)
+        throw new Error("The supervised daemon generation is unavailable.");
+    const response = await supervisorRequest(coordinates.socketPath, {
+        version: negotiated.protocolVersion,
+        id: randomUUID(),
+        method: "supervisor.execute_bounded_tool",
+        params: {
+            entry_id: coordinates.entryId,
+            work_attempt_id: coordinates.workAttemptId,
+            execution_generation_id: coordinates.executionGenerationId,
+            ...(coordinates.providerTurnId ? { provider_turn_id: coordinates.providerTurnId } : {}),
+            daemon_generation: negotiated.generation,
+            mcp_request_id: input.mcpRequestId,
+            tool_name: input.toolName,
+            input: input.input,
+        },
+    }, null);
+    if (!response.ok) {
+        if (/Unsupported daemon method:\s*supervisor\.execute_bounded_tool/i.test(response.error ?? "")) {
+            return { state: "unsupported" };
+        }
+        throw new Error(response.error || "The daemon-owned supervised tool was rejected.");
+    }
+    const result = response.result && typeof response.result === "object"
+        ? response.result
+        : {};
+    const roomId = typeof result.room_id === "string" ? result.room_id.trim() : "";
+    if (!roomId || roomId.length > 1_024 || /[\u0000-\u001f\u007f]/.test(roomId)) {
+        throw new Error("The supervised daemon did not return valid exact room authority.");
+    }
+    return { state: "completed", roomId, result: result.result };
+}
+export async function prepareCurrentSupervisedEffect(input, env = process.env, options = {}) {
+    const coordinates = await requireCurrentSupervisedCoordinates(env, options);
+    const timeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const negotiated = await negotiateSupervisor(coordinates.socketPath, timeoutMs);
+    if (negotiated.generation === null)
+        throw new Error("The supervised daemon generation is unavailable.");
+    const response = await supervisorRequest(coordinates.socketPath, {
+        version: negotiated.protocolVersion,
+        id: randomUUID(),
+        method: "supervisor.prepare_bounded_effect",
+        params: {
+            entry_id: coordinates.entryId,
+            work_attempt_id: coordinates.workAttemptId,
+            execution_generation_id: coordinates.executionGenerationId,
+            ...(coordinates.providerTurnId ? { provider_turn_id: coordinates.providerTurnId } : {}),
+            daemon_generation: negotiated.generation,
+            mcp_request_id: input.mcpRequestId,
+            tool_name: input.toolName,
+            input: input.input,
+            mutation: input.mutation,
+        },
+    }, timeoutMs);
+    if (!response.ok)
+        throw new Error(response.error || "The supervised effect was rejected.");
+    const result = response.result && typeof response.result === "object" ? response.result : {};
+    const roomId = typeof result.room_id === "string" ? result.room_id.trim() : "";
+    if (!roomId || roomId.length > 1_024 || /[\u0000-\u001f\u007f]/.test(roomId)) {
+        throw new Error("The supervised daemon did not return valid exact room authority.");
+    }
+    if (result.state === "completed")
+        return { state: "completed", roomId, result: result.result };
+    const effectId = typeof result.effect_id === "string" ? result.effect_id : "";
+    if (!effectId)
+        throw new Error("The supervised effect journal did not return an effect id.");
+    if (result.state === "uncertain") {
+        const error = typeof result.error === "string" && result.error.trim()
+            ? result.error
+            : "The mutating tool outcome is uncertain.";
+        return { state: "uncertain", roomId, effectId, error };
+    }
+    if (result.state !== "prepared") {
+        throw new Error("The supervised effect journal returned an unsupported state.");
+    }
+    if (result.action === "execute") {
+        return { state: "prepared", roomId, effectId, action: "execute" };
+    }
+    if (result.action === "use_final_answer" && typeof result.source_message_id === "string" && result.source_message_id.trim()) {
+        return { state: "prepared", roomId, effectId, action: "use_final_answer", sourceMessageId: result.source_message_id };
+    }
+    if (result.action === "room_move_prepared" && typeof result.destination_room === "string" && result.destination_room.trim()) {
+        return { state: "prepared", roomId, effectId, action: "room_move_prepared", destinationRoom: result.destination_room };
+    }
+    throw new Error("The supervised effect journal returned an unsupported action.");
+}
+export async function completeCurrentSupervisedEffect(input, env = process.env, options = {}) {
+    const coordinates = await requireCurrentSupervisedCoordinates(env, options);
+    const timeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    let retryAttempt = 0;
+    while (true) {
+        let response;
+        try {
+            // Completion is idempotent by effect id. A daemon handoff can race the
+            // first socket request after the external callback already succeeded,
+            // so keep renegotiating within one bounded request budget instead of
+            // stranding an executing journal or tempting the caller to repeat the
+            // side effect. The successor's unlink-to-listen gap can span multiple
+            // failed socket attempts during process startup.
+            const negotiated = await negotiateSupervisor(coordinates.socketPath, remainingRequestTimeout(deadline));
+            if (negotiated.generation === null)
+                throw new Error("The supervised daemon generation is unavailable.");
+            response = await supervisorRequest(coordinates.socketPath, {
+                version: negotiated.protocolVersion,
+                id: randomUUID(),
+                method: "supervisor.complete_bounded_effect",
+                params: {
+                    entry_id: coordinates.entryId,
+                    work_attempt_id: coordinates.workAttemptId,
+                    execution_generation_id: coordinates.executionGenerationId,
+                    ...(coordinates.providerTurnId ? { provider_turn_id: coordinates.providerTurnId } : {}),
+                    daemon_generation: negotiated.generation,
+                    effect_id: input.effectId,
+                    result: input.result,
+                    error: input.error,
+                },
+            }, remainingRequestTimeout(deadline));
+        }
+        catch (error) {
+            const failure = error instanceof Error ? error : new Error(String(error));
+            if (!completionMayHaveRacedHandoff(failure)
+                || !await waitForCompletionHandoffRetry(deadline, retryAttempt++))
+                throw error;
+            continue;
+        }
+        if (response.ok)
+            return;
+        const rejection = new Error(response.error || "The supervised effect completion was rejected.");
+        if (!completionMayHaveRacedHandoff(rejection)
+            || !await waitForCompletionHandoffRetry(deadline, retryAttempt++))
+            throw rejection;
+    }
+}
+function completionMayHaveRacedHandoff(error) {
+    return isRetryableSupervisorBridgeError(error)
+        || /stale.*(?:daemon|supervisor).*generation|handoff/i.test(error.message);
+}
+async function waitForCompletionHandoffRetry(deadline, attempt) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        return false;
+    const delay = Math.min(25 * (2 ** Math.min(attempt, 4)), 250, remaining);
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    return Date.now() < deadline;
+}
+async function requireCurrentSupervisedCoordinates(env, options) {
+    if (env.LETAGENTS_EXECUTION_PROFILE?.trim() !== "supervised_room_turn") {
+        throw new Error("Supervised effects require the supervised_room_turn execution profile.");
+    }
+    const coordinates = await resolveSupervisorCoordinates(supervisedContextSession(env), env, options);
+    if (!coordinates)
+        throw new Error("The exact supervised daemon coordinates are unavailable.");
+    return coordinates;
+}
+/**
+ * Resolve and borrow for the MCP process itself. Unlike registration, this
+ * never reads local agent state: the daemon-owned launch context is the sole
+ * authority for the exact worker session identity.
+ */
+export async function borrowCurrentSupervisedWorkerCredential(env = process.env, options = {}) {
+    if (env.LETAGENTS_SUPERVISED_BOUNDED_TURNS?.trim() !== "1") {
+        return { state: "not_supervised" };
+    }
+    const seed = supervisedContextSession(env);
+    const coordinates = await resolveSupervisorCoordinates(seed, env, options);
+    const roomId = getCurrentSupervisedRoomAuthority();
+    if (!coordinates?.agentSessionId || !roomId) {
+        return { state: "stale", code: "SUPERVISED_CREDENTIAL_STALE" };
+    }
+    return borrowSupervisedWorkerCredential({
+        ...seed,
+        session_id: coordinates.agentSessionId,
+        room_id: roomId,
+    }, env, { ...options, resolvedCoordinates: coordinates });
+}
+/** A public, non-secret session-shaped marker for supervised MCP tools. */
+export async function resolveCurrentSupervisedWorkerSession(roomId, env = process.env, options = {}) {
+    const seed = supervisedContextSession(env);
+    const coordinates = await resolveSupervisorCoordinates(seed, env, options);
+    const boundRoomId = getCurrentSupervisedRoomAuthority();
+    if (!coordinates?.agentSessionId || !boundRoomId) {
+        throw new Error("Daemon-supervised bounded turn is missing its exact worker session context.");
+    }
+    if (roomId && roomId !== boundRoomId) {
+        throw new Error(`Daemon-supervised worker session is registered for ${boundRoomId}, not ${roomId}.`);
+    }
+    const displayName = coordinates.agentDisplayName || "Daemon-supervised worker";
+    return {
+        ...seed,
+        session_id: coordinates.agentSessionId,
+        room_id: boundRoomId,
+        agent_key: coordinates.agentSessionId,
+        actor_label: displayName,
+        display_name: displayName,
+    };
+}
+function supervisedContextSession(env = process.env) {
+    const now = new Date(0).toISOString();
+    // Codex is the only provider that can recover supervisor coordinates from
+    // the worktree context file. Other supervised providers pass their exact
+    // coordinates and provider identity through the daemon-created MCP
+    // environment, so the fallback must remain Codex for existing context-file
+    // sessions rather than inventing a provider that cannot own the file.
+    const provider = env.LETAGENTS_SUPERVISOR_PROVIDER?.trim() || "codex";
+    const label = provider === "open-model"
+        ? "Open Model"
+        : provider === "claude-code"
+            ? "Claude Code"
+            : provider === "codex"
+                ? "Codex"
+                : "Supervised agent";
+    return {
+        session_id: "", session_token: "", room_id: "", session_kind: "worker", runtime: provider,
+        actor_label: "Daemon-supervised worker", agent_key: "daemon-supervised-worker",
+        display_name: "Daemon-supervised worker", owner_label: "", ide_label: label,
+        created_at: now, updated_at: now, last_seen_at: now,
+    };
+}
+/**
+ * Borrow an in-memory, exact-generation worker bearer. This intentionally has
+ * no fallback to the owner/session token: a daemon restarted without Electron
+ * handoff must retain its durable inbox and wait.
+ */
+export async function borrowSupervisedWorkerCredential(session, env = process.env, options = {}) {
+    const coordinates = options.resolvedCoordinates ?? await resolveSupervisorCoordinates(session, env, options);
+    if (!coordinates)
+        return { state: "not_supervised" };
+    if (session.session_kind !== "worker")
+        return { state: "stale", code: "SUPERVISED_CREDENTIAL_STALE" };
+    const timeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const apiUrl = normalizedWorkerApiOrigin(env);
+    const negotiated = await negotiateSupervisor(coordinates.socketPath, timeoutMs);
+    if (negotiated.generation === null)
+        return { state: "stale", code: "SUPERVISED_CREDENTIAL_STALE" };
+    const response = await supervisorRequest(coordinates.socketPath, {
+        version: negotiated.protocolVersion,
+        id: randomUUID(),
+        method: "supervisor.borrow_worker_credential",
+        params: {
+            entry_id: coordinates.entryId, room_id: session.room_id, work_attempt_id: coordinates.workAttemptId,
+            execution_generation_id: coordinates.executionGenerationId, agent_session_id: session.session_id,
+            ...(coordinates.providerTurnId ? { provider_turn_id: coordinates.providerTurnId } : {}),
+            daemon_generation: negotiated.generation, api_url: apiUrl,
+        },
+    }, timeoutMs);
+    if (!response.ok || response.version !== negotiated.protocolVersion)
+        return { state: "stale", code: "SUPERVISED_CREDENTIAL_STALE" };
+    const result = response.result && typeof response.result === "object" ? response.result : {};
+    if (result.status === "deferred")
+        return { state: "deferred", code: "SUPERVISED_CREDENTIAL_UNAVAILABLE" };
+    if (result.status !== "available" || typeof result.credential !== "string" || !result.credential.trim()) {
+        return { state: "stale", code: "SUPERVISED_CREDENTIAL_STALE" };
+    }
+    return { state: "available", credential: result.credential };
+}
+function normalizedWorkerApiOrigin(env) {
+    const apiUrl = env.LETAGENTS_API_URL?.trim() || "https://letagents.chat";
+    let parsed;
+    try {
+        parsed = new URL(apiUrl);
+    }
+    catch {
+        throw new Error("Daemon-supervised worker requires a valid LETAGENTS_API_URL.");
+    }
+    const loopbackHosts = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+    if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && loopbackHosts.has(parsed.hostname.toLowerCase()))) {
+        throw new Error("Daemon-supervised worker requires HTTPS unless LETAGENTS_API_URL uses an exact loopback host.");
+    }
+    return parsed.origin;
+}
 /** Bind the exact worker credential minted by registration to its daemon lane. */
 export async function bindSupervisedWorkerSession(session, env = process.env, options = {}) {
-    const entryId = env.LETAGENTS_SUPERVISOR_ENTRY_ID?.trim();
-    const socketPath = env.LETAGENTS_SUPERVISOR_DAEMON_SOCKET?.trim();
-    const workAttemptId = env.LETAGENTS_SUPERVISOR_WORK_ATTEMPT_ID?.trim();
-    const executionGenerationId = env.LETAGENTS_SUPERVISOR_EXECUTION_GENERATION_ID?.trim();
-    if (!entryId && !socketPath && !workAttemptId && !executionGenerationId)
-        return false;
-    if (!entryId || !socketPath || !workAttemptId || !executionGenerationId)
-        throw new Error("Supervised worker bridge environment is incomplete.");
+    return (await bindSupervisedWorkerSessionWithContext(session, env, options)).bound;
+}
+/**
+ * Bind and return the validated file-backed route, when one was used.
+ * Registration persists this route so later wait/checkpoint calls do not fall
+ * back to an unrelated long-lived MCP process cwd.
+ */
+export async function bindSupervisedWorkerSessionWithContext(session, env = process.env, options = {}) {
+    const coordinates = options.resolvedCoordinates ?? await resolveSupervisorCoordinates(session, env, options);
+    if (!coordinates)
+        return { bound: false, supervisorContextCwd: null };
+    const { entryId, socketPath, workAttemptId, executionGenerationId } = coordinates;
     if (session.session_kind !== "worker")
         throw new Error("A supervised provider must register a worker session.");
     const timeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
     if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1)
         throw new Error("Supervisor bridge timeout must be a positive integer.");
-    const negotiation = await supervisorRequest(socketPath, {
-        version: NEGOTIATION_PROTOCOL_VERSION,
-        id: randomUUID(),
-        method: "daemon.negotiate",
-    }, timeoutMs);
-    if (!negotiation.ok)
-        throw new Error(negotiation.error || "Supervisor protocol negotiation failed.");
-    const protocolVersion = negotiationProtocolVersion(negotiation.result);
-    if (negotiation.version !== protocolVersion)
-        throw new Error("Supervisor negotiation response version does not match its negotiated protocol.");
+    const requestKey = bindingRequestKey(session, coordinates, env);
+    if (options.allowConfirmedFastPath && confirmedRequestsBySession.get(session.session_id) === requestKey) {
+        const confirmedProtocol = confirmedProtocolsBySession.get(session.session_id);
+        if (!confirmedProtocol)
+            throw new Error("The supervised worker binding protocol is not confirmed.");
+        try {
+            await verifyConfirmedBinding(session, coordinates, env, confirmedProtocol, Math.min(timeoutMs, CONFIRMED_BINDING_VERIFY_TIMEOUT_MS));
+        }
+        catch (error) {
+            clearBindingConfirmationIfCurrent(session.session_id, requestKey);
+            throw error;
+        }
+        return { bound: true, supervisorContextCwd: coordinates.supervisorContextCwd };
+    }
+    const deadline = Date.now() + timeoutMs;
+    const { protocolVersion, daemonIdentity } = await negotiateSupervisor(socketPath, timeoutMs);
+    const bindingKey = daemonIdentity ? `${requestKey}\u0000${daemonIdentity}` : null;
+    if (bindingKey && confirmedBindingsBySession.get(session.session_id) === bindingKey) {
+        confirmedRequestsBySession.set(session.session_id, requestKey);
+        confirmedProtocolsBySession.set(session.session_id, protocolVersion);
+        return { bound: true, supervisorContextCwd: coordinates.supervisorContextCwd };
+    }
     const response = await supervisorRequest(socketPath, {
         version: protocolVersion,
         id: randomUUID(),
@@ -41,13 +348,355 @@ export async function bindSupervisedWorkerSession(session, env = process.env, op
             agent_session_token: session.session_token,
             api_url: env.LETAGENTS_API_URL?.trim() || "https://letagents.chat",
         },
-    }, timeoutMs);
+    }, remainingRequestTimeout(deadline));
     if (!response.ok)
         throw new Error(response.error || "Supervisor rejected the worker session binding.");
     if (response.version !== protocolVersion)
         throw new Error("Supervisor binding response used an unexpected protocol version.");
+    if (bindingKey) {
+        confirmedRequestsBySession.set(session.session_id, requestKey);
+        confirmedBindingsBySession.set(session.session_id, bindingKey);
+        confirmedProtocolsBySession.set(session.session_id, protocolVersion);
+    }
+    else {
+        // Without a stable daemon identity we cannot prove that a later process at
+        // the same socket owns this confirmation, so every wait binds strictly.
+        confirmedRequestsBySession.delete(session.session_id);
+        confirmedBindingsBySession.delete(session.session_id);
+        confirmedProtocolsBySession.delete(session.session_id);
+    }
+    return { bound: true, supervisorContextCwd: coordinates.supervisorContextCwd };
+}
+function bindingRequestKey(session, coordinates, env) {
+    const tokenDigest = createHash("sha256").update(session.session_token).digest("hex");
+    return [
+        coordinates.socketPath,
+        coordinates.entryId,
+        coordinates.workAttemptId,
+        coordinates.executionGenerationId,
+        session.session_id,
+        session.room_id,
+        tokenDigest,
+        new URL(env.LETAGENTS_API_URL?.trim() || "https://letagents.chat").origin,
+    ].join("\u0000");
+}
+async function verifyConfirmedBinding(session, coordinates, env, protocolVersion, timeoutMs) {
+    const response = await supervisorRequest(coordinates.socketPath, {
+        version: protocolVersion,
+        id: randomUUID(),
+        method: "supervisor.verify_worker_session",
+        params: {
+            entry_id: coordinates.entryId,
+            room_id: session.room_id,
+            work_attempt_id: coordinates.workAttemptId,
+            execution_generation_id: coordinates.executionGenerationId,
+            agent_session_id: session.session_id,
+            agent_session_token: session.session_token,
+            api_url: env.LETAGENTS_API_URL?.trim() || "https://letagents.chat",
+        },
+    }, timeoutMs);
+    if (!response.ok)
+        throw new Error(response.error || "Supervisor rejected the worker session verification.");
+    if (response.version !== protocolVersion)
+        throw new Error("Supervisor verification response used an unexpected protocol version.");
+}
+function clearBindingConfirmationIfCurrent(sessionId, requestKey) {
+    if (confirmedRequestsBySession.get(sessionId) !== requestKey)
+        return;
+    confirmedRequestsBySession.delete(sessionId);
+    confirmedBindingsBySession.delete(sessionId);
+    confirmedProtocolsBySession.delete(sessionId);
+}
+/** Persist the room-delivery cursor beside the daemon-private exact worker credential. */
+export async function checkpointSupervisedWorkerCursor(session, roomCursor, env = process.env, options = {}) {
+    const coordinates = options.resolvedCoordinates ?? await resolveSupervisorCoordinates(session, env, options);
+    if (!coordinates)
+        return false;
+    const { entryId, socketPath, workAttemptId, executionGenerationId } = coordinates;
+    if (session.session_kind !== "worker")
+        throw new Error("A supervised provider must use a worker session.");
+    if (!roomCursor.trim())
+        throw new Error("Supervised worker cursor is required.");
+    const timeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    const { protocolVersion } = await negotiateSupervisor(socketPath, timeoutMs);
+    const response = await supervisorRequest(socketPath, {
+        version: protocolVersion,
+        id: randomUUID(),
+        method: "supervisor.checkpoint_worker_cursor",
+        params: {
+            entry_id: entryId,
+            work_attempt_id: workAttemptId,
+            execution_generation_id: executionGenerationId,
+            agent_session_id: session.session_id,
+            room_cursor: roomCursor,
+        },
+    }, remainingRequestTimeout(deadline));
+    if (!response.ok)
+        throw new Error(response.error || "Supervisor rejected the worker cursor checkpoint.");
+    if (response.version !== protocolVersion)
+        throw new Error("Supervisor cursor checkpoint response used an unexpected protocol version.");
     return true;
 }
+/**
+ * Coalesce an already-acknowledged cursor outside the MCP response path. The
+ * caller acknowledges a prior delivery by passing it as `after_message_id` on
+ * the next wait; newly observed output must never be checkpointed here.
+ */
+export function scheduleSupervisedWorkerCursorCheckpoint(session, roomCursor, env = process.env, options = {}) {
+    void enqueueSupervisedWorkerCursorCheckpoint(session, roomCursor, env, options).catch((error) => {
+        console.error("[letagents] Supervised cursor checkpoint could not be scheduled:", error instanceof Error ? error.message : "unknown supervisor error");
+    });
+}
+async function enqueueSupervisedWorkerCursorCheckpoint(session, roomCursor, env, options) {
+    if (parseRoomMessageNumber(roomCursor) === null)
+        return;
+    const coordinates = await resolveSupervisorCoordinates(session, env, options);
+    if (!coordinates)
+        return;
+    const key = [
+        session.session_id,
+        session.room_id,
+        coordinates.socketPath,
+        coordinates.entryId,
+        coordinates.workAttemptId,
+        coordinates.executionGenerationId,
+    ].join("\u0000");
+    const existing = pendingCursorCheckpoints.get(key);
+    if (existing && !isNewerRoomCursor(roomCursor, existing.roomCursor))
+        return;
+    pendingCursorCheckpoints.set(key, {
+        session,
+        roomCursor,
+        env,
+        options: { ...options, resolvedCoordinates: coordinates },
+        retryAttempt: 0,
+    });
+    const retryTimer = cursorCheckpointRetryTimers.get(key);
+    if (retryTimer) {
+        clearTimeout(retryTimer);
+        cursorCheckpointRetryTimers.delete(key);
+    }
+    startCursorCheckpointDrain(key);
+}
+async function drainCursorCheckpoints(key) {
+    try {
+        while (true) {
+            const pending = pendingCursorCheckpoints.get(key);
+            if (!pending)
+                return;
+            pendingCursorCheckpoints.delete(key);
+            try {
+                await checkpointSupervisedWorkerCursor(pending.session, pending.roomCursor, pending.env, pending.options);
+            }
+            catch (error) {
+                const queued = pendingCursorCheckpoints.get(key);
+                if (queued && isNewerRoomCursor(queued.roomCursor, pending.roomCursor))
+                    continue;
+                if (isRetryableSupervisorBridgeError(error)
+                    && pending.retryAttempt < CURSOR_CHECKPOINT_RETRY_DELAYS_MS.length) {
+                    // A failed newer acknowledgement must not be replaced by an older
+                    // concurrent wait that happened to enqueue while I/O was in flight.
+                    if (queued)
+                        pendingCursorCheckpoints.delete(key);
+                    const delayMs = CURSOR_CHECKPOINT_RETRY_DELAYS_MS[pending.retryAttempt];
+                    pendingCursorCheckpoints.set(key, { ...pending, retryAttempt: pending.retryAttempt + 1 });
+                    const timer = setTimeout(() => {
+                        cursorCheckpointRetryTimers.delete(key);
+                        startCursorCheckpointDrain(key);
+                    }, delayMs);
+                    timer.unref?.();
+                    cursorCheckpointRetryTimers.set(key, timer);
+                    console.warn("[letagents] Supervised cursor checkpoint is pending:", error instanceof Error ? error.message : "unknown supervisor error");
+                    return;
+                }
+                // An authority/generation rejection is not a harmless transport blip.
+                // Make the next wait prove the exact binding again before it can read.
+                await clearCheckpointBindingConfirmationIfCurrent(pending);
+                pendingCursorCheckpoints.delete(key);
+                console.error("[letagents] Supervised cursor checkpoint was rejected:", error instanceof Error ? error.message : "unknown supervisor error");
+            }
+        }
+    }
+    finally {
+        activeCursorCheckpointDrains.delete(key);
+        if (pendingCursorCheckpoints.has(key) && !cursorCheckpointRetryTimers.has(key)) {
+            startCursorCheckpointDrain(key);
+        }
+    }
+}
+async function clearCheckpointBindingConfirmationIfCurrent(pending) {
+    try {
+        const coordinates = pending.options.resolvedCoordinates
+            ?? await resolveSupervisorCoordinates(pending.session, pending.env, pending.options);
+        if (!coordinates)
+            return;
+        clearBindingConfirmationIfCurrent(pending.session.session_id, bindingRequestKey(pending.session, coordinates, pending.env));
+    }
+    catch {
+        // Missing or invalid context already fails the next wait closed.
+    }
+}
+function startCursorCheckpointDrain(key) {
+    if (activeCursorCheckpointDrains.has(key) || cursorCheckpointRetryTimers.has(key))
+        return;
+    activeCursorCheckpointDrains.add(key);
+    setImmediate(() => { void drainCursorCheckpoints(key); });
+}
+function isNewerRoomCursor(candidate, current) {
+    if (candidate === current)
+        return false;
+    const candidateNumber = parseRoomMessageNumber(candidate);
+    const currentNumber = parseRoomMessageNumber(current);
+    if (candidateNumber === null)
+        return false;
+    if (currentNumber === null)
+        return true;
+    return candidateNumber > currentNumber;
+}
+function parseRoomMessageNumber(cursor) {
+    return parsePositivePgIntegerScopedId(cursor, "msg");
+}
+/** Transport failures are retryable bookkeeping failures, not worker failures. */
+export function isRetryableSupervisorBridgeError(error) {
+    const code = error?.code;
+    if (code && ["ECONNREFUSED", "ECONNRESET", "EPIPE", "ENOENT", "ETIMEDOUT"].includes(code))
+        return true;
+    const message = error instanceof Error ? error.message : String(error ?? "");
+    return /timed out communicating|socket hang up|connection (?:closed|refused|reset)|broken pipe/i.test(message);
+}
+function remainingRequestTimeout(deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining < 1)
+        throw new Error("Timed out communicating with the supervisor daemon.");
+    return remaining;
+}
+async function resolveSupervisorCoordinates(session, env, options) {
+    const environmentCoordinates = {
+        entryId: env.LETAGENTS_SUPERVISOR_ENTRY_ID?.trim() ?? "",
+        socketPath: env.LETAGENTS_SUPERVISOR_DAEMON_SOCKET?.trim() ?? "",
+        workAttemptId: env.LETAGENTS_SUPERVISOR_WORK_ATTEMPT_ID?.trim() ?? "",
+        executionGenerationId: env.LETAGENTS_SUPERVISOR_EXECUTION_GENERATION_ID?.trim() ?? "",
+        providerTurnId: env.LETAGENTS_SUPERVISOR_PROVIDER_TURN_ID?.trim() || undefined,
+        agentSessionId: env.LETAGENTS_SUPERVISOR_AGENT_SESSION_ID?.trim() || undefined,
+        roomId: env.LETAGENTS_SUPERVISOR_ROOM_ID?.trim() || undefined,
+        agentDisplayName: env.LETAGENTS_SUPERVISOR_AGENT_DISPLAY_NAME?.trim() || undefined,
+    };
+    const values = [
+        environmentCoordinates.entryId,
+        environmentCoordinates.socketPath,
+        environmentCoordinates.workAttemptId,
+        environmentCoordinates.executionGenerationId,
+    ];
+    const hasEnvironmentCoordinates = values.some((value) => Boolean(value));
+    if (hasEnvironmentCoordinates && values.some((value) => !value)) {
+        throw new Error("Supervised worker bridge environment is incomplete.");
+    }
+    if (hasEnvironmentCoordinates) {
+        return { ...environmentCoordinates, supervisorContextCwd: null };
+    }
+    const context = await readCodexSupervisorContext(options.cwd ?? session.supervisor_context_cwd ?? process.cwd());
+    if (!context) {
+        if (session.supervisor_context_cwd?.trim()) {
+            throw new Error("The persisted supervised worker context is missing.");
+        }
+        return null;
+    }
+    if (!/^codex(?::|$)/i.test(session.runtime.trim())) {
+        throw new Error("Codex supervisor bridge context cannot bind a non-Codex worker session.");
+    }
+    if (session.room_id && context.roomId !== session.room_id) {
+        throw new Error("Codex supervisor bridge context does not match the worker room.");
+    }
+    return {
+        ...context,
+        socketPath: options.trustedDaemonSocketPath ?? join(homedir(), ".letagents", "daemon.sock"),
+    };
+}
+async function readCodexSupervisorContext(cwd) {
+    const path = join(cwd, SUPERVISOR_CONTEXT_FILE);
+    let encoded;
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.isSymbolicLink() || info.size > MAX_SUPERVISOR_CONTEXT_BYTES) {
+            throw new Error("Codex supervisor bridge context must be a small regular file.");
+        }
+        encoded = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    let value;
+    try {
+        value = JSON.parse(encoded);
+    }
+    catch {
+        throw new Error("Codex supervisor bridge context is not valid JSON.");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Codex supervisor bridge context is malformed.");
+    }
+    const record = value;
+    if (record.version !== 1 || record.provider !== "codex") {
+        throw new Error("Codex supervisor bridge context has an unsupported identity.");
+    }
+    const required = {
+        entryId: record.entry_id,
+        roomId: record.room_id,
+        workAttemptId: record.work_attempt_id,
+        executionGenerationId: record.execution_generation_id,
+    };
+    for (const [field, candidate] of Object.entries(required)) {
+        if (typeof candidate !== "string" || !candidate.trim()) {
+            throw new Error(`Codex supervisor bridge context ${field} is required.`);
+        }
+    }
+    const coordinates = Object.fromEntries(Object.entries(required).map(([field, candidate]) => [field, candidate.trim()]));
+    const agentSessionId = typeof record.agent_session_id === "string" && record.agent_session_id.trim()
+        ? record.agent_session_id.trim()
+        : undefined;
+    const agentDisplayName = typeof record.agent_display_name === "string" && record.agent_display_name.trim()
+        ? record.agent_display_name.trim()
+        : undefined;
+    const marker = await readWorkAttemptMarker(cwd);
+    if (marker.workAttemptId !== coordinates.workAttemptId) {
+        throw new Error("Codex supervisor bridge context does not match the daemon-owned worktree.");
+    }
+    return { ...coordinates, agentSessionId, agentDisplayName, supervisorContextCwd: await realpath(cwd) };
+}
+async function readWorkAttemptMarker(cwd) {
+    const path = join(cwd, WORK_ATTEMPT_MARKER_FILE);
+    let encoded;
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.isSymbolicLink() || info.size > MAX_SUPERVISOR_CONTEXT_BYTES) {
+            throw new Error("Daemon work-attempt marker must be a small regular file.");
+        }
+        encoded = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error("Codex supervisor bridge context is outside a daemon-owned worktree.");
+        }
+        throw error;
+    }
+    let value;
+    try {
+        value = JSON.parse(encoded);
+    }
+    catch {
+        throw new Error("Daemon work-attempt marker is not valid JSON.");
+    }
+    const workAttemptId = value && typeof value === "object" && !Array.isArray(value)
+        ? value.work_attempt_id
+        : null;
+    if (value?.version !== 1 || typeof workAttemptId !== "string" || !workAttemptId.trim()) {
+        throw new Error("Daemon work-attempt marker is malformed.");
+    }
+    return { workAttemptId: workAttemptId.trim() };
+}
 function negotiationProtocolVersion(result) {
     if (!result || typeof result !== "object")
         throw new Error("Supervisor protocol negotiation returned a malformed result.");
@@ -58,21 +707,50 @@ function negotiationProtocolVersion(result) {
     }
     return protocolVersion;
 }
+async function negotiateSupervisor(socketPath, timeoutMs) {
+    const negotiation = await supervisorRequest(socketPath, {
+        version: NEGOTIATION_PROTOCOL_VERSION,
+        id: randomUUID(),
+        method: "daemon.negotiate",
+    }, timeoutMs);
+    if (!negotiation.ok)
+        throw new Error(negotiation.error || "Supervisor protocol negotiation failed.");
+    const protocolVersion = negotiationProtocolVersion(negotiation.result);
+    if (negotiation.version !== protocolVersion)
+        throw new Error("Supervisor negotiation response version does not match its negotiated protocol.");
+    const result = negotiation.result;
+    const hasCompleteIdentity = typeof result.generation === "number"
+        && Number.isSafeInteger(result.generation)
+        && typeof result.pid === "number"
+        && Number.isSafeInteger(result.pid)
+        && typeof result.started_at === "string"
+        && Boolean(result.started_at.trim());
+    const daemonIdentity = hasCompleteIdentity
+        ? [result.generation, result.pid, result.started_at].join(":")
+        : null;
+    return { protocolVersion, daemonIdentity, generation: hasCompleteIdentity ? Number(result.generation) : null };
+}
 function supervisorRequest(socketPath, request, timeoutMs) {
     return new Promise((resolve, reject) => {
         const socket = createConnection(socketPath);
         let buffer = "";
-        const timer = setTimeout(() => {
+        let finished = false;
+        const timer = timeoutMs === null ? null : setTimeout(() => {
             socket.destroy();
-            reject(new Error("Timed out communicating with the supervisor daemon."));
+            finish(() => reject(new Error("Timed out communicating with the supervisor daemon.")));
         }, timeoutMs);
-        timer.unref();
+        timer?.unref();
         const finish = (operation) => {
-            clearTimeout(timer);
+            if (finished)
+                return;
+            finished = true;
+            if (timer)
+                clearTimeout(timer);
             operation();
         };
         socket.setEncoding("utf8");
         socket.once("error", (error) => finish(() => reject(error)));
+        socket.once("close", () => finish(() => reject(new Error("Supervisor connection closed before a response."))));
         socket.on("data", (chunk) => {
             buffer += chunk;
             const newline = buffer.indexOf("\n");