@ctrl-spc/cs 0.2.0 → 0.3.1

package/dist/mcp.js

@@ -0,0 +1,2332 @@
+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';
+import { mcpToken, readSession } from './config.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}`);
+    }
+}
+/** Columns a feedback round exposes to the agent (feature 09, Phase 5) — the
+ *  web writes `artifact_feedback` rows (cumulative review rounds, each tagged
+ *  with the presentation's primary artifact and its revision at send time); the
+ *  CLI reads them through RLS `artifact_feedback_select`
+ *  (`app.can_access_task`). Round BODIES stay web-written and immutable; the
+ *  ONE thing the CLI writes back is resolution state, via `resolve_feedback`
+ *  (hybrid resolution — the DB's status-only guard rejects any other change).
+ *  status ('open' | 'resolved' | 'reopened'), resolved_in_revision (the
+ *  revision the resolver claims addressed the round), and status_changed_at
+ *  make each round's state obvious: 'open' / 'reopened' rounds need attention,
+ *  'resolved' ones don't. */
+const FEEDBACK_BASE_COLUMNS = 'id,artifact_id,artifact_revision,body,created_at,created_by';
+const FEEDBACK_COLUMNS = `${FEEDBACK_BASE_COLUMNS},status,resolved_in_revision,status_changed_at`;
+/** True when a PostgREST/Postgres error means "column does not exist"
+ *  (SQLSTATE 42703) — the shape a database that predates migration
+ *  20260724210000 returns for the resolution columns. Detected narrowly (code
+ *  or message) so every other failure keeps surfacing as a real error. */
+function isUndefinedColumnError(error) {
+    return error.code === '42703' || /column .* does not exist/i.test(error.message);
+}
+/**
+ * Fetch a task's feedback rounds, degrading gracefully against a database that
+ * predates migration 20260724210000 (the published CLI is versioned
+ * independently of DB migrations): if selecting the resolution columns fails
+ * with an undefined-column error, retry with the pre-resolution column list
+ * and default every round to status 'open' with null resolution stamps —
+ * mirroring the web's degrade posture — instead of letting the whole get_task
+ * die. Any OTHER error still throws, so genuinely failed queries surface
+ * through get_task's normal error path.
+ */
+async function fetchFeedbackRounds(client, taskId) {
+    const roundsQuery = (columns) => client
+        .from('artifact_feedback')
+        .select(columns)
+        .eq('task_id', taskId)
+        .order('created_at', { ascending: true })
+        .order('id', { ascending: true });
+    const { data, error } = await roundsQuery(FEEDBACK_COLUMNS);
+    if (!error)
+        return data ?? [];
+    if (!isUndefinedColumnError(error))
+        throw new Error(error.message);
+    const rows = await must(roundsQuery(FEEDBACK_BASE_COLUMNS));
+    return (rows ?? []).map((row) => ({
+        ...row,
+        status: 'open',
+        resolved_in_revision: null,
+        status_changed_at: null,
+    }));
+}
+/**
+ * Read one task by id (RLS-scoped) with its tags, comments, live artifacts,
+ * decisions (D3 — so the agent can read the answers to questions it asked), and
+ * feedback rounds (feature 09, Phase 5 — the cumulative wireframe-review rounds
+ * the user sends from the web, each tagged with the presented primary artifact
+ * and its revision at send time; per-note option attribution is inline in the
+ * body).
+ * 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, feedback] = 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 })),
+            // Feature 09 Phase 5: the item's feedback rounds — cumulative review
+            // rounds the user sent on presented artifacts (bodies web-written and
+            // immutable), oldest first, each tagged with the presentation's primary
+            // artifact and its revision at send time (the presentation's version
+            // stamp; option attribution is inline in the round's body). Each carries
+            // its resolution state (status / resolved_in_revision /
+            // status_changed_at) so the agent can tell which rounds still need
+            // attention ('open' / 'reopened') and which don't ('resolved'). Against
+            // a pre-20260724210000 database the helper degrades to the base columns
+            // with defaulted resolution state rather than failing the whole read.
+            fetchFeedbackRounds(client, row.id),
+        ]);
+        const { task_tags: _drop, ...task } = row;
+        return textResult({
+            task: { ...task, tags: tagsOf(row) },
+            comments: comments ?? [],
+            artifacts: artifacts ?? [],
+            decisions: decisions ?? [],
+            feedback: feedback ?? [],
+        });
+    }
+    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.');
+        }
+        // The 'wireframe_option:' namespace is reserved exactly like 'context:'
+        // (feature 09, Phase 2): the web suppresses idx > 0 wireframe_option
+        // artifacts from the Artifacts list, so an agent re-using a purpose_key it
+        // saw in a present_wireframes / present_mocks result could silently hide an
+        // ordinary artifact. Mocks share the namespace deliberately (feature 10),
+        // so this ONE reservation covers both tools.
+        // update_artifact cannot set purpose_key at all (its patch is
+        // built only from title/type/format/content), so INSERT is the only door.
+        if (args.purpose_key?.trim().startsWith('wireframe_option:')) {
+            return errorResult("The purpose_key prefix 'wireframe_option:' is reserved for present_wireframes / present_mocks presentations.");
+        }
+        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}`);
+    }
+}
+/** Option labels the review outcome reserves (feature 09, Phase 2): 'approve'
+ *  is the single-shape approval sentinel `answer_task_decision_v2`'s machinery
+ *  keys on to auto-write `artifact_approvals`, and 'request changes' is the
+ *  iterate outcome appended to EVERY review decision's options. A user-named
+ *  option matching either (case-insensitively) would collide with the outcome
+ *  derivation, so validation rejects them. */
+const RESERVED_OPTION_LABELS = ['approve', 'request changes'];
+/**
+ * Present 1..N renders to the user for fullscreen review — the composition BOTH
+ * review tools run (feature 09-present-wireframes-tool Phase 2, which REPLACED
+ * Phase 1's free_text shape; feature 10-present-mocks-tool Phase 1–2). The caller
+ * supplies a `spec`; the plumbing below is identical for wireframes and mocks
+ * on purpose, so the web's ONE review surface serves both. A COMPOSITION of
+ * existing plumbing — no new tables, no migrations, no new RPCs:
+ *   1. each render becomes a normal artifact on the SESSION'S task, inserted
+ *      exactly the way create_artifact does (AS THE USER, `from_agent` null —
+ *      the deployed guard reserves agent attribution for the coordinated path
+ *      this feature does not use — plus the same best-effort
+ *      cliv2_agent_outputs attribution, one row per artifact): type
+ *      'wireframe' for a UI diagram, 'diagram' for an architecture diagram,
+ *      'mock' for an interactive mock, format 'html'. The multi shape
+ *      (options: 2..11 of {label, html})
+ *      creates one artifact per option, in order, and maps option ↔ artifact
+ *      through purpose_key 'wireframe_option:<presentation-uuid>:<idx>' on
+ *      EVERY option artifact (idx 0 included) — the web matches decision
+ *      options[i] to the artifact with idx i. Idx 0 is the PRIMARY: it carries
+ *      the presentation title verbatim (idx > 0 titles are '<title> — <label>')
+ *      and the review decision relates to it. The single shape (html) stays
+ *      exactly Phase 1's one untagged artifact — NO purpose_key.
+ *   2. the review request becomes a single_select decision opened through the
+ *      SAME `cliv2_ask_question` RPC ask_question uses — category
+ *      'wireframe_review' is the sentinel the web keys on to render the
+ *      fullscreen review surface instead of a plain question, the context
+ *      carries the title, and `p_related_artifact` points at the primary
+ *      artifact. Options: ['approve', 'request changes'] (single) or
+ *      [...labels, 'request changes'] (multi). One uniform outcome for 1..N:
+ *      the user either APPROVES — 'approve' is the exact shape
+ *      answer_task_decision_v2 keys on to auto-write artifact_approvals;
+ *      picking an option label IS approving that option (derived in the web) —
+ *      or requests changes; their comment rides along as answer_note. Hence
+ *      'approve' / 'request changes' are RESERVED label values, and the DB's
+ *      12-option decision cap bounds the labels at 11.
+ * The review loop (Phase 5 — cumulative feedback rounds): the user sends any
+ * number of feedback rounds, any time, without waiting — each is a web-written
+ * `artifact_feedback` row tagged with the presentation's PRIMARY (idx 0)
+ * artifact and its artifact_revision at send time. That tag is the version
+ * stamp of the presentation as a whole, NOT a per-option pointer: in a
+ * multi-option presentation, which option a note concerns is named inline in
+ * the note's "(…)" option label within the round's body. The agent reads the
+ * rounds from get_task's `feedback` list (oldest first). The
+ * decision above is the APPROVAL GATE only: it stays open across rounds and
+ * decides ONLY when the user approves (selected_options[0] 'approve' or an
+ * option label; answer_note may carry a final comment). To iterate, the agent
+ * revises the presented render IN PLACE with update_artifact — the DB bumps
+ * its revision automatically, so later rounds self-identify against the new
+ * version — and keeps polling; it must NOT call the presentation tool again for
+ * iterations of the same design. Requires an open session (like ask_question —
+ * the decision lives on the session's task, so there's no task_id arg). Full
+ * version history is a later phase.
+ */
+async function presentationHandler(client, userId, session, args, spec) {
+    try {
+        if (!session) {
+            return errorResult(`${spec.tool} needs an open work session — call begin_work first.`);
+        }
+        if (!args.title || !args.title.trim())
+            return errorResult(`${spec.tool} requires a non-empty title.`);
+        const extra = spec.extraValidation?.();
+        if (extra)
+            return errorResult(extra);
+        // Exactly ONE of the two shapes: html (a single render, exactly Phase 1)
+        // or options (2..11 competing renders).
+        const hasHtml = args.html !== undefined;
+        const hasOptions = args.options !== undefined;
+        if (hasHtml && hasOptions) {
+            return errorResult(`${spec.tool} takes either html (one ${spec.unit}) or options (2..11 competing ${spec.unit}s), not both.`);
+        }
+        if (!hasHtml && !hasOptions) {
+            return errorResult(`${spec.tool} requires html (one ${spec.unit}) or options (2..11 competing ${spec.unit}s).`);
+        }
+        const multi = hasOptions;
+        let opts = [];
+        if (multi) {
+            if (!Array.isArray(args.options) || args.options.length < 2 || args.options.length > 11) {
+                return errorResult(`${spec.tool} requires 2..11 options (use html for a single ${spec.unit}; a review decision is capped at 12 options including the reserved one).`);
+            }
+            opts = args.options.map((option) => ({ label: (option.label ?? '').trim(), html: option.html ?? '' }));
+            if (opts.some((o) => !o.label)) {
+                return errorResult(`${spec.tool} requires a non-empty label for every option.`);
+            }
+            if (opts.some((o) => !o.html.trim())) {
+                return errorResult(`${spec.tool} requires non-empty html for every option (${spec.htmlSpec}).`);
+            }
+            const lowered = opts.map((o) => o.label.toLowerCase());
+            if (new Set(lowered).size !== lowered.length) {
+                return errorResult(`${spec.tool} requires distinct option labels (case-insensitive).`);
+            }
+            if (lowered.some((label) => RESERVED_OPTION_LABELS.includes(label))) {
+                return errorResult(`${spec.tool} option labels 'approve' and 'request changes' are reserved review outcomes — rename the option.`);
+            }
+        }
+        else if (!args.html || !args.html.trim()) {
+            return errorResult(`${spec.tool} requires non-empty html (${spec.htmlSpec}).`);
+        }
+        const title = args.title.trim();
+        // Sentence-initial form of the artifact noun, for the attribution warning.
+        const capitalNoun = spec.artifactNoun.charAt(0).toUpperCase() + spec.artifactNoun.slice(1);
+        // The review decision's question — the recovery message below quotes it
+        // LITERALLY, so both must come from this one string.
+        const question = `Review the ${spec.artifactNoun} and leave feedback.`;
+        // One entry per artifact to create, in presentation order (idx 0 = the
+        // primary). Multi tags EVERY entry with the option ↔ artifact mapping key;
+        // single stays untagged, exactly Phase 1.
+        const presentationId = multi ? randomUUID() : null;
+        const renders = multi
+            ? opts.map((option, idx) => ({
+                title: idx === 0 ? title : `${title} — ${option.label}`,
+                html: option.html,
+                purpose_key: `wireframe_option:${presentationId}:${idx}`,
+            }))
+            : [{ title, html: args.html, purpose_key: null }];
+        // The review decision's options: the approval outcome(s) first, 'request
+        // changes' always last (the DB caps decision options at 12, hence ≤11 labels).
+        const reviewOptions = multi ? [...opts.map((o) => o.label), 'request changes'] : ['approve', 'request changes'];
+        // The renders land on the session's task. Confirm it is live under the
+        // user's RLS first (mirrors create_artifact) so a task archived after
+        // begin_work gets a clean error instead of an opaque insert failure.
+        const task = await must(client.from('tasks').select('id').eq('id', session.taskId).is('archived_at', null).maybeSingle());
+        if (!task)
+            return errorResult(`No task found for id "${session.taskId}".`);
+        // 1. Each render as a normal artifact — the SAME insert create_artifact
+        // does, one row per render, in presentation order.
+        const created = [];
+        const attributionWarnings = [];
+        for (const render of renders) {
+            let row = null;
+            try {
+                row = await must(client
+                    .from('artifacts')
+                    .insert({
+                    task_id: session.taskId,
+                    type: spec.artifactType,
+                    format: 'html',
+                    title: render.title,
+                    ...(render.purpose_key ? { purpose_key: render.purpose_key } : {}),
+                    content: render.html,
+                    created_by: userId,
+                    from_agent: null,
+                    agent_run_id: null,
+                })
+                    .select(ARTIFACT_COLUMNS)
+                    .single());
+                if (!row)
+                    throw new Error('Artifact insert returned no row.');
+            }
+            catch (err) {
+                // Nothing created yet → fatal and generic, exactly the Phase 1 path.
+                if (created.length === 0)
+                    throw err;
+                // A later option insert failing orphans the already-created options:
+                // return them (ids included) with guidance the agent can actually act
+                // on. No tool can delete an artifact (update_artifact has no deleted_at
+                // and there is no delete tool), so "clean up" is not an instruction the
+                // agent can execute — removal is a manual web action, and the agent's
+                // job is to surface it and hold off re-presenting (a blind retry would
+                // duplicate the created options).
+                const createdIds = created.map((row) => row.id).join(', ');
+                const failure = {
+                    artifacts: created,
+                    error: `${spec.tool}: created ${created.length} of ${renders.length} option artifacts, then the insert for ` +
+                        `'${render.title}' failed: ${err.message}. No review request was opened. There is no delete ` +
+                        `tool: the created artifacts (${createdIds}) are inert until removed manually in the web. Report this ` +
+                        `failure to the user with those ids, and do NOT call ${spec.tool} again (it would duplicate the ` +
+                        'created options) until the user confirms.',
+                };
+                if (attributionWarnings.length)
+                    failure.attribution_warning = attributionWarnings.join(' ');
+                return { ...textResult(failure), isError: true };
+            }
+            created.push(row);
+            // Best-effort session attribution per artifact (mirrors create_artifact:
+            // the session's task matches by construction). The artifact already exists
+            // and is part of the real return value, so a failed attribution write must
+            // NOT fail the tool — it is surfaced in the returned text, never dropped.
+            try {
+                await must(client.from('cliv2_agent_outputs').insert({
+                    user_id: userId,
+                    session_id: session.sessionId,
+                    kind: 'artifact',
+                    product_id: row.id,
+                }));
+            }
+            catch (err) {
+                attributionWarnings.push(`${capitalNoun} artifact created, but recording session attribution failed: ${err.message}`);
+            }
+        }
+        const primary = created[0];
+        // 2. The review request as a single_select decision — the SAME RPC
+        // ask_question uses; 'wireframe_review' is the sentinel category the web
+        // keys on (feature 09). The artifacts above already exist, so from here a
+        // failure must NOT be the generic fatal error: swallowing them would orphan
+        // them in the DB (plain cards with no "feedback requested"), leave the
+        // agent with no ids to recover with, and invite a blind retry that
+        // duplicates artifacts. So this step gets its OWN try/catch (the FIRST
+        // artifact-insert failure path above stays fatal and generic), and on
+        // failure the error result STILL carries the created artifact(s) plus a
+        // message telling the agent to retry the review step — via ask_question
+        // with related_artifact_id — or clean up, not re-present.
+        let decision;
+        try {
+            const decisionId = await must(client.rpc('cliv2_ask_question', {
+                p_session: session.sessionId,
+                p_category: 'wireframe_review',
+                p_context: title,
+                p_question: question,
+                p_answer_mode: 'single_select',
+                p_options: reviewOptions,
+                p_related_artifact: primary.id,
+            }));
+            if (!decisionId)
+                throw new Error('Review request insert returned no decision id.');
+            // Best-effort attribution for the decision (mirrors ask_question exactly).
+            try {
+                await must(client.from('cliv2_agent_outputs').insert({
+                    user_id: userId,
+                    session_id: session.sessionId,
+                    kind: 'decision',
+                    product_id: decisionId,
+                }));
+            }
+            catch (err) {
+                attributionWarnings.push(`Review request 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 can later read the feedback back with
+            // get_task.
+            const fetched = await must(client.from('decisions').select(DECISION_COLUMNS).eq('id', decisionId).maybeSingle());
+            if (!fetched)
+                throw new Error('Created review decision could not be re-fetched.');
+            decision = fetched;
+        }
+        catch (err) {
+            // The recovery instruction must be LITERAL and complete: the web's review
+            // surface matches ONLY category === 'wireframe_review' (a sentinel that is
+            // deliberately not in any tool description, and that mocks reuse verbatim
+            // — there is no 'mock_review'), and the decision-consistency
+            // guard makes category immutable — so a plausible-but-wrong retry category
+            // would leave the review permanently stuck as a generic question. Spell out
+            // the exact ask_question call, with the real title, the full literal
+            // options array, and the primary artifact id. The multi failure payload
+            // carries ALL created artifacts (ids included).
+            const optionsLiteral = `[${reviewOptions.map((label) => `'${label}'`).join(', ')}]`;
+            const failure = {
+                ...(multi ? { artifacts: created } : { artifact: primary }),
+                error: `${spec.tool}: the ${spec.artifactNoun} artifact${multi ? 's were' : ' was'} created, but opening the review request failed: ` +
+                    `${err.message}. Do NOT call ${spec.tool} again (it would duplicate the artifact${multi ? 's' : ''}) — ` +
+                    `retry the review step with ask_question({ category: 'wireframe_review', context: '${title}', ` +
+                    `question: '${question}', answer_mode: 'single_select', ` +
+                    `options: ${optionsLiteral}, related_artifact_id: '${primary.id}' }) — the category string must be exactly ` +
+                    "'wireframe_review' or the web will not show the review UI — or clean up.",
+            };
+            if (attributionWarnings.length)
+                failure.attribution_warning = attributionWarnings.join(' ');
+            return { ...textResult(failure), isError: true };
+        }
+        const payload = {
+            ...(multi ? { artifacts: created } : { artifact: primary }),
+            decision,
+            instruction: multi
+                ? `The user has been asked to review ${created.length} competing options. They send CUMULATIVE feedback ` +
+                    "rounds — any number, any time, without waiting for you: poll get_task and read them from its `feedback` " +
+                    'list (oldest first). Every round is tagged with the presentation PRIMARY artifact (the first option) and ' +
+                    'its artifact_revision at send time — the version stamp of the presentation, NOT a per-option pointer. ' +
+                    "Which OPTION a note concerns is named inline in the note's \"(…)\" option label within the round's body. " +
+                    'This decision is the approval gate only: it stays open across rounds and decides ONLY when the user ' +
+                    'approves — once its state is decided, selected_options[0] is the approved option label and answer_note ' +
+                    'may carry a final comment. To act on feedback, revise the option artifact each note names IN PLACE with ' +
+                    'update_artifact (its revision bumps automatically), then call resolve_feedback with the ids of the ' +
+                    "rounds that revision actually addressed and the revised OPTION artifact's NEW revision number — only " +
+                    'rounds you genuinely acted on. Option revisions are their own number-space (not the primary v-tags): ' +
+                    'the review surface shows a multi round as resolved WITHOUT a version number, so name WHICH option you ' +
+                    'revised in any accompanying update, and never expect the primary revision to move when only options ' +
+                    "changed. A round the user flips back to 'reopened' is open feedback again: address it on the next pass " +
+                    `and re-resolve. Keep polling. Do NOT call ${spec.tool} ` +
+                    'again for iterations of this same design.'
+                : `The user has been asked to review the ${spec.artifactNoun}. They send CUMULATIVE feedback rounds — any number, any ` +
+                    "time, without waiting for you: poll get_task and read them from its `feedback` list (oldest first), each " +
+                    'tagged with the artifact_revision it critiques so you know which version the notes are about. This ' +
+                    'decision is the approval gate only: it stays open across rounds and decides ONLY when the user approves ' +
+                    "— once its state is decided, selected_options[0] is 'approve' and answer_note may carry a final comment. " +
+                    `To act on feedback, revise this ${spec.artifactNoun} IN PLACE with update_artifact (its revision bumps ` +
+                    'automatically, so later rounds name the new version), then call resolve_feedback with the ids of the ' +
+                    'rounds that revision actually addressed and the NEW revision number — only rounds you genuinely acted ' +
+                    "on. A round the user flips back to 'reopened' is open feedback again: address it on the next pass and " +
+                    `re-resolve. Keep polling. Do NOT call ${spec.tool} ` +
+                    'again for iterations of this same design.',
+        };
+        if (attributionWarnings.length)
+            payload.attribution_warning = attributionWarnings.join(' ');
+        return textResult(payload);
+    }
+    catch (err) {
+        return errorResult(`${spec.tool} failed: ${err.message}`);
+    }
+}
+/**
+ * present_wireframes (feature 09) — 1..N lo-fi HTML wireframes (kind 'ui') or
+ * architecture diagrams (kind 'architecture'). A thin spec over the shared
+ * presentation handler; `kind` is the only thing it adds, and it picks the
+ * artifact type. Exported (like badgeReason) so the self-check
+ * (test-tools.mjs) can exercise its branching with a stub client, without a
+ * live MCP handshake.
+ */
+export async function presentWireframesHandler(client, userId, session, args) {
+    return presentationHandler(client, userId, session, args, {
+        tool: 'present_wireframes',
+        unit: 'diagram',
+        htmlSpec: 'a self-contained lo-fi HTML/CSS diagram',
+        artifactType: args.kind === 'ui' ? 'wireframe' : 'diagram',
+        artifactNoun: 'wireframe',
+        extraValidation: () => args.kind !== 'ui' && args.kind !== 'architecture'
+            ? "present_wireframes requires kind to be 'ui' or 'architecture'."
+            : null,
+    });
+}
+/**
+ * present_mocks (feature 10-present-mocks-tool) — the mocks sibling of
+ * present_wireframes: 1..N SELF-CONTAINED INTERACTIVE mocks (HTML + CSS + JS in
+ * one document) that actually work — tabs switch, inputs type, buttons act. No
+ * `kind`: a mock IS the kind, and the artifact type is always 'mock' /
+ * format 'html'.
+ *
+ * It reuses the wireframe review plumbing WHOLESALE and on purpose — same
+ * 'wireframe_review' decision sentinel, same 'wireframe_option:' purpose_key
+ * namespace, same reserved 'approve' / 'request changes' labels, same 2..11
+ * cap, same open-session requirement, same partial-failure recovery. That is
+ * what lets the web's existing review surface (cover, Feedback drawer, rounds,
+ * resolution, approve) serve mocks with no new sentinel, no new reservation and
+ * no parallel implementation. The ONE thing the web adds for mocks is the
+ * FREEZE: while the user is in Feedback mode the injected annotate script
+ * swallows clicks/keys so they select elements to annotate instead of driving
+ * the mock (scrolling stays live) — which is why the tool description insists
+ * the mock be meaningful in its DEFAULT state.
+ *
+ * SCOPE (Phase 2): competing mocks are live. Phase 1 shipped one mock only and
+ * refused `options` here; Phase 2 lifted that guard, so a mocks presentation is
+ * now exactly a wireframes presentation with the mock nouns — one call = one
+ * presentation of 1..N options, and the user picks by approving the option on
+ * screen. The registered schema declares the shape but constrains none of it
+ * (see the comment at registerTool), so EVERY refusal below is reachable over
+ * MCP and the agent reads the written message rather than a raw zod "Too
+ * small". present_wireframes keeps its constrained schema — feature 09's
+ * shipped surface — so the two now differ there and only there.
+ */
+export async function presentMocksHandler(client, userId, session, args) {
+    return presentationHandler(client, userId, session, args, {
+        tool: 'present_mocks',
+        unit: 'mock',
+        htmlSpec: 'a self-contained interactive HTML/CSS/JS mock',
+        artifactType: 'mock',
+        artifactNoun: 'mock',
+    });
+}
+/** Loose UUID shape check (any version), so a malformed id gets a clean tool
+ *  error naming it instead of a Postgres `invalid input syntax for type uuid`
+ *  failing the whole batch. */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Mark feedback rounds resolved by a revision (feature 09, Phase 5 — hybrid
+ * resolution). After update_artifact ships a revision, the agent calls this
+ * with the ids of the rounds that revision actually addressed and the NEW
+ * revision number; each round flips to status 'resolved' with
+ * resolved_in_revision = revision. The user can flip a round back to
+ * 'reopened' in the web when the change wasn't material, and this same call
+ * re-resolves it on the next pass. This is the ONE write the CLI makes to
+ * `artifact_feedback`: a plain UPDATE as the user through RLS
+ * `artifact_feedback_update` (task access + the 'comment' grant) and the
+ * column-level grant on the four resolution columns. The DB's status-only
+ * guard keeps round bodies immutable and stamps status_changed_at/_by itself
+ * (never trusted from here), so only status + resolved_in_revision are sent.
+ *
+ * The UPDATE's `.in(...)` silently skips ids that don't exist, aren't visible
+ * under RLS, or belong to a task the user can't touch — so the result rows are
+ * compared against the request and ANY shortfall is an error that lists the
+ * missing ids (and the ones that DID update, since those flips committed).
+ * Requires an open session, like the sibling review tools. Exported (like
+ * presentWireframesHandler) so the self-check can exercise it with a stub
+ * client.
+ */
+export async function resolveFeedbackHandler(client, session, args) {
+    try {
+        if (!session) {
+            return errorResult('resolve_feedback needs an open work session — call begin_work first.');
+        }
+        if (!Array.isArray(args.feedback_ids) || args.feedback_ids.length === 0) {
+            return errorResult('resolve_feedback requires feedback_ids (at least one feedback round id).');
+        }
+        if (!Number.isInteger(args.revision) || args.revision < 1) {
+            return errorResult('resolve_feedback requires revision (a positive integer — the artifact revision that addressed the rounds).');
+        }
+        const ids = [...new Set(args.feedback_ids.map((id) => id.trim()))];
+        const malformed = ids.filter((id) => !UUID_RE.test(id));
+        if (malformed.length) {
+            return errorResult(`resolve_feedback: not valid feedback round id(s): ${malformed.join(', ')}.`);
+        }
+        const rows = (await must(client
+            .from('artifact_feedback')
+            .update({ status: 'resolved', resolved_in_revision: args.revision })
+            .in('id', ids)
+            .select('id'))) ?? [];
+        const updated = rows.map((row) => row.id);
+        if (updated.length !== ids.length) {
+            const missing = ids.filter((id) => !updated.includes(id));
+            return errorResult(`resolve_feedback: ${updated.length} of ${ids.length} round(s) updated. Not found (or not accessible): ` +
+                `${missing.join(', ')}.${updated.length ? ` Already marked resolved: ${updated.join(', ')}.` : ''} ` +
+                'Check the ids against the most recent get_task `feedback` list.');
+        }
+        return textResult({ resolved: updated, revision: args.revision });
+    }
+    catch (err) {
+        return errorResult(`resolve_feedback 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 twenty-two 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',
+    'present_wireframes',
+    'present_mocks',
+    'resolve_feedback',
+    '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 twenty-two 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, decisions (so you can read the answers to questions ' +
+            'you asked), and feedback (the cumulative wireframe-review rounds the user sent, each tagged with the ' +
+            "presented primary artifact and its artifact_revision at send time — the presentation's version stamp). " +
+            "Each feedback round carries its resolution state: rounds with status 'open' or 'reopened' need your " +
+            "attention ('reopened' means the user flipped a round you resolved back to not resolved — treat it as " +
+            "open feedback on your next pass); 'resolved' rounds don't (resolved_in_revision names the revision that " +
+            'addressed them; mark rounds resolved with resolve_feedback after revising). ' +
+            '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('present_wireframes', {
+        description: 'Present lo-fi HTML wireframes (kind ui) or architecture diagrams (kind architecture) to the user for ' +
+            'fullscreen review in the web work item — either ONE diagram (html) or 2..11 competing options ' +
+            '(options: [{label, html}, …]); pass exactly one of html / options. Every html must be a self-contained ' +
+            'lo-fi HTML/CSS diagram. The user then sends CUMULATIVE feedback rounds — any number, any time, without ' +
+            "waiting for you: poll get_task and read them from its `feedback` list. Every round is tagged with the " +
+            "presentation's primary artifact and its artifact_revision at send time — the presentation's version " +
+            'stamp, not a per-option pointer; in a multi-option presentation, which option a note concerns is named ' +
+            'inline in the note\'s "(…)" option label within body, so revise the option artifact the notes name. ' +
+            'The returned review ' +
+            'decision is the approval gate only: it stays open across rounds and decides ONLY when the user approves ' +
+            "(selected_options[0] is 'approve', or the approved option's label — choosing an option is approving it; " +
+            'answer_note may carry a final comment). To act on feedback, revise the wireframe IN PLACE with ' +
+            'update_artifact (the revision bumps automatically), then call resolve_feedback with the ids of the ' +
+            'rounds that revision actually addressed and the NEW revision number — only rounds you genuinely acted ' +
+            "on. The user can flip a round back to 'reopened' when the change wasn't material; treat a reopened " +
+            'round as open feedback on the next pass (resolve_feedback re-resolves it). Keep polling — do NOT call ' +
+            'present_wireframes ' +
+            'again for iterations of the same design. Requires an open session (begin_work). If diagrams are created ' +
+            'but the review request fails, the error includes the created artifacts and exact recovery instructions ' +
+            '— follow them instead of calling this tool again.',
+        inputSchema: {
+            title: z.string().min(1).describe('Short title for the presentation (shown on the work item)'),
+            kind: z.enum(['ui', 'architecture']).describe("'ui' for wireframes, 'architecture' for code/flow diagrams"),
+            html: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('A single self-contained lo-fi HTML/CSS diagram (exactly one of html / options)'),
+            options: z
+                .array(z.object({ label: z.string().min(1), html: z.string().min(1) }))
+                .min(2)
+                .max(11)
+                .optional()
+                .describe('2..11 competing diagrams, each with a short distinct label (exactly one of html / options; ' +
+                "the labels 'approve' and 'request changes' are reserved)"),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return presentWireframesHandler(client, userId, openSessions.get(connectionId) ?? null, args);
+    });
+    server.registerTool('present_mocks', {
+        description: 'Present WORKING, INTERACTIVE HTML mocks to the user for fullscreen review in the web work item — ' +
+            'either ONE mock (html) or 2..11 competing options (options: [{label, html}, …]); pass exactly one of ' +
+            'html / options. One call = ONE presentation: the user flips between the options and picks one by ' +
+            'APPROVING the option on screen. ' +
+            'Every html must be a SELF-CONTAINED interactive mock: HTML, CSS and JS all inline in the one ' +
+            'document, with fake in-memory data, so it actually works — tabs switch, inputs type, buttons act. No ' +
+            'external assets, no network (the sandboxed iframe blocks fetch/XHR/CDN links) and no storage ' +
+            '(localStorage/cookies are unavailable) — anything that needs them will silently fail. IMPORTANT: while ' +
+            'the user is in Feedback mode the viewer FREEZES the mock — clicks and keys select elements to annotate ' +
+            'instead of driving it (only scrolling stays live) — so the mock must be readable and meaningful in its ' +
+            'DEFAULT state; never hide the substance behind an interaction the user cannot perform while annotating. ' +
+            'That applies per option: whichever option is on screen is the one that freezes. ' +
+            'The user then sends CUMULATIVE feedback rounds — any number, any time, without waiting for you: poll ' +
+            "get_task and read them from its `feedback` list. Every round is tagged with the presentation's primary " +
+            "artifact and its artifact_revision at send time — the presentation's version stamp, not a per-option " +
+            'pointer; in a multi-option presentation, which option a note concerns is named inline in the ' +
+            'note\'s "(…)" option label within body, so revise the option artifact the notes name. ' +
+            'The returned review ' +
+            'decision is the approval gate only: it stays open across rounds and decides ONLY when the user approves ' +
+            "(selected_options[0] is 'approve', or the approved option's label — choosing an option is approving it; " +
+            'answer_note may carry a final comment). To act on feedback, revise the mock IN PLACE with ' +
+            'update_artifact (the revision bumps automatically), then call resolve_feedback with the ids of the ' +
+            'rounds that revision actually addressed and the NEW revision number — only rounds you genuinely acted ' +
+            "on. The user can flip a round back to 'reopened' when the change wasn't material; treat a reopened " +
+            'round as open feedback on the next pass (resolve_feedback re-resolves it). Keep polling — do NOT call ' +
+            'present_mocks ' +
+            'again for iterations of the same design. Requires an open session (begin_work). If mocks are created ' +
+            'but the review request fails, the error includes the created artifacts and exact recovery instructions ' +
+            '— follow them instead of calling this tool again.',
+        // This schema DECLARES every field the handler reads and CONSTRAINS none
+        // of what the handler validates — the two halves of the Phase 1 defect.
+        // DECLARE, because the SDK parses args with z.object(inputSchema) and
+        // passes parseResult.data on, so a Zod object silently STRIPS anything it
+        // was not told about: a field left off is discarded and never seen by the
+        // handler (that is how `options` vanished in Phase 1). Do NOT constrain,
+        // because a zod refusal is what the AGENT receives: a `.min(1)` here, or
+        // `.min(2).max(11)` on options, pre-empts the handler's written message
+        // ("use html for a single mock; a review decision is capped at 12 options
+        // including the reserved one") with a bare "Too small: expected array to
+        // have >=2 items" — true, but it doesn't say what to do instead. So the
+        // real bounds live in `.describe()`, which is how tools/list teaches the
+        // agent the shape up front, and are ENFORCED by the shared handler, which
+        // rejects every case the removed constraints did. present_wireframes
+        // deliberately still carries those constraints: it is feature 09's
+        // shipped surface, and changing the errors its agents already get is not
+        // this feature's call to make.
+        inputSchema: {
+            title: z.string().min(1).describe('Short title for the presentation (shown on the work item)'),
+            html: z
+                .string()
+                .optional()
+                .describe('A single self-contained interactive mock: HTML + CSS + JS inline, no external assets, ' +
+                'no network, no storage (exactly one of html / options)'),
+            options: z
+                .array(z.object({ label: z.string(), html: z.string() }))
+                .optional()
+                .describe('2..11 competing mocks, each self-contained and interactive, with a short distinct label ' +
+                "(exactly one of html / options; the labels 'approve' and 'request changes' are reserved)"),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return presentMocksHandler(client, userId, openSessions.get(connectionId) ?? null, args);
+    });
+    server.registerTool('resolve_feedback', {
+        description: 'Mark feedback rounds resolved after you revised the presented artifact: pass the ids of the rounds the ' +
+            'revision actually addressed (from get_task\'s `feedback` list) and the NEW revision number ' +
+            'update_artifact returned. Only mark rounds you genuinely acted on. The user can flip a round back to ' +
+            "'reopened' when the change wasn't material — treat it as open feedback on your next pass and re-resolve " +
+            'it with this tool. Round bodies never change; only resolution state does. Requires an open session (begin_work).',
+        inputSchema: {
+            feedback_ids: z
+                .array(z.string())
+                .min(1)
+                .describe("Ids of the feedback rounds the revision addressed (from get_task's feedback list)"),
+            revision: z
+                .number()
+                .int()
+                .positive()
+                .describe('The artifact revision that addressed these rounds (from the update_artifact result)'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return resolveFeedbackHandler(client, 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 token = mcpToken();
+    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;
+        }
+        // Client auth: only clients registered by CTRL+SPC carry the per-install
+        // token (embedded in the URL written to Claude/Codex configs). Any other
+        // local process that finds the loopback port is refused before the MCP
+        // protocol — and the credential tools — are reachable.
+        if (url.searchParams.get('token') !== token) {
+            res.writeHead(401, { 'Content-Type': 'text/plain' }).end('Unauthorized');
+            return;
+        }
+        // Logout gate: terminal `cs logout` runs in a different process and can only
+        // clear session.json — it can't reach this server's in-memory session. So
+        // every request (including ones on an already-open MCP connection) re-checks
+        // the on-disk session; once it's gone, nothing is served for the old account.
+        if (!readSession()) {
+            res.writeHead(401, { 'Content-Type': 'text/plain' }).end('Logged out');
+            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?token=${mcpToken()}`;
+    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?token=${mcpToken()}`;
+    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 };
+}