@ctrl-spc/cli 1.1.14 → 1.2.0

package/dist/mcp.js

@@ -0,0 +1,1732 @@
+import { randomUUID } from 'node:crypto';
+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 { PROTOCOL_FULL, PROTOCOL_SHORT } from './protocol.js';
+import { MCP_PORT } from './env.js';
+import { getMachineIdentity } from './config.js';
+/**
+ * From the MCP `initialize` request's `clientInfo.name` (spec: "Agent
+ * attribution: from the MCP initialize request's clientInfo.name — map
+ * /claude/i -> 'claude', /codex/i -> 'codex', else null").
+ */
+export function attributionFromClientName(name) {
+    if (!name)
+        return null;
+    if (/claude/i.test(name))
+        return 'claude';
+    if (/codex/i.test(name))
+        return 'codex';
+    return null;
+}
+const QUESTION_CATEGORIES = [
+    'clarification', 'reproduction', 'intent', 'dependency', 'checkout', 'collision', 'split',
+];
+// ---------------------------------------------------------------------------
+// Query plumbing
+// ---------------------------------------------------------------------------
+/**
+ * Awaits a Supabase (or RPC) call and throws on error — callers catch once,
+ * at the handler boundary. Takes the query's result loosely typed (`unknown`
+ * data): the client used everywhere here is untyped (no generated `Database`
+ * generic, per Task 1's `getClient()`), so postgrest-js can't infer embedded
+ * relationships' cardinality (owner/sprint are to-one at runtime — confirmed
+ * against the live schema — but statically inferred as arrays without real
+ * schema types); the caller's explicit `T` is the source of truth for shape.
+ */
+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 };
+}
+function relationOne(value) {
+    return Array.isArray(value) ? value[0] ?? null : value;
+}
+/**
+ * Resolve the broker's live project set from owner-private machine workspaces.
+ * A projectId is accepted only for legacy unit/direct-handler callers; the
+ * production broker never carries a cwd project forever.
+ */
+async function accessibleProjects(deps, machineId = deps.machineId) {
+    if (deps.projectId)
+        return [{ id: deps.projectId }];
+    if (!machineId)
+        return [];
+    const rows = (await must(deps.client
+        .from('machine_workspaces')
+        .select('project_id,project:projects!machine_workspaces_project_id_fkey(id,name)')
+        .eq('user_id', deps.userId)
+        .eq('machine_id', machineId))) ?? [];
+    const projects = new Map();
+    for (const row of rows) {
+        const project = relationOne(row.project);
+        projects.set(row.project_id, { id: row.project_id, ...(project?.name ? { name: project.name } : {}) });
+    }
+    return [...projects.values()].sort((left, right) => (left.name ?? left.id).localeCompare(right.name ?? right.id) || left.id.localeCompare(right.id));
+}
+function bindProject(deps, projectId) {
+    return { ...deps, projectId };
+}
+function requiredProjectId(deps, action) {
+    if (!deps.projectId)
+        throw new Error(`${action} requires a project-bound agent run`);
+    return deps.projectId;
+}
+/**
+ * One future-proof task read model. `*` keeps every direct task column without
+ * requiring a CLI release when an additive migration lands. Every relationship
+ * uses the exact FK name, including relationships that are currently unique,
+ * so adding another FK can never make this query ambiguous later.
+ */
+const TASK_SELECT = '*,owner:profiles!tasks_owner_id_fkey(*),updater:profiles!tasks_updated_by_fkey(*),' +
+    'sprint:sprints!tasks_sprint_id_fkey(*),' +
+    'task_tags:task_tags!task_tags_task_id_fkey(*,tag:tags!task_tags_tag_id_fkey(*)),' +
+    'predecessor_edges:task_dependencies!task_dependencies_task_id_fkey(' +
+    '*,predecessor:tasks!task_dependencies_depends_on_task_id_fkey(*)),' +
+    'dependent_edges:task_dependencies!task_dependencies_depends_on_task_id_fkey(' +
+    '*,dependent:tasks!task_dependencies_task_id_fkey(*))';
+const COMMENT_SELECT = '*,author:profiles!comments_author_id_fkey(*),agent_run:agent_runs!comments_agent_run_id_fkey(*)';
+const ARTIFACT_SELECT = '*,creator:profiles!artifacts_created_by_fkey(*),updater:profiles!artifacts_updated_by_fkey(*),' +
+    'deleter:profiles!artifacts_deleted_by_fkey(*),agent_run:agent_runs!artifacts_agent_run_id_fkey(*),' +
+    'repository_coverage:artifact_repository_coverage!artifact_repository_coverage_artifact_id_fkey(' +
+    '*,repository_scope:repository_scopes!artifact_repository_coverage_repository_scope_id_fkey(*),' +
+    'acknowledgement:unavailable_checkout_acknowledgements!' +
+    'artifact_repository_coverage_acknowledgement_id_fkey(*))';
+const TASK_VERSION_SELECT = '*,saved_by_profile:profiles!task_versions_saved_by_fkey(*),' +
+    'agent_run:agent_runs!task_versions_agent_run_id_fkey(*)';
+const AGENT_RUN_SELECT = '*,user:profiles!agent_runs_user_id_fkey(*),machine:machines!agent_runs_machine_id_fkey(*)';
+const TASK_CLAIM_SELECT = '*,agent_run:agent_runs!task_claims_agent_run_id_fkey(*)';
+const WORK_RESERVATION_SELECT = '*,repository_scope:repository_scopes!work_reservations_repository_scope_id_fkey(*),' +
+    'repository_checkout:repository_checkouts!work_reservations_repository_checkout_id_fkey(*)';
+const COLLABORATION_DOCUMENT_SELECT = '*,updated_by_profile:profiles!collaboration_documents_updated_by_fkey(*)';
+function parseTaskRow(row) {
+    const { owner, updater = null, sprint, task_tags: taskTags, predecessor_edges: rawPredecessorEdges, dependent_edges: rawDependentEdges, task_dependencies: legacyDependencies, ...properties } = row;
+    const tagRecords = (taskTags ?? [])
+        .map((entry) => entry.tag ?? entry.tags ?? null)
+        .filter((tag) => Boolean(tag))
+        .sort((left, right) => left.name.localeCompare(right.name) || left.id.localeCompare(right.id));
+    const predecessorEdges = [...(rawPredecessorEdges ?? legacyDependencies ?? [])]
+        .sort((left, right) => String(left.created_at ?? '').localeCompare(String(right.created_at ?? '')) ||
+        String(left.depends_on_task_id ?? left.predecessor?.id ?? left.depends_on?.id ?? '')
+            .localeCompare(String(right.depends_on_task_id ?? right.predecessor?.id ?? right.depends_on?.id ?? '')));
+    const dependentEdges = [...(rawDependentEdges ?? [])]
+        .sort((left, right) => String(left.created_at ?? '').localeCompare(String(right.created_at ?? '')) ||
+        String(left.task_id ?? left.dependent?.id ?? '').localeCompare(String(right.task_id ?? right.dependent?.id ?? '')));
+    const predecessors = predecessorEdges
+        .map((edge) => edge.predecessor ?? edge.depends_on ?? null)
+        .filter((dependency) => Boolean(dependency));
+    return {
+        ...properties,
+        id: row.id,
+        name: row.name,
+        description: row.description,
+        due_date: row.due_date,
+        status: row.status,
+        position: row.position,
+        created_at: row.created_at,
+        revision: row.revision,
+        updated_at: row.updated_at,
+        updated_by: row.updated_by,
+        properties,
+        owner,
+        updater,
+        sprint,
+        tags: tagRecords.map((tag) => tag.name),
+        tag_records: tagRecords,
+        predecessor_edges: predecessorEdges,
+        dependent_edges: dependentEdges,
+        unmet_dependencies: predecessors
+            .filter((dependency) => dependency.status !== 'done')
+            .map((dependency) => ({
+            id: String(dependency.id),
+            name: String(dependency.name),
+            status: dependency.status,
+        })),
+    };
+}
+function recordArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => Boolean(item) && typeof item === 'object')
+        : [];
+}
+function sortRecords(rows, ...keys) {
+    return [...rows].sort((left, right) => {
+        for (const key of keys) {
+            const comparison = String(left[key] ?? '').localeCompare(String(right[key] ?? ''), undefined, { numeric: true });
+            if (comparison !== 0)
+                return comparison;
+        }
+        return 0;
+    });
+}
+function normalizeComment(row) {
+    const body = typeof row.body === 'string' ? row.body : '';
+    const question = body.match(/^\[question:([a-z_]+)]\s+([\s\S]+)$/);
+    return {
+        ...row,
+        ...(question ? { question_category: question[1], question_text: question[2] } : {}),
+    };
+}
+function normalizeArtifact(row) {
+    const repositoryCoverage = sortRecords(recordArray(row.repository_coverage), 'repository_scope_id', 'created_at');
+    return { ...row, repository_coverage: repositoryCoverage };
+}
+/** Resolves each name against the project's tags (case-insensitive), creating any that don't exist yet. */
+async function resolveOrCreateTags(client, projectId, names) {
+    const wanted = [...new Set(names.map((n) => n.trim().toLowerCase()).filter(Boolean))];
+    if (wanted.length === 0)
+        return [];
+    const existing = (await must(client.from('tags').select('id,name').eq('project_id', projectId))) ?? [];
+    const byLower = new Map(existing.map((t) => [t.name.toLowerCase(), t]));
+    const missing = wanted.filter((n) => !byLower.has(n));
+    if (missing.length > 0) {
+        const created = (await must(client
+            .from('tags')
+            .insert(missing.map((name) => ({ project_id: projectId, name })))
+            .select('id,name'))) ?? [];
+        for (const tag of created)
+            byLower.set(tag.name.toLowerCase(), tag);
+    }
+    return wanted.map((n) => byLower.get(n)).filter((t) => Boolean(t));
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** `owner` fields accept either a profile id or an email (spec: "owner (email or profile id)"). */
+async function resolveOwnerId(client, owner) {
+    if (UUID_RE.test(owner))
+        return owner;
+    const profile = await must(client.from('profiles').select('id').eq('email', owner).maybeSingle());
+    if (!profile)
+        throw new Error(`No profile found for owner "${owner}".`);
+    return profile.id;
+}
+/**
+ * Resolves a sprint by name (case-insensitive), creating one if it doesn't
+ * exist yet.
+ *
+ * ponytail: update_task's `sprint` field is name-only — no start/end dates —
+ * so a newly-created sprint defaults to a single-day window (today). Real
+ * date ranges are set from the web UI; this path only covers an agent
+ * referencing a sprint name that doesn't exist yet.
+ */
+async function resolveOrCreateSprint(client, projectId, name) {
+    const existing = (await must(client.from('sprints').select('id,name').eq('project_id', projectId))) ?? [];
+    const match = existing.find((s) => s.name.toLowerCase() === name.trim().toLowerCase());
+    if (match)
+        return match.id;
+    const today = new Date().toISOString().slice(0, 10);
+    const created = await must(client.from('sprints').insert({ project_id: projectId, name, start_date: today, end_date: today }).select('id').single());
+    if (!created)
+        throw new Error('Sprint creation returned no row.');
+    return created.id;
+}
+async function loadAgentProjectTopology(client, projectId, userId, machineId) {
+    const project = await must(client.from('projects').select('topology_revision').eq('id', projectId).single());
+    if (!project)
+        throw new Error('Project topology could not be loaded.');
+    const scopeRows = (await must(client
+        .from('project_repository_scopes')
+        .select('repository_scope_id,purpose,required,position,' +
+        'scope:repository_scopes!project_repository_scopes_repository_scope_id_fkey(' +
+        'id,repository_id,scope_path,kind,name,' +
+        'repository:repositories!repository_scopes_repository_id_fkey(id,remote_key,name))')
+        .eq('project_id', projectId)
+        .eq('active', true)
+        .order('position', { ascending: true }))) ?? [];
+    const workspace = await must(client
+        .from('machine_workspaces')
+        .select('id,workspace_root')
+        .eq('user_id', userId)
+        .eq('machine_id', machineId)
+        .eq('project_id', projectId)
+        .maybeSingle());
+    const checkouts = workspace
+        ? (await must(client
+            .from('repository_checkouts')
+            .select('id,repository_id,local_path,availability,verified_remote_key,head_sha,is_worktree,verified_at')
+            .eq('machine_workspace_id', workspace.id))) ?? []
+        : [];
+    const checkoutsByRepository = new Map();
+    for (const checkout of checkouts) {
+        const existing = checkoutsByRepository.get(checkout.repository_id) ?? [];
+        existing.push(checkout);
+        checkoutsByRepository.set(checkout.repository_id, existing);
+    }
+    const scopes = scopeRows.flatMap((row) => {
+        const scope = row.scope;
+        if (!scope?.repository)
+            return [];
+        const candidates = [...(checkoutsByRepository.get(scope.repository_id) ?? [])]
+            .sort((left, right) => Number(right.availability === 'available') - Number(left.availability === 'available') ||
+            left.local_path.localeCompare(right.local_path) || left.id.localeCompare(right.id));
+        const checkout = candidates.find((candidate) => candidate.availability === 'available') ?? candidates[0] ?? null;
+        const availability = checkout?.availability ?? 'missing';
+        return [{
+                repository_scope_id: scope.id,
+                repository_id: scope.repository.id,
+                repository_name: scope.repository.name,
+                remote_key: scope.repository.remote_key,
+                scope_name: scope.name,
+                scope_path: scope.scope_path,
+                scope_kind: scope.kind,
+                purpose: row.purpose,
+                required: row.required,
+                position: row.position,
+                checkouts: candidates.map((candidate) => ({
+                    id: candidate.id,
+                    local_path: candidate.local_path,
+                    availability: candidate.availability,
+                    verified_remote_key: candidate.verified_remote_key,
+                    head_sha: candidate.head_sha,
+                    is_worktree: candidate.is_worktree,
+                    verified_at: candidate.verified_at,
+                })),
+                checkout: checkout
+                    ? {
+                        id: checkout.id,
+                        local_path: checkout.local_path,
+                        availability,
+                        verified_remote_key: checkout.verified_remote_key,
+                        head_sha: checkout.head_sha,
+                        is_worktree: checkout.is_worktree,
+                        verified_at: checkout.verified_at,
+                    }
+                    : { id: null, local_path: null, availability: 'missing' },
+                fetch_offer: availability === 'available'
+                    ? null
+                    : {
+                        available: Boolean(scope.repository.remote_key),
+                        instruction: 'Warn the user that this repository is unavailable locally and offer to fetch it. Never fetch without approval.',
+                    },
+            }];
+    });
+    const missingRequiredScopeIds = scopes
+        .filter((scope) => scope.required && scope.checkout.availability !== 'available')
+        .map((scope) => scope.repository_scope_id);
+    return {
+        revision: Number(project.topology_revision),
+        workspace_root: workspace?.workspace_root ?? null,
+        scopes,
+        complete: missingRequiredScopeIds.length === 0,
+        missing_required_scope_ids: missingRequiredScopeIds,
+        instruction: missingRequiredScopeIds.length === 0
+            ? 'Inspect every repository scope before planning or implementation; reserve only the paths you will edit.'
+            : 'Required repositories are unavailable on this machine. Warn the user and offer to fetch them before claiming they were reviewed.',
+    };
+}
+function coordinationError(action, err) {
+    const raw = err instanceof Error ? err.message : String(err);
+    if (/stale project topology revision|claim was created against a stale project topology|project repository topology changed/i.test(raw)) {
+        return errorResult(`${action}: the project's repository topology changed after this agent began. ` +
+            'Do not edit. End this run, fetch the task and repository list again, then begin a fresh run.');
+    }
+    if (/lease is not active|lease has expired|agent run is not active|stale agent lease generation|stale or missing task claim fencing token/i.test(raw)) {
+        return errorResult(`${action}: this agent no longer owns an active lease. Stop editing and call begin_work again before continuing.`);
+    }
+    return errorResult(`${action} failed: ${raw}`);
+}
+function runOrError(session, action) {
+    if (session.run)
+        return session.run;
+    return errorResult(`${action} requires an active agent run. Call begin_work for the task before editing or writing back.`);
+}
+function joinedRunOrError(session, action) {
+    const run = runOrError(session, action);
+    if ('content' in run)
+        return run;
+    if (run.state === 'joined')
+        return run;
+    return errorResult(`${action} is blocked while required repositories are unavailable. ` +
+        'Warn the user and offer to fetch them, or acknowledge each unavailable checkout, then call begin_work again.');
+}
+/**
+ * Begins one durable run for this MCP connection. Calling begin_work is the
+ * explicit collaboration action: the first live run coordinates; later runs
+ * join as collaborators but still may not edit until path reservation succeeds.
+ */
+export async function beginAgentRunHandler(deps, session, args) {
+    try {
+        const previousExploration = session.exploration;
+        if (!args.task_id)
+            return errorResult('begin_work requires task_id.');
+        if (session.run && session.run.taskId !== args.task_id) {
+            return errorResult(`This agent is already working on task ${session.run.taskId}. ` +
+                'Call end_work before beginning a different task in the same agent session.');
+        }
+        const task = deps.projectId
+            ? await must(deps.client.from('tasks').select('id,project_id').eq('id', args.task_id).eq('project_id', deps.projectId).maybeSingle())
+            : await must(deps.client.from('tasks').select('id,project_id').eq('id', args.task_id).maybeSingle());
+        if (!task)
+            return errorResult(`No accessible task found for id "${args.task_id}".`);
+        const taskProjectId = task.project_id ?? deps.projectId;
+        if (!taskProjectId)
+            throw new Error('task resolution returned no project id');
+        const projects = await accessibleProjects(deps, session.machineId);
+        if (!projects.some((project) => project.id === taskProjectId)) {
+            return errorResult(`Task "${args.task_id}" belongs to a project that is not initialized on this machine. ` +
+                'Initialize or link that project before beginning work.');
+        }
+        const result = await must(deps.client.rpc('begin_agent_run', {
+            p_task: args.task_id,
+            p_machine: session.machineId,
+            p_session: session.sessionId,
+            p_agent_kind: session.agentKind || 'unknown',
+            p_client_name: session.clientName,
+            p_client_version: session.clientVersion,
+        }));
+        if (!result)
+            throw new Error('begin_agent_run returned no lifecycle data');
+        const runProjectId = result.project_id ?? taskProjectId;
+        if (runProjectId !== taskProjectId) {
+            throw new Error('begin_agent_run returned a project that does not match the requested task');
+        }
+        if (result.status === 'missing_checkouts') {
+            session.exploration = null;
+            session.run = {
+                state: 'waiting',
+                runId: result.run_id,
+                taskId: args.task_id,
+                projectId: runProjectId,
+                topologyRevision: Number(result.topology_revision),
+                leaseGeneration: Number(result.lease_generation),
+                leaseExpiresAt: result.lease_expires_at,
+                missingRepositories: result.missing_repositories ?? [],
+                choices: result.choices ?? ['fetch', 'acknowledge_unavailable'],
+            };
+            return textResult({
+                coordination: {
+                    status: 'missing_checkouts',
+                    role: 'waiting',
+                    repository_edits_allowed: false,
+                    mutations_allowed: false,
+                    instruction: 'Required repositories are unavailable on this machine. Warn the user and offer to fetch each repository. ' +
+                        'If the user chooses to continue without one, call acknowledge_unavailable_checkout for that scope. ' +
+                        'After every missing repository is fetched or acknowledged, call begin_work again to obtain a joined claim.',
+                    choices: session.run.choices,
+                },
+                missing_repositories: session.run.missingRepositories,
+                agent_run: session.run,
+            });
+        }
+        session.run = {
+            state: 'joined',
+            runId: result.run_id,
+            taskId: args.task_id,
+            projectId: runProjectId,
+            claimId: result.claim_id,
+            role: result.role,
+            fencingToken: Number(result.fencing_token),
+            topologyRevision: Number(result.topology_revision),
+            leaseGeneration: Number(result.lease_generation),
+            leaseExpiresAt: result.lease_expires_at,
+        };
+        session.exploration = previousExploration?.agentRunId === result.run_id &&
+            previousExploration.taskId === args.task_id &&
+            previousExploration.topologyRevision === Number(result.topology_revision)
+            ? previousExploration
+            : null;
+        const collaborator = result.role === 'collaborator';
+        return textResult({
+            coordination: {
+                status: collaborator ? 'joined_as_collaborator' : 'coordinating',
+                role: result.role,
+                another_agent_is_active: collaborator,
+                repository_edits_allowed: false,
+                instruction: collaborator
+                    ? 'Another agent is coordinating this task. Inspect the full repository topology, agree on a disjoint scope, and call reserve_work_paths before editing. A collision response means you must narrow, wait, request handoff, or use an isolated worktree.'
+                    : 'You are coordinating this task. Inspect every repository, then call reserve_work_paths before editing. Collaborators may join with disjoint reservations.',
+            },
+            agent_run: session.run,
+        });
+    }
+    catch (err) {
+        return coordinationError('begin_work', err);
+    }
+}
+export async function heartbeatAgentRunHandler(deps, session) {
+    const active = runOrError(session, 'heartbeat_work');
+    if ('content' in active)
+        return active;
+    try {
+        const result = await must(deps.client.rpc('heartbeat_agent_run', {
+            p_run: active.runId,
+            p_lease_generation: active.leaseGeneration,
+        }));
+        if (!result)
+            throw new Error('heartbeat_agent_run returned no lease data');
+        active.leaseGeneration = Number(result.lease_generation);
+        active.leaseExpiresAt = result.lease_expires_at;
+        return textResult({ agent_run: active });
+    }
+    catch (err) {
+        return coordinationError('heartbeat_work', err);
+    }
+}
+export async function reserveWorkPathsHandler(deps, session, args) {
+    const active = joinedRunOrError(session, 'reserve_work_paths');
+    if ('content' in active)
+        return active;
+    if (!Number.isInteger(args.topology_revision) || args.topology_revision < 1) {
+        return errorResult('reserve_work_paths requires topology_revision from begin_work.');
+    }
+    if (args.topology_revision !== active.topologyRevision) {
+        return errorResult(`reserve_work_paths topology mismatch: this run began at revision ${active.topologyRevision}, ` +
+            `but the request used ${args.topology_revision}. Stop editing and refresh the project topology.`);
+    }
+    if (!Array.isArray(args.reservations) || args.reservations.length === 0) {
+        return errorResult('reserve_work_paths requires at least one repository/path reservation.');
+    }
+    const missingCheckout = args.reservations.find((reservation) => (reservation.mode ?? 'write') === 'write' && !reservation.repository_checkout_id);
+    if (missingCheckout) {
+        return errorResult('Every write reservation requires repository_checkout_id from get_task topology.checkouts. ' +
+            'Choose the exact checkout or isolated worktree before editing.');
+    }
+    try {
+        const result = await must(deps.client.rpc('reserve_work_paths', {
+            p_run: active.runId,
+            p_topology_revision: args.topology_revision,
+            p_reservations: args.reservations,
+        }));
+        if (!result)
+            throw new Error('reserve_work_paths returned no result');
+        if (!result.accepted) {
+            return textResult({
+                coordination: {
+                    status: 'collision',
+                    repository_edits_allowed: false,
+                    instruction: 'Do not edit the conflicting path. Narrow the scope, wait, request a handoff, or work in an isolated worktree before retrying.',
+                    choices: result.choices ?? ['narrow_scope', 'wait', 'handoff', 'isolated_worktree'],
+                },
+                conflicts: result.conflicts ?? [],
+            });
+        }
+        return textResult({
+            coordination: {
+                status: 'reserved',
+                repository_edits_allowed: true,
+                instruction: 'Edit only the reserved repository paths. Release them or end_work when finished.',
+            },
+            reservations: result.reservations ?? [],
+        });
+    }
+    catch (err) {
+        return coordinationError('reserve_work_paths', err);
+    }
+}
+export async function releaseWorkPathsHandler(deps, session, args) {
+    const active = joinedRunOrError(session, 'release_work_paths');
+    if ('content' in active)
+        return active;
+    try {
+        const count = await must(deps.client.rpc('release_work_paths', {
+            p_run: active.runId,
+            p_reservation_ids: args.reservation_ids ?? null,
+        }));
+        return textResult({ released_count: Number(count ?? 0), agent_run_id: active.runId });
+    }
+    catch (err) {
+        return coordinationError('release_work_paths', err);
+    }
+}
+export async function transferCoordinationHandler(deps, session, args) {
+    const active = joinedRunOrError(session, 'transfer_coordination');
+    if ('content' in active)
+        return active;
+    if (active.role !== 'coordinator') {
+        return errorResult('transfer_coordination is available only to the current task coordinator.');
+    }
+    if (!args.target_run_id?.trim())
+        return errorResult('transfer_coordination requires target_run_id.');
+    try {
+        const result = await must(deps.client.rpc('transfer_task_coordination', {
+            p_run: active.runId,
+            p_target_run: args.target_run_id.trim(),
+        }));
+        if (!result)
+            throw new Error('transfer_task_coordination returned no result');
+        active.role = 'collaborator';
+        return textResult({
+            coordination: {
+                status: 'transferred',
+                role: 'collaborator',
+                coordinator_run_id: args.target_run_id.trim(),
+                instruction: 'You are now a collaborator. Keep only disjoint path reservations and coordinate before changing scope.',
+            },
+            transfer: result,
+            agent_run: active,
+        });
+    }
+    catch (err) {
+        return coordinationError('transfer_coordination', err);
+    }
+}
+export async function acknowledgeUnavailableCheckoutHandler(deps, session, args) {
+    const active = runOrError(session, 'acknowledge_unavailable_checkout');
+    if ('content' in active)
+        return active;
+    if (!args.reason?.trim())
+        return errorResult('acknowledge_unavailable_checkout requires a clear reason.');
+    try {
+        const acknowledgementId = await must(deps.client.rpc('acknowledge_unavailable_checkout', {
+            p_run: active.runId,
+            p_repository_scope: args.repository_scope_id,
+            p_reason: args.reason.trim(),
+        }));
+        if (!acknowledgementId)
+            throw new Error('acknowledge_unavailable_checkout returned no id');
+        return textResult({
+            acknowledgement_id: acknowledgementId,
+            repository_scope_id: args.repository_scope_id,
+            instruction: 'This repository remains unavailable and must be marked unavailable_acknowledged in artifact coverage. ' +
+                'Call begin_work again after every missing repository is fetched or acknowledged; acknowledgement alone does not grant a claim.',
+        });
+    }
+    catch (err) {
+        return coordinationError('acknowledge_unavailable_checkout', err);
+    }
+}
+async function activeRepositoryScopes(client, projectId) {
+    const rows = (await must(client
+        .from('project_repository_scopes')
+        .select('repository_scope_id,position,created_at')
+        .eq('project_id', projectId)
+        .eq('active', true)
+        .order('position', { ascending: true })
+        .order('created_at', { ascending: true })
+        .order('repository_scope_id', { ascending: true }))) ?? [];
+    return rows;
+}
+function exactScopeSet(expected, received, label) {
+    const unique = new Set(received);
+    if (unique.size !== received.length)
+        return `${label} assigns at least one repository scope more than once.`;
+    const expectedSet = new Set(expected);
+    const missing = expected.filter((id) => !unique.has(id));
+    const extra = received.filter((id) => !expectedSet.has(id));
+    if (missing.length > 0 || extra.length > 0) {
+        return `${label} must include every active repository scope exactly once. ` +
+            `Missing: ${missing.join(', ') || 'none'}. Extra: ${extra.join(', ') || 'none'}.`;
+    }
+    return null;
+}
+function explorationArtifactContent(args, orderedCoverage) {
+    const lines = [
+        '# Context exploration',
+        '',
+        `Topology revision: ${args.topology_revision}`,
+        `Status: ${args.blocked_reason ? 'blocked — read-only subagents unavailable' : 'complete'}`,
+    ];
+    if (args.summary?.trim())
+        lines.push('', args.summary.trim());
+    if (args.blocked_reason) {
+        lines.push('', 'No implementation, decision, question, reservation, or task mutation is authorized by this receipt.');
+    }
+    else {
+        lines.push('', '## Read-only subagent reports');
+        const reports = [...args.reports].sort((left, right) => left.agent.localeCompare(right.agent) || left.focus.localeCompare(right.focus));
+        for (const report of reports) {
+            lines.push('', `### ${report.agent.trim()} — ${report.focus.trim()}`, '', `Repository scopes: ${report.repository_scope_ids.join(', ')}`, `Inspected paths: ${report.inspected_paths.join(', ') || 'none available'}`, '', '**Findings**', ...report.findings.map((finding) => `- ${finding.trim()}`), '', `Likely impact: ${report.likely_impact.trim()}`, '', '**Unresolved questions**', ...(report.unresolved_questions.length > 0
+                ? report.unresolved_questions.map((question) => `- ${question.trim()}`)
+                : ['- None reported']));
+        }
+    }
+    lines.push('', '## Repository coverage');
+    for (const coverage of orderedCoverage) {
+        lines.push(`- ${coverage.repository_scope_id}: ${coverage.disposition} — ${coverage.reason.trim()}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Persists proof that read-only exploration happened before any decision or
+ * mutation. The receipt is deliberately session-local while its evidence is a
+ * durable analysis artifact tied to the exact task, run, and topology revision.
+ */
+export async function recordContextExplorationHandler(deps, attribution, session, args) {
+    const active = joinedRunOrError(session, 'record_context_exploration');
+    if ('content' in active)
+        return active;
+    if (args.task_id !== active.taskId) {
+        return errorResult(`record_context_exploration must stay on this agent run's task (${active.taskId}).`);
+    }
+    if (!Number.isInteger(args.topology_revision) || args.topology_revision !== active.topologyRevision) {
+        return errorResult(`record_context_exploration requires this run's topology revision (${active.topologyRevision}).`);
+    }
+    const blocked = args.blocked_reason === 'subagents_unavailable';
+    if (blocked && args.reports.length > 0) {
+        return errorResult('A subagents_unavailable receipt must not claim any read-only subagent reports.');
+    }
+    if (!blocked && (!Array.isArray(args.reports) || args.reports.length < 1)) {
+        return errorResult('record_context_exploration requires at least one structured read-only subagent report.');
+    }
+    try {
+        const scopes = await activeRepositoryScopes(deps.client, active.projectId);
+        const scopeIds = scopes.map((scope) => scope.repository_scope_id);
+        if (scopeIds.length === 0) {
+            return errorResult('record_context_exploration found no active repository scopes for this project.');
+        }
+        if (!blocked) {
+            for (const report of args.reports) {
+                if (!report.agent?.trim() || !report.focus?.trim() || !report.likely_impact?.trim()) {
+                    return errorResult('Every exploration report requires agent, focus, and likely_impact.');
+                }
+                if (!Array.isArray(report.repository_scope_ids) || report.repository_scope_ids.length === 0) {
+                    return errorResult('Every exploration report must be assigned at least one repository scope.');
+                }
+                if (!Array.isArray(report.inspected_paths) || !Array.isArray(report.findings) || report.findings.length === 0) {
+                    return errorResult('Every exploration report requires inspected_paths and at least one finding.');
+                }
+                if (!Array.isArray(report.unresolved_questions)) {
+                    return errorResult('Every exploration report requires an unresolved_questions array (which may be empty).');
+                }
+            }
+            const reportScopeError = exactScopeSet(scopeIds, args.reports.flatMap((report) => report.repository_scope_ids), 'Exploration reports');
+            if (reportScopeError)
+                return errorResult(reportScopeError);
+        }
+        if (!Array.isArray(args.coverage)) {
+            return errorResult('record_context_exploration requires repository coverage.');
+        }
+        const coverageError = exactScopeSet(scopeIds, args.coverage.map((coverage) => coverage.repository_scope_id), 'Repository coverage');
+        if (coverageError)
+            return errorResult(coverageError);
+        const coverageByScope = new Map(args.coverage.map((coverage) => [coverage.repository_scope_id, coverage]));
+        const orderedCoverage = scopeIds.map((scopeId) => coverageByScope.get(scopeId));
+        for (const coverage of orderedCoverage) {
+            if (!coverage.reason?.trim()) {
+                return errorResult('Every exploration coverage entry requires a non-empty reason.');
+            }
+            const unavailable = coverage.disposition === 'unavailable_acknowledged';
+            if (unavailable !== Boolean(coverage.acknowledgement_id)) {
+                return errorResult('Exploration coverage acknowledgement_id is required only for unavailable_acknowledged repositories.');
+            }
+        }
+        const artifactResult = await createArtifactHandler(bindProject(deps, active.projectId), attribution, {
+            task_id: active.taskId,
+            type: 'analysis',
+            format: 'md',
+            content: explorationArtifactContent(args, orderedCoverage),
+            coverage: orderedCoverage,
+        }, active);
+        if (artifactResult.isError)
+            return artifactResult;
+        const first = artifactResult.content[0];
+        if (!first || first.type !== 'text')
+            throw new Error('analysis artifact returned no text result');
+        const payload = JSON.parse(first.text);
+        const artifactId = typeof payload.artifact?.id === 'string' ? payload.artifact.id : null;
+        if (!artifactId)
+            throw new Error('analysis artifact returned no id');
+        session.exploration = {
+            artifactId,
+            taskId: active.taskId,
+            projectId: active.projectId,
+            agentRunId: active.runId,
+            topologyRevision: active.topologyRevision,
+            repositoryScopeIds: scopeIds,
+            status: blocked ? 'blocked' : 'explored',
+        };
+        return textResult({
+            status: blocked ? 'blocked' : 'explored',
+            artifact_id: artifactId,
+            repository_coverage: orderedCoverage,
+            reports_recorded: args.reports.length,
+            instruction: blocked
+                ? 'Read-only subagents are unavailable. Do not make decisions, ask questions, reserve paths, or mutate work. End with a blocked or aborted persistence receipt.'
+                : 'Context exploration is persisted. Decision, question, reservation, and mutation tools are now available for this session.',
+        });
+    }
+    catch (err) {
+        return coordinationError('record_context_exploration', err);
+    }
+}
+function isRealQuestion(text) {
+    const trimmed = text?.trim() ?? '';
+    return trimmed.length >= 4 && /[\p{L}\p{N}]/u.test(trimmed) && trimmed.includes('?');
+}
+function isPersistedAgentQuestion(row, taskId, agentRunId) {
+    if (row.task_id !== taskId || row.agent_run_id !== agentRunId || typeof row.body !== 'string')
+        return false;
+    const match = row.body.match(/^\[question:([a-z_]+)]\s+([\s\S]+)$/);
+    return Boolean(match &&
+        QUESTION_CATEGORIES.includes(match[1]) &&
+        isRealQuestion(match[2]));
+}
+export async function askQuestionHandler(deps, attribution, args, agentRun) {
+    if (args.task_id !== agentRun.taskId) {
+        return errorResult(`ask_question must stay on this agent run's task (${agentRun.taskId}).`);
+    }
+    if (!QUESTION_CATEGORIES.includes(args.category))
+        return errorResult('ask_question requires a supported category.');
+    if (!isRealQuestion(args.question)) {
+        return errorResult('ask_question requires real question text containing a question mark.');
+    }
+    const question = args.question.trim();
+    const result = await addCommentHandler(bindProject(deps, agentRun.projectId), attribution, { task_id: agentRun.taskId, body: `[question:${args.category}] ${question}` }, agentRun.runId);
+    if (result.isError)
+        return result;
+    const first = result.content[0];
+    if (!first || first.type !== 'text')
+        return errorResult('ask_question returned no persisted comment.');
+    const payload = JSON.parse(first.text);
+    return textResult({
+        question: { category: args.category, text: question, comment_id: payload.comment?.id ?? null },
+        comment: payload.comment ?? null,
+    });
+}
+export async function endAgentRunHandler(deps, session, args = {}, options = {}) {
+    const active = runOrError(session, 'end_work');
+    if ('content' in active)
+        return active;
+    try {
+        if (options.requirePersistenceReceipt) {
+            const exploration = session.exploration;
+            const receipt = args.persistence_receipt;
+            if (!exploration || !receipt) {
+                return errorResult('end_work requires a persistence_receipt and this session\'s persisted context exploration artifact.');
+            }
+            const outcome = receipt.outcome ?? 'completed';
+            if (exploration.status === 'blocked' && !['blocked', 'aborted'].includes(outcome)) {
+                return errorResult('A subagents_unavailable session may end only with outcome blocked or aborted.');
+            }
+            if (exploration.status === 'explored' && !['completed', 'blocked'].includes(outcome)) {
+                return errorResult('An explored session may end as completed, or blocked after persisting a question for the user.');
+            }
+            if (exploration.status === 'explored' && outcome === 'blocked') {
+                const questionRows = (await must(deps.client
+                    .from('comments')
+                    .select('id,task_id,agent_run_id,body,created_at')
+                    .eq('task_id', active.taskId)
+                    .eq('agent_run_id', active.runId)
+                    .order('created_at', { ascending: true })
+                    .order('id', { ascending: true }))) ?? [];
+                if (!questionRows.some((row) => isPersistedAgentQuestion(row, active.taskId, active.runId))) {
+                    return errorResult('An explored session may end as blocked only after ask_question persists a real categorized question for this run.');
+                }
+            }
+            if (!Number.isInteger(receipt.final_task_revision) || receipt.final_task_revision < 1) {
+                return errorResult('end_work persistence_receipt requires a positive final_task_revision.');
+            }
+            if (!Array.isArray(receipt.artifact_ids) || receipt.artifact_ids.length === 0) {
+                return errorResult('end_work persistence_receipt requires persisted artifact ids.');
+            }
+            const artifactIds = [...new Set(receipt.artifact_ids)];
+            if (artifactIds.length !== receipt.artifact_ids.length) {
+                return errorResult('end_work persistence_receipt artifact_ids must be unique.');
+            }
+            if (!artifactIds.includes(exploration.artifactId)) {
+                return errorResult('end_work persistence_receipt must include the context exploration artifact id.');
+            }
+            const task = await must(deps.client
+                .from('tasks')
+                .select('id,revision')
+                .eq('id', active.taskId)
+                .eq('project_id', active.projectId)
+                .maybeSingle());
+            if (!task || Number(task.revision) !== receipt.final_task_revision) {
+                return errorResult('end_work final_task_revision is stale. Fetch the task and persist the latest revision first.');
+            }
+            const artifactRows = (await must(deps.client
+                .from('artifacts')
+                .select('id,task_id,agent_run_id,deleted_at')
+                .eq('task_id', active.taskId)
+                .eq('agent_run_id', active.runId)
+                .is('deleted_at', null)
+                .order('created_at', { ascending: true })
+                .order('id', { ascending: true }))) ?? [];
+            const artifactsById = new Map(artifactRows.map((artifact) => [artifact.id, artifact]));
+            const persistedArtifactIds = artifactRows.map((artifact) => artifact.id);
+            const missingArtifactIds = persistedArtifactIds.filter((id) => !artifactIds.includes(id));
+            const foreignArtifactIds = artifactIds.filter((id) => !artifactsById.has(id));
+            if (missingArtifactIds.length > 0 || foreignArtifactIds.length > 0) {
+                return errorResult('end_work persistence_receipt artifact_ids must exactly match every non-deleted artifact persisted by ' +
+                    `this task run. Missing: ${missingArtifactIds.join(', ') || 'none'}. ` +
+                    `Foreign or deleted: ${foreignArtifactIds.join(', ') || 'none'}.`);
+            }
+            const explorationArtifact = artifactsById.get(exploration.artifactId);
+            if (!explorationArtifact || explorationArtifact.task_id !== exploration.taskId ||
+                explorationArtifact.agent_run_id !== exploration.agentRunId) {
+                return errorResult('end_work could not verify this session\'s persisted context exploration artifact.');
+            }
+        }
+        const ended = await must(deps.client.rpc('end_agent_run', {
+            p_run: active.runId,
+            p_reason: args.reason?.trim() || 'completed',
+        }));
+        session.run = null;
+        session.exploration = null;
+        return textResult({
+            ended: Boolean(ended),
+            agent_run_id: active.runId,
+            ...(args.persistence_receipt ? { persistence_receipt: args.persistence_receipt } : {}),
+        });
+    }
+    catch (err) {
+        return coordinationError('end_work', err);
+    }
+}
+// ---------------------------------------------------------------------------
+// Handlers — plain async functions, unit-testable without a transport.
+// ---------------------------------------------------------------------------
+export async function listTasksHandler(deps, args = {}) {
+    try {
+        const projects = await accessibleProjects(deps);
+        if (args.project_id && !projects.some((project) => project.id === args.project_id)) {
+            return errorResult(`Project "${args.project_id}" is not initialized on this machine.`);
+        }
+        const projectIds = args.project_id ? [args.project_id] : projects.map((project) => project.id);
+        if (projectIds.length === 0)
+            return textResult({ projects: [], tasks: [] });
+        let query = deps.client.from('tasks').select(TASK_SELECT);
+        query = projectIds.length === 1
+            ? query.eq('project_id', projectIds[0])
+            : query.in('project_id', projectIds);
+        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(parseTaskRow).map((t, index) => ({
+            id: t.id,
+            project_id: rows[index]?.project_id,
+            project: projects.find((project) => project.id === rows[index]?.project_id) ?? { id: rows[index]?.project_id },
+            name: t.name,
+            status: t.status,
+            owner: t.owner,
+            due_date: t.due_date,
+            tags: t.tags,
+            unmet_dependency_count: t.unmet_dependencies.length,
+        }));
+        return textResult({ projects, tasks });
+    }
+    catch (err) {
+        return errorResult(`list_tasks failed: ${err.message}`);
+    }
+}
+export async function getTaskHandler(deps, _attribution, args, machineId) {
+    try {
+        const { client } = deps;
+        const projects = await accessibleProjects(deps, machineId);
+        const allowedProjectIds = new Set(projects.map((project) => project.id));
+        let highlightArtifactId = null;
+        let row = deps.projectId
+            ? await must(client.from('tasks').select(TASK_SELECT).eq('id', args.id).eq('project_id', deps.projectId).maybeSingle())
+            : await must(client.from('tasks').select(TASK_SELECT).eq('id', args.id).maybeSingle());
+        if (!row) {
+            // spec: get_task also accepts an artifact id (the `/ctrl-spc artifact
+            // <id>` path) — resolve to its parent task, highlighted first.
+            const artifact = await must(client.from('artifacts').select('id,task_id').eq('id', args.id).maybeSingle());
+            if (!artifact)
+                return errorResult(`No task or artifact found for id "${args.id}".`);
+            highlightArtifactId = artifact.id;
+            row = deps.projectId
+                ? await must(client.from('tasks').select(TASK_SELECT).eq('id', artifact.task_id).eq('project_id', deps.projectId).maybeSingle())
+                : await must(client.from('tasks').select(TASK_SELECT).eq('id', artifact.task_id).maybeSingle());
+            if (!row)
+                return errorResult(`No task or artifact found for id "${args.id}".`);
+        }
+        if (!allowedProjectIds.has(row.project_id)) {
+            return errorResult(`The resolved item belongs to project "${row.project_id}", which is not initialized on this machine.`);
+        }
+        const task = parseTaskRow(row);
+        const topologyMachineId = machineId ?? deps.machineId;
+        const [rawComments, rawArtifacts, rawVersions, rawAgentRuns, rawTaskClaims, collaborationDocument, topology] = await Promise.all([
+            must(client
+                .from('comments')
+                .select(COMMENT_SELECT)
+                .eq('task_id', row.id)
+                .order('created_at', { ascending: true })
+                .order('id', { ascending: true })),
+            must(client
+                .from('artifacts')
+                .select(ARTIFACT_SELECT)
+                .eq('task_id', row.id)
+                .is('deleted_at', null)
+                .order('created_at', { ascending: true })
+                .order('id', { ascending: true })),
+            must(client
+                .from('task_versions')
+                .select(TASK_VERSION_SELECT)
+                .eq('task_id', row.id)
+                .order('seq', { ascending: true })
+                .order('id', { ascending: true })),
+            must(client
+                .from('agent_runs')
+                .select(AGENT_RUN_SELECT)
+                .eq('task_id', row.id)
+                .in('state', ['preparing', 'active', 'waiting', 'ready'])
+                .is('ended_at', null)
+                .order('started_at', { ascending: true })
+                .order('id', { ascending: true })),
+            must(client
+                .from('task_claims')
+                .select(TASK_CLAIM_SELECT)
+                .eq('task_id', row.id)
+                .eq('state', 'active')
+                .is('released_at', null)
+                .order('created_at', { ascending: true })
+                .order('id', { ascending: true })),
+            must(client
+                .from('collaboration_documents')
+                .select(COLLABORATION_DOCUMENT_SELECT)
+                .eq('resource_type', 'task_description')
+                .eq('resource_id', row.id)
+                .eq('active', true)
+                .maybeSingle()),
+            topologyMachineId
+                ? loadAgentProjectTopology(client, row.project_id, deps.userId, topologyMachineId)
+                : Promise.resolve(undefined),
+        ]);
+        const comments = sortRecords((rawComments ?? []).map(normalizeComment), 'created_at', 'id');
+        const normalizedArtifacts = sortRecords((rawArtifacts ?? []).map(normalizeArtifact), 'created_at', 'id');
+        const artifacts = highlightArtifactId
+            ? [
+                ...normalizedArtifacts.filter((artifact) => artifact.id === highlightArtifactId),
+                ...normalizedArtifacts.filter((artifact) => artifact.id !== highlightArtifactId),
+            ]
+            : normalizedArtifacts;
+        const taskVersions = sortRecords(rawVersions ?? [], 'seq', 'id');
+        const now = Date.now();
+        const leaseIsLive = (value) => typeof value === 'string' && Number.isFinite(new Date(value).getTime()) && new Date(value).getTime() > now;
+        const activeAgentRuns = sortRecords((rawAgentRuns ?? []).filter((run) => leaseIsLive(run.lease_expires_at)), 'started_at', 'id');
+        const activeRunIds = new Set(activeAgentRuns.map((run) => String(run.id)));
+        const activeTaskClaims = sortRecords((rawTaskClaims ?? []).filter((claim) => activeRunIds.has(String(claim.agent_run_id)) && leaseIsLive(claim.expires_at)), 'created_at', 'fencing_token', 'id');
+        const claimIds = activeTaskClaims.map((claim) => String(claim.id));
+        const rawReservations = claimIds.length > 0
+            ? (await must(client
+                .from('work_reservations')
+                .select(WORK_RESERVATION_SELECT)
+                .in('task_claim_id', claimIds)
+                .is('released_at', null)
+                .order('created_at', { ascending: true })
+                .order('id', { ascending: true }))) ?? []
+            : [];
+        const activeWorkReservations = sortRecords(rawReservations.filter((reservation) => leaseIsLive(reservation.expires_at)), 'created_at', 'fencing_token', 'id');
+        const collaborationPlainText = typeof collaborationDocument?.plain_text === 'string'
+            ? collaborationDocument.plain_text
+            : row.description;
+        const collaborativeDescription = collaborationDocument
+            ? { ...collaborationDocument, plain_text: collaborationPlainText }
+            : {
+                active: false,
+                resource_type: 'task_description',
+                resource_id: row.id,
+                plain_text: row.description,
+                source_revision: row.revision,
+            };
+        const project = projects.find((candidate) => candidate.id === row.project_id) ?? { id: row.project_id };
+        return textResult({
+            project,
+            task: {
+                ...task,
+                description: collaborationPlainText,
+                persisted_description: row.description,
+            },
+            unmet_dependencies: task.unmet_dependencies,
+            predecessor_edges: task.predecessor_edges,
+            dependent_edges: task.dependent_edges,
+            comments,
+            artifacts,
+            task_versions: taskVersions,
+            active_agent_runs: activeAgentRuns,
+            active_task_claims: activeTaskClaims,
+            active_work_reservations: activeWorkReservations,
+            collaborative_description: collaborativeDescription,
+            ...(topology ? { topology } : {}),
+            highlighted_artifact_id: highlightArtifactId,
+            protocol: PROTOCOL_SHORT,
+        });
+    }
+    catch (err) {
+        return errorResult(`get_task failed: ${err.message}`);
+    }
+}
+export async function createTaskHandler(deps, _attribution, args) {
+    try {
+        if (!args.name || !args.name.trim())
+            return errorResult('create_task requires a non-empty name.');
+        const { client, userId } = deps;
+        const projectId = requiredProjectId(deps, 'create_task');
+        const tags = await resolveOrCreateTags(client, projectId, args.tags ?? []);
+        const inserted = await must(client
+            .from('tasks')
+            .insert({
+            project_id: projectId,
+            name: args.name,
+            description: args.description ?? '',
+            owner_id: userId,
+            status: 'backlog',
+        })
+            .select('id')
+            .single());
+        if (!inserted)
+            throw new Error('Task insert returned no row.');
+        const taskId = inserted.id;
+        if (tags.length > 0) {
+            await must(client.from('task_tags').insert(tags.map((t) => ({ task_id: taskId, tag_id: t.id }))));
+        }
+        if (args.depends_on && args.depends_on.length > 0) {
+            await must(client.from('task_dependencies').insert(args.depends_on.map((depId) => ({ task_id: taskId, depends_on_task_id: depId }))));
+        }
+        if (args.before_task_id) {
+            await must(client.rpc('move_task', { p_task_id: taskId, p_status: 'backlog', p_before_task_id: args.before_task_id }));
+        }
+        const fresh = await must(client.from('tasks').select(TASK_SELECT).eq('id', taskId).maybeSingle());
+        if (!fresh)
+            throw new Error('Created task could not be re-fetched.');
+        return textResult({ task: parseTaskRow(fresh) });
+    }
+    catch (err) {
+        return errorResult(`create_task failed: ${err.message}`);
+    }
+}
+export async function updateTaskHandler(deps, _attribution, args, agentRun) {
+    try {
+        const { client } = deps;
+        const projectId = requiredProjectId(deps, 'update_task');
+        const { id, fields, expected_revision } = args;
+        if (agentRun && (id !== agentRun.taskId || projectId !== agentRun.projectId)) {
+            return errorResult(`update_task must stay on this agent run's task ${agentRun.taskId} in project ${agentRun.projectId}.`);
+        }
+        if (!Number.isInteger(expected_revision) || expected_revision < 1) {
+            return errorResult('update_task requires expected_revision from the most recent get_task response.');
+        }
+        // A blank/whitespace-only sprint name would silently create a garbage
+        // sprint row via resolveOrCreateSprint's insert-if-missing path. Reject
+        // it up front — before any query — leaving `null` (clear assignment) as
+        // the only valid way to unset a sprint.
+        if (fields.sprint !== undefined && fields.sprint !== null && fields.sprint.trim() === '') {
+            return errorResult('update_task: sprint name cannot be empty or whitespace-only.');
+        }
+        const current = await must(client.from('tasks').select('id,status,revision').eq('id', id).eq('project_id', projectId).maybeSingle());
+        if (!current)
+            return errorResult(`No task found for id "${id}" in this project.`);
+        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.owner !== undefined)
+            patch.owner_id = await resolveOwnerId(client, fields.owner);
+        if (fields.sprint !== undefined) {
+            patch.sprint_id = fields.sprint === null ? null : await resolveOrCreateSprint(client, projectId, fields.sprint);
+        }
+        if (fields.status !== undefined)
+            patch.status = fields.status;
+        // A status change implies append-to-destination; an explicit
+        // before_task_id reorders within the current/destination column. A
+        // same-value status without before_task_id preserves board position.
+        const statusChanged = fields.status !== undefined && fields.status !== current.status;
+        let tagIds = null;
+        if (fields.tags !== undefined) {
+            const tags = await resolveOrCreateTags(client, projectId, fields.tags);
+            tagIds = tags.map((tag) => tag.id);
+        }
+        await must(client.rpc(agentRun ? 'save_agent_task_if_current' : 'save_task_if_current', agentRun ? {
+            p_run: agentRun.runId,
+            p_claim_fencing_token: agentRun.fencingToken,
+            p_expected_revision: expected_revision,
+            p_changes: patch,
+            p_tag_ids: tagIds,
+            p_reorder: statusChanged || fields.before_task_id !== undefined,
+            p_before_task_id: fields.before_task_id ?? null,
+        } : {
+            p_task_id: id,
+            p_expected_revision: expected_revision,
+            p_changes: patch,
+            p_tag_ids: tagIds,
+            p_reorder: statusChanged || fields.before_task_id !== undefined,
+            p_before_task_id: fields.before_task_id ?? null,
+        }));
+        const fresh = await must(client.from('tasks').select(TASK_SELECT).eq('id', id).maybeSingle());
+        if (!fresh)
+            throw new Error('Updated task could not be re-fetched.');
+        return textResult({ task: parseTaskRow(fresh) });
+    }
+    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.');
+        }
+        if (agentRun)
+            return coordinationError('update_task', err);
+        return errorResult(`update_task failed: ${err.message}`);
+    }
+}
+export async function createArtifactHandler(deps, attribution, args, agentRun) {
+    try {
+        if (!args.task_id)
+            return errorResult('create_artifact requires task_id.');
+        if (!args.content)
+            return errorResult('create_artifact requires content.');
+        if (agentRun) {
+            if (agentRun.state !== 'joined') {
+                return errorResult('create_artifact is blocked while repositories are unavailable. Fetch or acknowledge them, then call begin_work again.');
+            }
+            if (args.task_id !== agentRun.taskId) {
+                return errorResult(`create_artifact task_id must match this agent run's task (${agentRun.taskId}).`);
+            }
+            if (!Array.isArray(args.coverage) || args.coverage.length === 0) {
+                return errorResult('create_artifact requires repository coverage for every active project scope.');
+            }
+            for (const coverage of args.coverage) {
+                if (!coverage.repository_scope_id || !coverage.reason?.trim()) {
+                    return errorResult('Every create_artifact coverage entry requires repository_scope_id and a non-empty reason.');
+                }
+                const unavailable = coverage.disposition === 'unavailable_acknowledged';
+                if (unavailable !== Boolean(coverage.acknowledgement_id)) {
+                    return errorResult('create_artifact coverage acknowledgement_id is required only for unavailable_acknowledged repositories.');
+                }
+            }
+            const artifact = await must(deps.client.rpc('create_agent_artifact', {
+                p_run: agentRun.runId,
+                p_claim_fencing_token: agentRun.fencingToken,
+                p_topology_revision: agentRun.topologyRevision,
+                p_type: args.type,
+                p_format: args.format ?? 'md',
+                p_content: args.content,
+                p_storage_path: null,
+                p_coverage: args.coverage.map((coverage) => ({
+                    repository_scope_id: coverage.repository_scope_id,
+                    disposition: coverage.disposition,
+                    reason: coverage.reason.trim(),
+                    acknowledgement_id: coverage.acknowledgement_id ?? null,
+                })),
+            }));
+            if (!artifact)
+                throw new Error('create_agent_artifact returned no artifact');
+            return textResult({ artifact, repository_coverage: args.coverage });
+        }
+        if (attribution) {
+            return errorResult('Agent artifacts require a joined agent run and complete repository coverage.');
+        }
+        const task = await must(deps.client.from('tasks').select('id').eq('id', args.task_id)
+            .eq('project_id', requiredProjectId(deps, 'create_artifact')).maybeSingle());
+        if (!task)
+            return errorResult(`No task found for id "${args.task_id}" in this project.`);
+        const row = await must(deps.client
+            .from('artifacts')
+            .insert({
+            task_id: args.task_id,
+            type: args.type,
+            format: args.format ?? 'md',
+            content: args.content,
+            created_by: deps.userId,
+            from_agent: null,
+            agent_run_id: null,
+        })
+            .select('id,task_id,type,format,content,storage_path,created_by,from_agent,created_at')
+            .single());
+        if (!row)
+            throw new Error('Artifact insert returned no row.');
+        return textResult({ artifact: row });
+    }
+    catch (err) {
+        if (agentRun)
+            return coordinationError('create_artifact', err);
+        return errorResult(`create_artifact failed: ${err.message}`);
+    }
+}
+export async function addCommentHandler(deps, attribution, args, agentRunId) {
+    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(deps.client.from('tasks').select('id').eq('id', args.task_id)
+            .eq('project_id', requiredProjectId(deps, 'add_comment')).maybeSingle());
+        if (!task)
+            return errorResult(`No task found for id "${args.task_id}" in this project.`);
+        const row = await must(deps.client
+            .from('comments')
+            .insert({
+            task_id: args.task_id,
+            author_id: deps.userId,
+            body: args.body,
+            from_agent: attribution,
+            agent_run_id: agentRunId ?? null,
+        })
+            .select('id,task_id,body,author_id,from_agent,created_at,updated_at')
+            .single());
+        if (!row)
+            throw new Error('Comment insert returned no row.');
+        return textResult({ comment: row });
+    }
+    catch (err) {
+        return errorResult(`add_comment failed: ${err.message}`);
+    }
+}
+export function protocolPromptHandler() {
+    return {
+        description: 'CTRL+SPC §5a agent working protocol',
+        messages: [{ role: 'user', content: { type: 'text', text: PROTOCOL_FULL } }],
+    };
+}
+// ---------------------------------------------------------------------------
+// Wiring — Streamable HTTP transport on a plain node:http server, session
+// mode (spec: clientInfo must be captured for attribution; in stateless mode
+// the initialize request doesn't durably attach to a Server instance across
+// requests, so this uses `sessionIdGenerator: () => randomUUID()` and one
+// `McpServer` per session — `server.server.getClientVersion()` is populated
+// synchronously during that session's `initialize` request and stays valid
+// for every later tool call on the same transport/session).
+// ---------------------------------------------------------------------------
+const IDLE_TIMEOUT_MS = 10 * 60 * 1000;
+const HEARTBEAT_INTERVAL_MS = 30 * 1000;
+export const BROKER_VERSION = '1.2.0';
+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;
+}
+export async function startMcpServer(deps) {
+    const port = deps.port ?? MCP_PORT;
+    const machineId = deps.machineId ?? getMachineIdentity().id;
+    const handlerDeps = {
+        client: deps.client,
+        ...(deps.projectId ? { projectId: deps.projectId } : {}),
+        machineId,
+        userId: deps.userId,
+        presence: deps.presence,
+    };
+    function resultMessage(result) {
+        const first = result.content[0];
+        return first?.type === 'text' ? first.text : 'unknown coordination error';
+    }
+    function stopRunTimers(session) {
+        if (session.idleTimer)
+            clearTimeout(session.idleTimer);
+        if (session.heartbeatTimer)
+            clearInterval(session.heartbeatTimer);
+        session.idleTimer = undefined;
+        session.heartbeatTimer = undefined;
+        session.heartbeatFailures = 0;
+    }
+    async function endManagedSession(session, reason) {
+        if (session.ending)
+            return session.ending;
+        session.ending = (async () => {
+            stopRunTimers(session);
+            if (!session.context.run)
+                return;
+            const result = await endAgentRunHandler(handlerDeps, session.context, { reason });
+            if (result.isError) {
+                // The durable lease still expires server-side. Drop local authority so
+                // a disconnected/stale agent cannot keep mutating through this session.
+                console.warn(`Warning: could not end agent run cleanly: ${resultMessage(result)}`);
+                session.context.run = null;
+                session.context.exploration = null;
+            }
+        })();
+        try {
+            await session.ending;
+        }
+        finally {
+            session.ending = undefined;
+        }
+    }
+    function resetSessionIdleTimer(session) {
+        if (!session.context.run)
+            return;
+        if (session.idleTimer)
+            clearTimeout(session.idleTimer);
+        session.idleTimer = setTimeout(() => {
+            void endManagedSession(session, 'MCP session idle timeout');
+        }, IDLE_TIMEOUT_MS);
+        session.idleTimer.unref();
+    }
+    function startRunTimers(session) {
+        stopRunTimers(session);
+        session.heartbeatFailures = 0;
+        resetSessionIdleTimer(session);
+        session.heartbeatTimer = setInterval(() => {
+            if (!session.context.run)
+                return;
+            void heartbeatAgentRunHandler(handlerDeps, session.context).then((result) => {
+                if (!result.isError) {
+                    session.heartbeatFailures = 0;
+                    return;
+                }
+                console.warn(`Warning: agent lease heartbeat failed: ${resultMessage(result)}`);
+                session.heartbeatFailures = (session.heartbeatFailures ?? 0) + 1;
+                const definitelyLost = /no longer owns an active lease/i.test(resultMessage(result));
+                if (definitelyLost || session.heartbeatFailures >= 3) {
+                    stopRunTimers(session);
+                    session.context.run = null;
+                }
+            });
+        }, HEARTBEAT_INTERVAL_MS);
+        session.heartbeatTimer.unref();
+    }
+    function requireActiveSessionRun(session, tool) {
+        if (!session.context.run) {
+            return errorResult(`${tool} requires begin_work in this MCP session before any mutation.`);
+        }
+        if (session.context.run.state !== 'joined') {
+            return errorResult(`${tool} is blocked while required repositories are unavailable. ` +
+                'Only heartbeat_work, acknowledge_unavailable_checkout, end_work, and begin_work are allowed for this waiting run.');
+        }
+        resetSessionIdleTimer(session);
+        return null;
+    }
+    function requireExploredSessionRun(session, tool) {
+        const missing = requireActiveSessionRun(session, tool);
+        if (missing)
+            return missing;
+        const run = session.context.run;
+        const exploration = session.context.exploration;
+        if (!exploration || exploration.agentRunId !== run.runId ||
+            exploration.taskId !== run.taskId || exploration.topologyRevision !== run.topologyRevision) {
+            return errorResult(`${tool} is blocked until record_context_exploration persists complete read-only subagent reports ` +
+                'and repository coverage for this task and topology revision.');
+        }
+        if (exploration.status !== 'explored') {
+            return errorResult(`${tool} is blocked because read-only subagents were unavailable. ` +
+                'Do not continue; end_work with a blocked or aborted persistence receipt.');
+        }
+        return null;
+    }
+    function buildServer(session) {
+        const server = new McpServer({ name: 'ctrl-spc', version: BROKER_VERSION });
+        function attribution() {
+            return attributionFromClientName(server.server.getClientVersion()?.name);
+        }
+        function syncClientIdentity() {
+            const info = server.server.getClientVersion();
+            session.context.clientName = info?.name ?? '';
+            session.context.clientVersion = info?.version ?? '';
+            session.context.agentKind = attributionFromClientName(info?.name) ?? info?.name?.trim() ?? 'unknown';
+        }
+        server.registerTool('list_tasks', {
+            description: 'List tasks across every project initialized on this machine, with project identity. Optionally filter to one project.',
+            inputSchema: { project_id: z.string().optional() },
+        }, async (args) => {
+            resetSessionIdleTimer(session);
+            return listTasksHandler(handlerDeps, args);
+        });
+        server.registerTool('get_task', {
+            description: 'Read a full task — tags, sprint, comments, live artifacts, unmet dependencies, and compact protocol. Also accepts an artifact id. This read has no status, presence, claim, or reservation side effects; call begin_work explicitly before editing.',
+            inputSchema: { id: z.string().describe('Task id, or an artifact id (resolves to its parent task)') },
+        }, async ({ id }) => {
+            resetSessionIdleTimer(session);
+            return getTaskHandler(handlerDeps, attribution(), { id }, session.context.machineId);
+        });
+        server.registerTool('begin_work', {
+            description: 'Explicitly begin work on a task. The first live agent coordinates; later agents join as collaborators. No agent may edit repository paths until reserve_work_paths succeeds.',
+            inputSchema: { task_id: z.string() },
+        }, async (args) => {
+            syncClientIdentity();
+            const result = await beginAgentRunHandler(handlerDeps, session.context, args);
+            if (!result.isError && session.context.run)
+                startRunTimers(session);
+            return result;
+        });
+        server.registerTool('heartbeat_work', { description: 'Refresh this MCP session\'s agent-run lease. The broker also does this automatically.' }, async () => {
+            resetSessionIdleTimer(session);
+            return heartbeatAgentRunHandler(handlerDeps, session.context);
+        });
+        server.registerTool('reserve_work_paths', {
+            description: 'Atomically reserve repository-relative paths before editing. Write reservations require the exact repository_checkout_id from get_task topology.checkouts, including when selecting an isolated worktree.',
+            inputSchema: {
+                topology_revision: z.number().int().positive(),
+                reservations: z.array(z.object({
+                    repository_scope_id: z.string(),
+                    repository_checkout_id: z.string().optional().describe('Required for write mode; choose an exact id from get_task topology.checkouts'),
+                    path: z.string().optional().describe('Path relative to the selected repository scope; empty means the whole scope'),
+                    mode: z.enum(['read', 'write']).optional(),
+                    intent: z.string().optional(),
+                })).min(1),
+            },
+        }, async (args) => {
+            const missing = requireExploredSessionRun(session, 'reserve_work_paths');
+            if (missing)
+                return missing;
+            return reserveWorkPathsHandler(handlerDeps, session.context, args);
+        });
+        server.registerTool('record_context_exploration', {
+            description: 'Persist structured read-only subagent exploration for every active repository scope before any decision, question, reservation, or mutation.',
+            inputSchema: {
+                task_id: z.string(),
+                topology_revision: z.number().int().positive(),
+                reports: z.array(z.object({
+                    agent: z.string(),
+                    focus: z.string(),
+                    repository_scope_ids: z.array(z.string()).min(1),
+                    inspected_paths: z.array(z.string()),
+                    findings: z.array(z.string()).min(1),
+                    likely_impact: z.string(),
+                    unresolved_questions: z.array(z.string()),
+                })),
+                coverage: z.array(z.object({
+                    repository_scope_id: z.string(),
+                    disposition: z.enum(['affected', 'reviewed_no_change', 'context_only', 'unavailable_acknowledged']),
+                    reason: z.string(),
+                    acknowledgement_id: z.string().nullable().optional(),
+                })).min(1),
+                summary: z.string().optional(),
+                blocked_reason: z.literal('subagents_unavailable').optional(),
+            },
+        }, async (args) => {
+            const missing = requireActiveSessionRun(session, 'record_context_exploration');
+            if (missing)
+                return missing;
+            return recordContextExplorationHandler(handlerDeps, attribution(), session.context, args);
+        });
+        server.registerTool('release_work_paths', {
+            description: 'Release selected reservations, or every reservation owned by this agent when reservation_ids is omitted.',
+            inputSchema: { reservation_ids: z.array(z.string()).optional() },
+        }, async (args) => {
+            resetSessionIdleTimer(session);
+            return releaseWorkPathsHandler(handlerDeps, session.context, args);
+        });
+        server.registerTool('transfer_coordination', {
+            description: 'Hand coordinator authority to an active collaborator on this task. The caller remains joined as a collaborator.',
+            inputSchema: { target_run_id: z.string() },
+        }, async (args) => {
+            resetSessionIdleTimer(session);
+            return transferCoordinationHandler(handlerDeps, session.context, args);
+        });
+        server.registerTool('acknowledge_unavailable_checkout', {
+            description: 'Record that one project repository could not be inspected locally after warning the user and offering to fetch it. This never pretends the repository was reviewed.',
+            inputSchema: { repository_scope_id: z.string(), reason: z.string() },
+        }, async (args) => {
+            resetSessionIdleTimer(session);
+            return acknowledgeUnavailableCheckoutHandler(handlerDeps, session.context, args);
+        });
+        server.registerTool('end_work', {
+            description: 'End only this agent run after verifying its final task revision and persisted artifact receipt. Other collaborators remain active.',
+            inputSchema: {
+                reason: z.string().optional(),
+                persistence_receipt: z.object({
+                    final_task_revision: z.number().int().positive(),
+                    artifact_ids: z.array(z.string()).min(1),
+                    outcome: z.enum(['completed', 'blocked', 'aborted']).optional(),
+                }),
+            },
+        }, async (args) => {
+            const result = await endAgentRunHandler(handlerDeps, session.context, args, { requirePersistenceReceipt: true });
+            if (!result.isError)
+                stopRunTimers(session);
+            return result;
+        });
+        server.registerTool('create_task', {
+            description: 'Create a task in this agent run\'s bound project (status: backlog). Used when a work item is split.',
+            inputSchema: {
+                name: z.string(),
+                description: z.string().optional(),
+                tags: z.array(z.string()).optional(),
+                depends_on: z.array(z.string()).optional().describe('Task ids this new task depends on'),
+                before_task_id: z.string().optional().describe('Insert before this task in the backlog column'),
+            },
+        }, async (args) => {
+            const missing = requireExploredSessionRun(session, 'create_task');
+            if (missing)
+                return missing;
+            const run = session.context.run;
+            return createTaskHandler(bindProject(handlerDeps, run.projectId), attribution(), args);
+        });
+        server.registerTool('update_task', {
+            description: 'Update a task atomically. Pass the revision from get_task; stale updates are rejected so another person’s changes are never silently overwritten. Returns the fresh task.',
+            inputSchema: {
+                id: z.string(),
+                expected_revision: z.number().int().positive().describe('The revision returned by the most recent get_task call'),
+                fields: z.object({
+                    name: z.string().optional(),
+                    description: z.string().optional(),
+                    due_date: z.string().nullable().optional(),
+                    owner: z.string().optional().describe('Email or profile id'),
+                    status: z.enum(['backlog', 'in_progress', 'done']).optional(),
+                    sprint: z.string().nullable().optional().describe('Sprint name — resolved or created'),
+                    tags: z.array(z.string()).optional().describe('Full replacement tag set, by name'),
+                    before_task_id: z.string().nullable().optional(),
+                }),
+            },
+        }, async (args) => {
+            const missing = requireExploredSessionRun(session, 'update_task');
+            if (missing)
+                return missing;
+            const run = session.context.run;
+            return updateTaskHandler(bindProject(handlerDeps, run.projectId), attribution(), args, run);
+        });
+        server.registerTool('create_artifact', {
+            description: 'Persist an analysis/plan/spec/diagram/mock/wireframe on a task after context exploration. Never write planning documents into a repository.',
+            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'),
+                content: z.string(),
+                coverage: z.array(z.object({
+                    repository_scope_id: z.string(),
+                    disposition: z.enum(['affected', 'reviewed_no_change', 'context_only', 'unavailable_acknowledged']),
+                    reason: z.string(),
+                    acknowledgement_id: z.string().nullable().optional(),
+                })).min(1).describe('Exactly one disposition for every active repository scope returned by get_task'),
+            },
+        }, async (args) => {
+            const missing = requireExploredSessionRun(session, 'create_artifact');
+            if (missing)
+                return missing;
+            const run = session.context.run;
+            return createArtifactHandler(bindProject(handlerDeps, run.projectId), attribution(), args, run);
+        });
+        server.registerTool('ask_question', {
+            description: 'Persist a categorized, actionable question after complete context exploration. Questions are comments on the current work item.',
+            inputSchema: {
+                task_id: z.string(),
+                category: z.enum(['clarification', 'reproduction', 'intent', 'dependency', 'checkout', 'collision', 'split']),
+                question: z.string(),
+            },
+        }, async (args) => {
+            const missing = requireExploredSessionRun(session, 'ask_question');
+            if (missing)
+                return missing;
+            const run = session.context.run;
+            return askQuestionHandler(handlerDeps, attribution(), args, run);
+        });
+        server.registerTool('add_comment', {
+            description: 'Legacy question-only alias. Agent progress narration is not persisted; use ask_question for categorized questions.',
+            inputSchema: { task_id: z.string(), body: z.string() },
+        }, async (args) => {
+            const missing = requireExploredSessionRun(session, 'add_comment');
+            if (missing)
+                return missing;
+            const run = session.context.run;
+            if (args.task_id !== run.taskId) {
+                return errorResult(`add_comment must stay on this agent run's task (${run.taskId}).`);
+            }
+            if (!isRealQuestion(args.body)) {
+                return errorResult('add_comment is question-only for agent sessions. Use ask_question with real question text.');
+            }
+            return askQuestionHandler(handlerDeps, attribution(), {
+                task_id: args.task_id,
+                category: 'clarification',
+                question: args.body,
+            }, run);
+        });
+        server.registerPrompt('ctrl-spc-protocol', { description: 'The full §5a agent working protocol.' }, async () => {
+            resetSessionIdleTimer(session);
+            return protocolPromptHandler();
+        });
+        return server;
+    }
+    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', machine_id: machineId, version: BROKER_VERSION }));
+            return;
+        }
+        if (url.pathname !== '/mcp') {
+            res.writeHead(404).end('Not found');
+            return;
+        }
+        try {
+            const sessionIdHeader = req.headers['mcp-session-id'];
+            const sessionId = typeof sessionIdHeader === 'string' ? sessionIdHeader : undefined;
+            const existing = sessionId ? sessions.get(sessionId) : undefined;
+            if (existing) {
+                await existing.transport.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 context = {
+                sessionId: randomUUID(),
+                machineId,
+                agentKind: 'unknown',
+                clientName: '',
+                clientVersion: '',
+                run: null,
+                exploration: null,
+            };
+            let managed;
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (sid) => {
+                    context.sessionId = sid;
+                    sessions.set(sid, managed);
+                },
+                // Security: reject requests whose Host header doesn't match the
+                // server we actually bound (localhost-only, see `httpServer.listen`
+                // below) — closes the DNS-rebinding hole where a page on a public
+                // domain that resolves to 127.0.0.1 could otherwise drive this MCP
+                // server from a victim's browser.
+                enableDnsRebindingProtection: true,
+                allowedHosts: [`localhost:${port}`, `127.0.0.1:${port}`],
+            });
+            managed = { transport, context };
+            transport.onclose = () => {
+                const sid = transport.sessionId;
+                if (sid)
+                    sessions.delete(sid);
+                void endManagedSession(managed, 'MCP transport closed');
+            };
+            const server = buildServer(managed);
+            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);
+    });
+    // Security: bind loopback-only (matches login.ts's callback server) — an
+    // unqualified `listen(port, cb)` binds all interfaces (`::`), exposing the
+    // write-back tool surface to anything on the local network.
+    //
+    // A bare `listen(port, resolve)` also has no failure path: if the port is
+    // already taken (e.g. a second `ctrl-spc` instance in another repo), Node
+    // emits an unhandled 'error' event and the process dies with a raw
+    // EADDRINUSE stack — after presence has already been tracked as
+    // "available". The 'error'/'listening' race below turns that into a
+    // rejected promise so the caller (run.ts) can untrack presence and print a
+    // friendly message before exiting.
+    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');
+    });
+    return {
+        async close() {
+            const activeSessions = [...sessions.values()];
+            await Promise.all(activeSessions.map((session) => endManagedSession(session, 'CTRL+SPC broker stopped').catch(() => { })));
+            await Promise.all(activeSessions.map((session) => session.transport.close().catch(() => { })));
+            sessions.clear();
+            await new Promise((resolve, reject) => {
+                httpServer.close((err) => (err ? reject(err) : resolve()));
+            });
+        },
+    };
+}