@ctrl-spc/cli 1.1.15 → 1.2.0

package/dist/commands/run.js

@@ -0,0 +1,622 @@
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { getClient } from '../supabase.js';
+import { currentRepoRemote, normalizeRemoteUrl } from '../git.js';
+import { detectAgents, resolveAgentCommand } from '../agents.js';
+import { claudeSkillPath, codexSkillPath, installSkills } from '../skills.js';
+import { startPresence } from '../presence.js';
+import { MCP_PORT } from '../env.js';
+import { startMcpServer } from '../mcp.js';
+import { getMachineIdentity } from '../config.js';
+import { discoverRepositoryTopology } from '../topology.js';
+function mcpUrl() {
+    return `http://localhost:${MCP_PORT}/mcp`;
+}
+export async function existingBrokerStatus(machineId, port = MCP_PORT, fetcher = fetch) {
+    try {
+        const response = await fetcher(`http://127.0.0.1:${port}/health`, {
+            method: 'GET',
+            signal: AbortSignal.timeout(750),
+        });
+        if (!response.ok)
+            return 'not_running';
+        const health = await response.json();
+        if (health.status !== 'ok' || !health.machine_id)
+            return 'not_running';
+        return health.machine_id === machineId ? 'same_machine' : 'different_machine';
+    }
+    catch {
+        return 'not_running';
+    }
+}
+function one(value) {
+    return Array.isArray(value) ? value[0] ?? null : value;
+}
+function isWithin(parent, child) {
+    const path = relative(parent, child);
+    return path === '' || (!path.startsWith(`..${sep}`) && path !== '..' && !isAbsolute(path));
+}
+function gitText(cwd, args) {
+    try {
+        const output = execFileSync('git', args, {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return output || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Inspect only a path already discovered or previously registered. */
+export function inspectLocalCheckout(path) {
+    if (!existsSync(path))
+        return null;
+    const remote = currentRepoRemote(path);
+    const gitDir = gitText(path, ['rev-parse', '--path-format=absolute', '--git-dir']);
+    const commonDir = gitText(path, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+    return {
+        localPath: path,
+        remoteKey: remote ? normalizeRemoteUrl(remote) : null,
+        headSha: gitText(path, ['rev-parse', 'HEAD']),
+        isWorktree: Boolean(gitDir && commonDir && gitDir !== commonDir),
+    };
+}
+/**
+ * Discovers checkouts from real Git roots only. Alternate linked worktrees are
+ * inspected independently; a repository without a verifiable origin is kept
+ * as an observation but can never be matched to a hosted repository record.
+ */
+export function observeLocalWorkspace(cwd) {
+    const topology = discoverRepositoryTopology(cwd);
+    const paths = new Set();
+    for (const repository of topology.repositories) {
+        paths.add(repository.rootPath);
+        for (const alternate of repository.alternateWorktreeRoots)
+            paths.add(alternate);
+    }
+    return {
+        workspaceRoot: topology.scanRoot,
+        checkouts: [...paths]
+            .sort((left, right) => left.localeCompare(right))
+            .map(inspectLocalCheckout)
+            .filter((checkout) => checkout !== null),
+    };
+}
+export async function registerMachineIdentity(client, userId, machine, now = new Date().toISOString()) {
+    const { error } = await client.from('machines').upsert({
+        id: machine.id,
+        user_id: userId,
+        name: machine.name,
+        last_seen_at: now,
+    }, { onConflict: 'id' });
+    if (error)
+        throw new Error(`Could not register this machine: ${error.message}`);
+}
+export async function loadMachineProjects(client, userId, machineId) {
+    const { data, error } = await client
+        .from('machine_workspaces')
+        .select('project_id,project:projects!machine_workspaces_project_id_fkey(id,name)')
+        .eq('user_id', userId)
+        .eq('machine_id', machineId);
+    if (error)
+        throw new Error(`Could not load initialized projects: ${error.message}`);
+    const projects = new Map();
+    for (const row of (data ?? [])) {
+        const project = one(row.project);
+        if (project)
+            projects.set(project.id, project);
+    }
+    return [...projects.values()].sort((left, right) => left.name.localeCompare(right.name) || left.id.localeCompare(right.id));
+}
+/** Legacy fallback only: multiple projects sharing one remote are deliberately
+ * returned as multiple candidates, never collapsed to an arbitrary project. */
+export async function legacyCurrentProjectCandidates(client, cwd) {
+    const remote = currentRepoRemote(cwd);
+    if (!remote)
+        return [];
+    const { data, error } = await client
+        .from('projects')
+        .select('id,name')
+        .eq('git_remote_url', normalizeRemoteUrl(remote));
+    if (error)
+        throw new Error(`Could not resolve the current repository: ${error.message}`);
+    return (data ?? []).sort((left, right) => left.name.localeCompare(right.name) || left.id.localeCompare(right.id));
+}
+function checkoutPlan(workspaceId, repositories, observation, existing, inspectCheckout, verifiedAt) {
+    const rows = new Map();
+    const availableRepositoryIds = new Set();
+    const record = (repositoryId, checkout, fallback) => {
+        const localPath = checkout?.localPath ?? fallback?.local_path;
+        if (!localPath)
+            return; // A missing repository without a known path is not fabricated.
+        const expectedRemote = [...repositories.entries()].find(([, id]) => id === repositoryId)?.[0];
+        if (!expectedRemote)
+            return;
+        const availability = checkout === null
+            ? 'missing'
+            : checkout.remoteKey === expectedRemote
+                ? 'available'
+                : 'mismatched';
+        if (availability === 'available')
+            availableRepositoryIds.add(repositoryId);
+        rows.set(`${repositoryId}\u0000${localPath}`, {
+            machine_workspace_id: workspaceId,
+            repository_id: repositoryId,
+            local_path: localPath,
+            availability,
+            verified_remote_key: checkout?.remoteKey ?? fallback?.verified_remote_key ?? null,
+            head_sha: checkout?.headSha ?? fallback?.head_sha ?? null,
+            is_worktree: checkout?.isWorktree ?? fallback?.is_worktree ?? false,
+            verified_at: verifiedAt,
+        });
+    };
+    for (const checkout of observation.checkouts) {
+        if (!checkout.remoteKey)
+            continue;
+        const repositoryId = repositories.get(checkout.remoteKey);
+        if (repositoryId)
+            record(repositoryId, checkout, null);
+    }
+    // A previous mapping is deterministic evidence for a now-missing checkout.
+    // Re-inspect it instead of assuming that an absent discovery result means
+    // the directory disappeared; it may simply sit outside today's scan root.
+    for (const prior of existing) {
+        if (![...repositories.values()].includes(prior.repository_id))
+            continue;
+        const key = `${prior.repository_id}\u0000${prior.local_path}`;
+        if (rows.has(key))
+            continue;
+        record(prior.repository_id, inspectCheckout(prior.local_path), prior);
+    }
+    return { rows: [...rows.values()], availableRepositoryIds };
+}
+/**
+ * Registers the stable machine, this project's private workspace root, and
+ * every checkout that can be proven from Git or a prior local mapping.
+ */
+export async function registerMachineWorkspace(client, userId, projectId, machine, cwd, deps = {}) {
+    const now = (deps.now ?? (() => new Date().toISOString()))();
+    const observation = (deps.observeWorkspace ?? observeLocalWorkspace)(cwd);
+    await registerMachineIdentity(client, userId, machine, now);
+    const { data: scopeData, error: scopeError } = await client
+        .from('project_repository_scopes')
+        .select('required,scope:repository_scopes!project_repository_scopes_repository_scope_id_fkey(' +
+        'repository_id,repository:repositories!repository_scopes_repository_id_fkey(id,remote_key))')
+        .eq('project_id', projectId)
+        .eq('active', true);
+    if (scopeError)
+        throw new Error(`Could not load project repositories: ${scopeError.message}`);
+    const repositories = new Map();
+    const requiredRepositoryIds = new Set();
+    for (const row of (scopeData ?? [])) {
+        const scope = one(row.scope);
+        const repository = scope ? one(scope.repository) : null;
+        if (repository) {
+            repositories.set(repository.remote_key, repository.id);
+            if (row.required)
+                requiredRepositoryIds.add(repository.id);
+        }
+    }
+    if (repositories.size === 0) {
+        throw new Error('This project has no active repository topology. Run `ctrl-spc init` again to repair it.');
+    }
+    const { data: priorWorkspaceData, error: priorWorkspaceError } = await client
+        .from('machine_workspaces')
+        .select('id,workspace_root')
+        .eq('user_id', userId)
+        .eq('machine_id', machine.id)
+        .eq('project_id', projectId)
+        .maybeSingle();
+    if (priorWorkspaceError) {
+        throw new Error(`Could not load this project workspace: ${priorWorkspaceError.message}`);
+    }
+    const priorWorkspace = priorWorkspaceData;
+    // Running later from one child repository must not shrink a previously
+    // registered combined workspace back down to that child. Likewise, a
+    // broker launched from project A must not move project B's workspace root.
+    const observationMatchesProject = observation.checkouts.some((checkout) => checkout.remoteKey !== null && repositories.has(checkout.remoteKey));
+    const workspaceRoot = priorWorkspace && (isWithin(priorWorkspace.workspace_root, observation.workspaceRoot) || !observationMatchesProject)
+        ? priorWorkspace.workspace_root
+        : observation.workspaceRoot;
+    const { data: workspaceData, error: workspaceError } = await client
+        .from('machine_workspaces')
+        .upsert({
+        user_id: userId,
+        machine_id: machine.id,
+        project_id: projectId,
+        workspace_root: workspaceRoot,
+        verified_at: now,
+    }, { onConflict: 'user_id,machine_id,project_id' })
+        .select('id')
+        .single();
+    if (workspaceError || !workspaceData) {
+        throw new Error(`Could not register this project workspace: ${workspaceError?.message ?? 'no workspace returned'}`);
+    }
+    const workspaceId = workspaceData.id;
+    const { data: existingData, error: existingError } = await client
+        .from('repository_checkouts')
+        .select('repository_id,local_path,verified_remote_key,head_sha,is_worktree')
+        .eq('machine_workspace_id', workspaceId);
+    if (existingError)
+        throw new Error(`Could not load repository checkouts: ${existingError.message}`);
+    const plan = checkoutPlan(workspaceId, repositories, observation, (existingData ?? []), deps.inspectCheckout ?? inspectLocalCheckout, now);
+    for (const row of plan.rows) {
+        const { error } = await client.from('repository_checkouts').upsert(row, {
+            onConflict: 'machine_workspace_id,repository_id,local_path',
+        });
+        if (error)
+            throw new Error(`Could not register repository checkout ${row.local_path}: ${error.message}`);
+    }
+    // Preserve a combine/separate relink marker until the entire reconciliation
+    // succeeds and every repository used by a required scope is available.
+    // Optional-only repositories are still inspected above, but do not make a
+    // workspace permanently impossible to acknowledge.
+    const requiredRepositoriesAvailable = [...requiredRepositoryIds]
+        .every((repositoryId) => plan.availableRepositoryIds.has(repositoryId));
+    if (requiredRepositoriesAvailable) {
+        const { error } = await client
+            .from('machine_workspaces')
+            .update({ needs_relink: false })
+            .eq('id', workspaceId);
+        if (error)
+            throw new Error(`Could not confirm this project workspace relink: ${error.message}`);
+    }
+    return {
+        workspaceId,
+        availableRepositories: plan.availableRepositoryIds.size,
+        missingRepositories: repositories.size - plan.availableRepositoryIds.size,
+    };
+}
+/**
+ * Turns a raw MCP-server startup rejection into the error `run()` throws.
+ * `EADDRINUSE` specifically (a second `ctrl-spc` instance, or anything else
+ * bound to the port) gets a message a human can act on instead of a raw
+ * Node stack; anything else passes through unchanged.
+ */
+export function formatMcpStartupError(err, port) {
+    if (err?.code === 'EADDRINUSE') {
+        return new Error(`port ${port} in use — is another ctrl-spc running? (override with CTRL_SPC_PORT)`);
+    }
+    return err instanceof Error ? err : new Error(String(err));
+}
+const runCommand = (command, args) => execFileSync(command, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+});
+function claudeScope(details) {
+    const scope = details.match(/Scope:\s*(User|Local|Project)/i)?.[1]?.toLowerCase();
+    return scope === 'user' || scope === 'local' || scope === 'project' ? scope : undefined;
+}
+function failedCommandOutput(err) {
+    const stdout = err?.stdout;
+    return typeof stdout === 'string' ? stdout : stdout?.toString('utf8') ?? '';
+}
+function syncClaudeMcp(command, url, runner) {
+    let details = '';
+    try {
+        details = runner(command, ['mcp', 'get', 'ctrl-spc']);
+    }
+    catch (err) {
+        // Claude's `mcp get` health-checks HTTP servers and can exit non-zero
+        // while ctrl-spc is still starting, even though it prints the saved URL
+        // and scope. Preserve that stdout so a correct registration is not
+        // mistaken for a missing one.
+        details = failedCommandOutput(err);
+    }
+    const scope = claudeScope(details);
+    if (details.includes(`URL: ${url}`) && scope === 'user') {
+        console.log('Claude MCP: ctrl-spc registered (user scope).');
+        return;
+    }
+    if (details) {
+        const removeArgs = ['mcp', 'remove', 'ctrl-spc'];
+        if (scope)
+            removeArgs.push('-s', scope);
+        runner(command, removeArgs);
+    }
+    runner(command, ['mcp', 'add', '--transport', 'http', '--scope', 'user', 'ctrl-spc', url]);
+    console.log('Claude MCP: ctrl-spc registered (user scope).');
+}
+/** Codex user config, respecting the same CODEX_HOME override as the Codex CLI. */
+export function codexConfigPath() {
+    return join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'config.toml');
+}
+/**
+ * Keeps normal non-interactive Codex runs from cancelling ctrl-spc MCP calls.
+ * The Codex CLI owns creation of the canonical MCP block; this function only
+ * repairs its tool approval mode while preserving every unrelated TOML byte.
+ */
+export function ensureCodexMcpApproval(path = codexConfigPath()) {
+    if (!existsSync(path))
+        throw new Error(`Codex config not found after MCP registration: ${path}`);
+    const content = readFileSync(path, 'utf8');
+    const header = /^[ \t]*\[mcp_servers\.(?:ctrl-spc|"ctrl-spc")\][ \t]*(?:#.*)?$/m.exec(content);
+    if (!header)
+        throw new Error(`Codex MCP registration did not create [mcp_servers.ctrl-spc] in ${path}`);
+    const headerEnd = header.index + header[0].length;
+    const afterHeader = content.slice(headerEnd);
+    const nextHeader = /^[ \t]*\[\[?[^\]\r\n]+\]\]?[ \t]*(?:#.*)?$/m.exec(afterHeader);
+    const blockEnd = headerEnd + (nextHeader?.index ?? afterHeader.length);
+    const block = content.slice(headerEnd, blockEnd);
+    const approval = /^([ \t]*default_tools_approval_mode[ \t]*=[ \t]*)(?:"([^"\r\n]*)"|'([^'\r\n]*)'|([^#\r\n]*?))([ \t]*(?:#.*)?)$/m.exec(block);
+    // Only a TOML string is valid for this schema field. Repair an unquoted
+    // bare value even if its text happens to say `approve`.
+    if (approval && (approval[2] === 'approve' || approval[3] === 'approve'))
+        return;
+    let updated;
+    if (approval) {
+        const valueStart = headerEnd + approval.index;
+        const valueEnd = valueStart + approval[0].length;
+        updated = content.slice(0, valueStart) + `${approval[1]}"approve"${approval[5]}` + content.slice(valueEnd);
+    }
+    else {
+        const newline = content.includes('\r\n') ? '\r\n' : '\n';
+        const leadingNewline = blockEnd > 0 && content[blockEnd - 1] !== '\n' ? newline : '';
+        updated = content.slice(0, blockEnd) + `${leadingNewline}default_tools_approval_mode = "approve"${newline}` + content.slice(blockEnd);
+    }
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    const mode = statSync(path).mode & 0o777;
+    const tempPath = join(dir, `.config.toml.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        writeFileSync(tempPath, updated, { encoding: 'utf8', mode });
+        chmodSync(tempPath, mode);
+        renameSync(tempPath, path);
+    }
+    catch (err) {
+        rmSync(tempPath, { force: true });
+        throw err;
+    }
+}
+function syncCodexMcp(command, url, runner, repairApproval) {
+    const raw = runner(command, ['mcp', 'list', '--json']);
+    const entries = JSON.parse(raw);
+    const managed = entries.filter((entry) => entry.name === 'ctrl-spc' || entry.name === 'ctrl_spc');
+    const canonical = managed.find((entry) => entry.name === 'ctrl-spc');
+    if (managed.length === 1 &&
+        canonical?.enabled === true &&
+        !canonical.disabled_reason &&
+        canonical.transport?.type === 'streamable_http' &&
+        canonical.transport.url === url) {
+        repairApproval();
+        console.log('Codex MCP: ctrl-spc registered.');
+        return;
+    }
+    for (const entry of managed) {
+        if (entry.name)
+            runner(command, ['mcp', 'remove', entry.name]);
+    }
+    runner(command, ['mcp', 'add', 'ctrl-spc', '--url', url]);
+    repairApproval();
+    console.log('Codex MCP: ctrl-spc registered.');
+}
+/**
+ * Makes the detected-agent list truthful: only agents whose MCP config is
+ * confirmed at the current endpoint are published as available presence.
+ */
+export function registerAgentMcps(agents, url, runner = runCommand, commandResolver = resolveAgentCommand, repairCodexApproval = () => ensureCodexMcpApproval()) {
+    if (process.env.CTRL_SPC_SKIP_MCP_REGISTER === '1') {
+        console.log('Agent MCP registration skipped (CTRL_SPC_SKIP_MCP_REGISTER=1).');
+        return [];
+    }
+    const registered = [];
+    for (const agent of agents) {
+        const command = commandResolver(agent);
+        if (!command)
+            continue;
+        try {
+            if (agent === 'claude')
+                syncClaudeMcp(command, url, runner);
+            else
+                syncCodexMcp(command, url, runner, repairCodexApproval);
+            registered.push(agent);
+        }
+        catch (err) {
+            console.warn(`Warning: could not register ctrl-spc with ${agent}: ${err.message}`);
+        }
+    }
+    return registered;
+}
+/** Always refresh agent skills and MCP registrations, even when this command
+ * will hand control back to an already-running same-machine broker. */
+export async function prepareBrokerAgents(machineId, deps = {}) {
+    const brokerAlreadyRunning = await (deps.status ?? ((id) => existingBrokerStatus(id)))(machineId) === 'same_machine';
+    const agents = (deps.detect ?? detectAgents)();
+    console.log(`Agents detected: ${agents.length > 0 ? agents.join(', ') : 'none'}`);
+    if (agents.length === 0) {
+        throw new Error('No supported coding agent found. Install Claude Code or Codex, then run `ctrl-spc` again.');
+    }
+    const url = mcpUrl();
+    const install = deps.install ?? installSkills;
+    install(agents, url);
+    if (agents.includes('claude'))
+        console.log(`Skill installed: ${claudeSkillPath()}`);
+    if (agents.includes('codex'))
+        console.log(`Skill installed: ${codexSkillPath()}`);
+    const registeredAgents = (deps.register ?? registerAgentMcps)(agents, url);
+    if (registeredAgents.length === 0) {
+        throw new Error('No detected coding agent could be registered with ctrl-spc. Fix the warnings above, then run `ctrl-spc` again.');
+    }
+    return { registeredAgents, brokerAlreadyRunning };
+}
+async function loadProfileName(client, userId) {
+    const { data, error } = await client.from('profiles').select('name').eq('id', userId).single();
+    if (error || !data) {
+        throw new Error(`Could not load your profile: ${error?.message ?? 'no profile returned'}`);
+    }
+    return data.name;
+}
+/**
+ * Keeps one Presence channel per current machine workspace while retaining a
+ * single MCP listener. Reconciliation is serialized so a slow network poll
+ * can never create duplicate channels for the same project.
+ */
+export function createProjectPresenceReconciler(client, userId, profileName, machine, agents, deps = {}) {
+    const controllers = new Map();
+    const loadProjects = deps.loadProjects ?? loadMachineProjects;
+    const openPresence = deps.openPresence ?? startPresence;
+    const intervalMs = deps.intervalMs ?? 30_000;
+    let timer;
+    let chain = Promise.resolve();
+    const runReconcile = async () => {
+        const projects = await loadProjects(client, userId, machine.id);
+        const currentIds = new Set(projects.map((project) => project.id));
+        for (const project of projects) {
+            if (controllers.has(project.id))
+                continue;
+            controllers.set(project.id, openPresence(client, {
+                userId,
+                name: profileName,
+                machineId: machine.id,
+                machineName: machine.name,
+                agents,
+                projectId: project.id,
+                status: 'available',
+            }));
+        }
+        for (const [projectId, controller] of [...controllers]) {
+            if (currentIds.has(projectId))
+                continue;
+            controllers.delete(projectId);
+            await controller.stop();
+        }
+    };
+    return {
+        reconcile() {
+            // Recover the queue after a transient failed poll; the caller still
+            // receives this run's rejection, but later intervals keep reconciling.
+            chain = chain.catch(() => { }).then(runReconcile);
+            return chain;
+        },
+        start() {
+            if (timer)
+                return;
+            timer = setInterval(() => {
+                void this.reconcile().catch((err) => {
+                    console.warn(`Warning: could not refresh project presence: ${err.message}`);
+                });
+            }, intervalMs);
+            timer.unref();
+        },
+        projectIds: () => [...controllers.keys()].sort(),
+        setWorking: () => { },
+        setAvailable: () => { },
+        async stop() {
+            if (timer)
+                clearInterval(timer);
+            timer = undefined;
+            await chain.catch(() => { });
+            const active = [...controllers.values()];
+            controllers.clear();
+            await Promise.all(active.map((controller) => controller.stop()));
+        },
+    };
+}
+/**
+ * Installs a SIGINT/SIGTERM handler that closes the MCP server (so no new
+ * tool call can flip presence back to "working" mid-shutdown) and only then
+ * untracks presence, before exiting.
+ */
+function installShutdownHandler(presence, mcpServer) {
+    let shuttingDown = false;
+    const shutdown = () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.log('\nShutting down — closing MCP server, untracking presence...');
+        mcpServer
+            .close()
+            .catch(() => { })
+            .then(() => presence.stop())
+            .catch(() => { })
+            .then(() => process.exit(0));
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+/**
+ * `ctrl-spc` (no args): one long-running broker per machine. It serves every
+ * initialized machine workspace through one listener and any number of MCP
+ * sessions; begin_work binds each session to the pasted task's project.
+ */
+export async function run() {
+    const cwd = process.cwd();
+    const client = await getClient();
+    const { data: userData, error: userError } = await client.auth.getUser();
+    if (userError || !userData.user) {
+        console.error(`Could not resolve the signed-in user: ${userError?.message ?? 'no user returned'}`);
+        process.exitCode = 1;
+        return;
+    }
+    const userId = userData.user.id;
+    const profileName = await loadProfileName(client, userId);
+    const machine = getMachineIdentity();
+    await registerMachineIdentity(client, userId, machine);
+    let localObservation = null;
+    const observeOnce = () => {
+        localObservation ??= observeLocalWorkspace(cwd);
+        return localObservation;
+    };
+    let projects = await loadMachineProjects(client, userId, machine.id);
+    const legacyCandidates = await legacyCurrentProjectCandidates(client, cwd);
+    if (legacyCandidates.length === 1 && !projects.some((project) => project.id === legacyCandidates[0].id)) {
+        await registerMachineWorkspace(client, userId, legacyCandidates[0].id, machine, cwd, {
+            observeWorkspace: observeOnce,
+        });
+        projects = await loadMachineProjects(client, userId, machine.id);
+    }
+    else if (legacyCandidates.length > 1) {
+        console.log(`Current repository belongs to ${legacyCandidates.length} projects; the broker kept their existing explicit workspace links.`);
+    }
+    let availableRepositories = 0;
+    let missingRepositories = 0;
+    for (const project of projects) {
+        const workspace = await registerMachineWorkspace(client, userId, project.id, machine, cwd, {
+            observeWorkspace: observeOnce,
+        });
+        availableRepositories += workspace.availableRepositories;
+        missingRepositories += workspace.missingRepositories;
+    }
+    console.log(`Broker projects: ${projects.length}; repositories: ${availableRepositories} available` +
+        (missingRepositories > 0 ? `, ${missingRepositories} missing` : ''));
+    const url = mcpUrl();
+    const prepared = await prepareBrokerAgents(machine.id);
+    const registeredAgents = prepared.registeredAgents;
+    if (prepared.brokerAlreadyRunning) {
+        console.log(`Broker already running: ${url}`);
+        return;
+    }
+    // Project channels reconcile independently from the one MCP listener, so
+    // `ctrl-spc init` can add a project without restarting this broker.
+    const presence = createProjectPresenceReconciler(client, userId, profileName, machine, registeredAgents);
+    await presence.reconcile();
+    presence.start();
+    let mcpServer;
+    try {
+        mcpServer = await startMcpServer({
+            client,
+            userId,
+            machineId: machine.id,
+            presence,
+            port: MCP_PORT,
+        });
+    }
+    catch (err) {
+        // Presence is already tracked as "available" at this point — untrack it
+        // before propagating so a failed startup doesn't leave a phantom
+        // "available" agent on the board.
+        await presence.stop().catch(() => { });
+        throw formatMcpStartupError(err, MCP_PORT);
+    }
+    console.log(`MCP: ${url} (tools: list_tasks, get_task, begin_work, heartbeat_work, reserve_work_paths, ` +
+        'release_work_paths, transfer_coordination, acknowledge_unavailable_checkout, record_context_exploration, ' +
+        'ask_question, end_work, create_task, update_task, create_artifact, add_comment)');
+    console.log(`Projects: ${projects.length > 0 ? projects.map((project) => project.name).join(', ') : 'none initialized on this machine'}`);
+    console.log('Presence: available');
+    installShutdownHandler(presence, mcpServer);
+}

package/dist/config.js

@@ -0,0 +1,68 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, chmodSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+const SESSION_FILE_NAME = 'session.json';
+const MACHINE_FILE_NAME = 'machine.json';
+/** Config directory: `CTRL_SPC_CONFIG_DIR` env override, else `~/.config/ctrl-spc`. */
+export function configDir() {
+    return process.env.CTRL_SPC_CONFIG_DIR || join(homedir(), '.config', 'ctrl-spc');
+}
+function sessionFilePath() {
+    return join(configDir(), SESSION_FILE_NAME);
+}
+function machineFilePath() {
+    return join(configDir(), MACHINE_FILE_NAME);
+}
+/** Stable per-machine identity used as the Realtime presence key. */
+export function getMachineIdentity() {
+    const path = machineFilePath();
+    if (existsSync(path)) {
+        try {
+            const stored = JSON.parse(readFileSync(path, 'utf8'));
+            if (typeof stored.id === 'string' && stored.id && typeof stored.name === 'string' && stored.name) {
+                return { id: stored.id, name: stored.name };
+            }
+        }
+        catch { /* replace a corrupt identity below */ }
+    }
+    const identity = {
+        id: randomUUID(),
+        name: hostname().replace(/\.local$/i, '') || 'This machine',
+    };
+    mkdirSync(configDir(), { recursive: true });
+    writeFileSync(path, JSON.stringify(identity, null, 2), { mode: 0o600 });
+    chmodSync(path, 0o600);
+    return identity;
+}
+/** Reads the stored session, or `null` if none has been saved yet or the file is corrupted. */
+export function readSession() {
+    const path = sessionFilePath();
+    if (!existsSync(path))
+        return null;
+    const raw = readFileSync(path, 'utf8');
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Deletes the stored session. Returns whether one existed. */
+export function clearSession() {
+    const path = sessionFilePath();
+    if (!existsSync(path))
+        return false;
+    rmSync(path);
+    return true;
+}
+/** Persists the session to disk, creating the config dir if needed, mode 0600. */
+export function writeSession(session) {
+    const dir = configDir();
+    mkdirSync(dir, { recursive: true });
+    const path = sessionFilePath();
+    writeFileSync(path, JSON.stringify(session, null, 2), { mode: 0o600 });
+    // writeFileSync's `mode` only applies when the file is created; chmod
+    // explicitly so re-writing an existing session.json still ends up 0600.
+    chmodSync(path, 0o600);
+}