@ctrl-spc/cli 1.2.0 → 1.2.2

package/dist/commands/init.js

@@ -6,6 +6,7 @@ import { getClient } from '../supabase.js';
 import { ask, select } from '../prompt.js';
 import { buildTopologyTargets, componentTargetId, discoverRepositoryTopology, planExplicitGrouping, readGroupingManifest, repositoryTargetId, } from '../topology.js';
 import { upsertProjectLink } from './link.js';
+import { registerMachineWorkspace } from './run.js';
 function setGrouping(flags, grouping) {
     if (flags.grouping) {
         throw new Error(`Choose exactly one grouping option: --combine, --split, or --manifest <file>.`);
@@ -370,8 +371,16 @@ export async function init(argv = []) {
                 console.log(`Created project "${result.project_name}" in "${result.org_name ?? orgLabel}" — ${key}`);
                 break;
         }
-        await upsertProjectLink(client, userId, result.project_id, repository.rootPath);
-        console.log(`Linked — local path ${repository.rootPath}`);
+        try {
+            const machine = getMachineIdentity();
+            await registerMachineWorkspace(client, userId, result.project_id, machine, repository.rootPath);
+            await upsertProjectLink(client, userId, result.project_id, repository.rootPath);
+            console.log(`Linked — local path ${repository.rootPath}`);
+        }
+        catch (err) {
+            console.error(`Failed to initialize this machine: ${err instanceof Error ? err.message : String(err)}`);
+            process.exitCode = 1;
+        }
         return;
     }
     try {

package/dist/commands/run.js

@@ -15,6 +15,34 @@ import { discoverRepositoryTopology } from '../topology.js';
 function mcpUrl() {
     return `http://localhost:${MCP_PORT}/mcp`;
 }
+/** Retires the pre-1.2 background launcher, whose pinned repo checkout can
+ * otherwise reclaim the MCP port after an upgrade or reboot. */
+export function retireLegacyDaemon(deps = {}) {
+    if (process.platform !== 'darwin' && !deps.launchAgentPath)
+        return false;
+    const path = deps.launchAgentPath ?? join(homedir(), 'Library', 'LaunchAgents', 'com.ctrl-spc.daemon.plist');
+    if (!(deps.exists ?? existsSync)(path))
+        return false;
+    const read = deps.read ?? ((target) => readFileSync(target, 'utf8'));
+    const contents = read(path);
+    if (!contents.includes('com.ctrl-spc.daemon') || !contents.includes('daemon'))
+        return false;
+    const uid = deps.uid ?? process.getuid?.();
+    if (uid !== undefined) {
+        try {
+            const bootout = deps.bootout ?? ((domain, target) => {
+                execFileSync('launchctl', ['bootout', domain, target], { stdio: 'ignore' });
+            });
+            bootout(`gui/${uid}`, path);
+        }
+        catch {
+            // An unloaded service is already safe; still remove its stale launcher.
+        }
+    }
+    const remove = deps.remove ?? rmSync;
+    remove(path);
+    return true;
+}
 export async function existingBrokerStatus(machineId, port = MCP_PORT, fetcher = fetch) {
     try {
         const response = await fetcher(`http://127.0.0.1:${port}/health`, {
@@ -127,6 +155,67 @@ export async function legacyCurrentProjectCandidates(client, cwd) {
         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));
 }
+async function loadActiveProjectRemoteKeys(client, projectId) {
+    const { data, error } = await client
+        .from('project_repository_scopes')
+        .select('scope:repository_scopes!project_repository_scopes_repository_scope_id_fkey(' +
+        'repository:repositories!repository_scopes_repository_id_fkey(remote_key))')
+        .eq('project_id', projectId)
+        .eq('active', true);
+    if (error)
+        throw new Error(`Could not load project repositories: ${error.message}`);
+    const remotes = new Set();
+    for (const row of (data ?? [])) {
+        const scope = one(row.scope);
+        const repository = scope ? one(scope.repository) : null;
+        if (repository?.remote_key)
+            remotes.add(repository.remote_key);
+    }
+    return remotes;
+}
+/**
+ * Moves verifiable pre-machine project links onto this machine automatically.
+ * A legacy path is trusted only when it still exists as a Git checkout and its
+ * origin resolves back to the explicitly linked project. Stale paths from a
+ * different computer are ignored.
+ */
+export async function recoverLegacyProjectLinks(client, userId, machine, initializedProjectIds, deps = {}) {
+    const { data, error } = await client
+        .from('project_links')
+        .select('project_id,local_path')
+        .eq('user_id', userId);
+    if (error)
+        throw new Error(`Could not load legacy project links: ${error.message}`);
+    const observe = deps.observeWorkspace ?? observeLocalWorkspace;
+    const loadExpectedRemoteKeys = deps.loadExpectedRemoteKeys ?? loadActiveProjectRemoteKeys;
+    const register = deps.registerWorkspace ?? registerMachineWorkspace;
+    const recovered = [];
+    const links = [...(data ?? [])]
+        .sort((left, right) => left.project_id.localeCompare(right.project_id) || left.local_path.localeCompare(right.local_path));
+    for (const link of links) {
+        if (initializedProjectIds.has(link.project_id))
+            continue;
+        let observation;
+        try {
+            observation = observe(link.local_path);
+        }
+        catch {
+            continue;
+        }
+        const expectedRemoteKeys = await loadExpectedRemoteKeys(client, link.project_id);
+        const observedRemoteKeys = new Set(observation.checkouts
+            .map((checkout) => checkout.remoteKey)
+            .filter((remote) => remote !== null));
+        if (![...expectedRemoteKeys].some((remote) => observedRemoteKeys.has(remote)))
+            continue;
+        await register(client, userId, link.project_id, machine, link.local_path, {
+            observeWorkspace: () => observation,
+        });
+        initializedProjectIds.add(link.project_id);
+        recovered.push(link.project_id);
+    }
+    return recovered;
+}
 function checkoutPlan(workspaceId, repositories, observation, existing, inspectCheckout, verifiedAt) {
     const rows = new Map();
     const availableRepositoryIds = new Set();
@@ -545,6 +634,9 @@ function installShutdownHandler(presence, mcpServer) {
  * sessions; begin_work binds each session to the pasted task's project.
  */
 export async function run() {
+    if (retireLegacyDaemon()) {
+        console.log('Removed obsolete CTRL+SPC background launcher.');
+    }
     const cwd = process.cwd();
     const client = await getClient();
     const { data: userData, error: userError } = await client.auth.getUser();
@@ -563,6 +655,11 @@ export async function run() {
         return localObservation;
     };
     let projects = await loadMachineProjects(client, userId, machine.id);
+    const recoveredProjects = await recoverLegacyProjectLinks(client, userId, machine, new Set(projects.map((project) => project.id)));
+    if (recoveredProjects.length > 0) {
+        console.log(`Recovered ${recoveredProjects.length} initialized ${recoveredProjects.length === 1 ? 'project' : 'projects'} for this machine.`);
+        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, {

package/dist/mcp.js

@@ -372,7 +372,7 @@ export async function beginAgentRunHandler(deps, session, args) {
         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.');
+                `From that project's checkout, run \`ctrl-spc link --project ${taskProjectId}\`.`);
         }
         const result = await must(deps.client.rpc('begin_agent_run', {
             p_task: args.task_id,
@@ -879,7 +879,8 @@ 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.`);
+            return errorResult(`Project "${args.project_id}" is not initialized on this machine. ` +
+                `From its checkout, run \`ctrl-spc link --project ${args.project_id}\`.`);
         }
         const projectIds = args.project_id ? [args.project_id] : projects.map((project) => project.id);
         if (projectIds.length === 0)
@@ -933,7 +934,8 @@ export async function getTaskHandler(deps, _attribution, args, machineId) {
                 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.`);
+            return errorResult(`The resolved item belongs to project "${row.project_id}", which is not initialized on this machine. ` +
+                `From that project's checkout, run \`ctrl-spc link --project ${row.project_id}\`.`);
         }
         const task = parseTaskRow(row);
         const topologyMachineId = machineId ?? deps.machineId;
@@ -1281,7 +1283,7 @@ export function protocolPromptHandler() {
 // ---------------------------------------------------------------------------
 const IDLE_TIMEOUT_MS = 10 * 60 * 1000;
 const HEARTBEAT_INTERVAL_MS = 30 * 1000;
-export const BROKER_VERSION = '1.2.0';
+export const BROKER_VERSION = '1.2.1';
 async function readJsonBody(req) {
     const chunks = [];
     for await (const chunk of req)

package/dist/protocol.js

@@ -13,6 +13,24 @@ export const PROTOCOL_FULL = `## 5a. Agent working protocol
 
 Delivered redundantly (installed skill + MCP), phrased imperatively for the agent:
 
+**HARD STOP — unclear novel feature.** After \`record_context_exploration\` succeeds,
+if the task does not explicitly request a build or name a deliverable, the immediate
+next tool call is \`ask_question\` with category \`intent\` and the exact question:
+“What should I produce for this feature? Select one or more: build, plan, spec,
+diagram, mock, wireframe.” Then call \`end_work\` with reason
+\`pending_user_answer\` and outcome \`blocked\`. Do not call \`get_task\` again,
+\`update_task\`, \`create_artifact\`, \`reserve_work_paths\`, or any intervening tool.
+The context artifact is the only artifact allowed before the answer. A read-only
+execution sandbox is not a missing checkout and never changes this intent question.
+Multiple selections are allowed.
+
+Before the context artifact exists, never state or imply a requested deliverable and
+never mention repository counts, contents, tests, findings, or likely impact. If
+progress commentary is required, use only: “The required CTRL+SPC context review is
+in progress; no decision or repository change has been made.” After persistence and
+before the intent question, either say nothing or only: “The required context review
+is saved to the work item. I am applying the task's explicit intent gate now.”
+
 1. **Resolve without side effects.** \`/ctrl-spc work <id>\` → call \`get_task(id)\` before
    anything else. \`get_task\` is read-only: it does not change task status, presence,
    collaboration, claims, or reservations. The ID is the only context in the paste;
@@ -64,9 +82,9 @@ Delivered redundantly (installed skill + MCP), phrased imperatively for the agen
    authorized deliverable. Perform the action only when the item explicitly names it; do
    not ask for confirmation. Otherwise use \`ask_question\`. For a bug, ask for reproduction steps,
    expected behavior, or actual behavior only when each is missing and not discoverable.
-   For a novel feature with no explicit build action or deliverable, the mandatory next
-   mutating call after \`record_context_exploration\` is \`ask_question\`: ask whether to build
-   and/or create a plan, spec, diagram, mock, or wireframe; multiple selections are allowed.
+   For a novel feature with no explicit build action or deliverable, apply the HARD STOP
+   above; the immediate next call is the exact build/plan/spec/diagram/mock/wireframe
+   \`ask_question\`.
    Generic goals such as “improve,” “coordinate,” “prepare,” or “support” do not authorize
    analysis, a release decision, implementation, or another artifact. In this state do not
    call \`update_task\`, \`create_artifact\`, \`reserve_work_paths\`, or \`create_task\`; do not
@@ -109,6 +127,7 @@ Delivered redundantly (installed skill + MCP), phrased imperatively for the agen
    abandoning the run. Missing, stale, foreign, duplicate, or incomplete receipts are
    rejected. Ending releases only this session's work.`;
 export const PROTOCOL_SHORT = 'ctrl-spc protocol (compact — full text: MCP prompt `ctrl-spc-protocol`): ' +
+    'HARD STOP unclear novel feature: immediately after record_context_exploration, ask_question category intent exactly “What should I produce for this feature? Select one or more: build, plan, spec, diagram, mock, wireframe.” Then end_work blocked pending_user_answer. No intervening get_task/update_task/create_artifact/reservation/tool; read-only sandbox is not a missing checkout. ' +
     '1) get_task is read-only; begin_work (run coordinator); resolve missing checkouts via fetch/link or acknowledge_unavailable_checkout. ' +
     '2) Every item needs read-only subagents covering scope IDs once. Codex spawn_agent MUST use fork_turns:none; its self-contained prompt has exact IDs/paths/focus, no copied command. Child calls no ctrl-spc tools and writes nothing. If unavailable, record blocked; stop. ' +
     '3) Parent must record_context_exploration before deciding, asking, planning, reserving, or editing. Before success narrate process only—no findings/conclusions/impact/decisions. Later summaries add no unpersisted facts. ' +

package/dist/skills.js

@@ -38,12 +38,16 @@ export function codexLegacySkillPath() {
 function protocolBody(mcpUrl) {
     return `Resolve a CTRL+SPC work item or artifact pasted as \`/ctrl-spc work <id>\` or \`/ctrl-spc artifact <id>\`, then follow the ctrl-spc working protocol:
 
+HARD STOP — unclear novel feature: after \`record_context_exploration\` succeeds, if the task does not explicitly request a build or name a deliverable, the next tool call MUST be \`ask_question\` with category \`intent\` and this exact question: “What should I produce for this feature? Select one or more: build, plan, spec, diagram, mock, wireframe.” Then call \`end_work\` with reason \`pending_user_answer\` and outcome \`blocked\`. In that run, never call \`get_task\` again, \`update_task\`, \`create_artifact\`, \`reserve_work_paths\`, or any other tool between the context artifact and \`ask_question\`. The context artifact is the only allowed artifact. Do not copy findings into the task description before the user answers. A read-only execution sandbox is not a missing checkout and must not change this intent question.
+
+Before the context artifact exists, never state or imply a requested deliverable and never mention repository counts, contents, tests, findings, or likely impact. If progress commentary is required, use only: “The required CTRL+SPC context review is in progress; no decision or repository change has been made.” After the context artifact and before the intent question, either say nothing or use only: “The required context review is saved to the work item. I am applying the task's explicit intent gate now.”
+
 1. Resolve without side effects — call \`get_task\` before anything else. It is read-only: it does not change status, presence, claims, or reservations. The ID is the only context in the paste; everything current lives in ctrl-spc.
 2. Begin explicitly — call \`begin_work\` after reading the topology. The first live run is coordinator and \`begin_work\` moves Backlog to In Progress; later runs join as collaborators. Only the coordinator changes status. Never mark an item \`done\` autonomously.
 3. Repair missing context — if \`begin_work\` reports an unavailable checkout, warn the user and offer to fetch or link it. Never fetch without approval. If the user explicitly continues without it, call \`acknowledge_unavailable_checkout\`, then call \`begin_work\` again after every missing scope is fetched or acknowledged.
 4. Delegate exploration — every pasted work item MUST use at least one read-only subagent. After \`begin_work\` joins, partition every available repository scope exactly once across bounded subagent invocations. Every child prompt must explicitly list its assigned \`repository_scope_ids\`; across the batch each available ID appears exactly once. When using Codex \`spawn_agent\`, MUST pass \`fork_turns: "none"\`; never pass \`all\` or a recent-turn count. Give each child a self-contained assignment containing only its exact scope IDs, checkout paths, inspection focus, read-only restrictions, and required report shape. Never include or inherit the parent \`/ctrl-spc work\` command. The child must not call any ctrl-spc tool—including \`get_task\` or \`begin_work\`—or pick up the work item; it only inspects assigned paths and returns its report. If zero scopes are available after explicit acknowledgements, one child inspects the task/artifact context and reports those unavailable scopes without pretending they were reviewed. Children inspect only: no file mutation, path reservation, ctrl-spc call, \`tee\`, shell redirection, temp/capture file, install, formatter, cache-generating command, or any command that can write. Inspection-first is sufficient; do not decide intent before reports are persisted. Each report uses \`{ agent, focus, repository_scope_ids, inspected_paths, findings, likely_impact, unresolved_questions }\`. If no subagent is available, do not explore directly: call \`record_context_exploration\` with \`blocked_reason = subagents_unavailable\`, tell the user, and stop.
 5. Persist context before deciding — the parent consolidates every child report and MUST call \`record_context_exploration\` to create the work item's analysis artifact before deciding what to do, asking a task question, planning, reserving, or editing. Pass the structured reports plus a separate coverage array; include every active scope exactly once, and give unavailable scopes their acknowledgement. Before the tool succeeds, commentary may state process only: never disclose findings, conclusions, likely impact, or decisions. After persistence, terminal summaries may reference the persisted artifact/question but must add no unpersisted facts.
-6. Decide or ask deterministically — after exploration is recorded, classify intent only from the work item's explicit wording and accepted answers, never from findings. Findings do not authorize a deliverable. Infer and perform the action only when the item explicitly names it. Otherwise persist only the necessary question with \`ask_question\`. For a bug, ask for reproduction steps, expected behavior, or actual behavior only when each is missing and not discoverable. For a novel feature with no explicit build action or deliverable, the mandatory next mutating call after \`record_context_exploration\` is \`ask_question\`: ask the user to select one or more: build, plan, spec, diagram, mock, wireframe. Generic goals such as “improve,” “coordinate,” “prepare,” or “support” are not deliverables. In this state do not call \`update_task\`, \`create_artifact\`, \`reserve_work_paths\`, or \`create_task\`; do not decide, edit, or complete. The context analysis is the only allowed artifact before the answer. Ask before overriding an unmet dependency, splitting work, fetching, or accepting a collision handoff. After \`ask_question\` succeeds, do no more work in that run: call \`end_work\` with reason \`pending_user_answer\` and outcome \`blocked\`, then wait for a later pasted run.
+6. Decide or ask deterministically — after exploration is recorded, classify intent only from the work item's explicit wording and accepted answers, never from findings. Findings do not authorize a deliverable. Infer and perform the action only when the item explicitly names it. Otherwise persist only the necessary question with \`ask_question\`. For a bug, ask for reproduction steps, expected behavior, or actual behavior only when each is missing and not discoverable. For a novel feature with no explicit build action or deliverable, apply the HARD STOP above: the mandatory next mutating call after \`record_context_exploration\` is \`ask_question\`; it must say “select one or more: build, plan, spec, diagram, mock, wireframe.” Generic goals such as “improve,” “coordinate,” “prepare,” or “support” are not deliverables. In this state do not call \`update_task\`, \`create_artifact\`, \`reserve_work_paths\`, or \`create_task\`; do not decide, edit, or complete. The context analysis is the only allowed artifact before the answer. Ask before overriding an unmet dependency, splitting work, fetching, or accepting a collision handoff. After \`ask_question\` succeeds, do no more work in that run: call \`end_work\` with reason \`pending_user_answer\` and outcome \`blocked\`, then wait for a later pasted run.
 7. Persist answers and findings — after every accepted answer, call \`update_task\` to add the decision, constraint, acceptance criterion, and durable findings to the description. Pass the latest revision and refetch/reconcile on conflict. Do not use progress comments; do not leave findings only in the terminal.
 8. Reserve before writing — call \`reserve_work_paths\` with the topology revision, exact checkout ID, and every repository-relative path you intend to edit. Do not edit until the full atomic request succeeds. On collision, narrow to disjoint paths, wait, ask for an explicit handoff, or use an isolated Git worktree. Never edit a conflicting path.
 9. Persist every output — every substantive non-question output must be a ctrl-spc artifact before it is presented as complete. Use \`create_artifact\` type \`analysis\` for research/findings, \`plan\` for plans, \`spec\` for specifications or proposed schemas, and the matching type for diagrams, mocks, and wireframes. Never write planning documents into a repository. Every artifact includes exactly one coverage disposition and non-empty reason for every active repository scope.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl-spc/cli",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "CTRL+SPC CLI — per-machine agent for browser login, project linking, presence, and the local MCP server.",
   "engines": {
     "node": ">=22"
@@ -23,7 +23,6 @@
     "typecheck:e2e-contract": "tsc -p e2e/tsconfig.json",
     "run:e2e-copied-work": "node --experimental-strip-types e2e/run-copied-work-item.ts",
     "run:e2e-hosted-topology": "npm run build && node --experimental-strip-types e2e/run-hosted-topology-management.ts",
-    "run:e2e-hosted-topology": "npm run build && node --experimental-strip-types e2e/run-hosted-topology-management.ts",
     "setup:e2e-multirepo": "node --experimental-strip-types e2e/setup-multirepo-matrix.ts",
     "verify:e2e-multirepo": "npm run build && node --experimental-strip-types e2e/run-multirepo-matrix.ts"
   },