conductor-remote 1.117.0 → 1.118.0

package/dist-node/src/http/routes/prompts.js

@@ -0,0 +1,363 @@
+import { attachmentPrompt, writeAttachment } from "../../files/attachments.js";
+import { discardStagedAttachment, materializeStagedAttachments, stageAttachment } from "../../files/staged-attachments.js";
+import { captureForkWorkspace, materializeForkWorkspace, releaseForkWorkspace } from "../../git/fork-workspace.js";
+import { acceptDelegation, delegationHttpStatus } from "../../orchestration/delegation/intake.js";
+import { WorkflowCoordinatorError } from "../../orchestration/workflow/errors.js";
+import { routeParam, routes } from "../../routes.js";
+import { renderTranscript, transcriptMessage, transcriptThrough } from "../../transcript/parser.js";
+import { EFFORT_LABELS } from "../../writes/agent-options.js";
+import { lockBlocked } from "../../writes/guards.js";
+import { NOT_HANDLED } from "../router-types.js";
+export function createPromptsRoutes(services) {
+    const { orchestration, orchestrationUnavailableReason, readBody, json, workflowOwningSession, reads, roleStore, modelCache, delegationStore, delegationQueue, workflowFrozenError, sendBudget, sendOnce, firstPrompts, actuator, STAGED_ATTACHMENTS_DIR, applyAgentPatch, parkedPrompts, PARKED_ERROR, deliverPrompt, createWorkspaceAndRead, sleep, openChat } = services;
+    return async (req, res, url) => {
+        const { pathname } = url;
+        const delegateFrom = routeParam(routes.delegateTask, req.method, pathname);
+        if (delegateFrom) {
+            if (!orchestration.writable) {
+                throw new WorkflowCoordinatorError('workflow_incompatible_relay', orchestrationUnavailableReason(), {
+                    status: 409
+                });
+            }
+            let body;
+            try {
+                body = JSON.parse((await readBody(req)) || '{}');
+            }
+            catch {
+                return json(req, res, 400, {
+                    ok: false,
+                    error: { code: 'invalid_request', message: 'delegation must be valid JSON', retryable: false }
+                });
+            }
+            const result = acceptDelegation(delegateFrom, body, {
+                ownsSession: sessionId => workflowOwningSession(sessionId) !== null,
+                sessionWorkspaceId: sessionId => reads.sessionWorkspaceId(sessionId),
+                getSession: sessionId => reads.getSession(sessionId),
+                getWorkspace: workspaceId => reads.getWorkspace(workspaceId),
+                getMessages: sessionId => reads.getMessages(sessionId).entries,
+                readRoles: () => roleStore.read(),
+                models: () => modelCache.list(),
+                enqueue: (workspace, job) => {
+                    const store = delegationStore(workspace);
+                    if (!store)
+                        throw new Error('worktree path unresolved');
+                    delegationQueue.enqueue(store, job);
+                }
+            });
+            return json(req, res, result.ok ? 202 : delegationHttpStatus(result.error), result);
+        }
+        // POST /api/sessions/:id/prompt { text, agent? } — ordinary staged settings
+        // are applied before the prompt so the two cannot come apart.
+        const promptTo = routeParam(routes.sendPrompt, req.method, pathname);
+        if (promptTo) {
+            const sessionId = promptTo;
+            const body = JSON.parse((await readBody(req)) || '{}');
+            if ('workflow' in body) {
+                return json(req, res, 400, { error: 'Workflow starts through POST /api/workflows.' });
+            }
+            if (body.text !== undefined && typeof body.text !== 'string') {
+                return json(req, res, 400, { error: 'prompt must be a string' });
+            }
+            const rawText = (body.text ?? '').trim();
+            if (!rawText)
+                return json(req, res, 400, { error: 'empty prompt' });
+            if (body.agent !== undefined && (!body.agent || typeof body.agent !== 'object' || Array.isArray(body.agent))) {
+                return json(req, res, 400, { error: 'agent must be a settings object' });
+            }
+            const requestedAgent = body.agent && Object.keys(body.agent).length ? body.agent : undefined;
+            const frozen = workflowFrozenError(sessionId);
+            if (frozen &&
+                requestedAgent &&
+                (requestedAgent.model !== undefined || requestedAgent.effort !== undefined || requestedAgent.fast !== undefined)) {
+                return json(req, res, 409, frozen);
+            }
+            const ws = body.workspaceId
+                ? reads.getWorkspace(body.workspaceId)
+                : (reads.listWorkspaces().find(w => w.active_session_id === sessionId) ?? null);
+            if (!ws)
+                return json(req, res, 404, { error: 'workspace for session not found' });
+            // One deadline for the whole request: settings eat into the send's budget
+            // rather than extending it past what the phone said it would wait.
+            const deadline = Date.now() + sendBudget(req);
+            const queue = body.queue === true;
+            if (requestedAgent?.effort && !EFFORT_LABELS[requestedAgent.effort]) {
+                return json(req, res, 400, { error: `effort must be one of ${Object.keys(EFFORT_LABELS).join(', ')}` });
+            }
+            // One prompt per intent (src/delivery/sendonce.ts). Everything that can *say something
+            // to Conductor* sits inside, so an answer the phone never heard is replayed
+            // rather than re-performed — including the parked branches, since parking the
+            // same intent twice queues the same prompt twice for the unlock.
+            if (body.clientId && sendOnce.recall(body.clientId)) {
+                console.info(`[relay] send to ${ws.branch ?? ws.id} already delivered for this tap — answering, not resending`);
+            }
+            const answer = await sendOnce.run(body.clientId, async () => {
+                const text = rawText;
+                const agent = requestedAgent;
+                // A failed first-prompt entry offers the same Retry button as an ordinary
+                // prompt. If staging had been the failure, put its files in place before
+                // that retry reaches the attachment tokens.
+                const first = firstPrompts.get(ws.id);
+                if (first?.attachmentIds?.length && first.text === text) {
+                    if (!ws.worktree)
+                        return {
+                            status: 409,
+                            body: { ok: false, strategy: actuator.name, error: 'worktree path unresolved' }
+                        };
+                    try {
+                        materializeStagedAttachments(STAGED_ATTACHMENTS_DIR, ws.worktree, first.attachmentIds);
+                    }
+                    catch (err) {
+                        return {
+                            status: 409,
+                            body: {
+                                ok: false,
+                                strategy: actuator.name,
+                                error: err instanceof Error ? err.message : 'the attached files could not be copied'
+                            }
+                        };
+                    }
+                }
+                if (agent) {
+                    const applied = await applyAgentPatch(ws, sessionId, agent);
+                    if (!applied.ok) {
+                        if (lockBlocked(applied.error)) {
+                            const queued = parkedPrompts.park(ws.id, sessionId, text, agent, queue);
+                            return {
+                                status: 202,
+                                body: { ok: false, parked: true, queued, strategy: actuator.name, error: PARKED_ERROR }
+                            };
+                        }
+                        return { status: 502, body: { ok: false, strategy: actuator.name, error: applied.error } };
+                    }
+                }
+                // Retries live inside deliverPrompt, confirmed against the transcript each time,
+                // and inside the deadline this phone told us it would wait.
+                const result = await deliverPrompt(ws, sessionId, text, deadline - Date.now(), queue);
+                if (result.ok) {
+                    // Whatever a queue was still holding has now been said by hand — the first
+                    // prompt (including a failed entry retried from the chat), and any parked
+                    // copy of this exact text, which delivering again would double.
+                    firstPrompts.forget(ws.id);
+                    parkedPrompts.forgetDelivered(sessionId, text);
+                    return { status: 200, body: result };
+                }
+                if (lockBlocked(result.error)) {
+                    // Settings (if any) already stuck, so the entry parks without them.
+                    const queued = parkedPrompts.park(ws.id, sessionId, text, undefined, queue);
+                    return {
+                        status: 202,
+                        body: { ok: false, parked: true, queued, strategy: result.strategy, error: PARKED_ERROR }
+                    };
+                }
+                return { status: 502, body: result };
+            });
+            return json(req, res, answer.status, answer.body);
+        }
+        // POST /api/sessions/:id/split
+        //      { prompt?, includeThinking?, includeTools?, throughRowid?, onlyRowid?, destination? }
+        //
+        // Conductor's own tab fork resumes the agent's real session. This copies the
+        // conversation instead, as a Conductor attachment, which is the cut that survives
+        // being read by a *different* agent: prose and reasoning, no tool churn. Its
+        // destination can be another tab over the same files, or a new workspace whose
+        // Git layers are restored from the source's current worktree snapshot.
+        // Two reasons it exists at all. A tangent asked inside a running chat leaves three
+        // conversations interleaved in one tab, which reads badly for everyone afterwards;
+        // and Conductor's fork lives on a hover menu over one message, which an agent
+        // cannot reach and which the relay would have to find by walking a transcript that
+        // gets more expensive the longer the chat is.
+        //
+        // It stops before sending. The composed prompt goes out through the ordinary send
+        // route so it inherits the retry loop, the transcript confirm and the parked queue.
+        // For a tab, that also keeps ⌘T plus a send from becoming two UI turns inside one
+        // request (28s + 55s against the MCP client's 75s); for a workspace it leaves the
+        // staged handoff as the same editable draft the phone already presents for a tab.
+        const splitFrom = routeParam(routes.splitChat, req.method, pathname);
+        if (splitFrom) {
+            const sessionId = splitFrom;
+            const body = JSON.parse((await readBody(req)) || '{}');
+            // `active_session_id` is how every other route resolves this, and it would only
+            // ever find the tab on screen. Splitting a chat you are not looking at is the
+            // normal case here, so the session's own column decides.
+            const workspaceId = body.workspaceId ?? reads.sessionWorkspaceId(sessionId);
+            const ws = workspaceId ? reads.getWorkspace(workspaceId) : null;
+            if (!ws)
+                return json(req, res, 404, { error: 'workspace for session not found' });
+            if (!ws.worktree)
+                return json(req, res, 409, { error: 'worktree path unresolved' });
+            const source = reads.listSessions(ws.id).find(s => s.id === sessionId);
+            if (!source)
+                return json(req, res, 404, { error: 'chat not found in that workspace' });
+            const destination = body.destination ?? 'chat';
+            if (destination !== 'chat' && destination !== 'workspace') {
+                return json(req, res, 400, { error: 'destination must be chat or workspace' });
+            }
+            const format = { thinking: body.includeThinking !== false, tools: body.includeTools === true };
+            const { entries } = reads.getMessages(sessionId);
+            const through = body.throughRowid;
+            const only = body.onlyRowid;
+            if (through !== undefined && (!Number.isSafeInteger(through) || through < 1)) {
+                return json(req, res, 400, { error: 'throughRowid must be a positive integer' });
+            }
+            if (only !== undefined && (!Number.isSafeInteger(only) || only < 1)) {
+                return json(req, res, 400, { error: 'onlyRowid must be a positive integer' });
+            }
+            if (through !== undefined && only !== undefined) {
+                return json(req, res, 400, { error: 'throughRowid and onlyRowid cannot be combined' });
+            }
+            const cut = only !== undefined
+                ? transcriptMessage(entries, only)
+                : through === undefined
+                    ? { entries, earlier: 0, later: 0 }
+                    : transcriptThrough(entries, through);
+            if (!cut)
+                return json(req, res, 409, { error: 'that message is not in this chat' });
+            const rendered = renderTranscript(cut.entries, format);
+            const elided = { ...rendered.elided, earlier: 'earlier' in cut ? cut.earlier : 0, later: cut.later };
+            if (!rendered.kept)
+                return json(req, res, 409, { error: 'that chat has nothing to copy yet' });
+            // Conductor's own name for a copied transcript, so the chip reads the same as one
+            // saved by hand. The header states the cut, because a transcript that silently
+            // drops half a chat is worse than one that admits to it.
+            const title = source.title?.trim() || 'chat';
+            const carried = [`thinking ${format.thinking ? 'included' : 'omitted'}`];
+            carried.push(`tool calls ${format.tools ? 'included' : 'omitted'}`);
+            const stops = only !== undefined
+                ? ['The copy contains only the selected source message; all earlier and later messages are omitted.']
+                : cut.later
+                    ? [
+                        `The copy stops partway through: ${cut.later} later ${cut.later === 1 ? 'entry is' : 'entries are'} not in it.`
+                    ]
+                    : [];
+            const header = [
+                `# Transcript of ${title}`,
+                '',
+                `${[ws.repo_name, ws.branch].filter(Boolean).join(' · ')}`,
+                `Copied from the Conductor chat \`${sessionId}\` by conductor-remote. ${carried.join(', ')}.`,
+                ...stops,
+                '',
+                ''
+            ].join('\n');
+            const transcript = header + rendered.text;
+            if (destination === 'workspace') {
+                if (!(ws.repo_name && ws.repo_root)) {
+                    return json(req, res, 409, { error: 'the source workspace has no repository checkout to fork' });
+                }
+                let snapshot;
+                try {
+                    snapshot = await captureForkWorkspace(ws.worktree);
+                }
+                catch (err) {
+                    const reason = err instanceof Error ? err.message : 'Git could not capture the worktree';
+                    return json(req, res, 502, { error: `Could not snapshot the source workspace: ${reason}` });
+                }
+                let staged;
+                let materialized = false;
+                let created;
+                try {
+                    staged = stageAttachment(STAGED_ATTACHMENTS_DIR, `Transcript of ${title}.md`, Buffer.from(transcript));
+                    const creation = await createWorkspaceAndRead('', ws.repo_root, ws.repo_name);
+                    if (!creation.result.ok)
+                        return json(req, res, 502, creation.result);
+                    created = creation.created;
+                    if (!created) {
+                        return json(req, res, 502, {
+                            error: 'Conductor didn’t create the fork workspace — check it’s running and not showing a dialog.'
+                        });
+                    }
+                    // The DB row can precede `.git` by a tick. Install the snapshot at the
+                    // first verified worktree path, before Conductor starts the new agent.
+                    let target = reads.getWorkspace(created.id) ?? created;
+                    for (let attempt = 0; attempt < 20 && !target.worktree; attempt++) {
+                        await sleep(250);
+                        target = reads.getWorkspace(created.id) ?? target;
+                    }
+                    if (!target.worktree)
+                        throw new Error('the new workspace worktree path never became available');
+                    await materializeForkWorkspace(snapshot, target.worktree);
+                    materializeStagedAttachments(STAGED_ATTACHMENTS_DIR, target.worktree, [staged.stageId]);
+                    materialized = true;
+                    discardStagedAttachment(STAGED_ATTACHMENTS_DIR, staged.stageId);
+                    let destinationSession = reads.listSessions(created.id)[0];
+                    for (let attempt = 0; attempt < 12 && !destinationSession; attempt++) {
+                        await sleep(250);
+                        destinationSession = reads.listSessions(created.id)[0];
+                    }
+                    return json(req, res, 200, {
+                        ok: true,
+                        destination,
+                        sessionId: destinationSession?.id ?? null,
+                        workspaceId: created.id,
+                        text: attachmentPrompt(staged.token, body.prompt),
+                        attachment: {
+                            name: staged.name,
+                            path: staged.path,
+                            bytes: staged.bytes,
+                            kept: rendered.kept,
+                            elided
+                        }
+                    });
+                }
+                catch (err) {
+                    const reason = err instanceof Error ? err.message : 'the current files could not be copied';
+                    return json(req, res, 502, {
+                        error: created
+                            ? `Workspace ${created.id} was created, but its code fork failed: ${reason}`
+                            : `Could not create the code fork: ${reason}`
+                    });
+                }
+                finally {
+                    if (staged && !materialized)
+                        discardStagedAttachment(STAGED_ATTACHMENTS_DIR, staged.stageId);
+                    await releaseForkWorkspace(snapshot).catch(err => {
+                        console.warn(`[relay] could not release fork snapshot ${snapshot.ref}: ${err instanceof Error ? err.message : err}`);
+                    });
+                }
+            }
+            const attachment = writeAttachment(ws.worktree, `Transcript of ${title}.md`, transcript);
+            const opened = await openChat(ws);
+            if ('error' in opened) {
+                return json(req, res, 502, {
+                    ...opened.result,
+                    destination,
+                    attachment: { ...attachment, ...rendered, elided }
+                });
+            }
+            // The token is what Conductor turns into the attachment chip and supplies to the
+            // receiving agent. Do not repeat `attachment.relPath` in prose: that renders a
+            // second link to the same transcript in the new chat.
+            const text = attachmentPrompt(attachment.token, body.prompt);
+            return json(req, res, 200, {
+                ok: true,
+                destination,
+                sessionId: opened.sessionId,
+                workspaceId: ws.id,
+                text,
+                attachment: {
+                    name: attachment.name,
+                    path: attachment.relPath,
+                    bytes: attachment.bytes,
+                    kept: rendered.kept,
+                    elided
+                }
+            });
+        }
+        // DELETE /api/workspaces/:id/prompt — dismiss an undelivered first prompt
+        const forgetFirst = routeParam(routes.dismissFirstPrompt, req.method, pathname);
+        if (forgetFirst) {
+            const workspaceId = forgetFirst;
+            if (!firstPrompts.forget(workspaceId))
+                return json(req, res, 404, { error: 'no pending prompt' });
+            return json(req, res, 200, { ok: true });
+        }
+        // DELETE /api/sessions/:id/prompt — dismiss whatever is parked for this chat
+        const forgetParked = routeParam(routes.dismissParkedPrompt, req.method, pathname);
+        if (forgetParked) {
+            const sessionId = forgetParked;
+            if (!parkedPrompts.forgetSession(sessionId))
+                return json(req, res, 404, { error: 'no parked prompt' });
+            return json(req, res, 200, { ok: true });
+        }
+        return NOT_HANDLED;
+    };
+}

