conductor-remote 1.42.3 → 1.44.0

package/dist-node/src/mcp-tools.js

@@ -1,10 +1,17 @@
 /**
- * The ten MCP tools, and the JSON-RPC dispatcher that serves them.
+ * The MCP tools, and the JSON-RPC dispatcher that serves them.
  *
  * Shared by both transports, which is the only reason they can't drift: `src/mcp.ts`
  * runs this over stdio as a separate process, and `src/server.ts` mounts the same
  * dispatcher at `POST /mcp` for clients that can only reach a URL.
  *
+ * The tool set tracks `/api`, minus the routes that only exist to back a button on the
+ * phone. An agent needs no `merge` (it holds `gh`, and `send_prompt` can ask the agent
+ * that owns the branch), no push subscription, and no settings editor. What it does need
+ * is everything it cannot reach any other way: the model/effort/plan/fast controls, which
+ * live in Conductor's UI and nowhere else, the prompts the relay is holding on its behalf,
+ * the sleep window that keeps this Mac reachable at all, and the relay's own log.
+ *
  * Every tool is an HTTP call to the relay, injected as `call`, and that is the
  * load-bearing decision rather than a convenience. Conductor has one shared window,
  * so the only thing that makes writes safe is `writes.ts` ▸ `uiTurn`, and that lock is
@@ -18,11 +25,12 @@
  * router it would otherwise have to be carved out of, and it keeps *one* code path:
  * a tool cannot behave differently over HTTP than it does over stdio.
  */
+import { routes } from "./routes.js";
 import { HIT_CLOSE, HIT_OPEN, workspaceTitle } from "./shared.js";
 /** Versions we know how to speak. The client's choice wins when we know it. */
 export const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
 export const SERVER_INFO = { name: 'conductor-remote', version: '1' };
-export const INSTRUCTIONS = 'Drives local Conductor agents through the conductor-remote relay. search_chats and read_chat reach archived workspaces, which is where most finished work lives. create_workspace touches no UI. send_prompt, stop_turn and set_workspace_status drive the real Mac UI and steal focus for a few seconds — confirm with the user before using them on a chat they did not name.';
+export const INSTRUCTIONS = 'Drives local Conductor agents through the conductor-remote relay. search_chats and read_chat reach archived workspaces, which is where most finished work lives. create_workspace, dismiss_prompt, keep_awake and relay_logs touch no UI. send_prompt, split_chat, stop_turn, set_agent_options, list_models and set_workspace_status drive the real Mac UI and steal focus for a few seconds — confirm with the user before using them on a chat they did not name.';
 /** Reads are quick; a UI write is measured in tens of seconds (writes.ts ▸ SEND_ATTEMPT_MS). */
 export const READ_TIMEOUT_MS = 10_000;
 export const WRITE_TIMEOUT_MS = 75_000;
