@ctrl-spc/cs 0.2.0 → 0.3.0

package/dist/mcp.js

@@ -0,0 +1,1679 @@
+import { randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { createServer as createHttpServer } from 'node:http';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { TOOLS_SERVER_PORT, SESSION_TTL_MS } from './env.js';
+import { agentPath } from './agents.js';
+export function attributionFromClientName(name) {
+    if (!name)
+        return null;
+    if (/claude/i.test(name))
+        return 'claude';
+    if (/codex/i.test(name))
+        return 'codex';
+    return null;
+}
+/** Awaits a Supabase call and throws on error — callers catch once, at the
+ *  handler boundary (mirrors v1's `must`). */
+async function must(query) {
+    const { data, error } = await query;
+    if (error)
+        throw new Error(error.message);
+    return data;
+}
+function textResult(payload) {
+    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+}
+function errorResult(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+/** Columns v1 returns for a freshly created artifact (cli/src/mcp.ts:2239) —
+ *  reused verbatim so get_task and create_artifact hand back the same shape, plus
+ *  `revision` so the agent has the optimistic-concurrency token update_artifact
+ *  needs for `expected_revision` (mirrors how get_task returns tasks.revision). */
+const ARTIFACT_COLUMNS = 'id,task_id,type,format,title,purpose_key,system_kind,content,storage_path,created_by,from_agent,created_at,revision';
+/** Columns a decision row exposes to the agent (D3) — reused verbatim so get_task
+ *  and ask_question hand back the same shape. RLS `decisions_select` grants the
+ *  signed-in user read via `app.can_access_task`. */
+const DECISION_COLUMNS = 'id,task_id,state,category,context,question,answer_mode,options,answer,selected_options,answer_note,question_comment_id,related_artifact_id,asked_by,asked_by_agent_run_id,asked_at,decided_by,decided_at';
+/** Tags come from the same `task_tags`→`tags` join the web reads. */
+const TASK_TAGS = 'task_tags:task_tags!task_tags_task_id_fkey(tag:tags!task_tags_tag_id_fkey(id,name))';
+function tagsOf(row) {
+    return (row.task_tags ?? [])
+        .map((entry) => entry.tag?.name)
+        .filter((name) => Boolean(name))
+        .sort((a, b) => a.localeCompare(b));
+}
+/**
+ * List the signed-in user's tasks across all their projects (RLS-scoped),
+ * optionally filtered to one project. No machine/workspace resolver — RLS on
+ * `tasks` already confines the rows to the user's own projects.
+ */
+async function listTasksHandler(client, args) {
+    try {
+        const projects = (await must(client.from('projects').select('id, name'))) ?? [];
+        let query = client
+            .from('tasks')
+            .select(`id, project_id, name, status, due_date, ${TASK_TAGS}`)
+            .is('archived_at', null);
+        if (args.project_id)
+            query = query.eq('project_id', args.project_id);
+        const rows = (await must(query
+            .order('status', { ascending: true })
+            .order('position', { ascending: true })
+            .order('created_at', { ascending: true })
+            .order('id', { ascending: true }))) ?? [];
+        const tasks = rows.map((row) => ({
+            id: row.id,
+            project_id: row.project_id,
+            project: projects.find((p) => p.id === row.project_id) ?? { id: row.project_id },
+            name: row.name,
+            status: row.status,
+            due_date: row.due_date,
+            tags: tagsOf(row),
+        }));
+        return textResult({ projects, tasks });
+    }
+    catch (err) {
+        return errorResult(`list_tasks failed: ${err.message}`);
+    }
+}
+/**
+ * Read one task by id (RLS-scoped) with its tags, comments, live artifacts, and
+ * decisions (D3 — so the agent can read the answers to questions it asked).
+ * Adapted from v1's `getTaskHandler` for the column shapes, with every
+ * topology / checkout / coordination section dropped.
+ */
+async function getTaskHandler(client, args) {
+    try {
+        const row = await must(client
+            .from('tasks')
+            .select(`*, ${TASK_TAGS}`)
+            .eq('id', args.id)
+            .is('archived_at', null)
+            .maybeSingle());
+        if (!row)
+            return errorResult(`No task found for id "${args.id}".`);
+        const [comments, artifacts, decisions] = await Promise.all([
+            must(client
+                .from('comments')
+                .select('id,task_id,body,author_id,from_agent,agent_run_id,created_at,updated_at')
+                .eq('task_id', row.id)
+                .order('created_at', { ascending: true })
+                .order('id', { ascending: true })),
+            must(client
+                .from('artifacts')
+                .select(ARTIFACT_COLUMNS)
+                .eq('task_id', row.id)
+                .is('deleted_at', null)
+                .order('created_at', { ascending: true })
+                .order('id', { ascending: true })),
+            // D3: the item's decisions — the questions ask_question opened and the
+            // answers the user gave in the web UI, so the agent can read them back.
+            must(client
+                .from('decisions')
+                .select(DECISION_COLUMNS)
+                .eq('task_id', row.id)
+                .order('asked_at', { ascending: true })
+                .order('id', { ascending: true })),
+        ]);
+        const { task_tags: _drop, ...task } = row;
+        return textResult({
+            task: { ...task, tags: tagsOf(row) },
+            comments: comments ?? [],
+            artifacts: artifacts ?? [],
+            decisions: decisions ?? [],
+        });
+    }
+    catch (err) {
+        return errorResult(`get_task failed: ${err.message}`);
+    }
+}
+/**
+ * Create an artifact on a task the user owns (via RLS). Adapted from v1's simple
+ * (non-agent-run) path (cli/src/mcp.ts:2219): the task is looked up by id under
+ * RLS (no bound project), and the artifact is created AS THE USER
+ * (`created_by: userId`). `from_agent` is left null because the deployed DB guard
+ * `artifact_agent_insert_guard` reserves agent attribution for the coordinated
+ * `create_agent_artifact` RPC — the agent-run model this availability-only
+ * feature deliberately does not use. A direct `authenticated` insert that sets
+ * `from_agent` is rejected ("agent artifacts must be created through
+ * create_agent_artifact"), so un-coordinated tool use writes as the user.
+ */
+async function createArtifactHandler(client, userId, currentSession, args) {
+    try {
+        if (!args.task_id)
+            return errorResult('create_artifact requires task_id.');
+        if (!args.content)
+            return errorResult('create_artifact requires content.');
+        if (args.purpose_key?.trim().startsWith('context:')) {
+            return errorResult('Context is a reserved work-item artifact.');
+        }
+        const task = await must(client.from('tasks').select('id').eq('id', args.task_id).is('archived_at', null).maybeSingle());
+        if (!task)
+            return errorResult(`No task found for id "${args.task_id}".`);
+        const row = await must(client
+            .from('artifacts')
+            .insert({
+            task_id: args.task_id,
+            type: args.type,
+            format: args.format ?? 'md',
+            ...(args.title?.trim() ? { title: args.title.trim() } : {}),
+            ...(args.purpose_key?.trim() ? { purpose_key: args.purpose_key.trim() } : {}),
+            content: args.content,
+            created_by: userId,
+            from_agent: null,
+            agent_run_id: null,
+        })
+            .select(ARTIFACT_COLUMNS)
+            .single());
+        if (!row)
+            throw new Error('Artifact insert returned no row.');
+        // D1 attribution: if this connection has an open session for THIS task
+        // (the agent called begin_work first), record that the session produced this
+        // artifact — one cliv2_agent_outputs row, referencing the artifact BY VALUE.
+        // Best-effort: the artifact already exists and is the real return value, so a
+        // failed attribution write must NOT fail the tool — but it is surfaced in the
+        // returned text rather than silently dropped. With no open session (or a
+        // session for a different task) no attribution row is written — backward
+        // compatible with un-coordinated tool use.
+        let attributionWarning;
+        if (currentSession && currentSession.taskId === args.task_id) {
+            try {
+                await must(client.from('cliv2_agent_outputs').insert({
+                    user_id: userId,
+                    session_id: currentSession.sessionId,
+                    kind: 'artifact',
+                    product_id: row.id,
+                }));
+            }
+            catch (err) {
+                attributionWarning = `Artifact created, but recording session attribution failed: ${err.message}`;
+            }
+        }
+        return textResult(attributionWarning ? { artifact: row, attribution_warning: attributionWarning } : { artifact: row });
+    }
+    catch (err) {
+        return errorResult(`create_artifact failed: ${err.message}`);
+    }
+}
+/** Re-fetch one task with the SAME select get_task uses (`*` + the tag join),
+ *  returning the parsed task object ({ ...row, tags }, task_tags dropped) or null.
+ *  Shared by update_task and create_task so their result shape matches get_task's
+ *  `task`. */
+async function fetchTask(client, id) {
+    const row = await must(client.from('tasks').select(`*, ${TASK_TAGS}`).eq('id', id).is('archived_at', null).maybeSingle());
+    if (!row)
+        return null;
+    const { task_tags: _drop, ...task } = row;
+    return { ...task, tags: tagsOf(row) };
+}
+/**
+ * Update a task the user owns (via RLS). Adapted from v1's SIMPLE (non-agent-run)
+ * `updateTaskHandler` branch: no bound project (RLS scopes it), status + the plain
+ * text fields only — owner / sprint / tags / reorder / before_task_id are all
+ * deferred. Optimistic concurrency via `expected_revision` (from get_task) through
+ * the same `save_task_if_current` RPC v1 uses; an `edit_conflict` maps to a clear
+ * "call get_task again and retry" message. Re-fetches with get_task's select.
+ */
+async function updateTaskHandler(client, args) {
+    try {
+        const { id, fields, expected_revision } = args;
+        if (!Number.isInteger(expected_revision) || expected_revision < 1) {
+            return errorResult('update_task requires expected_revision (a positive integer) from the most recent get_task response.');
+        }
+        const current = await must(client.from('tasks').select('id,status,revision').eq('id', id).is('archived_at', null).maybeSingle());
+        if (!current)
+            return errorResult(`No task found for id "${id}".`);
+        const patch = {};
+        if (fields.name !== undefined)
+            patch.name = fields.name;
+        if (fields.description !== undefined)
+            patch.description = fields.description;
+        if (fields.due_date !== undefined)
+            patch.due_date = fields.due_date;
+        if (fields.status !== undefined)
+            patch.status = fields.status;
+        // A status change implies append-to-destination (reorder); a same-value
+        // status preserves board position. before_task_id ordering is deferred, so
+        // reorder is driven purely by whether the status actually changed.
+        const statusChanged = fields.status !== undefined && fields.status !== current.status;
+        await must(client.rpc('save_task_if_current', {
+            p_task_id: id,
+            p_expected_revision: expected_revision,
+            p_changes: patch,
+            p_tag_ids: null,
+            p_reorder: statusChanged,
+            p_before_task_id: null,
+        }));
+        const task = await fetchTask(client, id);
+        if (!task)
+            throw new Error('Updated task could not be re-fetched.');
+        return textResult({ task });
+    }
+    catch (err) {
+        if (err.message === 'edit_conflict') {
+            return errorResult('update_task conflict: this work item changed after it was read. Call get_task again, review the latest revision, and retry intentionally.');
+        }
+        return errorResult(`update_task failed: ${err.message}`);
+    }
+}
+/**
+ * Edit an artifact the user can access (via RLS). Mirrors updateTaskHandler's
+ * optimistic-concurrency shape exactly, over the run-free `save_artifact_if_current`
+ * RPC (security invoker, granted authenticated, NO p_run — the coordinated
+ * create_agent_artifact path is deliberately unused here). The deployed RPC accepts
+ * the artifact BODY keys `title` / `purpose_key` / `type` / `format` / `content`
+ * (plus `deleted_at`, which this tool never sends); this tool exposes
+ * `title` / `type` / `format` / `content` and deliberately NOT `purpose_key` — an
+ * UPDATE that set `purpose_key='context:<task>'` could relabel a normal artifact as
+ * canonical context and thereby escape the INSERT-only context-artifact reservation.
+ * `from_agent` is never touched. `expected_revision` comes from the most recent
+ * get_task; a revision mismatch raises `edit_conflict`, mapped to the same clear
+ * "call get_task again and retry" message updateTask uses. Re-fetches the live
+ * artifact with ARTIFACT_COLUMNS so the result matches get_task / create_artifact.
+ */
+async function updateArtifactHandler(client, args) {
+    try {
+        const { id, fields, expected_revision } = args;
+        if (!Number.isInteger(expected_revision) || expected_revision < 1) {
+            return errorResult('update_artifact requires expected_revision (a positive integer) from the most recent get_task response.');
+        }
+        // Build p_changes from the provided fields only — restricted to the keys this
+        // tool exposes (title / type / format / content). purpose_key is deliberately
+        // excluded (it could escape the context-artifact reservation), and deleted_at is
+        // never sent from here.
+        const patch = {};
+        if (fields.title !== undefined)
+            patch.title = fields.title;
+        if (fields.type !== undefined)
+            patch.type = fields.type;
+        if (fields.format !== undefined)
+            patch.format = fields.format;
+        if (fields.content !== undefined)
+            patch.content = fields.content;
+        await must(client.rpc('save_artifact_if_current', {
+            p_artifact_id: id,
+            p_expected_revision: expected_revision,
+            p_changes: patch,
+        }));
+        const artifact = await must(client.from('artifacts').select(ARTIFACT_COLUMNS).eq('id', id).is('deleted_at', null).maybeSingle());
+        if (!artifact)
+            throw new Error('Updated artifact could not be re-fetched.');
+        return textResult({ artifact });
+    }
+    catch (err) {
+        if (err.message === 'edit_conflict') {
+            return errorResult('update_artifact conflict: this artifact changed after it was read. Call get_task again, re-read the latest revision, and retry intentionally.');
+        }
+        return errorResult(`update_artifact failed: ${err.message}`);
+    }
+}
+/**
+ * Set the repository role slugs on a task — its role assignments. Replaces
+ * tasks.role_slugs with the given list via the run-free `set_task_role_slugs` RPC
+ * (security definer, granted authenticated, NO p_run; checks app.is_project_member).
+ * The RPC filters the requested slugs down to the project's active repository scopes,
+ * so a caller can't assign a slug the project doesn't define. Re-fetches with
+ * get_task's select so the result shape matches get_task's `task`.
+ *
+ * The RPC has no archived guard, but fetchTask filters `archived_at is null`, so
+ * without a pre-check a task archived after it was read would be written at the DB
+ * yet reported as a re-fetch failure. Mirror updateTaskHandler: confirm the task is
+ * live under RLS BEFORE calling the RPC, and return a clean "no task" error if not.
+ */
+async function setTaskRoleSlugsHandler(client, args) {
+    try {
+        const task = await must(client.from('tasks').select('id').eq('id', args.task_id).is('archived_at', null).maybeSingle());
+        if (!task)
+            return errorResult(`No task found for id "${args.task_id}".`);
+        await must(client.rpc('set_task_role_slugs', { p_task: args.task_id, p_role_slugs: args.role_slugs }));
+        const updated = await fetchTask(client, args.task_id);
+        if (!updated)
+            throw new Error('Task could not be re-fetched.');
+        return textResult({ task: updated });
+    }
+    catch (err) {
+        return errorResult(`set_task_role_slugs failed: ${err.message}`);
+    }
+}
+/**
+ * Leave a note on a task the user owns (via RLS). Adapted from v1's
+ * `addCommentHandler`, authored AS THE USER: `from_agent` is left null. Like
+ * `artifacts`, the `comments` table carries a `comment_agent_insert_guard` that
+ * reserves agent attribution for the coordinated path this feature does not use,
+ * so a direct `from_agent`-set insert would be rejected — writing as the user is
+ * the correct, consistent choice (matches create_artifact).
+ */
+async function addCommentHandler(client, userId, currentSession, args) {
+    try {
+        if (!args.task_id)
+            return errorResult('add_comment requires task_id.');
+        if (!args.body || !args.body.trim())
+            return errorResult('add_comment requires a non-empty body.');
+        const task = await must(client.from('tasks').select('id').eq('id', args.task_id).is('archived_at', null).maybeSingle());
+        if (!task)
+            return errorResult(`No task found for id "${args.task_id}".`);
+        const row = await must(client
+            .from('comments')
+            .insert({
+            task_id: args.task_id,
+            author_id: userId,
+            body: args.body,
+            from_agent: null,
+            agent_run_id: null,
+        })
+            .select('id,task_id,body,author_id,from_agent,created_at')
+            .single());
+        if (!row)
+            throw new Error('Comment insert returned no row.');
+        // D2a attribution: if this connection has an open session (the agent called
+        // begin_work), record that the session produced this comment — one
+        // cliv2_agent_outputs row referencing the comment BY VALUE. Unlike
+        // create_artifact this does NOT require the session's task to match: a comment
+        // produced while a session is open is attributed to it. Best-effort (mirrors
+        // D1): the comment already exists and is the real return value, so a failed
+        // attribution write must NOT fail the tool — it is surfaced in the returned
+        // text rather than silently dropped. With no open session no attribution row is
+        // written — backward compatible with un-coordinated tool use.
+        let attributionWarning;
+        if (currentSession) {
+            try {
+                await must(client.from('cliv2_agent_outputs').insert({
+                    user_id: userId,
+                    session_id: currentSession.sessionId,
+                    kind: 'comment',
+                    product_id: row.id,
+                }));
+            }
+            catch (err) {
+                attributionWarning = `Comment created, but recording session attribution failed: ${err.message}`;
+            }
+        }
+        return textResult(attributionWarning ? { comment: row, attribution_warning: attributionWarning } : { comment: row });
+    }
+    catch (err) {
+        return errorResult(`add_comment failed: ${err.message}`);
+    }
+}
+/**
+ * Create a new task in a project the user owns (via RLS), owned by the user.
+ * Adapted from v1's `createTaskHandler`, minimal — tags / depends_on /
+ * before_task_id are deferred. Uses the workflow-free `create_task` RPC
+ * (SECURITY DEFINER; the old `create_task_with_workflow` was removed with the
+ * Workflows feature, see 20260721150000_drop_workflows.sql) to insert the task
+ * and return its id, then re-fetches with get_task's select.
+ */
+async function createTaskHandler(client, userId, currentSession, args) {
+    try {
+        if (!args.name || !args.name.trim())
+            return errorResult('create_task requires a non-empty name.');
+        const taskId = await must(client.rpc('create_task', {
+            p_project: args.project_id,
+            p_name: args.name,
+            p_description: args.description ?? '',
+            p_owner: userId,
+        }));
+        if (!taskId)
+            throw new Error('Task insert returned no id.');
+        const task = await fetchTask(client, taskId);
+        if (!task)
+            throw new Error('Created task could not be re-fetched.');
+        // D2a attribution: if this connection has an open session, record that the
+        // session produced this NEW task — one cliv2_agent_outputs row referencing the
+        // task BY VALUE. This is a follow-up task the subagent created, NOT the
+        // session's anchored task, so there is deliberately NO task-id match to gate
+        // on: gate only on there being an open session. Best-effort (mirrors D1): the
+        // task already exists and is the real return value, so a failed attribution
+        // write must NOT fail the tool — it is surfaced in the returned text rather
+        // than silently dropped. With no open session no attribution row is written —
+        // backward compatible with un-coordinated tool use.
+        let attributionWarning;
+        if (currentSession) {
+            try {
+                await must(client.from('cliv2_agent_outputs').insert({
+                    user_id: userId,
+                    session_id: currentSession.sessionId,
+                    kind: 'task',
+                    product_id: taskId,
+                }));
+            }
+            catch (err) {
+                attributionWarning = `Task created, but recording session attribution failed: ${err.message}`;
+            }
+        }
+        return textResult(attributionWarning ? { task, attribution_warning: attributionWarning } : { task });
+    }
+    catch (err) {
+        return errorResult(`create_task failed: ${err.message}`);
+    }
+}
+/**
+ * Ask the user a question about the work item the open session is on (D3). Unlike
+ * the write tools, this REQUIRES an open session — the question is a decision on
+ * the session's task, and the `cliv2_ask_question` RPC resolves that task FROM the
+ * session (so there's no task_id arg). The RPC inserts the run-free `decisions`
+ * row AS THE USER and returns its id; the decision is the real return value, so
+ * (mirroring create_artifact) attribution is a best-effort `cliv2_agent_outputs`
+ * write whose failure is surfaced in the returned text, never fatal. The created
+ * decision is re-fetched with the SAME columns get_task returns so the agent sees
+ * exactly what it made and can later read the user's answer back with get_task.
+ */
+async function askQuestionHandler(client, userId, session, args) {
+    try {
+        if (!session) {
+            return errorResult('ask_question needs an open work session — call begin_work first.');
+        }
+        if (!args.category || !args.category.trim())
+            return errorResult('ask_question requires a non-empty category.');
+        if (!args.context || !args.context.trim())
+            return errorResult('ask_question requires a non-empty context.');
+        if (!args.question || !args.question.trim())
+            return errorResult('ask_question requires a non-empty question.');
+        const mode = args.answer_mode ?? 'free_text';
+        const decisionId = await must(client.rpc('cliv2_ask_question', {
+            p_session: session.sessionId,
+            p_category: args.category,
+            p_context: args.context,
+            p_question: args.question,
+            p_answer_mode: mode,
+            p_options: args.options ?? [],
+            p_related_artifact: args.related_artifact_id ?? null,
+        }));
+        if (!decisionId)
+            throw new Error('Question insert returned no decision id.');
+        // Best-effort attribution (mirrors create_artifact exactly): record that this
+        // session asked the question — one cliv2_agent_outputs row referencing the
+        // decision BY VALUE. The decision already exists and is the real return value,
+        // so a failed attribution write must NOT fail the tool — it is surfaced in the
+        // returned text rather than silently dropped.
+        let attributionWarning;
+        try {
+            await must(client.from('cliv2_agent_outputs').insert({
+                user_id: userId,
+                session_id: session.sessionId,
+                kind: 'decision',
+                product_id: decisionId,
+            }));
+        }
+        catch (err) {
+            attributionWarning = `Question created, but recording session attribution failed: ${err.message}`;
+        }
+        // Re-fetch the created decision with the SAME columns get_task returns, so the
+        // agent sees what it made (and later reads the answer back through get_task).
+        const decision = await must(client.from('decisions').select(DECISION_COLUMNS).eq('id', decisionId).maybeSingle());
+        if (!decision)
+            throw new Error('Created decision could not be re-fetched.');
+        return textResult(attributionWarning ? { decision, attribution_warning: attributionWarning } : { decision });
+    }
+    catch (err) {
+        return errorResult(`ask_question failed: ${err.message}`);
+    }
+}
+/**
+ * Record the user's answer to an OPEN decision on the work item (feature 05 / D4 —
+ * the run-free twin of v1's `record_user_input`). Unlike v1, this does NOT go through a
+ * run-gated batch RPC (`record_task_decisions` / `record_task_decision_responses`);
+ * it uses the exact RPC the web's `answerDecision` (web/src/lib/actions.ts) calls,
+ * `answer_task_decision_v2({ p_decision_id, p_selected_options, p_answer_note })`,
+ * AS THE USER under RLS — no run, no fencing token. The RPC is security-definer and
+ * validates access (`app.can_access_task`) plus the answer shape against the
+ * decision's `answer_mode`, so it is the source of truth for deep validation.
+ *
+ * The web routes EVERY answer_mode through this single v2 RPC; we replicate that
+ * mapping exactly:
+ *   - free_text            -> p_selected_options: [],           p_answer_note: <answer>
+ *   - single/multi_select  -> p_selected_options: <options>,    p_answer_note: <note ?? ''>
+ * (`answer_task_decision(id, answer)` is only a thin wrapper for v2 with '{}' — the
+ * web never calls it, so neither do we.) We read the decision's `answer_mode` first
+ * only to route + give a clean shape error; RLS scopes that read to the user. This
+ * MUTATES an existing decision, so there is no attribution row (nothing new is
+ * produced). Requires an open session, like ask_question. Re-fetches the decision
+ * with DECISION_COLUMNS so the caller sees the now-decided row (it shows answered in
+ * the web UI).
+ */
+async function recordUserInputHandler(client, session, args) {
+    try {
+        if (!session) {
+            return errorResult('record_user_input needs an open work session — call begin_work first.');
+        }
+        if (!args.decision_id || !args.decision_id.trim()) {
+            return errorResult('record_user_input requires a decision_id.');
+        }
+        // Read the decision to route by its answer_mode EXACTLY as the web does, and to
+        // give a clean shape error before the RPC. RLS (`decisions_select`) scopes this
+        // to a decision the signed-in user can access.
+        const decision = await must(client.from('decisions').select('id,answer_mode').eq('id', args.decision_id).maybeSingle());
+        if (!decision)
+            return errorResult(`No decision found for id "${args.decision_id}".`);
+        // Replicate the web's answerDecision mapping into answer_task_decision_v2.
+        let pSelectedOptions;
+        let pAnswerNote;
+        if (decision.answer_mode === 'free_text') {
+            if (!args.answer || !args.answer.trim()) {
+                return errorResult('record_user_input requires answer (the free-text answer) for a free_text decision.');
+            }
+            pSelectedOptions = [];
+            pAnswerNote = args.answer;
+        }
+        else {
+            if (!Array.isArray(args.selected_options) || args.selected_options.length === 0) {
+                return errorResult('record_user_input requires selected_options (the chosen option(s)) for a choice decision.');
+            }
+            pSelectedOptions = args.selected_options;
+            pAnswerNote = args.answer_note ?? '';
+        }
+        await must(client.rpc('answer_task_decision_v2', {
+            p_decision_id: args.decision_id,
+            p_selected_options: pSelectedOptions,
+            p_answer_note: pAnswerNote,
+        }));
+        // Hand back the now-decided decision in the SAME shape get_task / ask_question use.
+        const updated = await must(client.from('decisions').select(DECISION_COLUMNS).eq('id', args.decision_id).maybeSingle());
+        if (!updated)
+            throw new Error('Answered decision could not be re-fetched.');
+        return textResult({ decision: updated });
+    }
+    catch (err) {
+        return errorResult(`record_user_input failed: ${err.message}`);
+    }
+}
+/**
+ * Record what you explored for the work item as its CANONICAL context document
+ * (feature 05 / D4 — the run-free twin of v1's `record_context_exploration`). v1's
+ * version wrote the `system_kind='context'` artifact PLUS repository-coverage /
+ * topology through the run-gated `record_context_exploration_artifact` RPC; we drop
+ * the coverage and topology entirely and write ONLY the context document.
+ *
+ * The canonical context artifact is DB-reserved: the BEFORE-INSERT trigger
+ * `app.guard_agent_artifact_insert` admits a `system_kind='context'` row only when
+ * the session GUC `app.context_artifact_write` matches the task. The run-free
+ * SECURITY DEFINER RPC `cliv2_record_context(p_session, p_content)` sets that GUC and
+ * writes/UPSERTS the ONE canonical "Work item context" artifact for the session's
+ * task — task resolved FROM the session, no run / fencing / topology. So this tool
+ * takes only `content`: the document's title is fixed ("Work item context") and its
+ * task comes from the open session. Requires an open session.
+ *
+ * Because the RPC UPSERTS the same canonical row, repeated calls return the SAME
+ * artifact id. Best-effort attribution mirrors create_artifact (one
+ * cliv2_agent_outputs row, kind 'artifact', product_id BY VALUE) — but a second call
+ * re-inserting that same (kind, product_id) trips `unique(kind, product_id)` (23505):
+ * that is the already-attributed case, so 23505 is treated as success (no warning)
+ * and only OTHER failures surface as attribution_warning. Re-fetches with
+ * ARTIFACT_COLUMNS and returns { artifact }.
+ */
+async function recordContextExplorationHandler(client, userId, session, args) {
+    try {
+        if (!session) {
+            return errorResult('record_context_exploration needs an open work session — call begin_work first.');
+        }
+        if (!args.content || !args.content.trim())
+            return errorResult('record_context_exploration requires content.');
+        // Write/upsert the ONE canonical context document for the session's task via the
+        // run-free RPC (it resolves the task from p_session and sets the context-write GUC
+        // the INSERT guard requires). Returns the canonical artifact's id.
+        const artifactId = await must(client.rpc('cliv2_record_context', { p_session: session.sessionId, p_content: args.content }));
+        if (!artifactId)
+            throw new Error('cliv2_record_context returned no artifact id.');
+        // Best-effort session attribution (mirror create_artifact). The RPC UPSERTS the
+        // same canonical row, so a repeat call re-inserts the same (kind, product_id) and
+        // trips unique(kind, product_id) (23505) — that is "already attributed", not a
+        // failure, so 23505 is swallowed silently; any OTHER error is surfaced.
+        let attributionWarning;
+        const { error: attrError } = await client.from('cliv2_agent_outputs').insert({
+            user_id: userId,
+            session_id: session.sessionId,
+            kind: 'artifact',
+            product_id: artifactId,
+        });
+        if (attrError && attrError.code !== '23505') {
+            attributionWarning = `Context recorded, but recording session attribution failed: ${attrError.message}`;
+        }
+        // Re-fetch the (live) canonical context artifact so the result matches
+        // get_task / create_artifact.
+        const artifact = await must(client.from('artifacts').select(ARTIFACT_COLUMNS).eq('id', artifactId).is('deleted_at', null).maybeSingle());
+        if (!artifact)
+            throw new Error('Recorded context artifact could not be re-fetched.');
+        return textResult(attributionWarning ? { artifact, attribution_warning: attributionWarning } : { artifact });
+    }
+    catch (err) {
+        return errorResult(`record_context_exploration failed: ${err.message}`);
+    }
+}
+/**
+ * Reserve repo-relative paths on a codebase (D5) so concurrent agents don't collide.
+ * Session-anchored and run-free: every reservation is stamped with the open session's
+ * id/task and lives in the owner-scoped `cliv2_work_reservations` table (no agent-run,
+ * no fencing token). Reservations are ADVISORY — a conflicting write lease held by
+ * another session is REPORTED, never forced or waited on.
+ *
+ * Per requested path, decide reserve vs conflict vs already-held against the ACTIVE
+ * (`released_at is null`) reservations on this codebase+path:
+ *   - CONFLICT if any active row is by a DIFFERENT session AND at least one side is a
+ *     'write' lease (write-write and write-read collide; read-read coexists). Record
+ *     `{ path, held_by_session_id }` and insert nothing.
+ *   - ALREADY-HELD if THIS session already holds an active reservation on that path —
+ *     return its existing id, no duplicate insert. Exception: a read→write UPGRADE (this
+ *     session holds a read lease and now asks for write) mutates the row's mode to
+ *     'write' in place and reports it as RESERVED, so the stronger lease is recorded.
+ *   - otherwise RESERVE — insert this session's lease and return `{ id, path, mode }`.
+ * Paths pass through verbatim; the DB CHECK rejects absolute paths, and that error is
+ * surfaced cleanly by the try/catch. Requires an open session.
+ */
+async function reserveWorkPathsHandler(client, session, args) {
+    try {
+        if (!session) {
+            return errorResult('reserve_work_paths needs an open work session — call begin_work first.');
+        }
+        const mode = args.mode ?? 'write';
+        const reserved = [];
+        const already_held = [];
+        const conflicts = [];
+        for (const path of args.paths) {
+            // Active reservations on this codebase+path, across ALL of the user's sessions
+            // (RLS scopes the read to the user's own rows).
+            const rows = (await must(client
+                .from('cliv2_work_reservations')
+                .select('id,session_id,mode')
+                .eq('git_remote_url', args.git_remote_url)
+                .eq('path', path)
+                .is('released_at', null))) ?? [];
+            // Conflict FIRST: another session holds an active lease AND at least one side is
+            // 'write' (write-write or write-read collide; read-read is fine).
+            const conflict = rows.find((r) => r.session_id !== session.sessionId && (r.mode === 'write' || mode === 'write'));
+            if (conflict) {
+                conflicts.push({ path, held_by_session_id: conflict.session_id });
+                continue;
+            }
+            // Else this session already has an active lease here. A read→write UPGRADE must
+            // record the write, else another session's later read would see no conflict and
+            // be cleared to read a file this session is rewriting. Reaching this branch with
+            // mode==='write' means the conflict check found NO other-session row on this path
+            // (with mode==='write' the conflict OR is true for ANY other-session row), so no
+            // other session holds it and upgrading in place is safe. A write→read downgrade or
+            // a same-mode repeat stays already-held.
+            const mine = rows.find((r) => r.session_id === session.sessionId);
+            if (mine) {
+                if (mine.mode === 'read' && mode === 'write') {
+                    await must(client
+                        .from('cliv2_work_reservations')
+                        .update({ mode: 'write' })
+                        .eq('id', mine.id)
+                        .eq('session_id', session.sessionId)
+                        .select('id')
+                        .single());
+                    reserved.push({ id: mine.id, path, mode: 'write' });
+                }
+                else {
+                    already_held.push({ id: mine.id, path });
+                }
+                continue;
+            }
+            // Else reserve: free (or only compatible reads by others) — insert this
+            // session's lease. user_id defaults to auth.uid() in the DB; don't set it.
+            const inserted = await must(client
+                .from('cliv2_work_reservations')
+                .insert({
+                session_id: session.sessionId,
+                task_id: session.taskId,
+                git_remote_url: args.git_remote_url,
+                path,
+                mode,
+            })
+                .select('id,path,mode')
+                .single());
+            if (!inserted)
+                throw new Error('Reservation insert returned no row.');
+            reserved.push({ id: inserted.id, path: inserted.path, mode: inserted.mode });
+        }
+        return textResult({ reserved, already_held, conflicts });
+    }
+    catch (err) {
+        return errorResult(`reserve_work_paths failed: ${err.message}`);
+    }
+}
+/**
+ * Release path reservations by id (D5). Only THIS session's still-active reservations
+ * are released: the UPDATE is scoped by `session_id` (plus RLS to the user) and
+ * `released_at is null`, so ids belonging to another session, already-released rows, or
+ * unknown ids are silently no-ops. Returns the ids actually released. Requires an open
+ * session.
+ */
+async function releaseWorkPathsHandler(client, session, args) {
+    try {
+        if (!session) {
+            return errorResult('release_work_paths needs an open work session — call begin_work first.');
+        }
+        const rows = (await must(client
+            .from('cliv2_work_reservations')
+            .update({ released_at: new Date().toISOString() })
+            .in('id', args.reservation_ids)
+            .eq('session_id', session.sessionId)
+            .is('released_at', null)
+            .select('id'))) ?? [];
+        return textResult({ released: rows.map((r) => r.id) });
+    }
+    catch (err) {
+        return errorResult(`release_work_paths failed: ${err.message}`);
+    }
+}
+/**
+ * Hand off coordination of a task to another of the CALLER'S OWN agent sessions (D5). One
+ * coordinator per task: the `cliv2_task_coordinators` row is keyed on (user_id, task_id)
+ * and UPSERTED to point at the target session. The target is validated to be one of the
+ * caller's own sessions first — `cliv2_agent_sessions` carries TWO select policies (owner
+ * AND task-read, the latter org-visible via `app.can_access_task`), so an RLS-only read
+ * would ALSO admit a teammate's session on a shared task (a confused-deputy seed whose
+ * `on delete cascade` could later nuke the caller's coordinator row). The lookup is
+ * therefore constrained to `user_id = userId`, not RLS alone. Run-free, owner-scoped
+ * (user_id defaults to auth.uid()). Requires an open session.
+ */
+async function transferCoordinationHandler(client, userId, session, args) {
+    try {
+        if (!session) {
+            return errorResult('transfer_coordination needs an open work session — call begin_work first.');
+        }
+        // The target must be one of the CALLER'S OWN sessions. RLS alone is insufficient
+        // (the task-read policy would admit a teammate's session on a shared task), so pin
+        // the read to user_id = userId.
+        const target = await must(client
+            .from('cliv2_agent_sessions')
+            .select('id')
+            .eq('id', args.target_session_id)
+            .eq('user_id', userId)
+            .maybeSingle());
+        if (!target) {
+            return errorResult('target_session_id is not a session you can coordinate to.');
+        }
+        const coordinator = await must(client
+            .from('cliv2_task_coordinators')
+            .upsert({
+            task_id: args.task_id,
+            session_id: args.target_session_id,
+            updated_at: new Date().toISOString(),
+        }, { onConflict: 'user_id,task_id' })
+            .select('task_id,session_id,updated_at')
+            .single());
+        if (!coordinator)
+            throw new Error('Coordinator upsert returned no row.');
+        return textResult({ coordinator });
+    }
+    catch (err) {
+        return errorResult(`transfer_coordination failed: ${err.message}`);
+    }
+}
+/**
+ * Record that a codebase's checkout is unavailable to this session (D5) — e.g. it isn't
+ * cloned on this machine — with an optional reason. A plain owner-scoped insert into
+ * `cliv2_unavailable_checkouts`, stamped with the open session's id (user_id defaults to
+ * auth.uid()). Only a path-free git remote URL is stored — never a local filesystem path.
+ * Requires an open session.
+ */
+async function acknowledgeUnavailableCheckoutHandler(client, session, args) {
+    try {
+        if (!session) {
+            return errorResult('acknowledge_unavailable_checkout needs an open work session — call begin_work first.');
+        }
+        const row = await must(client
+            .from('cliv2_unavailable_checkouts')
+            .insert({
+            session_id: session.sessionId,
+            git_remote_url: args.git_remote_url,
+            reason: args.reason ?? null,
+        })
+            .select('id,git_remote_url,reason,created_at')
+            .single());
+        if (!row)
+            throw new Error('Acknowledgement insert returned no row.');
+        return textResult({ acknowledgement: row });
+    }
+    catch (err) {
+        return errorResult(`acknowledge_unavailable_checkout failed: ${err.message}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Credentials (feature 08, Phase 2) — agent MCP fetch. Read-only from the
+// CLI's point of view: `list_credentials` lists names + kinds through the
+// user-session client (RLS `credentials_select` scopes rows to the ones the
+// signed-in user created, in orgs they belong to), and `get_credential`
+// resolves a name case-insensitively then calls the SECURITY DEFINER
+// `reveal_credential` RPC — the ONLY read path for the secret value. The
+// secret goes into the tool RESULT and nowhere else: never console.log'd,
+// never cached, never written to disk.
+// ---------------------------------------------------------------------------
+/** The uniform access error, verbatim from the web RPCs
+ *  (20260723130000_credentials.sql) — a caller can never distinguish
+ *  "doesn't exist" from "not yours". */
+const CREDENTIAL_NOT_FOUND = 'credential not found or not accessible';
+/**
+ * List the signed-in user's stored credentials — names + kinds ONLY, never
+ * values, secret ids, or row ids (ui.html screen 7).
+ */
+async function listCredentialsHandler(client) {
+    try {
+        const rows = (await must(client.from('credentials').select('name, kind').order('name', { ascending: true }))) ?? [];
+        return textResult(rows.map((row) => ({ name: row.name, kind: row.kind })));
+    }
+    catch (err) {
+        return errorResult(`list_credentials failed: ${err.message}`);
+    }
+}
+/**
+ * Fetch one credential's decrypted value by name (ui.html screens 8–9).
+ * The name match is case-insensitive, like the web's uniqueness rule
+ * (`lower(name)`), and is done in JS over the caller's own RLS-visible rows
+ * (row counts are tiny; no pattern-injection surface). Unknown / inaccessible
+ * name → the exact uniform error above. On a match, `reveal_credential(p_id)`
+ * returns `{secret, username}`; that maps to screen 8's shapes —
+ * api_key → `{kind, secret}`, login → `{kind, username, password}`.
+ */
+async function getCredentialHandler(client, args) {
+    let match;
+    try {
+        const rows = (await must(client
+            .from('credentials')
+            .select('id, name, kind, org_id, created_by')
+            .order('created_at', { ascending: true }))) ?? [];
+        const wanted = args.name.toLowerCase();
+        // Uniqueness is per (org, creator): the caller can see two credentials
+        // with the same lowercased name across two of their orgs, or within one
+        // org (their own plus one shared to them by another creator). Never guess
+        // which secret was meant. org_id/created_by are read only to word this
+        // error; they never appear in tool output.
+        const matches = rows.filter((row) => row.name.toLowerCase() === wanted);
+        if (matches.length > 1) {
+            const sameOrg = matches.every((row) => row.org_id === matches[0].org_id);
+            return errorResult(sameOrg
+                ? `credential name "${args.name}" is ambiguous — you can access more than one credential with this name in the same organization (e.g. your own and one shared with you); delete or re-create yours under a different name, or ask an org owner to revoke a shared copy`
+                : `credential name "${args.name}" is ambiguous — you have access to credentials with this name in more than one of your organizations; delete or re-create one under a different name`);
+        }
+        match = matches[0];
+    }
+    catch (err) {
+        return errorResult(`get_credential failed: ${err.message}`);
+    }
+    if (!match)
+        return errorResult(CREDENTIAL_NOT_FOUND);
+    try {
+        const revealed = await must(client.rpc('reveal_credential', { p_id: match.id }));
+        if (!revealed)
+            throw new Error(CREDENTIAL_NOT_FOUND);
+        return textResult(match.kind === 'login'
+            ? { kind: 'login', username: revealed.username, password: revealed.secret }
+            : { kind: 'api_key', secret: revealed.secret });
+    }
+    catch (err) {
+        // The RPC's own message, verbatim — it is already uniform (the same
+        // 'credential not found or not accessible' on any access failure).
+        return errorResult(err.message);
+    }
+}
+// ---------------------------------------------------------------------------
+// The nineteen tools this server exposes. Exported for the self-check.
+// ---------------------------------------------------------------------------
+export const TOOL_NAMES = [
+    'list_tasks',
+    'get_task',
+    'create_artifact',
+    'update_task',
+    'update_artifact',
+    'set_task_role_slugs',
+    'add_comment',
+    'create_task',
+    'begin_work',
+    'end_work',
+    'ask_question',
+    'record_user_input',
+    'record_context_exploration',
+    'reserve_work_paths',
+    'release_work_paths',
+    'transfer_coordination',
+    'acknowledge_unavailable_checkout',
+    'list_credentials',
+    'get_credential',
+];
+/** Build a per-session McpServer with the nineteen tools. A fresh instance per
+ *  session is what makes `server.server.getClientVersion()` (populated during
+ *  that session's `initialize`) the right source for attribution — mirroring
+ *  v1's per-session `buildServer`. `connectionId` is this connection's key into
+ *  the module-level `openSessions` registry (D2b). */
+export function buildToolsServer(client, userId, machineId, connectionId) {
+    const server = new McpServer({ name: 'ctrl-spc', version: '0.1.0' });
+    // The MCP connection's open work session lives in the module-level `openSessions`
+    // registry, keyed by this connection's `connectionId` (D2b). One McpServer is
+    // built per MCP connection (see startToolsServer's per-initialize buildToolsServer),
+    // so `connectionId` identifies exactly this agent's session: begin_work sets the
+    // entry; create_artifact / add_comment / create_task read it to attribute outputs;
+    // end_work (and connection-close / logout) clear it; the presence heartbeat keeps
+    // it fresh. Read the entry at call time so each tool sees the latest begin_work.
+    // This connection's agent, derived from the `initialize` clientInfo.name once
+    // it has been negotiated (/claude/i -> 'claude', /codex/i -> 'codex', else null).
+    const attribution = () => attributionFromClientName(server.server.getClientVersion()?.name);
+    server.registerTool('list_tasks', {
+        description: 'List the tasks in your CTRL+SPC projects, with project identity. Optionally filter to one project.',
+        inputSchema: { project_id: z.string().optional() },
+    }, async (args) => {
+        touchSession(connectionId);
+        return listTasksHandler(client, args);
+    });
+    server.registerTool('get_task', {
+        description: 'Read a full task — its tags, comments, artifacts, and decisions (so you can read the answers to questions ' +
+            'you asked). Read-only; it has no status or presence side effects.',
+        inputSchema: { id: z.string().describe('Task id') },
+    }, async ({ id }) => {
+        touchSession(connectionId);
+        return getTaskHandler(client, { id });
+    });
+    server.registerTool('create_artifact', {
+        description: 'Create a titled analysis/plan/spec/diagram/mock/wireframe on a task. It appears in the web UI, attributed to you.',
+        inputSchema: {
+            task_id: z.string(),
+            type: z.enum(['analysis', 'plan', 'spec', 'diagram', 'mock', 'wireframe']),
+            format: z.enum(['md', 'html', 'json', 'svg']).optional().describe('Defaults to md'),
+            title: z.string().min(1).optional(),
+            purpose_key: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Stable machine-readable identity for this artifact purpose'),
+            content: z.string(),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return createArtifactHandler(client, userId, openSessions.get(connectionId) ?? null, args);
+    });
+    server.registerTool('update_task', {
+        description: 'Update a task you own — its status (backlog / in_progress / done), name, description, or due_date. ' +
+            'Pass expected_revision from the most recent get_task for optimistic concurrency; on a conflict, ' +
+            'call get_task again to re-read and retry. The change appears in the web board.',
+        inputSchema: {
+            id: z.string().describe('Task id'),
+            expected_revision: z
+                .number()
+                .int()
+                .positive()
+                .describe('The task revision from the most recent get_task (optimistic concurrency)'),
+            fields: z.object({
+                status: z.enum(['backlog', 'in_progress', 'done']).optional(),
+                name: z.string().optional(),
+                description: z.string().optional(),
+                due_date: z.string().nullable().optional().describe('ISO date, or null to clear'),
+            }),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return updateTaskHandler(client, args);
+    });
+    server.registerTool('update_artifact', {
+        description: 'Edit an artifact you can access — its title, content, type, or format. Pass expected_revision from the ' +
+            'most recent get_task (optimistic concurrency); on a conflict, call get_task again and retry. ' +
+            'The change appears in the web UI.',
+        inputSchema: {
+            id: z.string(),
+            expected_revision: z
+                .number()
+                .int()
+                .positive()
+                .describe('The artifact revision from the most recent get_task (optimistic concurrency)'),
+            fields: z.object({
+                title: z.string().min(1).optional(),
+                type: z.enum(['analysis', 'plan', 'spec', 'diagram', 'mock', 'wireframe']).optional(),
+                format: z.enum(['md', 'html', 'json', 'svg']).optional(),
+                content: z.string().optional(),
+            }),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return updateArtifactHandler(client, args);
+    });
+    server.registerTool('set_task_role_slugs', {
+        description: 'Set the repository role slugs on a task (its role assignments). Replaces the task\'s role_slugs with ' +
+            'the given list. The change appears in the web UI.',
+        inputSchema: {
+            task_id: z.string(),
+            role_slugs: z.array(z.string()),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return setTaskRoleSlugsHandler(client, args);
+    });
+    server.registerTool('add_comment', {
+        description: 'Leave a note on a task. The comment appears in the web UI, authored by you.',
+        inputSchema: {
+            task_id: z.string().describe('Task id'),
+            body: z.string().min(1),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return addCommentHandler(client, userId, openSessions.get(connectionId) ?? null, args);
+    });
+    server.registerTool('create_task', {
+        description: 'Create a new task in one of your projects — for splitting work or leaving follow-ups. ' +
+            'It appears on the web board, owned by you.',
+        inputSchema: {
+            project_id: z.string().describe('Project id the task belongs to'),
+            name: z.string().min(1),
+            description: z.string().optional(),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return createTaskHandler(client, userId, openSessions.get(connectionId) ?? null, args);
+    });
+    server.registerTool('begin_work', {
+        description: 'Open a work session on a task so the outputs you create afterward are attributed to this run. ' +
+            'Call it once, before create_artifact, for the task you are about to work. ' +
+            'Requires a supported agent (Claude or Codex). Reusing the same task returns the existing session.',
+        inputSchema: {
+            task_id: z.string().describe('Task id you are about to work on'),
+            model: z.string().optional().describe('Optional model identifier for this session (e.g. the agent model)'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        try {
+            // begin_work needs a supported agent — the session's `provider` is a NOT
+            // NULL, checked ('claude'|'codex') column. An unrecognized client can't
+            // open one.
+            const provider = attribution();
+            if (!provider) {
+                return errorResult('begin_work needs a supported agent (Claude or Codex); this client is not recognized as one.');
+            }
+            // The task must exist and be live under the user's RLS.
+            const task = await must(client.from('tasks').select('id').eq('id', args.task_id).is('archived_at', null).maybeSingle());
+            if (!task)
+                return errorResult(`No task found for id "${args.task_id}".`);
+            // Already have a session on THIS connection for THIS task: refresh its
+            // liveness (and model, if newly provided) and reuse it — no second row.
+            const prev = openSessions.get(connectionId);
+            if (prev && prev.taskId === args.task_id) {
+                const patch = { last_seen_at: new Date().toISOString() };
+                if (args.model !== undefined)
+                    patch.model = args.model;
+                const updated = await must(client
+                    .from('cliv2_agent_sessions')
+                    .update(patch)
+                    .eq('id', prev.sessionId)
+                    .select('id,task_id,provider,model,status')
+                    .single());
+                if (!updated)
+                    throw new Error('Session update returned no row.');
+                return textResult({ session: updated });
+            }
+            // Open the NEW session FIRST (FIX 3): if this insert throws, the registry
+            // still points at the previous (valid) session rather than an ended one.
+            // `prev`, if present here, is on a DIFFERENT task (same-task returned above).
+            const session = await must(client
+                .from('cliv2_agent_sessions')
+                .insert({
+                user_id: userId,
+                machine_id: machineId,
+                task_id: args.task_id,
+                provider,
+                model: args.model ?? null,
+                status: 'active',
+            })
+                .select('id,task_id,provider,model,status')
+                .single());
+            if (!session)
+                throw new Error('Session insert returned no row.');
+            // The new session opened: if this connection was on a DIFFERENT task,
+            // best-effort mark that PREVIOUS session ended so its board "working" chip
+            // clears promptly. Best-effort — a failure must NOT fail begin_work (the new
+            // session is the real result); the old row lapses via its own TTL/freshness.
+            if (prev) {
+                try {
+                    await must(client.from('cliv2_agent_sessions').update({ status: 'ended' }).eq('id', prev.sessionId));
+                }
+                catch (err) {
+                    console.warn(`begin_work: ending previous session failed: ${err.message}`);
+                }
+            }
+            // Record the new session in the registry keyed by connectionId, with a
+            // fresh activity-TTL (extended by every subsequent tool call).
+            openSessions.set(connectionId, {
+                sessionId: session.id,
+                taskId: session.task_id,
+                expiresAt: Date.now() + SESSION_TTL_MS,
+            });
+            return textResult({ session });
+        }
+        catch (err) {
+            return errorResult(`begin_work failed: ${err.message}`);
+        }
+    });
+    server.registerTool('end_work', {
+        description: 'Close the work session you opened with begin_work, when you finish the item. ' +
+            'After this, the board no longer shows you as working it. Safe to call with no open session.',
+        inputSchema: {},
+    }, async () => {
+        touchSession(connectionId);
+        try {
+            const s = openSessions.get(connectionId);
+            if (!s) {
+                return textResult({ ended: false, message: 'No open work session on this connection.' });
+            }
+            await must(client.from('cliv2_agent_sessions').update({ status: 'ended' }).eq('id', s.sessionId));
+            openSessions.delete(connectionId);
+            return textResult({ ended: true, session_id: s.sessionId });
+        }
+        catch (err) {
+            return errorResult(`end_work failed: ${err.message}`);
+        }
+    });
+    server.registerTool('ask_question', {
+        description: "Ask the user a question about the work item you're on. It appears as a decision on the item in the web UI; " +
+            'the user answers it there, and you read the answer back with get_task. Requires an open session (begin_work).',
+        inputSchema: {
+            category: z.string().min(1),
+            context: z.string().min(1),
+            question: z.string().min(1),
+            answer_mode: z.enum(['free_text', 'single_select', 'multi_select']).optional(),
+            options: z.array(z.string()).optional(),
+            related_artifact_id: z.string().optional(),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return askQuestionHandler(client, userId, openSessions.get(connectionId) ?? null, args);
+    });
+    server.registerTool('record_user_input', {
+        description: "Record the user's answer to an open decision on your work item (e.g. an answer they gave you directly). " +
+            'Updates the decision to decided; it then shows answered in the web UI.',
+        inputSchema: {
+            decision_id: z.string().describe('The decision id to answer'),
+            answer: z.string().optional().describe('The free-text answer (for a free_text decision)'),
+            selected_options: z
+                .array(z.string())
+                .optional()
+                .describe('The chosen option(s) (for a single_select / multi_select decision)'),
+            answer_note: z.string().optional().describe('Optional note alongside a choice answer'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return recordUserInputHandler(client, openSessions.get(connectionId) ?? null, args);
+    });
+    server.registerTool('record_context_exploration', {
+        description: "Record what you explored for this work item as its context document (the canonical 'Work item context' " +
+            'for the item). Repeated calls update the same document. Appears in the web UI.',
+        inputSchema: {
+            content: z.string().min(1),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return recordContextExplorationHandler(client, userId, openSessions.get(connectionId) ?? null, args);
+    });
+    server.registerTool('reserve_work_paths', {
+        description: "Reserve repo-relative paths you're about to edit on a codebase, so concurrent agents don't collide. " +
+            'Conflicts (a write lease another session holds) are reported, not forced. ' +
+            'Paths must be repo-relative, never absolute.',
+        inputSchema: {
+            git_remote_url: z.string().min(1),
+            paths: z.array(z.string().min(1)).min(1),
+            mode: z.enum(['read', 'write']).optional().describe('Defaults to write'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return reserveWorkPathsHandler(client, openSessions.get(connectionId) ?? null, args);
+    });
+    server.registerTool('release_work_paths', {
+        description: 'Release path reservations you previously made (by id). Only your own active reservations are released.',
+        inputSchema: {
+            reservation_ids: z.array(z.string()).min(1),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return releaseWorkPathsHandler(client, openSessions.get(connectionId) ?? null, args);
+    });
+    server.registerTool('transfer_coordination', {
+        description: 'Hand off coordination of a task to another of your agent sessions (by session id). One coordinator per task.',
+        inputSchema: {
+            task_id: z.string(),
+            target_session_id: z.string(),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return transferCoordinationHandler(client, userId, openSessions.get(connectionId) ?? null, args);
+    });
+    server.registerTool('acknowledge_unavailable_checkout', {
+        description: "Record that a codebase's checkout is unavailable to you (e.g. not cloned on this machine), with an optional reason.",
+        inputSchema: {
+            git_remote_url: z.string().min(1),
+            reason: z.string().optional(),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return acknowledgeUnavailableCheckoutHandler(client, openSessions.get(connectionId) ?? null, args);
+    });
+    server.registerTool('list_credentials', {
+        description: 'List the credentials the user has stored in CTRL+SPC — the names (and kinds: api_key or login) you can ' +
+            'fetch a value for with get_credential. Names and kinds only, never values.',
+        inputSchema: {},
+    }, async () => {
+        touchSession(connectionId);
+        return listCredentialsHandler(client);
+    });
+    server.registerTool('get_credential', {
+        description: "Fetch a stored credential's value by name (case-insensitive): an api_key's secret, or a login's " +
+            'username + password. The value is for runtime use in this session only — never write it into a file, ' +
+            'commit, log, or code, and never echo it back to the user unless they explicitly ask for it.',
+        inputSchema: {
+            name: z.string().min(1).describe('Credential name, as listed by list_credentials'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return getCredentialHandler(client, args);
+    });
+    return server;
+}
+let handle = null;
+// D2b: the open work session per live MCP connection, so the presence
+// heartbeat can keep it fresh and connection-close / logout can end it. Each
+// entry carries an activity-TTL `expiresAt` (ms epoch): begin_work sets it and
+// EVERY tool call extends it (touchSession), because a tool call proves the
+// agent is alive. The companion — not the agent — drives the heartbeat, and the
+// MCP SDK only fires transport.onclose on an explicit DELETE / server stop (NOT
+// on Ctrl-C / crash / kill / sleep). Without the TTL a dead agent would stay
+// "working" forever; heartbeatOpenSessions instead lapses an entry once its TTL
+// passes, flipping the row to 'ended' so the board chip clears.
+const openSessions = new Map();
+let toolsClient = null;
+/** Extend the activity-TTL of this connection's open session, if any. Called at
+ *  the very start of every tool callback — any tool call proves the agent is
+ *  alive, so its session should stay "working" for another TTL window. No-op when
+ *  no session is open. */
+function touchSession(connectionId) {
+    const s = openSessions.get(connectionId);
+    if (s)
+        s.expiresAt = Date.now() + SESSION_TTL_MS;
+}
+/** Set (or replace) the module client the session-lifecycle helpers use, so a
+ *  token the presence loop rebuilt after a wedge/refresh flows into the session
+ *  heartbeat too (FIX 2 — the CLI-v1 stale-token root cause). Only takes effect
+ *  while the tools server is running; the per-connection tool handlers keep their
+ *  own captured client, which is acceptable — the session heartbeat is what must
+ *  stay healthy for the presence chip. */
+export function setToolsClient(client) {
+    if (handle)
+        toolsClient = client;
+}
+/** Keep every LIVE open session's last_seen_at fresh, and lapse EXPIRED ones to
+ *  'ended', so the web presence chip stays lit while an agent works and clears
+ *  once it goes quiet past its TTL (finished / Ctrl-C'd / crashed / asleep).
+ *  Called from the presence heartbeat. Partitions the registry by `expiresAt`,
+ *  deletes expired entries locally, then does up to two batched best-effort
+ *  writes. `.eq('status','active')` keeps end_work / onclose races safe (never
+ *  re-touches or re-ends a row another path already ended). Never throws. */
+export async function heartbeatOpenSessions() {
+    if (!toolsClient || openSessions.size === 0)
+        return;
+    const now = Date.now();
+    const liveIds = [];
+    const expiredIds = [];
+    for (const [connectionId, s] of openSessions) {
+        if (now < s.expiresAt) {
+            liveIds.push(s.sessionId);
+        }
+        else {
+            expiredIds.push(s.sessionId);
+            openSessions.delete(connectionId);
+        }
+    }
+    if (liveIds.length) {
+        try {
+            const { error } = await toolsClient
+                .from('cliv2_agent_sessions')
+                .update({ last_seen_at: new Date().toISOString() })
+                .in('id', liveIds)
+                .eq('status', 'active');
+            if (error)
+                throw error;
+        }
+        catch (err) {
+            console.warn(`open-session heartbeat failed, will retry: ${err.message}`);
+        }
+    }
+    if (expiredIds.length) {
+        try {
+            const { error } = await toolsClient
+                .from('cliv2_agent_sessions')
+                .update({ status: 'ended' })
+                .in('id', expiredIds)
+                .eq('status', 'active');
+            if (error)
+                throw error;
+        }
+        catch (err) {
+            console.warn(`lapsing expired sessions failed: ${err.message}`);
+        }
+    }
+}
+/** Mark ONE connection's open session ended (connection closed). Best-effort. */
+export async function endConnectionSession(connectionId) {
+    const s = openSessions.get(connectionId);
+    if (!toolsClient || !s) {
+        openSessions.delete(connectionId);
+        return;
+    }
+    openSessions.delete(connectionId);
+    try {
+        const { error } = await toolsClient
+            .from('cliv2_agent_sessions')
+            .update({ status: 'ended' })
+            .eq('id', s.sessionId);
+        if (error)
+            throw error;
+    }
+    catch (err) {
+        console.warn(`ending session on connection close failed: ${err.message}`);
+    }
+}
+/** Mark ALL open sessions ended and clear the registry (server stop / logout). */
+export async function endAllOpenSessions() {
+    if (openSessions.size === 0) {
+        return;
+    }
+    const sessionIds = [...openSessions.values()].map((s) => s.sessionId);
+    openSessions.clear();
+    if (!toolsClient)
+        return;
+    try {
+        const { error } = await toolsClient
+            .from('cliv2_agent_sessions')
+            .update({ status: 'ended' })
+            .in('id', sessionIds);
+        if (error)
+            throw error;
+    }
+    catch (err) {
+        console.warn(`ending all open sessions failed: ${err.message}`);
+    }
+}
+async function readJsonBody(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(chunk);
+    const raw = Buffer.concat(chunks).toString('utf8');
+    return raw ? JSON.parse(raw) : undefined;
+}
+/** Start the local tools server. No-op if already running. Binds loopback-only;
+ *  rejects if the port is taken (caller treats a failure as best-effort). */
+export async function startToolsServer(deps) {
+    if (handle)
+        return;
+    // D2b: capture the client so the session-lifecycle helpers (heartbeat / end)
+    // can reach Supabase without a live MCP connection in hand.
+    toolsClient = deps.client;
+    const port = TOOLS_SERVER_PORT;
+    const sessions = new Map();
+    async function handleHttp(req, res) {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        if (url.pathname === '/health' && req.method === 'GET') {
+            res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+            res.end(JSON.stringify({ status: 'ok', server: 'ctrl-spc', process_id: process.pid }));
+            return;
+        }
+        if (url.pathname !== '/mcp') {
+            res.writeHead(404).end('Not found');
+            return;
+        }
+        try {
+            const sessionIdHeader = req.headers['mcp-session-id'];
+            const sessionId = typeof sessionIdHeader === 'string' ? sessionIdHeader : undefined;
+            const existing = sessionId ? sessions.get(sessionId) : undefined;
+            if (existing) {
+                await existing.handleRequest(req, res);
+                return;
+            }
+            if (req.method !== 'POST') {
+                res.writeHead(400, { 'Content-Type': 'text/plain' }).end('Bad Request: no valid session ID provided');
+                return;
+            }
+            const body = await readJsonBody(req);
+            if (!isInitializeRequest(body)) {
+                res.writeHead(400, { 'Content-Type': 'text/plain' }).end('Bad Request: no valid session ID provided');
+                return;
+            }
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (sid) => {
+                    sessions.set(sid, transport);
+                },
+                // Same DNS-rebinding guard as v1: reject any Host header that isn't the
+                // loopback address we actually bound, so a page on a public domain that
+                // re-resolves to 127.0.0.1 can't drive this server from the browser.
+                enableDnsRebindingProtection: true,
+                allowedHosts: [`localhost:${port}`, `127.0.0.1:${port}`],
+            });
+            // D2b: one connectionId per MCP connection, keying this connection's entry
+            // in openSessions. Generated before building the server so begin_work and
+            // onclose share the same key.
+            const connectionId = randomUUID();
+            transport.onclose = () => {
+                const sid = transport.sessionId;
+                if (sid)
+                    sessions.delete(sid);
+                // Connection dropped: end this connection's open session (best-effort).
+                void endConnectionSession(connectionId);
+            };
+            const server = buildToolsServer(deps.client, deps.userId, deps.machineId, connectionId);
+            await server.connect(transport);
+            await transport.handleRequest(req, res, body);
+        }
+        catch (err) {
+            if (!res.headersSent) {
+                res
+                    .writeHead(500, { 'Content-Type': 'application/json' })
+                    .end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32603, message: err.message }, id: null }));
+            }
+        }
+    }
+    const httpServer = createHttpServer((req, res) => void handleHttp(req, res));
+    // Bind loopback-only (never all interfaces) and turn the EADDRINUSE 'error'
+    // race into a rejected promise so the caller stays best-effort.
+    await new Promise((resolve, reject) => {
+        const onError = (err) => {
+            httpServer.off('listening', onListening);
+            reject(err);
+        };
+        const onListening = () => {
+            httpServer.off('error', onError);
+            resolve();
+        };
+        httpServer.once('error', onError);
+        httpServer.once('listening', onListening);
+        httpServer.listen(port, '127.0.0.1');
+    });
+    handle = {
+        async close() {
+            await Promise.all([...sessions.values()].map((t) => t.close().catch(() => { })));
+            sessions.clear();
+            await new Promise((resolve, reject) => {
+                httpServer.close((err) => (err ? reject(err) : resolve()));
+            });
+        },
+    };
+}
+/** Stop the tools server. Best-effort; safe to call when not running. */
+export async function stopToolsServer() {
+    const h = handle;
+    if (!h)
+        return;
+    handle = null;
+    regStatus.claude = 'idle';
+    regStatus.codex = 'idle';
+    // D2b: flip every open work session to ended (this needs toolsClient) BEFORE
+    // dropping the client reference, so the board's "working" chips clear on server
+    // stop / logout; then release the client alongside the reg-status resets.
+    await endAllOpenSessions();
+    toolsClient = null;
+    await h.close();
+}
+/** Whether the tools server is currently listening, and its fixed port. */
+export function toolsServerStatus() {
+    return { running: handle !== null, port: TOOLS_SERVER_PORT };
+}
+const regStatus = { claude: 'idle', codex: 'idle' };
+/**
+ * Per-agent SERIAL operation chain. register and unregister for the same agent
+ * must never interleave. `runRegister` does a slow (~7s) `mcp remove` then
+ * `mcp add`; a logout `unregisterFromX` issues its own `mcp remove`. With no
+ * ordering, an in-flight register's `add` can land AFTER logout's `remove`,
+ * re-writing a dead `ctrl-spc` entry into the agent config after the tools
+ * server is already gone — the exact dangling entry this feature prevents.
+ * Enqueuing every register/unregister onto this chain forces them to run in call
+ * order, so a logout queued mid-register runs AFTER the register's `add`
+ * completes → the entry ends up removed. Both queued ops never throw
+ * (`runRegister` and `actualUnregister` catch internally), so the chain always
+ * stays resolved.
+ */
+const opChain = {
+    claude: Promise.resolve(),
+    codex: Promise.resolve(),
+};
+const execFileAsync = promisify(execFile);
+/** Snapshot of each agent's registration lifecycle state (copy — callers can't
+ *  mutate the module's map). Drives the companion's connecting/connected/failed
+ *  badge (see badgeReason). */
+export function agentRegStatus() {
+    return { ...regStatus };
+}
+/** True once the ctrl-spc server has been registered into Claude this run. */
+export function isClaudeRegistered() {
+    return regStatus.claude === 'registered';
+}
+/** True once the ctrl-spc server has been registered into Codex this run. */
+export function isCodexRegistered() {
+    return regStatus.codex === 'registered';
+}
+/** The remove-then-add itself, run in the background off a fire-and-forget
+ *  register call. Ignores the remove result (a not-found exits non-zero), then
+ *  runs the add: success → 'registered', any error/timeout → 'failed'. Never
+ *  throws — it's caught here and reflected only in regStatus. */
+async function runRegister(agent, bin, removeArgs, addArgs) {
+    try {
+        await execFileAsync(bin, removeArgs, { timeout: 15000 });
+    }
+    catch {
+        /* not registered yet — fine */
+    }
+    try {
+        await execFileAsync(bin, addArgs, { timeout: 15000 });
+        regStatus[agent] = 'registered';
+    }
+    catch (err) {
+        console.warn(`Could not register ctrl-spc tools with ${agent}: ${err.message}`);
+        regStatus[agent] = 'failed';
+    }
+}
+/**
+ * Register the running tools server into Claude Code's user config. Non-blocking:
+ * resolves the `claude` binary the same way agents.ts does, marks 'registering'
+ * synchronously, then kicks off the async remove-then-add and returns immediately
+ * (the CLI's ~7s latency runs off the event loop, so sign-in no longer freezes).
+ * Best-effort — never throws. Registers the loopback `/mcp` endpoint (the only
+ * path handleHttp serves the MCP protocol on). Only that loopback URL reaches the
+ * LOCAL `~/.claude.json`; no absolute filesystem path and nothing cloud-bound is
+ * written.
+ */
+export function registerWithClaude(port) {
+    const bin = agentPath('claude');
+    if (!bin) {
+        regStatus.claude = 'failed';
+        return;
+    }
+    // Double-kick guard: a register is already queued/in-flight for this agent, so
+    // don't enqueue a second one. This makes the heartbeat retry (presence.ts) safe
+    // to fire every tick — it can't stack a second `mcp add` while one is running.
+    if (regStatus.claude === 'registering')
+        return;
+    regStatus.claude = 'registering';
+    const target = `http://127.0.0.1:${port}/mcp`;
+    opChain.claude = opChain.claude.then(() => runRegister('claude', bin, ['mcp', 'remove', '--scope', 'user', 'ctrl-spc'], ['mcp', 'add', '--scope', 'user', '--transport', 'http', 'ctrl-spc', target]));
+}
+/**
+ * Register the running tools server into Codex's config (Phase 2). Codex's
+ * `mcp add` is global (no `--scope`) and takes `--url` for a streamable HTTP
+ * server: `codex mcp add <name> --url <url>` / `codex mcp remove <name>`. Same
+ * non-blocking, best-effort, idempotent contract as Claude's.
+ */
+export function registerWithCodex(port) {
+    const bin = agentPath('codex');
+    if (!bin) {
+        regStatus.codex = 'failed';
+        return;
+    }
+    // Double-kick guard — see registerWithClaude.
+    if (regStatus.codex === 'registering')
+        return;
+    regStatus.codex = 'registering';
+    const target = `http://127.0.0.1:${port}/mcp`;
+    opChain.codex = opChain.codex.then(() => runRegister('codex', bin, ['mcp', 'remove', 'ctrl-spc'], ['mcp', 'add', 'ctrl-spc', '--url', target]));
+}
+/** The actual `mcp remove` for logout cleanup, run ON the agent's op chain so it
+ *  can never interleave with an in-flight register's `add`. Best-effort — swallows
+ *  errors and always lands the status back at 'idle'. Never throws (keeps the
+ *  chain resolved). Claude's remove is user-scoped; Codex's is global. */
+async function actualUnregister(agent) {
+    const bin = agentPath(agent);
+    if (bin) {
+        const removeArgs = agent === 'claude'
+            ? ['mcp', 'remove', '--scope', 'user', 'ctrl-spc']
+            : ['mcp', 'remove', 'ctrl-spc'];
+        try {
+            await execFileAsync(bin, removeArgs, { timeout: 15000 });
+        }
+        catch {
+            /* best-effort — a leftover entry is the pre-fix state */
+        }
+    }
+    regStatus[agent] = 'idle';
+}
+/**
+ * Remove the ctrl-spc entry from Claude's user config (logout cleanup). Enqueues
+ * the removal on the SAME per-agent op chain as register and returns that promise,
+ * so a logout queued while a register is in flight runs AFTER the register's `add`
+ * completes → the entry ends up removed (never re-written after the server is
+ * gone). Best-effort — swallows errors and always lands the status back at 'idle',
+ * so a logged-out machine leaves no dead ctrl-spc server that would show "failed to
+ * connect" the next time the user runs an agent. If Claude isn't installed there's
+ * nothing to remove; the status is reset regardless.
+ */
+export function unregisterFromClaude() {
+    return (opChain.claude = opChain.claude.then(() => actualUnregister('claude')));
+}
+/** Remove the ctrl-spc entry from Codex's config (logout cleanup). Same op-chain
+ *  ordering, best-effort, reset-to-'idle' contract as Claude's. */
+export function unregisterFromCodex() {
+    return (opChain.codex = opChain.codex.then(() => actualUnregister('codex')));
+}
+const CAP = { claude: 'Claude', codex: 'Codex' };
+/**
+ * Decide the badge state from the live signals:
+ *  - not signed in                    → signed-out
+ *  - no supported agent installed     → no-agent
+ *  - tools server not running         → failed
+ *  - any installed agent still idle/registering → connecting (lists all installed)
+ *  - else any registered              → connected (lists the registered ones)
+ *  - else (all installed failed)      → failed
+ */
+export function badgeReason(input) {
+    const server = 'ctrl-spc';
+    const { signedIn, installed, serverRunning, status } = input;
+    if (!signedIn)
+        return { connected: false, reason: 'signed-out', agent: '', server };
+    if (installed.length === 0)
+        return { connected: false, reason: 'no-agent', agent: '', server };
+    if (!serverRunning)
+        return { connected: false, reason: 'failed', agent: '', server };
+    const pending = installed.filter((a) => status[a] === 'registering' || status[a] === 'idle');
+    const registered = installed.filter((a) => status[a] === 'registered');
+    if (pending.length) {
+        return { connected: false, reason: 'connecting', agent: installed.map((a) => CAP[a]).join(', '), server };
+    }
+    if (registered.length) {
+        return { connected: true, reason: 'connected', agent: registered.map((a) => CAP[a]).join(', '), server };
+    }
+    return { connected: false, reason: 'failed', agent: '', server };
+}