package/dist-node/src/http/routes/sessions.js

@@ -0,0 +1,279 @@
+import { writeAttachment } from "../../files/attachments.js";
+import { noteViewing } from "../../notifications/notify.js";
+import { routeParam, routes } from "../../routes.js";
+import { VIEWING_HEADER } from "../../shared.js";
+import { EFFORT_LABELS, listAgentModels, setDefaultModel } from "../../writes/agent-options.js";
+import { closeChat, restoreChat, stopTurn } from "../../writes/chats.js";
+import { NOT_HANDLED } from "../router-types.js";
+export function createSessionsRoutes(services) {
+    const { json, reads, workflowFrozenError, locateChat, modelCache, readBody, applyAgentPatch, actuator, sleep, attachmentHeaderName, readAttachmentBody } = services;
+    return async (req, res, url) => {
+        const { pathname } = url;
+        // GET /api/sessions/:id/messages?after=<rowid>
+        const messagesOf = routeParam(routes.messages, req.method, pathname);
+        if (messagesOf) {
+            // The phone's 1s transcript poll doubles as its "I am reading this chat" heartbeat,
+            // which is what keeps a turn ending on screen from also buzzing the lock screen
+            // (src/notifications/notify.ts). Only this route is a claim: it is the one read that runs for the
+            // chat on screen and for no other.
+            const device = req.headers[VIEWING_HEADER];
+            if (typeof device === 'string' && device)
+                noteViewing(device, messagesOf);
+            const after = Number(url.searchParams.get('after') ?? 0);
+            return json(req, res, 200, reads.getMessages(messagesOf, Number.isFinite(after) ? after : 0));
+        }
+        // GET /api/sessions/:id/context — expensive enough to stay off the session poll.
+        const contextOf = routeParam(routes.context, req.method, pathname);
+        if (contextOf) {
+            const breakdown = reads.getContextBreakdown(contextOf);
+            if (!breakdown)
+                return json(req, res, 404, { error: 'chat not found' });
+            return json(req, res, 200, breakdown);
+        }
+        // GET /api/sessions/:id/models?workspaceId= — labels from Conductor's live picker
+        const modelsOf = routeParam(routes.models, req.method, pathname);
+        if (modelsOf) {
+            const sessionId = modelsOf;
+            const frozen = workflowFrozenError(sessionId);
+            if (frozen)
+                return json(req, res, 409, frozen);
+            const ws = reads.getWorkspace(url.searchParams.get('workspaceId') ?? '');
+            if (!ws)
+                return json(req, res, 404, { error: 'workspace for session not found' });
+            const located = locateChat(ws, sessionId);
+            if ('error' in located)
+                return json(req, res, 409, { error: located.error });
+            const result = await listAgentModels({ workspace: ws, sessionId, tab: located.tab });
+            if (result.ok && result.models)
+                modelCache.remember(located.session?.agent_type, result.models, result.defaultModel);
+            return json(req, res, result.ok ? 200 : 502, result);
+        }
+        // POST /api/sessions/:id/default-model { model, workspaceId? }
+        // The picker star is a combined "set default and select" action, so this
+        // changes both the user-wide default and this chat's model exactly as the
+        // desktop control does.
+        const defaultModelOf = routeParam(routes.defaultModel, req.method, pathname);
+        if (defaultModelOf) {
+            const sessionId = defaultModelOf;
+            const frozen = workflowFrozenError(sessionId);
+            if (frozen)
+                return json(req, res, 409, frozen);
+            const body = JSON.parse((await readBody(req)) || '{}');
+            if (typeof body.model !== 'string' || !body.model.trim()) {
+                return json(req, res, 400, { error: 'model must be a picker label' });
+            }
+            const ws = typeof body.workspaceId === 'string'
+                ? reads.getWorkspace(body.workspaceId)
+                : (reads.listWorkspaces().find(w => w.active_session_id === sessionId) ?? null);
+            if (!ws)
+                return json(req, res, 404, { error: 'workspace for session not found' });
+            const located = locateChat(ws, sessionId);
+            if ('error' in located)
+                return json(req, res, 409, { error: located.error });
+            const result = await setDefaultModel({ workspace: ws, sessionId, tab: located.tab }, body.model.trim());
+            if (!result.ok || !result.model) {
+                return json(req, res, 502, { ok: false, error: result.error ?? 'the default model did not change' });
+            }
+            const session = reads.listSessions(ws.id).find(row => row.id === sessionId);
+            modelCache.rememberModel(session?.agent_type, result.model);
+            modelCache.rememberDefault(result.model);
+            return json(req, res, 200, { ok: true, defaultModel: result.model, session });
+        }
+        // POST /api/sessions/:id/agent  { effort?, plan?, fast?, model? }
+        // Drives the composer's own model/effort/plan/fast controls for one chat.
+        const agentOf = routeParam(routes.agent, req.method, pathname);
+        if (agentOf) {
+            const sessionId = agentOf;
+            const body = JSON.parse((await readBody(req)) || '{}');
+            if (body.effort && !EFFORT_LABELS[body.effort]) {
+                return json(req, res, 400, { error: `effort must be one of ${Object.keys(EFFORT_LABELS).join(', ')}` });
+            }
+            const frozen = workflowFrozenError(sessionId);
+            if (frozen && (body.model !== undefined || body.effort !== undefined || body.fast !== undefined)) {
+                return json(req, res, 409, frozen);
+            }
+            const ws = body.workspaceId
+                ? reads.getWorkspace(body.workspaceId)
+                : (reads.listWorkspaces().find(w => w.active_session_id === sessionId) ?? null);
+            if (!ws)
+                return json(req, res, 404, { error: 'workspace for session not found' });
+            const applied = await applyAgentPatch(ws, sessionId, body);
+            if (!applied.ok)
+                return json(req, res, 502, { ok: false, strategy: actuator.name, error: applied.error });
+            return json(req, res, 200, { ok: true, session: reads.listSessions(ws.id).find(s => s.id === sessionId) });
+        }
+        // POST /api/sessions/:id/stop — the desktop app's stop button, for one chat.
+        const stopOf = routeParam(routes.stop, req.method, pathname);
+        if (stopOf) {
+            const sessionId = stopOf;
+            const body = JSON.parse((await readBody(req)) || '{}');
+            const ws = body.workspaceId
+                ? reads.getWorkspace(body.workspaceId)
+                : (reads.listWorkspaces().find(w => w.active_session_id === sessionId) ?? null);
+            if (!ws)
+                return json(req, res, 404, { error: 'workspace for session not found' });
+            const located = locateChat(ws, sessionId);
+            if ('error' in located)
+                return json(req, res, 409, { error: located.error });
+            // Nothing running is a success, not an error: the phone shows Stop the moment it
+            // sends (the optimistic hint) and a turn that ends on its own a beat before the tap
+            // is the common case, not a mistake worth a red banner. It also keeps the one
+            // keystroke this route presses off an idle chat entirely — Conductor's own
+            // composer has no stop button to mis-tap there either.
+            const before = reads.listSessions(ws.id).find(s => s.id === sessionId);
+            if (before?.status !== 'working') {
+                return json(req, res, 200, { ok: true, alreadyIdle: true, session: before });
+            }
+            const result = await stopTurn({ workspace: ws, sessionId, tab: located.tab });
+            if (!result.ok)
+                return json(req, res, 502, result);
+            // The DB is the receipt, exactly as it is for agent settings: the keystroke is
+            // fire-and-forget, so what counts is `status` leaving `working`. Conductor writes
+            // that a beat after it tears the turn down.
+            let observed = before.status;
+            for (let i = 0; i < 20 && observed === 'working'; i++) {
+                await sleep(300);
+                observed = reads.listSessions(ws.id).find(s => s.id === sessionId)?.status ?? observed;
+            }
+            if (observed === 'working') {
+                return json(req, res, 502, {
+                    ok: false,
+                    strategy: result.strategy,
+                    error: 'Conductor took the stop but the agent is still working. Try again, or stop it on your Mac.'
+                });
+            }
+            return json(req, res, 200, {
+                ok: true,
+                strategy: result.strategy,
+                session: reads.listSessions(ws.id).find(s => s.id === sessionId)
+            });
+        }
+        const restoreChatId = routeParam(routes.restoreChat, req.method, pathname);
+        if (restoreChatId) {
+            const body = JSON.parse((await readBody(req)) || '{}');
+            const ownerId = reads.sessionWorkspaceId(restoreChatId);
+            if (!ownerId)
+                return json(req, res, 404, { error: 'chat not found' });
+            if (body.workspaceId && body.workspaceId !== ownerId) {
+                return json(req, res, 409, { error: 'chat is not in that workspace' });
+            }
+            if (!reads.getWorkspace(ownerId)) {
+                return json(req, res, 409, { error: 'Restore this workspace in Conductor before restoring its tabs.' });
+            }
+            const result = await restoreChat(ownerId, restoreChatId, () => reads.getSession(restoreChatId) !== null);
+            if (!result.ok)
+                return json(req, res, 502, result);
+            return json(req, res, 200, { ...result, session: reads.getSession(restoreChatId) });
+        }
+        // DELETE /api/sessions/:id { workspaceId?, closeRunning? } — Conductor's
+        // reversible Close tab action (Command-W). A running chat gets the same
+        // explicit "Close anyway" gate as the desktop app.
+        const closeChatId = routeParam(routes.closeChat, req.method, pathname);
+        if (closeChatId) {
+            const sessionId = closeChatId;
+            const body = JSON.parse((await readBody(req)) || '{}');
+            const ownerId = reads.sessionWorkspaceId(sessionId);
+            if (!ownerId)
+                return json(req, res, 404, { error: 'chat not found' });
+            if (body.workspaceId && body.workspaceId !== ownerId) {
+                return json(req, res, 409, { error: 'chat is not in that workspace' });
+            }
+            const ws = reads.getWorkspace(ownerId);
+            if (!ws)
+                return json(req, res, 404, { error: 'workspace for session not found' });
+            const before = reads.listSessions(ws.id);
+            const session = before.find(s => s.id === sessionId);
+            const visibleActiveSession = () => {
+                const visible = reads.listSessions(ws.id);
+                const activeId = reads.getWorkspace(ws.id)?.active_session_id;
+                return visible.some(s => s.id === activeId) ? (activeId ?? null) : (visible[0]?.id ?? null);
+            };
+            // Closing is a soft delete. A repeat whose first response was lost is already
+            // in the requested state, so it is success rather than a stale-link error.
+            if (!session) {
+                return json(req, res, 200, {
+                    ok: true,
+                    alreadyClosed: true,
+                    activeSessionId: visibleActiveSession()
+                });
+            }
+            if ((session.status === 'working' || session.background_tasks.length > 0) && body.closeRunning !== true) {
+                return json(req, res, 409, {
+                    ok: false,
+                    agentRunning: true,
+                    error: 'The agent is still working in this chat. Confirm closing it anyway.'
+                });
+            }
+            const located = locateChat(ws, sessionId);
+            if ('error' in located)
+                return json(req, res, 409, { error: located.error });
+            const result = await closeChat({ workspace: ws, sessionId, tab: located.tab }, body.closeRunning === true);
+            if (!result.ok) {
+                // A turn can start after the status read above. The script dismisses
+                // Conductor's surprise dialog instead of accepting it, and this sends the
+                // caller back through the same explicit confirmation path.
+                if (body.closeRunning !== true && result.error?.includes('needs confirmation')) {
+                    return json(req, res, 409, {
+                        ok: false,
+                        agentRunning: true,
+                        error: 'The agent is still working in this chat. Confirm closing it anyway.'
+                    });
+                }
+                return json(req, res, 502, result);
+            }
+            // Command-W is fire-and-forget. The durable receipt is the same flag all tab
+            // reads filter on: this id disappearing from listSessions means Conductor set
+            // sessions.is_hidden, not merely that a keystroke happened.
+            let visible = true;
+            for (let i = 0; i < 20 && visible; i++) {
+                await sleep(300);
+                visible = reads.listSessions(ws.id).some(s => s.id === sessionId);
+            }
+            if (visible) {
+                return json(req, res, 502, {
+                    ok: false,
+                    strategy: result.strategy,
+                    error: 'Conductor took the close but the chat tab is still open. Try again, or close it on your Mac.'
+                });
+            }
+            return json(req, res, 200, {
+                ok: true,
+                strategy: result.strategy,
+                activeSessionId: visibleActiveSession()
+            });
+        }
+        // POST /api/sessions/:id/attachments?workspaceId= — raw bytes from the phone.
+        // Conductor derives an attachment from this on-disk layout plus the composer
+        // token, so its own database stays read-only from this relay's point of view.
+        const uploadTo = routeParam(routes.uploadAttachment, req.method, pathname);
+        if (uploadTo) {
+            const sessionId = uploadTo;
+            const ownerId = reads.sessionWorkspaceId(sessionId);
+            const workspaceId = url.searchParams.get('workspaceId') ?? ownerId;
+            const ws = workspaceId ? reads.getWorkspace(workspaceId) : null;
+            if (!ws)
+                return json(req, res, 404, { error: 'workspace for session not found' });
+            if (!ownerId || ownerId !== ws.id)
+                return json(req, res, 409, { error: 'chat is not in that workspace' });
+            if (!ws.worktree)
+                return json(req, res, 409, { error: 'worktree path unresolved' });
+            const name = attachmentHeaderName(req);
+            if (!name)
+                return json(req, res, 400, { error: 'missing attachment name' });
+            const bytes = await readAttachmentBody(req);
+            if (!bytes.length)
+                return json(req, res, 400, { error: 'empty attachment' });
+            const attachment = writeAttachment(ws.worktree, name, bytes);
+            return json(req, res, 200, {
+                ok: true,
+                attachment: {
+                    name: attachment.name,
+                    path: attachment.relPath,
+                    bytes: attachment.bytes,
+                    token: attachment.token
+                }
+            });
+        }
+        return NOT_HANDLED;
+    };
+}