@@ -36,6 +44,24 @@ function unmark(text) {
 function clip(text, max) {
     return text.length > max ? `${text.slice(0, max)}… [${text.length - max} more chars]` : text;
 }
+function plural(n, one, many = `${one}s`) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+/** Wall-clock stamp for a log line. Null on continuation lines the file parser couldn't date. */
+function stamp(t) {
+    if (t === null)
+        return '        ';
+    const d = new Date(t);
+    const p = (n) => String(n).padStart(2, '0');
+    return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+/** "in 42m" / "38m ago" — an absolute epoch is unreadable, and an agent's clock may differ. */
+function relative(at) {
+    const mins = Math.round((at - Date.now()) / 60_000);
+    if (mins > 0)
+        return `in ${mins}m`;
+    return mins < 0 ? `${-mins}m ago` : 'now';
+}
 const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
 const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);
 function need(args, key) {
@@ -61,7 +87,7 @@ export function createTools(call) {
             run: async (args) => {
                 const query = need(args, 'query');
                 const limit = num(args.limit);
-                const data = await call(`/api/search?q=${encodeURIComponent(query)}${limit ? `&limit=${limit}` : ''}`);
+                const data = await call(`${routes.search.path()}?q=${encodeURIComponent(query)}${limit ? `&limit=${limit}` : ''}`);
                 const lines = [];
                 if (data.index.error)
                     lines.push(`! chat index unavailable (${data.index.error}) — names matched only`);
@@ -92,20 +118,26 @@ export function createTools(call) {
                 properties: {
                     session_id: { type: 'string', description: 'From search_chats or list_chats.' },
                     limit: { type: 'number', description: 'How many trailing entries to return (default 40, max 400).' },
-                    include_tools: { type: 'boolean', description: 'Include tool-call and thinking rows (default false).' }
+                    include_thinking: { type: 'boolean', description: 'Include the agent’s reasoning (default false).' },
+                    include_tools: {
+                        type: 'boolean',
+                        description: 'Include tool calls and failed tool output (default false).'
+                    }
                 },
                 required: ['session_id']
             },
             run: async (args) => {
                 const sessionId = need(args, 'session_id');
                 const limit = Math.min(400, Math.max(1, num(args.limit) ?? 40));
+                // One flag each, because they answer different questions: tools are what the agent
+                // *did*, thinking is why it did it. Reading both off `include_tools` meant the only
+                // way to see the reasoning was to take the tool churn along with it.
                 const includeTools = args.include_tools === true;
-                const data = await call(`/api/sessions/${encodeURIComponent(sessionId)}/messages?after=0`, {
+                const includeThinking = args.include_thinking === true;
+                const data = await call(`${routes.messages.path(sessionId)}?after=0`, {
                     timeoutMs: 30_000
                 });
-                const wanted = includeTools
-                    ? data.entries
-                    : data.entries.filter(e => e.role === 'user' || e.role === 'assistant');
+                const wanted = data.entries.filter(e => e.role === 'thinking' ? includeThinking : e.role === 'tool' ? includeTools : true);
                 if (!wanted.length)
                     return `no messages in session ${sessionId}`;
                 const tail = wanted.slice(-limit);
@@ -122,7 +154,7 @@ export function createTools(call) {
         },
         {
             name: 'list_workspaces',
-            description: 'List the live (non-archived) Conductor workspaces with what each one is doing right now: agent status, model, branch, PR state. Use this to see what is running before starting or steering anything.',
+            description: 'List the live (non-archived) Conductor workspaces with what each one is doing right now: agent status, model, branch, PR state, and any prompt the relay is still holding for it. Use this to see what is running before starting or steering anything.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -134,16 +166,29 @@ export function createTools(call) {
             },
             run: async (args) => {
                 const status = str(args.status);
-                const data = await call('/api/state');
+                const data = await call(routes.state.path());
                 const shown = status ? data.workspaces.filter(w => w.session_status === status) : data.workspaces;
                 if (!shown.length)
                     return status ? `no workspace is ${status}` : 'no live workspaces';
                 return shown
-                    .map(w => [
-                    `${w.session_status === 'working' ? '▶' : '·'} ${workspaceTitle(w)}`,
-                    `    ${[w.repo_name, w.branch, w.model, w.pr_number ? `PR #${w.pr_number} ${w.pr_status ?? ''}`.trim() : null].filter(Boolean).join(' · ')}`,
-                    `    workspace_id: ${w.id}${w.active_session_id ? `  session_id: ${w.active_session_id}` : ''}`
-                ].join('\n'))
+                    .map(w => {
+                    const lines = [
+                        `${w.session_status === 'working' ? '▶' : '·'} ${workspaceTitle(w)}`,
+                        `    ${[w.repo_name, w.branch, w.model, w.pr_number ? `PR #${w.pr_number} ${w.pr_status ?? ''}`.trim() : null].filter(Boolean).join(' · ')}`,
+                        `    workspace_id: ${w.id}${w.active_session_id ? `  session_id: ${w.active_session_id}` : ''}`
+                    ];
+                    // An undelivered prompt is invisible from the DB — it lives in the relay's own
+                    // queues — so an agent reading only status would call a stalled workspace idle
+                    // and send a second copy of the prompt already waiting on it (dismiss_prompt).
+                    if (w.pending_prompt) {
+                        const p = w.pending_prompt;
+                        lines.push(`    ! first prompt ${p.status}: ${clip(unmark(p.text), 120)}${p.error ? ` — ${p.error}` : ''}`);
+                    }
+                    for (const p of w.parked_prompts ?? []) {
+                        lines.push(`    ! prompt ${p.status} for session ${p.sessionId} (${p.reason}): ${clip(unmark(p.text), 120)}`);
+                    }
+                    return lines.join('\n');
+                })
                     .join('\n');
             }
         },
@@ -157,7 +202,7 @@ export function createTools(call) {
             },
             run: async (args) => {
                 const id = need(args, 'workspace_id');
-                const data = await call(`/api/workspaces/${encodeURIComponent(id)}/sessions`);
+                const data = await call(routes.sessions.path(id));
                 if (!data.sessions.length)
                     return `no chats in workspace ${id}`;
                 return data.sessions
@@ -175,7 +220,7 @@ export function createTools(call) {
             },
             run: async (args) => {
                 const id = need(args, 'workspace_id');
-                const data = await call(`/api/workspaces/${encodeURIComponent(id)}/diff`, {
+                const data = await call(routes.diff.path(id), {
                     timeoutMs: 30_000
                 });
                 if (!data.files.length)
@@ -188,7 +233,7 @@ export function createTools(call) {
             description: 'The repos Conductor can create a workspace in. Use before create_workspace to get an exact repo name.',
             inputSchema: { type: 'object', properties: {} },
             run: async () => {
-                const data = await call('/api/repos');
+                const data = await call(routes.repos.path());
                 return data.repos.map(r => `${r.name}  (${r.default_branch ?? '?'})  ${r.root_path ?? ''}`).join('\n');
             }
         },
@@ -211,8 +256,8 @@ export function createTools(call) {
                 const repo = need(args, 'repo');
                 const prompt = str(args.prompt);
                 const send = args.wait_for_send === true;
-                const data = await call('/api/workspaces', {
-                    method: 'POST',
+                const data = await call(routes.createWorkspace.path(), {
+                    method: routes.createWorkspace.method,
                     body: { repo, prompt, send },
                     timeoutMs: send ? WRITE_TIMEOUT_MS : 30_000
                 });
@@ -247,8 +292,8 @@ export function createTools(call) {
             run: async (args) => {
                 const sessionId = need(args, 'session_id');
                 const text = need(args, 'text');
-                const data = await call(`/api/sessions/${encodeURIComponent(sessionId)}/prompt`, {
-                    method: 'POST',
+                const data = await call(routes.sendPrompt.path(sessionId), {
+                    method: routes.sendPrompt.method,
                     body: { text, workspaceId: str(args.workspace_id) },
                     timeoutMs: WRITE_TIMEOUT_MS
                 });
@@ -259,6 +304,73 @@ export function createTools(call) {
                 return data.warning ? `sent (${data.warning})` : 'sent';
             }
         },
+        {
+            name: 'split_chat',
+            description: 'Move a tangent out of a chat: copy that chat into a fresh tab beside it, as a Conductor attachment, and ask the new agent your question there. Use it when a conversation has grown a second topic — a running agent steered mid-turn ends up holding three threads at once, which reads badly for everyone afterwards. The copy carries the prose and the reasoning, not the tool calls, so the new agent knows what was said and decided but not every file that was read. This DRIVES THE REAL UI twice (a new tab, then the send) and steals focus for a few seconds. To split the chat you are in, find its session_id with list_chats on your own workspace.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    session_id: { type: 'string', description: 'The chat to copy (list_chats / search_chats).' },
+                    prompt: { type: 'string', description: 'What to ask in the new tab.' },
+                    workspace_id: { type: 'string', description: 'Its workspace. Resolved from the chat when omitted.' },
+                    include_thinking: {
+                        type: 'boolean',
+                        description: 'Carry the agent’s reasoning across (default true — it is usually the useful half).'
+                    },
+                    include_tools: {
+                        type: 'boolean',
+                        description: 'Carry tool calls across as one line each (default false — mostly noise, and most of the bytes).'
+                    }
+                },
+                required: ['session_id', 'prompt']
+            },
+            run: async (args) => {
+                const sessionId = need(args, 'session_id');
+                const prompt = need(args, 'prompt');
+                const split = await call(routes.splitChat.path(sessionId), {
+                    method: routes.splitChat.method,
+                    body: {
+                        prompt,
+                        workspaceId: str(args.workspace_id),
+                        includeThinking: args.include_thinking !== false,
+                        includeTools: args.include_tools === true
+                    },
+                    timeoutMs: WRITE_TIMEOUT_MS
+                });
+                if (!split.ok)
+                    throw new Error(split.error ?? 'the split did not open a tab');
+                const { attachment: file } = split;
+                // Name the cut. A transcript that quietly dropped half the chat reads exactly
+                // like a complete one to whoever gets it next.
+                const cut = [
+                    file.elided.tools ? plural(file.elided.tools, 'tool call') : '',
+                    file.elided.thinking ? plural(file.elided.thinking, 'thinking block') : ''
+                ].filter(Boolean);
+                const lines = [
+                    `copied ${plural(file.kept, 'entry', 'entries')} (${Math.round(file.bytes / 1024)}kB) to ${file.path}${cut.length ? `, without ${cut.join(' or ')}` : ''}`
+                ];
+                // The tab exists either way, so every path below leaves the caller somewhere to
+                // go rather than reporting a bare failure over work that half-happened.
+                if (!split.sessionId) {
+                    lines.push('the new tab is open, but the relay could not read its id back');
+                    lines.push('find it with list_chats, then send_prompt the question yourself');
+                    return lines.join('\n');
+                }
+                lines.push(`session_id: ${split.sessionId}`);
+                const sent = await call(routes.sendPrompt.path(split.sessionId), {
+                    method: routes.sendPrompt.method,
+                    body: { text: split.text, workspaceId: split.workspaceId },
+                    timeoutMs: WRITE_TIMEOUT_MS
+                });
+                if (sent.parked)
+                    lines.push('the Mac is locked — the prompt is parked and lands on unlock');
+                else if (!sent.ok)
+                    lines.push(`! the tab and the transcript are ready, but the prompt did not land (${sent.error ?? 'unknown'}) — retry it with send_prompt`);
+                else
+                    lines.push(sent.warning ? `sent (${sent.warning})` : 'sent');
+                return lines.join('\n');
+            }
+        },
         {
             name: 'stop_turn',
             description: 'Cancel the answer a chat is currently streaming — Conductor’s own "Cancel agent". Drives the real UI. A chat that already finished answers alreadyIdle, which is a success. This destroys the in-flight work of another agent, so ask the user first.',
@@ -275,8 +387,8 @@ export function createTools(call) {
             },
             run: async (args) => {
                 const sessionId = need(args, 'session_id');
-                const data = await call(`/api/sessions/${encodeURIComponent(sessionId)}/stop`, {
-                    method: 'POST',
+                const data = await call(routes.stop.path(sessionId), {
+                    method: routes.stop.method,
                     body: { workspaceId: str(args.workspace_id) },
                     timeoutMs: WRITE_TIMEOUT_MS
                 });
@@ -287,6 +399,75 @@ export function createTools(call) {
                 return 'stopped';
             }
         },
+        {
+            name: 'list_models',
+            description: 'The models this chat can be switched to, read live off Conductor’s own picker rather than a hard-coded list that would rot. This DRIVES THE REAL UI — it focuses the workspace and opens the menu — so it costs a few seconds of stolen focus, same as a send. Call it before set_agent_options when you do not already know the exact label.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    session_id: { type: 'string' },
+                    workspace_id: { type: 'string', description: 'Required: the relay locates the chat inside it.' }
+                },
+                required: ['session_id', 'workspace_id']
+            },
+            run: async (args) => {
+                const sessionId = need(args, 'session_id');
+                const workspaceId = need(args, 'workspace_id');
+                const data = await call(`${routes.models.path(sessionId)}?workspaceId=${encodeURIComponent(workspaceId)}`, { timeoutMs: WRITE_TIMEOUT_MS });
+                if (!data.ok)
+                    throw new Error(data.error ?? 'could not read the model menu');
+                return data.models?.length ? data.models.join('\n') : 'the menu listed no models';
+            }
+        },
+        {
+            name: 'set_agent_options',
+            description: 'Change how a chat’s agent runs: model, reasoning effort, plan mode, fast mode. Conductor keeps these in its composer and nowhere else, so this is the only way to reach them — a prompt cannot. DRIVES THE REAL UI and steals focus for a few seconds. The change is confirmed against Conductor’s database before this answers. Applies to the NEXT turn, so set it before send_prompt, not during one. Ask the user before re-pointing a chat they did not name at a different model.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    session_id: { type: 'string' },
+                    workspace_id: {
+                        type: 'string',
+                        description: 'Strongly recommended: it is what the relay asserts against before pressing anything.'
+                    },
+                    model: { type: 'string', description: 'A label from list_models. An unambiguous prefix is enough.' },
+                    effort: { type: 'string', enum: ['low', 'medium', 'high', 'xhigh', 'max', 'ultracode'] },
+                    plan: { type: 'boolean', description: 'Conductor’s Plan checkbox.' },
+                    fast: {
+                        type: 'boolean',
+                        description: 'Fast mode. Only some models offer it; a missing button is reported, not ignored.'
+                    }
+                },
+                required: ['session_id']
+            },
+            run: async (args) => {
+                const sessionId = need(args, 'session_id');
+                const patch = {
+                    model: str(args.model),
+                    effort: str(args.effort),
+                    plan: typeof args.plan === 'boolean' ? args.plan : undefined,
+                    fast: typeof args.fast === 'boolean' ? args.fast : undefined,
+                    workspaceId: str(args.workspace_id)
+                };
+                if (patch.model === undefined &&
+                    patch.effort === undefined &&
+                    patch.plan === undefined &&
+                    patch.fast === undefined)
+                    throw new Error('nothing to change — pass at least one of model, effort, plan, fast');
+                const data = await call(routes.agent.path(sessionId), {
+                    method: routes.agent.method,
+                    body: patch,
+                    timeoutMs: WRITE_TIMEOUT_MS
+                });
+                if (!data.ok)
+                    throw new Error(data.error ?? 'the change did not land');
+                // The re-read row is the receipt, so report *it* rather than what was asked for.
+                const s = data.session;
+                return s
+                    ? `now: ${[s.model, s.claude_effort_level, s.permission_mode, s.fast_mode ? 'fast' : null].filter(Boolean).join(' · ')}`
+                    : 'applied';
+            }
+        },
         {
             name: 'set_workspace_status',
             description: 'Set a workspace’s status in Conductor’s sidebar (backlog, in-progress, in-review, done, canceled). Drives the real UI through the sidebar row menu, but changes nothing on screen. Fails if the sidebar section holding that row is collapsed, because a collapsed row is invisible to Accessibility and there is no fallback.',
@@ -301,8 +482,8 @@ export function createTools(call) {
             run: async (args) => {
                 const id = need(args, 'workspace_id');
                 const status = need(args, 'status');
-                const data = await call(`/api/workspaces/${encodeURIComponent(id)}/status`, {
-                    method: 'POST',
+                const data = await call(routes.workspaceStatus.path(id), {
+                    method: routes.workspaceStatus.method,
                     body: { status },
                     timeoutMs: WRITE_TIMEOUT_MS
                 });
@@ -310,6 +491,112 @@ export function createTools(call) {
                     throw new Error(data.error ?? 'the status change did not land');
                 return `status set to ${status}`;
             }
+        },
+        {
+            name: 'dismiss_prompt',
+            description: 'Throw away a prompt the relay is still holding — a new workspace’s first prompt waiting on setup, or one parked behind a locked Mac. Touches no UI. list_workspaces shows these; a failed one stays visible until it is dismissed, on purpose. Pass session_id for a parked prompt, workspace_id for a first prompt.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    session_id: { type: 'string', description: 'Dismiss the prompt parked for this chat.' },
+                    workspace_id: { type: 'string', description: 'Dismiss this workspace’s undelivered first prompt.' }
+                }
+            },
+            run: async (args) => {
+                const sessionId = str(args.session_id);
+                const workspaceId = str(args.workspace_id);
+                // Both would be two deletes wearing one name, and the caller could not tell which
+                // half failed — so it is one or the other, never both.
+                if (!sessionId && !workspaceId)
+                    throw new Error('pass session_id or workspace_id');
+                if (sessionId && workspaceId)
+                    throw new Error('pass session_id or workspace_id, not both');
+                const route = sessionId ? routes.dismissParkedPrompt : routes.dismissFirstPrompt;
+                await call(route.path((sessionId ?? workspaceId)), { method: route.method });
+                return 'dismissed';
+            }
+        },
+        {
+            name: 'keep_awake',
+            description: 'Read or set the window that holds this Mac awake with the lid shut. Touches no UI. This is what keeps the relay reachable at all, so a long unattended run wants it: without it a closed lid sleeps the Mac and every agent on it stops. Needs `conductor-remote nosleep setup` to have been run once; without that the status says so and holding fails. Releasing a window while the lid is shut sleeps the Mac straight away.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    action: {
+                        type: 'string',
+                        enum: ['status', 'hold', 'release'],
+                        description: 'Default status.'
+                    },
+                    seconds: { type: 'number', description: 'How long to hold it awake. Required for hold.' }
+                }
+            },
+            run: async (args) => {
+                const action = str(args.action) ?? 'status';
+                if (action === 'status') {
+                    const s = await call(routes.nosleep.path());
+                    if (!s.available)
+                        return 'unavailable — run `conductor-remote nosleep setup` on the Mac first';
+                    if (!s.armed)
+                        return `sleeping normally; a window can be up to ${s.maxSeconds}s`;
+                    return `awake${s.until ? `, expires ${relative(s.until)}` : ' until stopped'} (pid ${s.pid})`;
+                }
+                if (action === 'release') {
+                    const r = await call(routes.disarmNoSleep.path(), { method: routes.disarmNoSleep.method });
+                    if (!r.ok)
+                        throw new Error(r.error ?? 'could not release the window');
+                    return r.willSleep ? 'released — the lid is shut, so the Mac is going to sleep now' : 'released';
+                }
+                if (action !== 'hold')
+                    throw new Error(`unknown action ${action}`);
+                const seconds = num(args.seconds);
+                if (seconds === undefined)
+                    throw new Error('seconds is required for hold');
+                const r = await call(routes.armNoSleep.path(), {
+                    method: routes.armNoSleep.method,
+                    body: { seconds }
+                });
+                if (!r.ok)
+                    throw new Error(r.error ?? 'could not hold the Mac awake');
+                return `awake${r.state.until ? `, expires ${relative(r.state.until)}` : ''}`;
+            }
+        },
+        {
+            name: 'relay_logs',
+            description: 'The relay’s own log — why a send failed, whether Conductor refused Accessibility, what the network did. Touches no UI. Default is the running relay’s captured console; `file` tails the daemon’s log on disk, which is the only place a *previous* process’s crash survives. Secrets are redacted before it leaves the relay.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    file: {
+                        type: 'string',
+                        enum: ['relay.log', 'relay.err.log'],
+                        description: 'Omit for this process’s live log.'
+                    },
+                    limit: { type: 'number', description: 'Most recent N lines. Default 200, max 2000.' },
+                    contains: {
+                        type: 'string',
+                        description: 'Keep only lines containing this (case-insensitive). Filtered here, not by the relay.'
+                    }
+                }
+            },
+            run: async (args) => {
+                const file = str(args.file);
+                const limit = Math.min(2000, Math.max(1, Math.trunc(num(args.limit) ?? 200)));
+                const q = new URLSearchParams({ limit: String(limit) });
+                if (file)
+                    q.set('file', file);
+                const data = await call(`${routes.logs.path()}?${q}`);
+                const needle = str(args.contains)?.toLowerCase();
+                const kept = needle ? data.entries.filter(e => e.text.toLowerCase().includes(needle)) : data.entries;
+                if (!kept.length)
+                    return needle ? `no line in ${data.source} matches ${needle}` : `${data.source} is empty`;
+                const lines = kept.map(e => `${stamp(e.t)} ${e.level === 'info' ? '' : `${e.level.toUpperCase()} `}${clip(e.text, 2000)}`);
+                // Whose log this is decides what it proves: an unmanaged relay's files belong to a
+                // *different* process, so a clean tail there says nothing about the one just called.
+                const head = data.managed
+                    ? data.source
+                    : `${data.source} (written by the LaunchAgent, not the relay just called)`;
+                return [`— ${head}, ${kept.length} lines —`, ...lines].join('\n');
+            }
         }
     ];
 }

package/dist-node/src/reads.js

@@ -190,6 +190,26 @@ export class Reads {
 			 LIMIT ?`, [...params, limit]);
         return rows.map(toSearchWorkspace);
     }
+    /**
+     * One workspace by id, whatever state it is in — the read behind opening an archived
+     * chat (`GET /api/workspaces/:id`).
+     *
+     * `getWorkspace` above is the *live* one: it resolves a worktree and a base branch,
+     * and returns null for the 1,846 archived workspaces here, which is right for every
+     * write (there is nothing to focus and nothing to diff) and wrong for reading. The
+     * transcript survives archiving — Conductor deletes the worktree, not the chat — so
+     * this returns the same `SearchWorkspace` a search result carries, with no worktree
+     * and no git, and `listSessions`/`getMessages` do the rest by id.
+     */
+    getAnyWorkspace(id) {
+        const rows = this.db.query(`SELECT w.id, w.workspace_name, w.pr_title, w.branch, w.directory_name, w.state, w.updated_at,
+			        r.name AS repo_name, r.icon AS repo_icon, r.root_path AS repo_root, r.remote_url AS remote_url
+			 FROM workspaces w
+			 LEFT JOIN repos r ON r.id = w.repository_id
+			 WHERE w.id = ?
+			 LIMIT 1`, [id]);
+        return rows[0] ? toSearchWorkspace(rows[0]) : null;
+    }
     /** Resolve a repo's icon by its name (the sidebar avatar) — null if the repo or icon is unknown. */
     resolveRepoIcon(repoName) {
         const rows = this.db.query('SELECT root_path FROM repos WHERE name = ? LIMIT 1', [
@@ -269,6 +289,19 @@ export class Reads {
         }
         return null;
     }
+    /**
+     * Which workspace a chat belongs to.
+     *
+     * Every other route resolves this by matching `active_session_id`, which only ever
+     * finds the tab that is currently on screen. That is fine for a phone, where the
+     * chat you are looking at is the chat you are sending to. It is wrong for anything
+     * addressing a chat by id — a background tab has a workspace too, and `sessions`
+     * has carried `workspace_id` all along.
+     */
+    sessionWorkspaceId(sessionId) {
+        const rows = this.db.query(`SELECT workspace_id FROM sessions WHERE id = ? LIMIT 1`, [sessionId]);
+        return rows[0]?.workspace_id ?? null;
+    }
     /** Session → worktree path, cached: it's stable for a session's lifetime and polled every tick. */
     worktreeBySession = new Map();
     sessionWorktree(sessionId) {

package/dist-node/src/routes.js

@@ -0,0 +1,98 @@
+/**
+ * Every `/api` path, declared once, for the three callers that must agree on it.
+ *
+ * The relay matches these, the phone builds them (`web/src/lib/api.ts`) and the MCP
+ * tools build them too (`src/mcp-tools.ts`). Before this each path was spelled three
+ * times: a regex here, a template literal there, another template literal in the third
+ * place. `src/wire.ts` had already made the *shapes* impossible to disagree about, and
+ * this is the other half — a renamed path used to typecheck cleanly in all three files
+ * and surface as a 404 on someone's phone.
+ *
+ * One pattern gives both directions. `param()` splits `/api/sessions/:id/stop` at the
+ * placeholder, so the same string builds `path(id)` for a client and the regex the relay
+ * matches with. They cannot drift because there is only one of them.
+ *
+ * **This module stays stdlib-free — no `node:` imports, ever.** It is one of the two
+ * files under `src/` the web app may import a *value* from (the other is
+ * `src/shared.ts`), and `scripts/check-imports.ts` walks both to enforce it. Anything
+ * needing Node belongs in the handler, not in the table.
+ */
+/** Escape a literal for use inside a RegExp — the paths are fixed strings, but `.` is real syntax. */
+function literal(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function flat(method, pattern) {
+    return { method, pattern, path: () => pattern };
+}
+function param(method, pattern) {
+    const [head, tail] = pattern.split(/:[a-zA-Z]+/);
+    if (tail === undefined)
+        throw new Error(`route ${pattern} declares no :param`);
+    return {
+        method,
+        pattern,
+        path: value => `${head}${encodeURIComponent(value)}${tail}`,
+        re: new RegExp(`^${literal(head)}([^/]+)${literal(tail)}$`)
+    };
+}
+/**
+ * The table. Names read as what the caller wants, not as the verb plus the noun, because
+ * the method is right there in the value.
+ */
+export const routes = {
+    // ── the relay itself ──
+    state: flat('GET', '/api/state'),
+    search: flat('GET', '/api/search'),
+    repos: flat('GET', '/api/repos'),
+    repoIcon: param('GET', '/api/repos/:repo/icon'),
+    logs: flat('GET', '/api/logs'),
+    settings: flat('GET', '/api/settings'),
+    updateSettings: flat('PATCH', '/api/settings'),
+    nosleep: flat('GET', '/api/nosleep'),
+    armNoSleep: flat('POST', '/api/nosleep'),
+    disarmNoSleep: flat('DELETE', '/api/nosleep'),
+    push: flat('GET', '/api/push'),
+    pushSubscribe: flat('POST', '/api/push/subscribe'),
+    pushUnsubscribe: flat('POST', '/api/push/unsubscribe'),
+    pushTest: flat('POST', '/api/push/test'),
+    // ── workspaces ──
+    createWorkspace: flat('POST', '/api/workspaces'),
+    /** One workspace by id, archived included — what `/api/state` deliberately leaves out. */
+    workspace: param('GET', '/api/workspaces/:workspaceId'),
+    sessions: param('GET', '/api/workspaces/:workspaceId/sessions'),
+    newChat: param('POST', '/api/workspaces/:workspaceId/sessions'),
+    diff: param('GET', '/api/workspaces/:workspaceId/diff'),
+    merge: param('POST', '/api/workspaces/:workspaceId/merge'),
+    workspaceStatus: param('POST', '/api/workspaces/:workspaceId/status'),
+    /** Dismiss a first prompt the relay never managed to deliver (src/firstprompt.ts). */
+    dismissFirstPrompt: param('DELETE', '/api/workspaces/:workspaceId/prompt'),
+    // ── chats ──
+    messages: param('GET', '/api/sessions/:sessionId/messages'),
+    models: param('GET', '/api/sessions/:sessionId/models'),
+    agent: param('POST', '/api/sessions/:sessionId/agent'),
+    stop: param('POST', '/api/sessions/:sessionId/stop'),
+    sendPrompt: param('POST', '/api/sessions/:sessionId/prompt'),
+    /** Copy a chat into a fresh tab beside it, as a Conductor attachment (src/attachments.ts). */
+    splitChat: param('POST', '/api/sessions/:sessionId/split'),
+    /** Dismiss a prompt parked behind the lock screen (src/parked.ts). */
+    dismissParkedPrompt: param('DELETE', '/api/sessions/:sessionId/prompt')
+};
+// ── matching, for the relay ─────────────────────────────────────────────────────
+// The client half of a route is a function call; the server half needs these two.
+/** Whether this request is that parameterless route. */
+export function isRoute(route, method, pathname) {
+    return method === route.method && pathname === route.pattern;
+}
+/**
+ * The decoded parameter when this request is that route, else null.
+ *
+ * Decoding here rather than at each call site is the point: a workspace id is safe
+ * either way, but a repo name is not, and one handler forgetting `decodeURIComponent`
+ * is exactly the bug this table exists to make unwritable.
+ */
+export function routeParam(route, method, pathname) {
+    if (method !== route.method)
+        return null;
+    const m = pathname.match(route.re);
+    return m ? decodeURIComponent(m[1]) : null;
+}