@turns/dev 0.0.1

package/dist/queue-worker.js

@@ -0,0 +1,1053 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { anchorId, connectExistingAgentAnchors, launchAgentAnchor, waitForAgentTurn } from "./agent-anchor-client.js";
+import { assertAllowedWorkingDirectory, workingDirectoryIsAllowed } from "./directory-policy.js";
+import { browseMachinePath } from "./file-browsing.js";
+import { nativeDescriptorAgentSessionId, nativeDescriptorWorkingDirectory } from "./local-session-sources.js";
+import { compactRuntimeValue } from "./native-record-compaction.js";
+import { createSecretRedactor } from "./secret-redaction.js";
+const QUEUE_WARM_MS = Math.max(1_000, Number(process.env.TURNS_QUEUE_WARM_MS) || 5 * 60_000);
+const QUEUE_TURN_TIMEOUT_MS = 12 * 60 * 60_000;
+const CLAIM_RENEW_MS = 60_000;
+const HARNESS_HEARTBEAT_MS = 30_000;
+const MACHINE_HEARTBEAT_MS = 10_000;
+const MACHINE_HEARTBEAT_TIMEOUT_MS = 15_000;
+const RUNTIME_BATCH_SIZE = 100;
+const MAX_RUNTIME_FLUSH_FAILURES = 10;
+const DEFAULT_REDACTOR = createSecretRedactor();
+function wait(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function backgroundWait(milliseconds) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, milliseconds);
+        timer.unref?.();
+    });
+}
+/** Keep the server-side queue claim leased until every completion side effect
+ * has settled. A Worker deployment can make the final runtime flush wait for a
+ * replacement socket; cancelling renewal before that wait requeues a turn that
+ * already ran when its five-minute claim lease expires. */
+export async function withActiveClaimRenewal(renewTimer, operation) {
+    try {
+        return await operation();
+    }
+    finally {
+        clearInterval(renewTimer);
+    }
+}
+export async function reserveCreatingNativeSession(request, creating, sessionId, agentSessionId) {
+    if (!creating)
+        return;
+    await request({ type: 'session.native.reserve', sessionId, agentSessionId });
+}
+/** The origin serving the same deployment as a `wss://…/api/socket` endpoint. */
+export function httpBaseUrl(websocketUrl) {
+    const url = new URL(websocketUrl);
+    url.protocol = url.protocol === 'wss:' ? 'https:' : 'http:';
+    url.pathname = '/';
+    url.search = '';
+    return url;
+}
+function safeAttachmentName(value) {
+    return (String(value || 'attachment')
+        .replace(/[\\/\0-\x1f]/gu, '_')
+        .slice(0, 180) || 'attachment');
+}
+export function attachmentMarkup({ id, name, type, size, path, sessionId }) {
+    return `<attachment>${JSON.stringify({
+        id: String(id || ''),
+        name: String(name || 'attachment'),
+        type: String(type || 'application/octet-stream'),
+        size: Number(size) || 0,
+        path: String(path || ''),
+        ...(sessionId ? { sessionId: String(sessionId) } : {}),
+    })}</attachment>`;
+}
+/**
+ * Spool one attachment body onto disk, and report how much of it arrived.
+ *
+ * The prompt only ever names the file it wrote, so the bytes have no reason to
+ * exist in this process at all — and an attachment may now run to hundreds of
+ * megabytes, which is more than a daemon minding several sessions at once can
+ * afford to hold just to check a number it is about to throw away. Piping keeps
+ * the cost flat and lets `stat` answer the size question afterwards.
+ *
+ * A failed pipe leaves a partial file behind; it is cleared here so a later
+ * attempt writes to a name nothing is squatting on.
+ */
+export async function writeAttachmentFile(response, file) {
+    if (!response.body)
+        throw new Error('Attachment response had no body.');
+    try {
+        await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(file, { mode: 0o600 }));
+    }
+    catch (error) {
+        fs.rmSync(file, { force: true });
+        throw error;
+    }
+    return fs.statSync(file).size;
+}
+async function preparePrompt({ prompt, sessionId, token, baseUrl }) {
+    const text = String(prompt.text || '').trim();
+    const attachments = Array.isArray(prompt.attachments) ? prompt.attachments : [];
+    if (!attachments.length)
+        return text;
+    const directory = path.join(os.homedir(), '.local', 'state', 'turns-dev', 'queue-attachments', sessionId, String(prompt.id));
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const used = new Set();
+    const notices = [];
+    for (const attachment of attachments) {
+        const requested = safeAttachmentName(attachment.name);
+        const dot = requested.lastIndexOf('.');
+        const stem = dot > 0 ? requested.slice(0, dot) : requested;
+        const extension = dot > 0 ? requested.slice(dot) : '';
+        let name = requested;
+        for (let suffix = 2; used.has(name); suffix += 1)
+            name = `${stem}-${suffix}${extension}`;
+        used.add(name);
+        const url = new URL(`/api/attachments/${encodeURIComponent(sessionId)}/${encodeURIComponent(attachment.id)}`, baseUrl);
+        const response = await fetch(url, { headers: { authorization: `Bearer ${token}` } });
+        if (!response.ok)
+            throw new Error(`Attachment ${requested} download failed (${response.status}).`);
+        const file = path.join(directory, name);
+        const written = await writeAttachmentFile(response, file);
+        if (written !== Number(attachment.size)) {
+            fs.rmSync(file, { force: true });
+            throw new Error(`Attachment ${requested} size mismatch.`);
+        }
+        notices.push(attachmentMarkup({
+            id: attachment.id,
+            name,
+            type: attachment.type || 'application/octet-stream',
+            size: written,
+            path: file,
+            sessionId,
+        }));
+    }
+    return [text, ...notices].filter(Boolean).join('\n\n').trim();
+}
+export function runtimeEvent(anchorName, messageId, event, redactor = DEFAULT_REDACTOR) {
+    const sequence = Number(event?.anchorEventSequence || 0);
+    const interactionScope = `${anchorName}:${messageId || event?.messageId || 'turn'}`;
+    const key = `anchor:${interactionScope}:${sequence || crypto.randomUUID()}`;
+    const ts = String(event?.capturedAt || new Date().toISOString());
+    if (['user.interaction', 'user.interaction_answer', 'user.interaction_expired'].includes(event?.event)) {
+        const interactionId = String(event.interaction?.id || '');
+        if (!interactionId)
+            return null;
+        const suffix = event.event === 'user.interaction'
+            ? 'interaction'
+            : event.event === 'user.interaction_answer'
+                ? 'interaction-answer'
+                : 'interaction-expired';
+        return {
+            eventKey: `${suffix}:${interactionScope}:${interactionId}`,
+            kind: event.event === 'user.interaction'
+                ? 'session.interaction_request'
+                : event.event === 'user.interaction_answer'
+                    ? 'session.interaction_answer'
+                    : 'session.interaction_expired',
+            phase: String(event.phase || 'queued'),
+            ts,
+            source: 'agent-anchor',
+            value: redactor.redactJsonLine(JSON.stringify({
+                id: interactionId,
+                interaction: event.interaction,
+                ...(Object.hasOwn(event, 'response') ? { response: event.response } : {}),
+                ...(event.reason ? { reason: event.reason } : {}),
+            })),
+        };
+    }
+    if (event?.direction === 'in' || event?.direction === 'out') {
+        const value = typeof event.raw === 'string' ? event.raw : JSON.stringify(event.json || {});
+        if (!value)
+            return null;
+        return {
+            eventKey: key,
+            kind: event.direction === 'out' ? 'stream.in' : 'stream.out',
+            phase: String(event.phase || 'queued'),
+            ts,
+            source: String(event.source || `${event.agent || 'agent'}.stdout`),
+            ...(event.method ? { method: String(event.method) } : {}),
+            value: compactRuntimeValue(redactor.redactText(value)),
+        };
+    }
+    if (event?.event === 'process.line') {
+        // CodexAppServerClient emits a decoded jsonrpc.response/notification before
+        // captureStream emits the same stdout bytes as process.line. Uploading both
+        // makes every short text delta arrive twice; retain process.line only for
+        // non-protocol output (and stderr), where there is no decoded counterpart.
+        if (event.source === 'app-server.stdout' && event.json && (event.json.id !== undefined || event.json.method))
+            return null;
+        const value = typeof event.raw === 'string' ? event.raw : JSON.stringify(event.json || {});
+        if (!value)
+            return null;
+        return {
+            eventKey: key,
+            kind: String(event.source || '').endsWith('.stderr') ? 'stream.err' : 'stream.out',
+            phase: String(event.phase || 'queued'),
+            ts,
+            source: String(event.source || `${event.agent || 'agent'}.stdout`),
+            value: compactRuntimeValue(redactor.redactText(value)),
+        };
+    }
+    if (event?.event === 'interrupt.issued' || event?.event === 'interrupt.settled') {
+        return {
+            eventKey: key,
+            kind: 'scenario.interrupt.issued',
+            phase: 'interrupted',
+            ts,
+            source: 'agent-anchor',
+            status: event.event === 'interrupt.settled' ? 'confirmed' : 'unconfirmed',
+            value: redactor.redactJsonLine(JSON.stringify(event)),
+        };
+    }
+    if (event?.event === 'turn.steer') {
+        return {
+            eventKey: key,
+            kind: 'session.queue_steer',
+            phase: 'queued',
+            ts,
+            source: 'agent-anchor',
+            value: redactor.redactJsonLine(JSON.stringify({
+                type: 'turns.session.queue_steer',
+                messageId: String(event.messageId || ''),
+                displayPrompt: String(event.displayPrompt || event.prompt || ''),
+                prompt: String(event.prompt || ''),
+                anchorId: String(event.anchorId || anchorName),
+            })),
+        };
+    }
+    return null;
+}
+export function resultError(result) {
+    if (!result)
+        return new Error('The anchored agent returned no result.');
+    // Interrupt-capable harnesses commonly report cancellation through their
+    // error channel. Once the anchor confirms that the user requested it, the
+    // queue item is consumed rather than retried.
+    if (result.interrupted)
+        return null;
+    if (result.error)
+        return new Error(result.error.message || String(result.error));
+    if (result.timedOut)
+        return new Error('The anchored agent turn timed out.');
+    if (result.exitCode !== undefined && result.exitCode !== null && result.exitCode !== 0) {
+        return new Error(`The anchored agent exited with ${result.signal || result.exitCode}.`);
+    }
+    return null;
+}
+export function dispatchErrorIsRetryable(error) {
+    const message = String(error?.message || error || '');
+    return !(/(?:not supported|does not support|no resumable native session|session key.*unavailable|no local transcript descriptor|working directory is unavailable|outside the daemon allowlist|agent executable not found)/iu.test(message) || /attachment .* (?:size mismatch|download failed \(4\d\d\))/iu.test(message));
+}
+export async function actualHarnessStatus(entry) {
+    if (!entry || entry.connection.closed)
+        return 'stopped';
+    const snapshot = await entry.connection.request('snapshot', {}, 5_000);
+    entry.snapshot = snapshot;
+    return snapshot.status === 'running' ? 'running' : 'idle';
+}
+export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors, stableSessionId, redactor = DEFAULT_REDACTOR, }) {
+    const workerId = `${machine}:turns-queue-worker`;
+    const workerInstanceId = crypto.randomUUID();
+    const baseUrl = httpBaseUrl(options.url);
+    const anchors = new Map();
+    const claims = new Map();
+    const claimStarts = new Set();
+    const recoveredTurns = new Set();
+    const runtimeQueues = new Map();
+    const descriptors = () => {
+        const byId = new Map();
+        for (const descriptor of getDescriptors()) {
+            byId.set(stableSessionId(machine, descriptor.harness, descriptor.sourcePath), descriptor);
+        }
+        return byId;
+    };
+    const request = (message, timeoutMs) => rpc.request(message, timeoutMs);
+    const flushRuntime = async (sessionId) => {
+        const state = runtimeQueues.get(sessionId);
+        if (!state || state.flushing)
+            return state?.promise;
+        state.flushing = true;
+        state.promise = (async () => {
+            while (state.events.length) {
+                const events = state.events.slice(0, RUNTIME_BATCH_SIZE);
+                try {
+                    await request({ type: 'session.runtime.append', sessionId, events });
+                    state.events.splice(0, events.length);
+                    state.failures = 0;
+                }
+                catch (error) {
+                    const message = String(error?.message || error);
+                    state.failures = (state.failures || 0) + 1;
+                    process.stderr.write(`Runtime event append failed for ${sessionId}: ${message}\n`);
+                    // Socket failures are retried inside request(). Keep valid anchor
+                    // events across other transient Worker/R2 failures too. Only discard
+                    // a batch when the session is gone or the internally constructed row
+                    // is permanently invalid; the anchor journal can still be inspected.
+                    //
+                    // A batch that keeps failing is discarded rather than retried without
+                    // end: this queue is what a queued turn's dispatch and completion wait
+                    // behind, so an undeliverable frame must cost live rows, never the
+                    // turn itself. The durable transcript still carries the content.
+                    if (/(?:session not found|not assigned to the registered machine|invalid runtime event|is too large|too big)/iu.test(message)) {
+                        state.events.splice(0, events.length);
+                        state.failures = 0;
+                    }
+                    else if (state.failures >= MAX_RUNTIME_FLUSH_FAILURES) {
+                        process.stderr.write(`Dropping ${events.length} undeliverable runtime events for ${sessionId} after ` +
+                            `${state.failures} attempts: ${message}\n`);
+                        state.events.splice(0, events.length);
+                        state.failures = 0;
+                    }
+                    else {
+                        await wait(1_000);
+                    }
+                }
+            }
+        })().finally(() => {
+            state.flushing = false;
+            state.promise = null;
+        });
+        return state.promise;
+    };
+    const enqueueRuntime = (sessionId, event, immediate = false) => {
+        if (!event)
+            return Promise.resolve();
+        let state = runtimeQueues.get(sessionId);
+        if (!state) {
+            state = { events: [], flushing: false, promise: null, timer: null, failures: 0 };
+            runtimeQueues.set(sessionId, state);
+        }
+        state.events.push(event);
+        if (immediate || state.events.length >= RUNTIME_BATCH_SIZE) {
+            clearTimeout(state.timer);
+            state.timer = null;
+            return flushRuntime(sessionId);
+        }
+        if (!state.timer) {
+            state.timer = setTimeout(() => {
+                state.timer = null;
+                void flushRuntime(sessionId);
+            }, 20);
+            state.timer.unref?.();
+        }
+        return Promise.resolve();
+    };
+    const reportHarness = async (sessionId, state, entry) => {
+        await request({
+            type: 'session.harness.update',
+            statuses: [
+                {
+                    sessionId,
+                    state,
+                    observedAt: new Date().toISOString(),
+                    ...(entry ? { anchorId: entry.id } : {}),
+                },
+            ],
+        });
+    };
+    const stopClaimRenewal = (claim) => {
+        if (!claim?.renewTimer)
+            return;
+        clearInterval(claim.renewTimer);
+        claim.renewTimer = null;
+    };
+    const reportActualHarness = async (sessionId, entry) => {
+        await reportHarness(sessionId, await actualHarnessStatus(entry), entry);
+    };
+    const bindAnchor = (connection, snapshot, expectedSessionId = '') => {
+        // A newly launched anchor is intentionally identity-less until its first
+        // send_message. Bind it to the claimed turns.dev session immediately so
+        // early status/live events and Cmd-. interrupts cannot fall into the empty
+        // session key before startTurn fills the anchor snapshot.
+        const sessionId = String(snapshot.sessionId || expectedSessionId || '');
+        const entry = {
+            id: anchorId(connection),
+            connection,
+            snapshot,
+            stop: null,
+        };
+        const previous = anchors.get(sessionId);
+        if (previous && previous.connection !== connection)
+            previous.connection.close();
+        anchors.set(sessionId, entry);
+        entry.stop = connection.onEvent((message) => {
+            if (message.type === 'anchor_hello' && message.anchor)
+                entry.snapshot = message.anchor;
+            if (message.type === 'session_identity') {
+                entry.snapshot = {
+                    ...entry.snapshot,
+                    agentSessionId: message.agentSessionId || entry.snapshot.agentSessionId,
+                    transcriptPath: message.transcriptPath || entry.snapshot.transcriptPath,
+                };
+                if (message.agentSessionId) {
+                    void request({
+                        type: 'session.native.bind',
+                        sessionId,
+                        agentSessionId: String(message.agentSessionId),
+                    }).catch(() => { });
+                }
+            }
+            if (message.type === 'session_status') {
+                entry.snapshot = { ...entry.snapshot, status: message.status };
+                const state = message.status === 'running' ? 'running' : 'idle';
+                // Anchor messages are ordered, but runtime rows are uploaded in small
+                // asynchronous batches. Flush every preceding live frame before the
+                // idle boundary so the canonical log cannot close a Claude turn between
+                // its deltas and assembled assistant frame.
+                void (async () => {
+                    if (state === 'idle')
+                        await flushRuntime(sessionId);
+                    await reportHarness(sessionId, state, entry);
+                })().catch((error) => process.stderr.write(`Harness status upload failed: ${error?.message || error}\n`));
+            }
+            if (message.type === 'live_event') {
+                const turnMessageId = String(message.messageId || entry.snapshot.currentTurn?.messageId || '');
+                if (message.event?.event === 'user.interaction') {
+                    entry.snapshot = {
+                        ...entry.snapshot,
+                        pendingInteractions: [
+                            ...(entry.snapshot.pendingInteractions || []).filter((interaction) => interaction.id !== message.event.interaction?.id),
+                            message.event.interaction,
+                        ].filter(Boolean),
+                    };
+                }
+                else if (['user.interaction_answer', 'user.interaction_expired'].includes(message.event?.event)) {
+                    entry.snapshot = {
+                        ...entry.snapshot,
+                        pendingInteractions: (entry.snapshot.pendingInteractions || []).filter((interaction) => interaction.id !== message.event.interaction?.id),
+                    };
+                }
+                const event = runtimeEvent(entry.id, turnMessageId, message.event, redactor);
+                void enqueueRuntime(sessionId, event);
+            }
+            if (message.type === 'anchor_disconnect') {
+                if (anchors.get(sessionId) === entry)
+                    anchors.delete(sessionId);
+                const claim = claims.get(sessionId);
+                if (claim?.entry === entry)
+                    stopClaimRenewal(claim);
+                entry.stop?.();
+                void (async () => {
+                    const messageId = String(entry.snapshot.currentTurn?.messageId || '');
+                    const reason = 'The detached harness stopped before this interaction was answered.';
+                    for (const interaction of entry.snapshot.pendingInteractions || []) {
+                        await enqueueRuntime(sessionId, runtimeEvent(entry.id, messageId, {
+                            event: 'user.interaction_expired',
+                            phase: 'queued',
+                            interaction,
+                            reason,
+                        }, redactor));
+                    }
+                    await flushRuntime(sessionId);
+                    await reportHarness(sessionId, 'stopped', entry);
+                })().catch(() => { });
+            }
+        });
+        return entry;
+    };
+    const existing = await connectExistingAgentAnchors();
+    for (const { connection, snapshot } of existing) {
+        if (!workingDirectoryIsAllowed(String(snapshot.cwd || ''), options.allowedDirectories)) {
+            connection.close();
+            continue;
+        }
+        bindAnchor(connection, snapshot);
+    }
+    const usableAnchor = async (sessionId, source, agentSessionId) => {
+        let entry = anchors.get(sessionId);
+        if (entry && !entry.connection.closed) {
+            entry.snapshot = await entry.connection.request('snapshot', {}, 5_000).catch(() => entry.snapshot);
+            if (String(entry.snapshot.source || '') === source &&
+                String(entry.snapshot.agentSessionId || '') === agentSessionId)
+                return entry;
+            if (entry.snapshot.status === 'running')
+                throw new Error('The surviving anchor is running a different session identity.');
+            await entry.connection.request('shutdown', {}, 2_000).catch(() => { });
+            entry.connection.close();
+            anchors.delete(sessionId);
+        }
+        const connection = await launchAgentAnchor(sessionId);
+        entry = bindAnchor(connection, connection.snapshot || {}, sessionId);
+        await reportHarness(sessionId, 'idle', entry);
+        return entry;
+    };
+    const queuePromptBoundary = (entry, claim) => redactor.redactValue({
+        eventKey: `queue:${claim.prompt.id}:prompt`,
+        kind: 'session.queue_prompt',
+        phase: 'queued',
+        ts: claim.prompt.createdAt || new Date().toISOString(),
+        source: 'turns-queue',
+        value: JSON.stringify({
+            type: 'turns.session.queue_prompt',
+            messageId: claim.prompt.id,
+            displayPrompt: claim.prompt.text,
+            prompt: claim.prompt.text,
+            anchorId: entry?.id,
+        }),
+    });
+    const finishClaim = async (sessionId, claim, entry, result) => {
+        await withActiveClaimRenewal(claim.renewTimer, async () => {
+            await flushRuntime(sessionId);
+            await reportHarness(sessionId, entry.connection.closed ? 'stopped' : 'idle', entry).catch(() => { });
+            const error = resultError(result);
+            if (error) {
+                await request({
+                    type: 'queue.fail',
+                    sessionId,
+                    promptId: claim.prompt.id,
+                    claimToken: claim.claimToken,
+                    error: redactor.redactText(error.message),
+                    retryable: dispatchErrorIsRetryable(error),
+                });
+            }
+            else {
+                await request({
+                    type: 'queue.complete',
+                    sessionId,
+                    promptId: claim.prompt.id,
+                    claimToken: claim.claimToken,
+                });
+            }
+        });
+        claims.delete(sessionId);
+    };
+    const runClaim = async (sessionId, claim, recovery = null) => {
+        if (claims.has(sessionId))
+            return;
+        // Publish the optimistic user turn before native-session lookup, attachment
+        // download, or a cold anchor launch. The stable event key makes recovery
+        // idempotent, and the outbound protocol frame will replace this placeholder.
+        // Dispatch deliberately does not wait for that publish: the queue preserves
+        // order on its own, and a frame the Worker will not accept must not be able
+        // to hold a claimed prompt back from the agent.
+        void enqueueRuntime(sessionId, queuePromptBoundary(recovery?.entry || anchors.get(sessionId), claim), true).catch((error) => process.stderr.write(`Queue prompt boundary publish failed for ${sessionId}: ${error?.message || error}\n`));
+        let descriptor;
+        let agentSessionId = '';
+        let creating = false;
+        let cwd = '';
+        let entry = recovery?.entry;
+        if (!recovery) {
+            const descriptorMap = descriptors();
+            let discovered = descriptorMap.get(sessionId);
+            const claimedAgentSessionId = String(claim.session?.agentSessionId || '');
+            if (!discovered && claimedAgentSessionId) {
+                for (const candidate of descriptorMap.values()) {
+                    if ((await nativeDescriptorAgentSessionId(candidate)) === claimedAgentSessionId) {
+                        discovered = candidate;
+                        break;
+                    }
+                }
+            }
+            const pendingNativeSession = !String(claim.session?.sourcePath || '');
+            creating = Boolean(claim.session?.createSession);
+            descriptor =
+                discovered ||
+                    (pendingNativeSession
+                        ? {
+                            harness: claim.session.harness,
+                            sourcePath: claim.session.sourcePath,
+                            file: path.join(os.tmpdir(), `turns-new-session-${sessionId}`),
+                        }
+                        : null);
+            if (!descriptor)
+                throw new Error(`No local transcript descriptor exists for ${sessionId}.`);
+            agentSessionId =
+                claimedAgentSessionId || (creating ? crypto.randomUUID() : await nativeDescriptorAgentSessionId(descriptor));
+            if (!agentSessionId)
+                throw new Error(`The ${descriptor.harness} transcript has no resumable native session key.`);
+            // Claude is given this UUID on its command line, so reserve the mapping
+            // before the anchor can create a transcript that the native watcher sees.
+            // The reservation is distinct from a completed bind: if launch fails, a
+            // retry still creates the same native session instead of trying to resume
+            // one that never started.
+            await reserveCreatingNativeSession(request, creating, sessionId, agentSessionId);
+            const workingDirectory = pendingNativeSession
+                ? String(claim.session?.workingDirectory || '')
+                : await nativeDescriptorWorkingDirectory(descriptor);
+            const fallbackDirectory = path.dirname(descriptor.file);
+            const selectedDirectory = workingDirectory && path.isAbsolute(workingDirectory) && fs.existsSync(workingDirectory)
+                ? workingDirectory
+                : fallbackDirectory;
+            cwd = assertAllowedWorkingDirectory(selectedDirectory, options.allowedDirectories);
+            if (!fs.statSync(cwd).isDirectory())
+                throw new Error(`Working directory is unavailable: ${cwd}`);
+            entry = await usableAnchor(sessionId, descriptor.harness, agentSessionId);
+        }
+        if (!entry)
+            throw new Error(`No surviving agent anchor exists for ${sessionId}.`);
+        const queued = {
+            ...claim,
+            entry,
+            renewTimer: null,
+        };
+        claims.set(sessionId, queued);
+        const renewClaim = () => request({
+            type: 'queue.renew',
+            sessionId,
+            promptId: claim.prompt.id,
+            claimToken: claim.claimToken,
+        });
+        const beginRenewal = () => {
+            if (queued.renewTimer)
+                return;
+            queued.renewTimer = setInterval(() => {
+                if (entry.connection.closed) {
+                    stopClaimRenewal(queued);
+                    void reportHarness(sessionId, 'stopped', entry).catch(() => { });
+                    return;
+                }
+                void renewClaim().catch((error) => process.stderr.write(`Queue lease renewal failed: ${error?.message || error}\n`));
+                // Never renew lifecycle state from an old in-memory snapshot. The
+                // anchor may have disconnected since the claim began, which would
+                // otherwise resurrect a canonical stopped edge as running.
+                void reportActualHarness(sessionId, entry).catch(async () => {
+                    if (entry.connection.closed) {
+                        stopClaimRenewal(queued);
+                        await reportHarness(sessionId, 'stopped', entry).catch(() => { });
+                    }
+                });
+            }, CLAIM_RENEW_MS);
+            queued.renewTimer.unref?.();
+        };
+        beginRenewal();
+        // Verify and extend the inherited lease before waiting on a recovered
+        // anchor. If the server has already replaced it, normal claiming plus the
+        // anchor's prompt idempotency will reconcile the surviving turn instead.
+        if (recovery)
+            await renewClaim();
+        const prompt = recovery?.prompt ||
+            (await preparePrompt({
+                prompt: claim.prompt,
+                sessionId,
+                token: options.token,
+                baseUrl,
+            }));
+        for (const event of recovery?.events || []) {
+            await enqueueRuntime(sessionId, runtimeEvent(entry.id, claim.prompt.id, event, redactor));
+        }
+        await reportHarness(sessionId, recovery ? (recovery.snapshot?.status === 'running' ? 'running' : 'idle') : 'idle', entry);
+        let result;
+        if (recovery) {
+            const eventCursor = entry.connection.eventCursor();
+            result = await waitForAgentTurn(entry.connection, claim.prompt.id, QUEUE_TURN_TIMEOUT_MS, recovery.snapshot, eventCursor);
+        }
+        else {
+            await reportHarness(sessionId, 'running', entry);
+            // Queue retries deliberately reuse the prompt ID. Remember the event
+            // boundary before starting this attempt so an earlier turn_error with
+            // that ID cannot immediately settle the new turn.
+            const eventCursor = entry.connection.eventCursor();
+            await entry.connection.request('send_message', {
+                source: descriptor.harness,
+                sessionId,
+                agentSessionId,
+                cwd,
+                transcriptPath: descriptor.file,
+                workerId,
+                messageId: claim.prompt.id,
+                claimToken: claim.claimToken,
+                prompt,
+                expectedText: claim.prompt.text,
+                createSession: creating,
+                permissionMode: String(claim.session?.permissionMode || 'bypassPermissions'),
+                codexHistoryMode: String(claim.session?.codexHistoryMode || ''),
+                timeoutMs: QUEUE_TURN_TIMEOUT_MS,
+                idleTimeoutMs: QUEUE_WARM_MS,
+            }, 30_000);
+            entry.snapshot = await entry.connection.request('snapshot', {}, 5_000).catch(() => entry.snapshot);
+            // Registration after acceptance is safe: the connection retains recent
+            // events and the snapshot carries a turn that completed immediately.
+            result = await waitForAgentTurn(entry.connection, claim.prompt.id, QUEUE_TURN_TIMEOUT_MS, entry.snapshot, eventCursor);
+            if (creating) {
+                const createdIdentity = String(entry.snapshot?.agentSessionId || agentSessionId);
+                await request({ type: 'session.native.bind', sessionId, agentSessionId: createdIdentity });
+            }
+        }
+        entry.snapshot = await entry.connection.request('snapshot', {}, 5_000).catch(() => ({
+            ...entry.snapshot,
+            status: 'idle',
+        }));
+        await finishClaim(sessionId, queued, entry, result);
+    };
+    const tryClaim = async (sessionId) => {
+        if (claims.has(sessionId) || claimStarts.has(sessionId))
+            return;
+        claimStarts.add(sessionId);
+        let claim;
+        try {
+            const response = await request({ type: 'queue.claim', sessionId });
+            claim = response.claim;
+            if (!claim)
+                return;
+            await runClaim(sessionId, claim);
+            // A completion can make the next item ready before its unsolicited event
+            // crosses the socket. Claim once more immediately for zero-gap draining.
+            queueMicrotask(() => void tryClaim(sessionId));
+        }
+        catch (error) {
+            process.stderr.write(`Queue dispatch failed for ${sessionId}: ${error?.message || error}\n`);
+            const held = claims.get(sessionId);
+            stopClaimRenewal(held);
+            if (held?.entry && !held.entry.connection.closed) {
+                held.entry.snapshot = await held.entry.connection
+                    .request('snapshot', {}, 2_000)
+                    .catch(() => held.entry.snapshot);
+                await reportHarness(sessionId, held.entry.snapshot?.status === 'running' ? 'running' : 'idle', held.entry).catch(() => { });
+            }
+            else if (held?.entry) {
+                await reportHarness(sessionId, 'stopped', held.entry).catch(() => { });
+            }
+            if (claim) {
+                await request({
+                    type: 'queue.fail',
+                    sessionId,
+                    promptId: claim.prompt.id,
+                    claimToken: claim.claimToken,
+                    error: redactor.redactText(error?.message || String(error)),
+                    retryable: dispatchErrorIsRetryable(error),
+                }).catch(() => { });
+            }
+            claims.delete(sessionId);
+        }
+        finally {
+            claimStarts.delete(sessionId);
+        }
+    };
+    const recoverAnchors = async () => {
+        for (const [sessionId, entry] of anchors) {
+            const snapshot = await entry.connection.request('snapshot', {}, 5_000).catch(() => entry.snapshot);
+            entry.snapshot = snapshot;
+            await reportHarness(sessionId, snapshot.status === 'running' ? 'running' : 'idle', entry).catch(() => { });
+            const turn = snapshot.currentTurn;
+            // A warm anchor retains its terminal turn for diagnostics. Probe the
+            // saved claim during recovery too: if completion acknowledgement was
+            // lost, the queue row still needs to be consumed; otherwise renewal
+            // rejects the stale token before any prompt can be sent.
+            if (!turn?.messageId || !turn.claimToken)
+                continue;
+            const recoveryKey = `${entry.id}:${turn.messageId}`;
+            if (recoveredTurns.has(recoveryKey) || claims.has(sessionId))
+                continue;
+            recoveredTurns.add(recoveryKey);
+            const prompt = {
+                id: String(turn.messageId),
+                sessionId,
+                text: String(turn.expectedText || turn.prompt || ''),
+                attachments: [],
+                position: 0,
+                paused: false,
+                claimed: true,
+                createdAt: String(turn.startedAt || new Date().toISOString()),
+                updatedAt: String(turn.startedAt || new Date().toISOString()),
+            };
+            const claim = {
+                prompt,
+                claimToken: String(turn.claimToken),
+                expiresAt: '',
+                session: null,
+            };
+            void runClaim(sessionId, claim, {
+                entry,
+                snapshot,
+                events: Array.isArray(snapshot.liveEvents) ? snapshot.liveEvents : [],
+                prompt: String(turn.prompt || turn.expectedText || ''),
+            }).catch(async (error) => {
+                const held = claims.get(sessionId);
+                stopClaimRenewal(held);
+                claims.delete(sessionId);
+                await reportActualHarness(sessionId, held?.entry || entry).catch(async () => {
+                    if ((held?.entry || entry).connection.closed) {
+                        await reportHarness(sessionId, 'stopped', held?.entry || entry).catch(() => { });
+                    }
+                });
+                process.stderr.write(`Anchor recovery failed for ${sessionId}: ${error?.message || error}\n`);
+            });
+        }
+    };
+    const handleSteer = async (message, replyRpc) => {
+        const sessionId = String(message.sessionId || '');
+        const entry = anchors.get(sessionId);
+        try {
+            if (!entry || entry.connection.closed || entry.snapshot?.status !== 'running') {
+                throw new Error('The detached harness is not actively running.');
+            }
+            const prompt = await preparePrompt({
+                prompt: message.prompt,
+                sessionId,
+                token: options.token,
+                baseUrl,
+            });
+            const steered = await entry.connection.request('steer', {
+                prompt,
+                messageId: message.prompt.id,
+            }, 30_000);
+            await flushRuntime(sessionId);
+            // Harnesses without a steering primitive interrupt the running turn
+            // instead of accepting the prompt mid-turn. Report which happened so the
+            // server keeps the prompt queued for the turn that follows.
+            const mode = steered?.mode === 'interrupt' ? 'interrupt' : 'steer';
+            replyRpc.notify({
+                type: 'session.steer.result',
+                requestId: message.requestId,
+                sessionId,
+                promptId: message.prompt.id,
+                ok: true,
+                mode,
+            });
+        }
+        catch (error) {
+            await reportActualHarness(sessionId, entry).catch(async () => {
+                if (!entry || entry.connection.closed) {
+                    await reportHarness(sessionId, 'stopped', entry).catch(() => { });
+                }
+            });
+            replyRpc.notify({
+                type: 'session.steer.result',
+                requestId: message.requestId,
+                sessionId,
+                promptId: message.prompt?.id || '',
+                ok: false,
+                error: redactor.redactText(error?.message || String(error)),
+            });
+        }
+    };
+    const handleInterrupt = async (message, replyRpc) => {
+        const sessionId = String(message.sessionId || '');
+        const entry = anchors.get(sessionId);
+        try {
+            if (!entry || entry.connection.closed || entry.snapshot?.status !== 'running') {
+                throw new Error('The detached harness is not actively running.');
+            }
+            await entry.connection.request('interrupt', {
+                messageId: String(entry.snapshot?.currentTurn?.messageId || ''),
+            }, 30_000);
+            replyRpc.notify({
+                type: 'session.interrupt.result',
+                requestId: message.requestId,
+                sessionId,
+                ok: true,
+            });
+        }
+        catch (error) {
+            await flushRuntime(sessionId).catch(() => { });
+            await reportHarness(sessionId, !entry || entry.connection.closed ? 'stopped' : 'idle', entry).catch(() => { });
+            replyRpc.notify({
+                type: 'session.interrupt.result',
+                requestId: message.requestId,
+                sessionId,
+                ok: false,
+                error: redactor.redactText(error?.message || String(error)),
+            });
+        }
+    };
+    const handleAnchorAction = async (message, replyRpc) => {
+        const sessionId = String(message.sessionId || '');
+        const action = message.action === 'compact' ? 'compact' : 'shutdown';
+        const entry = anchors.get(sessionId);
+        try {
+            if (!entry || entry.connection.closed)
+                throw new Error('The detached harness is offline.');
+            entry.snapshot = await entry.connection.request('snapshot', {}, 5_000);
+            if (entry.snapshot?.status === 'running')
+                throw new Error('The detached harness is actively running.');
+            if (action === 'compact' && entry.snapshot?.pendingInteractions?.length) {
+                throw new Error('The detached harness is awaiting user input.');
+            }
+            await entry.connection.request(action, {}, action === 'compact' ? QUEUE_TURN_TIMEOUT_MS : 5_000);
+            if (action === 'compact') {
+                await flushRuntime(sessionId);
+                entry.snapshot = await entry.connection.request('snapshot', {}, 5_000).catch(() => entry.snapshot);
+                await reportHarness(sessionId, 'idle', entry);
+            }
+            else {
+                entry.connection.close();
+                if (anchors.get(sessionId) === entry)
+                    anchors.delete(sessionId);
+                await reportHarness(sessionId, 'stopped', entry);
+            }
+            replyRpc.notify({
+                type: 'session.anchor.action.result',
+                requestId: message.requestId,
+                sessionId,
+                action,
+                ok: true,
+            });
+        }
+        catch (error) {
+            await flushRuntime(sessionId).catch(() => { });
+            await reportHarness(sessionId, !entry || entry.connection.closed ? 'stopped' : 'idle', entry).catch(() => { });
+            replyRpc.notify({
+                type: 'session.anchor.action.result',
+                requestId: message.requestId,
+                sessionId,
+                action,
+                ok: false,
+                error: redactor.redactText(error?.message || String(error)),
+            });
+        }
+    };
+    const handleInteractionAnswer = async (message, replyRpc) => {
+        const sessionId = String(message.sessionId || '');
+        const entry = anchors.get(sessionId);
+        try {
+            if (!entry || entry.connection.closed)
+                throw new Error('The detached harness is offline.');
+            entry.snapshot = await entry.connection.request('snapshot', {}, 5_000).catch(() => entry.snapshot);
+            if (!entry.snapshot?.pendingInteractions?.some((interaction) => interaction.id === message.interactionId)) {
+                throw new Error('The detached harness is no longer waiting for this interaction.');
+            }
+            await entry.connection.request('answer_interaction', {
+                interactionId: String(message.interactionId || ''),
+                response: message.response,
+            }, 30_000);
+            await flushRuntime(sessionId);
+            replyRpc.notify({
+                type: 'session.interaction.answer.result',
+                requestId: message.requestId,
+                sessionId,
+                interactionId: message.interactionId,
+                ok: true,
+            });
+        }
+        catch (error) {
+            await reportHarness(sessionId, !entry || entry.connection.closed ? 'stopped' : entry.snapshot?.status === 'running' ? 'running' : 'idle', entry).catch(() => { });
+            replyRpc.notify({
+                type: 'session.interaction.answer.result',
+                requestId: message.requestId,
+                sessionId,
+                interactionId: message.interactionId,
+                ok: false,
+                error: redactor.redactText(error?.message || String(error)),
+            });
+        }
+    };
+    /**
+     * Where a browse starts when the reader named nothing, or named it loosely.
+     *
+     * A running anchor knows its own working directory; a session without one is
+     * described by the transcript it came from. Either answer only decides what a
+     * bare or relative path means — an absolute path resolves to itself, and the
+     * daemon's allowlist is what actually bounds where a browse can reach.
+     */
+    const browseWorkingDirectory = async (sessionId) => {
+        const cwd = String(anchors.get(sessionId)?.snapshot?.cwd || '');
+        if (cwd)
+            return cwd;
+        const descriptor = descriptors().get(sessionId);
+        if (!descriptor)
+            return '';
+        let recorded = '';
+        try {
+            recorded = nativeDescriptorWorkingDirectory(descriptor);
+        }
+        catch { }
+        return recorded || path.dirname(descriptor.file);
+    };
+    /**
+     * Store one path this machine holds, so a reader can open it.
+     *
+     * Unlike the rest of these handlers this touches no harness: browsing is a
+     * property of the machine, so it answers for a stopped session as readily as
+     * for a running one.
+     */
+    const handleFileBrowse = async (message, replyRpc) => {
+        const sessionId = String(message.sessionId || '');
+        try {
+            const stored = await browseMachinePath({
+                requested: String(message.path || ''),
+                machine,
+                baseUrl,
+                options,
+                workingDirectory: await browseWorkingDirectory(sessionId),
+            });
+            replyRpc.notify({
+                type: 'session.file.browse.result',
+                requestId: message.requestId,
+                sessionId,
+                ok: true,
+                ...stored,
+            });
+        }
+        catch (error) {
+            replyRpc.notify({
+                type: 'session.file.browse.result',
+                requestId: message.requestId,
+                sessionId,
+                ok: false,
+                error: redactor.redactText(error?.message || String(error)),
+            });
+        }
+    };
+    const heartbeat = setInterval(() => {
+        for (const [sessionId, entry] of anchors) {
+            if (entry.connection.closed)
+                continue;
+            void reportHarness(sessionId, entry.snapshot?.status === 'running' ? 'running' : 'idle', entry).catch(() => { });
+        }
+    }, HARNESS_HEARTBEAT_MS);
+    heartbeat.unref?.();
+    rpc.onEvent((message) => {
+        if (message.type === 'queue.ready')
+            void tryClaim(message.sessionId);
+        if (message.type === 'session.steer')
+            void handleSteer(message, rpc);
+        if (message.type === 'session.interrupt.request')
+            void handleInterrupt(message, rpc);
+        if (message.type === 'session.anchor.action.request')
+            void handleAnchorAction(message, rpc);
+        if (message.type === 'session.interaction.answer.request')
+            void handleInteractionAnswer(message, rpc);
+        if (message.type === 'session.file.browse.request')
+            void handleFileBrowse(message, rpc);
+    });
+    const registered = new WeakSet();
+    const registering = new WeakSet();
+    const registerControl = async (control) => {
+        if (registered.has(control) || registering.has(control))
+            return;
+        registering.add(control);
+        try {
+            const ready = await control.request({
+                type: 'machine.register',
+                machineId: machine,
+                workerId,
+                workerInstanceId,
+                anchorSessionIds: [...anchors.keys()],
+            });
+            registered.add(control);
+            await recoverAnchors();
+            for (const sessionId of ready.sessionIds || [])
+                void tryClaim(sessionId);
+        }
+        catch (error) {
+            process.stderr.write(`Queue registration failed: ${error?.message || error}\n`);
+        }
+        finally {
+            registering.delete(control);
+        }
+    };
+    rpc.onConnect((control) => {
+        void registerControl(control);
+    });
+    await registerControl(await rpc.current());
+    for (;;) {
+        await backgroundWait(MACHINE_HEARTBEAT_MS);
+        try {
+            await registerControl(await rpc.current());
+            const status = await request({ type: 'machine.heartbeat' }, MACHINE_HEARTBEAT_TIMEOUT_MS);
+            for (const sessionId of status.sessionIds || [])
+                void tryClaim(sessionId);
+        }
+        catch (error) {
+            process.stderr.write(`Machine heartbeat failed: ${error?.message || error}\n`);
+        }
+    }
+}