@ctrl-spc/cli 1.3.1 → 1.3.3

package/dist/git.js

@@ -1,4 +1,73 @@
 import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+export const LOCAL_REPOSITORY_KEY_PREFIX = 'local:v1:';
+const LOCAL_REPOSITORY_CONFIG_KEY = 'ctrl-spc.repository-id';
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function gitOutput(cwd, args) {
+    try {
+        const value = execFileSync('git', args, {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return value || null;
+    }
+    catch {
+        return null;
+    }
+}
+export function localRepositoryKey(id) {
+    if (!UUID_PATTERN.test(id))
+        throw new Error('Invalid local repository identity.');
+    return `${LOCAL_REPOSITORY_KEY_PREFIX}${id.toLowerCase()}`;
+}
+export function isLocalRepositoryKey(value) {
+    return value.toLowerCase().startsWith(LOCAL_REPOSITORY_KEY_PREFIX);
+}
+export function readLocalRepositoryIdentity(cwd) {
+    const id = gitOutput(cwd, ['config', '--local', '--get', LOCAL_REPOSITORY_CONFIG_KEY]);
+    return id && UUID_PATTERN.test(id) ? localRepositoryKey(id) : null;
+}
+export function readRootCommitSha(cwd) {
+    const roots = gitOutput(cwd, ['rev-list', '--max-parents=0', 'HEAD']);
+    return roots?.split(/\s+/).filter(Boolean).sort()[0] ?? null;
+}
+/** Writes untracked Git metadata so identity survives moves and copied folders. */
+export function ensureLocalRepositoryIdentity(cwd, createId = randomUUID) {
+    const existing = readLocalRepositoryIdentity(cwd);
+    if (existing)
+        return existing;
+    if (!gitOutput(cwd, ['rev-parse', '--show-toplevel'])) {
+        throw new Error(`Not a Git repository: ${cwd}`);
+    }
+    const id = createId();
+    const key = localRepositoryKey(id);
+    execFileSync('git', ['config', '--local', LOCAL_REPOSITORY_CONFIG_KEY, id.toLowerCase()], {
+        cwd,
+        stdio: 'ignore',
+    });
+    return key;
+}
+export function writeLocalRepositoryIdentity(cwd, key, allowedPriorKey) {
+    if (!isLocalRepositoryKey(key))
+        throw new Error('Expected a local repository identity.');
+    const id = key.slice(LOCAL_REPOSITORY_KEY_PREFIX.length);
+    localRepositoryKey(id);
+    const existing = readLocalRepositoryIdentity(cwd);
+    if (existing && existing !== key && existing !== allowedPriorKey) {
+        throw new Error('This folder is already linked to a different CTRL+SPC repository.');
+    }
+    if (!gitOutput(cwd, ['rev-parse', '--show-toplevel']))
+        throw new Error(`Not a Git repository: ${cwd}`);
+    execFileSync('git', ['config', '--local', LOCAL_REPOSITORY_CONFIG_KEY, id], { cwd, stdio: 'ignore' });
+    return key;
+}
+export function currentRepoIdentity(cwd) {
+    const remote = currentRepoRemote(cwd);
+    if (remote)
+        return normalizeRemoteUrl(remote);
+    return readLocalRepositoryIdentity(cwd);
+}
 /**
  * Normalizes a git remote URL to a canonical `host/path` key (no scheme,
  * lowercase throughout — hosts are case-insensitive and GitHub/GitLab paths
@@ -52,13 +121,12 @@ export function currentRepoRemote(cwd) {
  * (`init`/`link`) must not treat it as such.
  */
 export async function resolveProject(client, cwd) {
-    const remote = currentRepoRemote(cwd);
-    if (!remote)
+    const key = currentRepoIdentity(cwd);
+    if (!key)
         return null;
-    const key = normalizeRemoteUrl(remote);
     const { data, error } = await client
         .from('projects')
-        .select('id, org_id, name, organizations(name)')
+        .select('id, org_id, name, archived_at, organizations(name)')
         .eq('git_remote_url', key)
         .maybeSingle();
     if (error)
@@ -66,5 +134,7 @@ export async function resolveProject(client, cwd) {
     if (!data)
         return null;
     const row = data;
+    if (row.archived_at)
+        return null;
     return { id: row.id, orgId: row.org_id, name: row.name, orgName: row.organizations?.name ?? '' };
 }

package/dist/index.js

@@ -5,16 +5,19 @@ import { init } from './commands/init.js';
 import { link } from './commands/link.js';
 import { fetchRepository } from './commands/fetch.js';
 import { run } from './commands/run.js';
+import { openCompanion, serveCompanion } from './companion.js';
 export const HELP_TEXT = `ctrl-spc — CTRL+SPC CLI
 
 Usage:
   ctrl-spc login    Sign in via the browser and store a session
   ctrl-spc logout   Remove the stored session from this machine
   ctrl-spc init     Discover repositories and explicitly group them into projects
+                    [--project <empty-project-id>] [--repo <path> ...] [--combine] [--yes]
   ctrl-spc link     Reconcile a project's full topology after grouping changes
                     [--project <project-id>]
   ctrl-spc fetch    Clone and link one unavailable project repository
                     [repository-id] [--project <project-id>] [--destination <path>] [--yes]
+  ctrl-spc open     Open the local connection manager
   ctrl-spc          Run the local agent process (presence + MCP server)
   ctrl-spc --help   Show this help text
 `;
@@ -36,6 +39,15 @@ export async function main(argv = process.argv.slice(2)) {
         case 'fetch':
             await fetchRepository(argv.slice(1));
             return;
+        case 'open':
+            await openCompanion();
+            return;
+        case '__broker':
+            await run();
+            return;
+        case '__companion':
+            await serveCompanion();
+            return;
         case '--help':
         case '-h':
             console.log(HELP_TEXT);

package/dist/mcp.js

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
-import { readFileSync } from 'node:fs';
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
 import { createServer as createHttpServer } from 'node:http';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
@@ -8,6 +9,8 @@ import { z } from 'zod';
 import { PROTOCOL_FULL, PROTOCOL_SHORT } from './protocol.js';
 import { MCP_PORT } from './env.js';
 import { getMachineIdentity } from './config.js';
+import { fetchServerCapabilities } from './supabase.js';
+import { resolveProjectRootRows } from './resolver.js';
 /**
  * From the MCP `initialize` request's `clientInfo.name` (spec: "Agent
  * attribution: from the MCP initialize request's clientInfo.name — map
@@ -64,12 +67,14 @@ async function accessibleProjects(deps, machineId = deps.machineId) {
         return [];
     const rows = (await must(deps.client
         .from('machine_workspaces')
-        .select('project_id,project:projects!machine_workspaces_project_id_fkey(id,name)')
+        .select('project_id,project:projects!machine_workspaces_project_id_fkey(id,name,archived_at)')
         .eq('user_id', deps.userId)
         .eq('machine_id', machineId))) ?? [];
     const projects = new Map();
     for (const row of rows) {
         const project = relationOne(row.project);
+        if (project && 'archived_at' in project && project.archived_at !== null)
+            continue;
         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));
@@ -248,92 +253,64 @@ async function resolveOrCreateSprint(client, projectId, name) {
         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());
+export async function loadAgentProjectTopology(client, projectId, machineId, inspectPath = statSync) {
+    const project = await must(client.from('projects').select('topology_revision,archived_at').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.',
-                    },
-            }];
+    if (project.archived_at)
+        throw new Error('This project is archived. Restore it in the web app before starting agent work.');
+    const rows = await resolveProjectRootRows(client, projectId, machineId);
+    const scopes = rows.map(row => {
+        const cwd = row.local_path ? join(row.local_path, row.scope_path) : null;
+        let status = row.status;
+        let remediation = row.remediation;
+        if (status === 'ready' && cwd) {
+            try {
+                inspectPath(cwd);
+            }
+            catch {
+                status = 'missing';
+                remediation = row.source_kind === 'local' ? 'copy_or_promote' : 'fetch';
+            }
+        }
+        const availability = status === 'ready'
+            ? 'available'
+            : status === 'unlabeled_role'
+                ? row.availability ?? 'missing'
+                : status;
+        const checkout = {
+            id: row.checkout_id,
+            local_path: row.local_path,
+            cwd,
+            availability,
+            head_sha: row.head_sha,
+            is_worktree: row.is_worktree,
+            verified_at: row.verified_at,
+        };
+        return {
+            repository_scope_id: row.root_id,
+            role_slug: row.role_slug,
+            role_label: row.role_label,
+            identity_key: row.identity_key,
+            source_kind: row.source_kind,
+            scope_path: row.scope_path,
+            scope_kind: row.kind,
+            required: row.required,
+            position: row.position,
+            contained_in_root_id: row.contained_in_root_id,
+            status,
+            remediation,
+            cwd,
+            checkouts: row.checkout_id ? [checkout] : [],
+            checkout,
+        };
     });
     const missingRequiredScopeIds = scopes
-        .filter((scope) => scope.required && scope.checkout.availability !== 'available')
+        .filter((scope) => scope.required && scope.status !== 'ready')
         .map((scope) => scope.repository_scope_id);
     return {
         revision: Number(project.topology_revision),
-        workspace_root: workspace?.workspace_root ?? null,
+        workspace_root: null,
         scopes,
         complete: missingRequiredScopeIds.length === 0,
         missing_required_scope_ids: missingRequiredScopeIds,
@@ -382,8 +359,8 @@ export async function beginAgentRunHandler(deps, session, args) {
                 '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,description').eq('id', args.task_id).eq('project_id', deps.projectId).maybeSingle())
-            : await must(deps.client.from('tasks').select('id,project_id,description').eq('id', args.task_id).maybeSingle());
+            ? await must(deps.client.from('tasks').select('id,project_id,description').eq('id', args.task_id).eq('project_id', deps.projectId).is('archived_at', null).maybeSingle())
+            : await must(deps.client.from('tasks').select('id,project_id,description').eq('id', args.task_id).is('archived_at', null).maybeSingle());
         if (!task)
             return errorResult(`No accessible task found for id "${args.task_id}".`);
         const taskProjectId = task.project_id ?? deps.projectId;
@@ -1114,7 +1091,7 @@ export async function listTasksHandler(deps, args = {}) {
         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);
+        let query = deps.client.from('tasks').select(TASK_SELECT).is('archived_at', null);
         query = projectIds.length === 1
             ? query.eq('project_id', projectIds[0])
             : query.in('project_id', projectIds);
@@ -1140,6 +1117,33 @@ export async function listTasksHandler(deps, args = {}) {
         return errorResult(`list_tasks failed: ${err.message}`);
     }
 }
+export async function setTaskRoleSlugsHandler(deps, session, args) {
+    const run = session.run;
+    if (!run || run.state !== 'joined')
+        return errorResult('set_task_role_slugs requires an active agent run.');
+    if (run.role !== 'coordinator')
+        return errorResult('Only the coordinator can set the folders this task needs.');
+    if (args.task_id !== run.taskId)
+        return errorResult(`set_task_role_slugs must stay on this agent run's task (${run.taskId}).`);
+    try {
+        const heartbeat = await heartbeatAgentRunHandler(deps, session);
+        if (heartbeat.isError)
+            return errorResult('set_task_role_slugs requires a current coordinator lease.');
+        if (!session.run || session.run.state !== 'joined' || session.run.role !== 'coordinator') {
+            return errorResult('set_task_role_slugs requires a current coordinator lease.');
+        }
+        const { data, error } = await deps.client.rpc('set_task_role_slugs', {
+            p_task: args.task_id,
+            p_role_slugs: args.role_slugs,
+        });
+        if (error)
+            throw error;
+        return textResult({ task_id: args.task_id, role_slugs: data ?? [] });
+    }
+    catch (error) {
+        return errorResult(`set_task_role_slugs failed: ${error.message}`);
+    }
+}
 export async function getTaskHandler(deps, _attribution, args, machineId) {
     try {
         const { client } = deps;
@@ -1147,18 +1151,18 @@ export async function getTaskHandler(deps, _attribution, args, 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());
+            ? await must(client.from('tasks').select(TASK_SELECT).eq('id', args.id).eq('project_id', deps.projectId).is('archived_at', null).maybeSingle())
+            : await must(client.from('tasks').select(TASK_SELECT).eq('id', args.id).is('archived_at', null).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());
+            const artifact = await must(client.from('artifacts').select('id,task_id').eq('id', args.id).is('deleted_at', null).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());
+                ? await must(client.from('tasks').select(TASK_SELECT).eq('id', artifact.task_id).eq('project_id', deps.projectId).is('archived_at', null).maybeSingle())
+                : await must(client.from('tasks').select(TASK_SELECT).eq('id', artifact.task_id).is('archived_at', null).maybeSingle());
             if (!row)
                 return errorResult(`No task or artifact found for id "${args.id}".`);
         }
@@ -1212,7 +1216,7 @@ export async function getTaskHandler(deps, _attribution, args, machineId) {
                 .eq('active', true)
                 .maybeSingle()),
             topologyMachineId
-                ? loadAgentProjectTopology(client, row.project_id, deps.userId, topologyMachineId)
+                ? loadAgentProjectTopology(client, row.project_id, topologyMachineId, deps.statPath ?? statSync)
                 : Promise.resolve(undefined),
             loadWorkflowContext(client, row.id),
         ]);
@@ -1293,7 +1297,7 @@ export async function createTaskHandler(deps, _attribution, args) {
             p_name: args.name,
             p_description: args.description ?? '',
             p_owner: userId,
-            p_use_workflow: true,
+            p_use_workflow: false,
             p_workflow_version: null,
         }));
         if (!taskId)
@@ -1307,7 +1311,7 @@ export async function createTaskHandler(deps, _attribution, args) {
         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());
+        const fresh = await must(client.from('tasks').select(TASK_SELECT).eq('id', taskId).is('archived_at', null).maybeSingle());
         if (!fresh)
             throw new Error('Created task could not be re-fetched.');
         return textResult({ task: parseTaskRow(fresh) });
@@ -1342,7 +1346,7 @@ export async function updateTaskHandler(deps, _attribution, args, agentRun) {
         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());
+        const current = await must(client.from('tasks').select('id,status,revision').eq('id', id).eq('project_id', projectId).is('archived_at', null).maybeSingle());
         if (!current)
             return errorResult(`No task found for id "${id}" in this project.`);
         const patch = {};
@@ -1384,7 +1388,7 @@ export async function updateTaskHandler(deps, _attribution, args, agentRun) {
             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());
+        const fresh = await must(client.from('tasks').select(TASK_SELECT).eq('id', id).is('archived_at', null).maybeSingle());
         if (!fresh)
             throw new Error('Updated task could not be re-fetched.');
         return textResult({ task: parseTaskRow(fresh) });
@@ -1445,7 +1449,7 @@ export async function createArtifactHandler(deps, attribution, args, agentRun) {
         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)
+        const task = await must(deps.client.from('tasks').select('id').eq('id', args.task_id).is('archived_at', null)
             .eq('project_id', requiredProjectId(deps, 'create_artifact')).maybeSingle());
         if (!task)
             return errorResult(`No task found for id "${args.task_id}" in this project.`);
@@ -1478,7 +1482,7 @@ export async function addCommentHandler(deps, attribution, args, agentRunId) {
             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)
+        const task = await must(deps.client.from('tasks').select('id').eq('id', args.task_id).is('archived_at', null)
             .eq('project_id', requiredProjectId(deps, 'add_comment')).maybeSingle());
         if (!task)
             return errorResult(`No task found for id "${args.task_id}" in this project.`);
@@ -1527,6 +1531,10 @@ async function readJsonBody(req) {
     return raw ? JSON.parse(raw) : undefined;
 }
 export async function startMcpServer(deps) {
+    const capabilities = deps.capabilities ?? await fetchServerCapabilities(deps.client);
+    if (!Boolean(capabilities.root_roles)) {
+        throw new Error("This server doesn't support folder labels yet — update the server before brokering.");
+    }
     const port = deps.port ?? MCP_PORT;
     const machineId = deps.machineId ?? getMachineIdentity().id;
     const handlerDeps = {
@@ -1684,6 +1692,16 @@ export async function startMcpServer(deps) {
             resetSessionIdleTimer(session);
             return heartbeatAgentRunHandler(handlerDeps, session.context);
         });
+        server.registerTool('set_task_role_slugs', {
+            description: 'Set the folder labels this task needs. Unknown labels are ignored by the server.',
+            inputSchema: {
+                task_id: z.string(),
+                role_slugs: z.array(z.string()),
+            },
+        }, async (args) => {
+            resetSessionIdleTimer(session);
+            return setTaskRoleSlugsHandler(handlerDeps, session.context, args);
+        });
         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: {
@@ -1968,7 +1986,16 @@ export async function startMcpServer(deps) {
         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 }));
+            res.end(JSON.stringify({
+                status: 'ok',
+                machine_id: machineId,
+                version: BROKER_VERSION,
+                process_id: process.pid,
+                runtime: deps.runtime ?? {
+                    kind: process.env.CTRL_SPC_RUNTIME_KIND || 'unlabeled',
+                    label: process.env.CTRL_SPC_RUNTIME_LABEL || 'Unlabeled connection',
+                },
+            }));
             return;
         }
         if (url.pathname !== '/mcp') {

package/dist/relink.js

@@ -0,0 +1,31 @@
+export function resolveRelinkRoots(roots, candidates) {
+    const used = new Set();
+    return roots.map(root => {
+        const remote = candidates.find(candidate => !used.has(candidate.path) && candidate.remoteKey === root.remoteKey);
+        if (remote) {
+            used.add(remote.path);
+            return { root, candidate: remote, rung: 'remote' };
+        }
+        const identity = candidates.find(candidate => !used.has(candidate.path) && candidate.stampedIdentityKey !== null && (candidate.stampedIdentityKey === root.identityKey || candidate.stampedIdentityKey === root.priorIdentityKey));
+        if (identity) {
+            used.add(identity.path);
+            return { root, candidate: identity, rung: 'identity' };
+        }
+        const shaMatches = candidates.filter(candidate => (!used.has(candidate.path) && root.rootCommitSha !== null && candidate.rootCommitSha === root.rootCommitSha));
+        if (shaMatches.length === 1) {
+            used.add(shaMatches[0].path);
+            return { root, candidate: shaMatches[0], rung: 'root_commit' };
+        }
+        return {
+            root,
+            candidate: null,
+            rung: 'manual',
+            manualReason: shaMatches.length > 1 || candidates.some(candidate => (!used.has(candidate.path) && !roots.some(known => (candidate.remoteKey === known.remoteKey
+                || candidate.stampedIdentityKey === known.identityKey
+                || candidate.stampedIdentityKey === known.priorIdentityKey
+                || (candidate.rootCommitSha !== null && candidate.rootCommitSha === known.rootCommitSha)))))
+                ? 'ambiguous'
+                : 'not_found',
+        };
+    });
+}

package/dist/resolver.js

@@ -0,0 +1,9 @@
+export async function resolveProjectRootRows(client, projectId, machineId) {
+    const { data, error } = await client.rpc('resolve_project_roots', {
+        p_project_id: projectId,
+        p_machine_id: machineId,
+    });
+    if (error)
+        throw new Error(`Project folders could not be resolved: ${error.message}`);
+    return (data ?? []);
+}

package/dist/role-detection.js

@@ -0,0 +1,101 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { ROLE_SUGGESTIONS } from './roles.js';
+const labelFor = (slug) => ROLE_SUGGESTIONS.find(role => role.slug === slug).label;
+const fileText = (path) => {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+};
+const rootEntries = (dir) => {
+    try {
+        return readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+};
+const hit = (slug, evidence) => ({ slug, label: labelFor(slug), evidence });
+const ANDROID_SCAN_SKIPS = new Set(['.git', 'build', 'dist', 'node_modules', 'target', 'vendor']);
+function findWithin(dir, name, depth, budget = { remaining: 256 }) {
+    if (depth < 0 || budget.remaining <= 0)
+        return null;
+    for (const entry of rootEntries(dir)) {
+        if (--budget.remaining < 0)
+            return null;
+        const path = join(dir, entry.name);
+        if (entry.isFile() && entry.name === name)
+            return path;
+        if (entry.isDirectory() && depth > 0 && !ANDROID_SCAN_SKIPS.has(entry.name)) {
+            const nested = findWithin(path, name, depth - 1, budget);
+            if (nested)
+                return nested;
+        }
+    }
+    return null;
+}
+function packageJson(dir) {
+    try {
+        return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function detectRoleFingerprint(dir) {
+    const entries = rootEntries(dir);
+    const names = new Set(entries.map(entry => entry.name));
+    const nameEvidence = basename(dir) ? [`folder:${basename(dir)}`] : [];
+    const apple = entries.find(entry => entry.name.endsWith('.xcodeproj') || entry.name.endsWith('.xcworkspace'));
+    if (apple)
+        return hit('ios-app', [`entry:${apple.name}`, ...nameEvidence]);
+    const gradle = ['build.gradle', 'build.gradle.kts'].find(name => names.has(name));
+    const manifest = gradle ? findWithin(dir, 'AndroidManifest.xml', 3) : null;
+    if (gradle && manifest)
+        return hit('android-app', [`file:${gradle}`, `file:${manifest}`, ...nameEvidence]);
+    if (names.has('pubspec.yaml') && /flutter/i.test(fileText(join(dir, 'pubspec.yaml')))) {
+        return hit('mobile-app', ['file:pubspec.yaml', ...nameEvidence]);
+    }
+    const pkg = packageJson(dir);
+    const packageDependencies = pkg?.dependencies ?? {};
+    const dependencies = {
+        ...packageDependencies,
+        ...(pkg?.devDependencies ?? {}),
+    };
+    const webDependency = ['react', 'next', 'vite'].find(name => name in dependencies);
+    if (webDependency)
+        return hit('web-app', [`package:${webDependency}`, ...nameEvidence]);
+    if ('express' in packageDependencies)
+        return hit('api', ['package:express', ...nameEvidence]);
+    if (names.has('Gemfile') && /rails/i.test(fileText(join(dir, 'Gemfile'))))
+        return hit('api', ['file:Gemfile', ...nameEvidence]);
+    if (names.has('manage.py'))
+        return hit('api', ['file:manage.py', ...nameEvidence]);
+    if ((names.has('Cargo.toml') && /\[\[bin\]\]/.test(fileText(join(dir, 'Cargo.toml')))) || existsSync(join(dir, 'src', 'main.rs'))) {
+        return hit('cli', [names.has('Cargo.toml') ? 'file:Cargo.toml' : 'file:src/main.rs', ...nameEvidence]);
+    }
+    if (pkg && pkg.bin !== undefined)
+        return hit('cli', ['package:bin', ...nameEvidence]);
+    if (existsSync(join(dir, 'prisma', 'schema.prisma')))
+        return hit('schema', ['file:prisma/schema.prisma', ...nameEvidence]);
+    const migrationEntries = rootEntries(join(dir, 'migrations')).filter(entry => entry.isFile());
+    if (migrationEntries.length > 0 && migrationEntries.filter(entry => entry.name.endsWith('.sql')).length / migrationEntries.length >= 0.5) {
+        return hit('schema', ['directory:migrations', ...nameEvidence]);
+    }
+    const files = entries.filter(entry => entry.isFile());
+    if (files.length > 0 && files.filter(entry => entry.name.endsWith('.sql')).length / files.length >= 0.5) {
+        return hit('schema', ['root:sql-majority', ...nameEvidence]);
+    }
+    if (names.has('Dockerfile'))
+        return hit('infra', ['file:Dockerfile', ...nameEvidence]);
+    const terraform = entries.find(entry => entry.isFile() && entry.name.endsWith('.tf'));
+    if (terraform)
+        return hit('infra', [`file:${terraform.name}`, ...nameEvidence]);
+    if (files.length > 0 && files.filter(entry => entry.name.toLowerCase().endsWith('.md')).length / files.length >= 0.6) {
+        return hit('docs', ['root:markdown-majority', ...nameEvidence]);
+    }
+    return null;
+}